Документация для разработчиков

1C-Битрикс: Управление сайтом

Основные сведения

"1C-Битрикс: Управление сайтом" - технологическое ядро для создания и управления сайтами. Использование этой системы управления содержимым сайта - экономичный способ разработки, поддержки и развития интернет-проекта.

Программный продукт "1C-Битрикс: Управление сайтом" может быть использован корпоративными заказчиками и индивидуальными разработчиками в качестве фундамента для создания новых проектов и управления уже существующими сайтами.

"1C-Битрикс: Управление сайтом" позволяет создавать неограниченное количество сайтов с применением одной копии (лицензии) продукта, размещая ядро и базу данных системы в единственном экземпляре на сервере.

Основные возможности "1C-Битрикс: Управление сайтом":

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

Продукт позволяет минимизировать расходы на сопровождение веб-сайта за счет простоты управления статической и динамической информацией. Для управления проектом вам не потребуются дополнительные услуги специалистов в области веб-дизайна. С помощью "1C-Битрикс: Управление сайтом" управлять веб-сайтом сможет штатный сотрудник компании, обычный пользователь персонального компьютера без специальных навыков программирования и HTML-вёрстки.

© «Битрикс», 2001-2008, «1C-Битрикс», 2008
© «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


Введение

В этом разделе

  • Настройки - описание настроек главного модуля.
  • Основные сведения - сведения о технологиях и основных принципах заложенных в систему.
  • Классы и функции - описание классов и функций главного модуля.
    •

    Данный раздел предназначен для технических специалистов со знанием PHP и HTML. Раздел содержит сведения о технологиях и основных принципах, заложенных в систему 1С-Битрикс: Управление сайтом, описание классов и функций главного модуля.


Настройки

Список настроек

  • Позволять ли пользователям регистрироваться самостоятельно?
  • При регистрации добавлять в группу
  • Разрешить запоминание авторизации
  • Использовать защищенное хранение авторизации в cookies
  • E-Mail адрес или список адресов через запятую на который будут дублироваться все исходящие сообщения
  • Отправлять в письме идентификаторы почтового события и шаблона
  • Дублировать E-Mail адрес в заголовок
  • E-Mail администратора сайта (отправитель по умолчанию)
  • Конвертировать символы новой строки Unix формата в Windows формат при отправке email
  • Конвертировать 8-битные символы в заголовке письма
  • Название сайта
  • URL сайта (без http://). Например: www.mysite.com
  • Имя сервера, содержащего обновления
  • Имя префикса для названия cookies
  • Папка по умолчанию для загрузки файлов
  • Посылать в заголовке статус 200 на 404 ошибку
  • Тип меню для нулевого уровня карты сайта
  • Тип меню для остальных уровней карты сайта
  • Режим вывода ошибок (error_reporting)
  • Распространять авторизацию на все домены
  • Сохранять исходные имена загружаемых файлов
  • Автоматически заменять невалидные символы в именах загружаемых файлов

Детальное описание настроек

Заголовок: | Позволять ли пользователям регистрироваться самостоятельно?
Идентификатор: | new_user_registration
Описание: | Если данный параметр установлен (равен "Y"), то в стандартных компонентах /main/auth/authorize.php, /main/auth/authorize_registration.php будет доступна ссылка "Регистрация".
По умолчанию: | Y
Заголовок: | При регистрации добавлять в группу.
Идентификатор: | new_user_registration_def_group
Описание: | В данном параметре можно указать группы к которым будет автоматически приписываться новый пользователь при его регистрации (при вызове функций CUser::Register, CUser::SimpleRegister).
По умолчанию: | 2 (группа Everyone)
Заголовок: | Разрешить запоминание авторизации.
Идентификатор: | store_password
Описание: | Если данный параметр установлен (равен "Y"), то авторизация пользователя будет сохраняться в его cookie файлах, при установке флага "Запомнить меня на этом компьютере" в момент авторизации. Данный параметр также используется в стандартных компонентах /main/auth/authorize.php, /main/auth/auth_form.php, /main/auth/authorize_registration.php для показа/скрытия флага "Запомнить меня на этом компьютере".
По умолчанию: | Y
Заголовок: | Использовать защищенное хранение авторизации в cookies
Идентификатор: | use_secure_password_cookies
Описание: | Если параметр "Разрешить запоминание авторизации" установлен (равен "Y"), то данный параметр будет управлять типом cookie переменной в которой будет храниться информация необходимая для авторизации. Если значение данного параметра равно "Y", то cookie авторизации будут устанавливаться с флагом secure, это означает что пользователь сможет автоматически авторизовываться на сайте только если он заходит на него по защищенному протоколу HTTPS.
По умолчанию: | N
Заголовок: | E-Mail адрес или список адресов через запятую на который будут дублироваться все исходящие сообщения.
Идентификатор: | all_bcc
Описание: | E-Mail адрес или список адресов через запятую на который будут дублироваться все исходящие сообщения.
По умолчанию: |
Заголовок: Отправлять в письме идентификаторы почтового события и шаблона.
Идентификатор: send_mid
Описание: Если данный параметр установлен (равен "Y"), то к телу письма снизу будет добавлено:
MID: EVENT_ID.TEMPLATE_ID (DATE_EVENT)
Где:
  • EVENT_ID - ID почтового события
  • TEMPLATE_ID - ID почтового шаблона
  • DATE_EVENT - дата создания почтового события
По умолчанию: N
Заголовок: | Дублировать E-Mail адрес в заголовок.
Идентификатор: | fill_to_mail
Описание: | Если данный параметр установлен (равен "Y"), то заголовок письма будет дополнительно продублировано поле "To".
По умолчанию: | N
Заголовок: | E-Mail администратора сайта (отправитель по умолчанию)
Идентификатор: | email_from
Описание: | В данном параметре как правило хранят EMail администратора сайта. Этот EMail будет доступен при редактировании почтовых шаблонов в поле #DEFAULT_EMAIL_FROM#.
По умолчанию: | "admin@".$_SERVER["SERVER_NAME"]
Заголовок: | Конвертировать символы новой строки Unix формата в Windows формат при отправке email
Идентификатор: | CONVERT_UNIX_NEWLINE_2_WINDOWS
Описание: | Если значение данного параметра "Y", то в теле сообщения все символы "новая строка" (\n) будут заменены парой символов "перевод каретки"+"новая строка" (\r\n). Зачастую это необходимо в ситуации, когда сайт был собран изначально на Unix хостинге (где во всех почтовых шаблонах в теле сообщения новая строка обозначалась символом \n), а затем перенесен на Windows хостинг (где новая строка обозначается уже парой символов \r\n). А так как в соответствии со стандартом RFC 2822 (стандарт формирования почтовых сообщений) в теле сообщения недопустимо использование по отдельности символов \n (или \r), то при разборе сообщения почтовым сервером могут быть ошибки. Зачастую символ "новая строка" обозначают как LF (line feed), а символ "перевод каретки" обозначают как CR (carriage return).
По умолчанию: | N (не конвертировать)
Заголовок: | Конвертировать 8-битные символы в заголовке письма.
Идентификатор: | convert_mail_header
Описание: | В соответствии с стандартом RFC 2822 в заголовке письма (в полях "To", "From", "Subject", "CC", "BCC" и т.п.) допустимо использование только символов с кодами от 33 (100001) до 126 (1111110) (это латинские символы, цифры, знаки препинания), данные символы называют 7-битными. Символы, коды которых лежат выше данного диапазона (начиная с кода 128), называют 8-ми и более битными символами, их использование в заголовках писем по стандарту RFC 2822 недопустимо и многие почтовые сервера не поддерживают 8-битные символы в заголовках писем в соответствии с этим стандартом. Поэтому, если вы например, используете кириллические символы (русские) в заголовке своих писем, то вам необходимо установить данный параметр в значение "Y", что позволит сконвертировать 8-битные символы в формат "MIME base64", используемый для передачи бинарных данных в системах не поддерживающих 8-битные символы.
По умолчанию: | Y (конвертировать)
Заголовок: | Название сайта.
Идентификатор: | site_name
Описание: | В данном параметре можно задать значение по умолчанию для названия сайта (поле "Название сайта" в настройках сайта). Использует как правило в почтовых шаблонах в поле #SITE_NAME#.
По умолчанию: | равен значению стандартной PHP переменной $_SERVER["SERVER_NAME"]
Заголовок: | URL сайта (без http://). Например: www.mysite.com
Идентификатор: | server_name
Описание: | В данном параметре можно задать значение по умолчанию для адреса сайта (поле "URL сервера" в настройках сайта). Использует как правило в почтовых шаблонах в поле #SERVER_NAME#.
По умолчанию: | равен значению стандартной PHP переменной $_SERVER["SERVER_NAME"]
Заголовок: | Имя сервера, содержащего обновления.
Идентификатор: | update_site
Описание: | URL сервера содержащего обновления.
По умолчанию: | www.bitrixsoft.ru
Заголовок: | Имя префикса для названия cookies
Идентификатор: | cookie_name
Описание: | Префикс имен cookie переменных устанавливаемых данным порталом.
По умолчанию: | BITRIX_SM
Заголовок: | Папка по умолчанию для загрузки файлов.
Идентификатор: | upload_dir
Описание: | Любой подкаталог каталога DocumentRoot в котором будут храниться все файлы загружаемые на сервер и сохраняемые функцией CFile::SaveFile. Данный параметр широко используется в функциях класса CFile. Под термином "загруженные файлы" понимаются как правило все файлы загружаемые через HTML формы, за исключением файлов которые могут быть загружены в любой каталог через меню "Структура сайта" -> "Управление" -> "Загрузить файл".
По умолчанию: | upload
Заголовок: | Посылать в заголовке статус 200 на 404 ошибку.
Идентификатор: | header_200
Описание: | Если данный параметр установлен (равен "Y"), то при возникновении 404 ошибки на сервере (страница не найдена) будет отсылаться статус 200 (страница найдена). Как правило данный параметр устанавливают для индексирующих роботов поисковых систем при создании каких либо сервисов на сайте на базе 404 ошибки. Например, для создания "красивых адресов" без параметров (например, /news/345.php), это также называют ЧПУ (человеко-понятные URL'ы).
По умолчанию: | Y
Заголовок: | Тип меню для нулевого уровня карты сайта.
Идентификатор: | map_top_menu_type
Описание: | Данный параметр используется стандартным компонентом /main/map/default.php выводящим карту сайта. В нем хранится тип меню с которого будет построен начальный уровень карты сайта.
По умолчанию: | top
Заголовок: | Тип меню для остальных уровней карты сайта.
Идентификатор: | map_left_menu_type
Описание: | Данный параметр используется стандартным компонентом /main/map/default.php выводящим карту сайта. В нем хранится тип меню с которого будет построены последующие уровни карты сайта (после начального уровня).
По умолчанию: | left
Заголовок: | Режим вывода ошибок (error_reporting)
Идентификатор: | error_reporting
Описание: | Данный параметр используется в служебной части пролога для установки уровня сообщений об ошибках (error) и предупреждениях (warning) PHP.
По умолчанию: | Только ошибки (E_COMPILE_ERROR|E_ERROR|E_CORE_ERROR|E_PARSE)
Заголовок: | Распространять авторизацию на все домены.
Идентификатор: | auth_multisite
Описание: | Если данный параметр установлен (равен "Y"), то авторизация пользователя (хранимая в cookie или текущая сессионная) будет распространяться на все домены всех сайтов портала.
По умолчанию: | N
Заголовок: | Сохранять исходные имена загружаемых файлов.
Идентификатор: | save_original_file_name
Описание: | Если данный параметр установлен (равен "Y"), то все имена всех загружаемых файлов будут сохранены в исходном виде. В противном случае, эти имена будут преобразованы в уникальные с помощью хэш функции MD5.
По умолчанию: | N
Заголовок: | Автоматически заменять невалидные символы в именах загружаемых файлов.
Идентификатор: | convert_original_file_name
Описание: | Если данный параметр установлен (равен "Y"), то в именах загружаемых файлов все невалидные символы не являющиеся символами латинского алфавита, цифрами, тире (-), подчеркиванием (_), точкой (.) будут преобразованы в произвольные валидные символы.
По умолчанию: | Y


Перенос сайта с локальной машины на удаленный хостинг

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

  1. Проверить:
    • соответствие удаленного хостинга, минимальным техническим требованиям продукта;
    • поддерживает ли удаленный хостинг Zend Optimizer версии не ниже 2.6.0 (необходимо только для демо версии продукта);
    • наличие прав не ниже (0644 – для файлов и 0744 для папок) на все файлы в корне сайта у пользователя, под которым работает Apache (PHP).
  2. Зайти в административный раздел копируемого сайта с правами администратора: "Рабочий стол > Настройки > Инструменты > Резервное копирование". Для полного копирования сайта с локальной машины на хостинг установите следующие параметры:
    • Архивировать по шагам: Да
    • Шаг архивации: установите в соответствие с настройками параметра max_execution_time в файле php.ini (по умолчанию 30 сек.)
    • Архивировать публичную часть: Да
    • Архивировать ядро: Да
    • Исключить из архива файлы размером более: 1024 кб (при этом в архив не попадут файлы, размер которых более 1 МБ)
    • Архивировать базу данных: Да
    При архивации базы данных можно значительно уменьшить объем файла резервной копии, исключив из него статистику и поисковый индекс.

  3. Установив необходимые параметры и нажмите кнопку Архивировать.
  4. После завершения операции резервного копирования, скачайте файл архива, а также файл restore.php.

  5. Далее при помощи протоколов ftp, ssh или другого доступного вам способа перенесите эти файлы на хостинг в корневую директорию веб-сервера.
  6. В адресной строке браузера наберите: http://www.ваш_сайт.ru/restore.php
  7. В открывшемся диалоговом окне выберете файл ранее скопированного архива, язык интерфейса и укажите время шага распаковки (устанавливается в соответствие с настройками php на хостинге – по умолчанию 30 сек.). Нажмите кнопку Распаковать.

  8. После завершения распаковки файлов, при переносе системы вместе с базой данных, необходимо указать настройки соединения с базой данных. Указав необходимые параметры, нажмите кнопку Восстановить.

    После успешной распаковки, во избежание повреждения вашего сайта или утечки информации, вам обязательно необходимо удалить следующие файлы:
    • /restore.php
    • /файл резервной копии (файл с расширением .tar.gz)
    • /bitrix/backup/дамп базы (файл с расширением .sql)
    Также, возможно, потребуется настройка параметров соединения с базой данных в файле /bitrix/php_interface/dbconn.php.


Введение

В данном разделе представлена общая информация по технологиям и принципам заложенным в систему:

  • Список терминов - определения основных терминов используемых в разделе "Главный модуль" руководства разработчика
  • Структура файлов - описание структуры файлов системы
  • Права доступа - описание идеалогии распределения прав доступа
  • Специальные константы - специальные константы используемые в системе
  • Специальные переменные - специальные переменные используемые в системе
  • Работа с датой и временем - примеры основных операций связанных в датой и временем
  • Навигационная цепочка - описание принципов работы с навигационной цепочкой
  • Меню - описание принципов работы с меню
  • Технологии - описание основных технологий реализованных в системе
  • Модули - описание принципов модульности и основных вопросов связанных с разработкой собственного модуля
  • Сайты - принципы многосайтовости
  • Языки - перевод скриптов системы на другие языки
  • Страницы - структура страницы
  • Компоненты - описание принципов работы с компонентами


Список терминов

  • Портал
  • Сайт
  • Шаблон сайта
  • Раздел сайта
  • Компонент 1.0
  • Компонент 2.0
  • Путь к компоненту
  • Включаемые области
  • Язык
  • Языковой файл
  • Шаблон страницы
  • Пролог
  • Эпилог
  • Тело страницы
  • Навигационная цепочка
  • Административная часть
  • Публичная часть
  • Режим редактирования сайта
  • Индексная страница (файл)
  • Мета-тэг
  • Локализация
  • Хост
  • Доменное имя (домен)
  • IP адрес
  • Accept-Language
  • Время в Unix-формате
  • Права в Unix системах
  • Путь относительно корня
  • Полный путь
  • Абсолютный путь
  • DocumentRoot
  • Сабмит
  • Сессия
  • HTML-безопасный вид
  • Связывание переменных
  • Дамп
  • cron (крон)
  • Буферизация
  • Постоянное соединение (persistent)
  • Почтовое событие
  • Тип почтового события
  • Почтовый шаблон
  • Бюджет пользователя

Термин | Описание
Портал | Один набор файлов хранящихся в каталоге /bitrix/modules/ и одна копия базы. Портал включает в себя один или более сайтов. Синонимом данного термина может служить: "экземпляр продукта", "одна инсталляция системы", "одна копия системы".
Сайт Совокупность таких понятий как:
  • учетная запись в базе данных - создаётся в административном меню "Сайты", включает в себя следующие основные параметры:
    • идентификатор - набор символов идентифицирующий сайт
    • доменное имя - одно или более доменное имя сайта
    • папка сайта - путь к каталогу в котором будет храниться публичная часть сайта
    • язык сайта
    • формат даты
    • формат времени
    • URL - протокол и доменное имя по умолчанию (например, "http://www.site.ru")
    • DocumentRoot - если многосайтовость организована по способу 2, то в данном параметре должен храниться путь в файловой системе сервера к корню сайта
    • условия подключения шаблонов - каждый сайт может иметь один или более шаблонов для отображения скриптов своей публичной части, каждый такой шаблон может быть подключен по тому или иному условию
  • публичная часть - совокупность скриптов (страниц) лежащих в "папке сайта" и принадлежащих этому сайту
  • настройки - каждый модуль может иметь ряд настроек связанных с сайтом, например, у модуля "Информационные блоки" эти настройки представляют из себя привязку информационного блока к тому или иному сайту, у модуля "Техподдержка" - привязку статуса, категории и т.п. к сайту.
Шаблон сайта Синонимом можно считать - "дизайн сайта", "скин сайта". Для показа одного сайта можно использовать несколько различных шаблонов. Строго говоря, в шаблон сайта входят:
  • учетная запись в базе данных - создаётся в административном меню "Шаблоны сайта"
  • набор файлов в каталоге /bitrix/templates/ID_шаблона/, где ID_шаблона - поле "ID" в форме редактирования шаблона сайта, ниже представлена структура данного каталога:
    • /ID модуля/ - каталог с компонентами 1.0, принадлежащими тому или иному модулю
    • /lang/ - языковые файлы принадлежащие как данному шаблону в целом, так и отдельным компонентам
    • /images/ - каталог с изображениями данного шаблона
    • /page_templates/ - каталог с шаблонами страниц и их описанием хранящимся в файле .content.php
    • /include_areas/ - каталог с файлами - содержимым включаемых областей;
    • header.php - пролог данного шаблона
    • footer.php - эпилог данного шаблона
    • styles.css - CSS стили, используемые на страницах сайта, когда используется данный шаблон
    • template_styles.css - CSS стили, используемые в самом шаблоне
    • .тип меню.menu_template.php - шаблон вывода меню соответствующего типа, если это версия 5.х
    • chain_template.php - шаблон по умолчанию для вывода навигационной цепочки (версия 5.х)
    • а также ряд других вспомогательных произвольных файлов, входящих в данный шаблон
Раздел сайта | Это ничто иное как каталог в файловой системе сервера. В "Битрикс: Управление сайтом" структура сайта - это файловая структура сервера, поэтому страницы сайта - это файлы, а разделы сайта - соответственно каталоги.
Компонент Является частью того или иного модуля, представляет из себя логически завершенный код, хранящийся в одном файле, принимающий ряд параметров, выполняющий ряд действий и выводящий какой либо результат (например, в виде HTML кода). Использование компонент является наиболее предпочтительным способом организации вывода информации как в публичной, так и в административной частях. В понятие "компонент" входят следующие элементы:
  • основной файл - подключается с помощью функции CMain::IncludeFile, представляет из себя скрипт на языке PHP реализующий логику компонента
  • языковые файлы - используются в компоненте для представления его результата на различных языках
  • описание - это PHP код используемый HTML редактором для визуального управления компонентом и его параметрами
Компонент 2.0 Компоненты являются блоками, с помощью которых строится публичная часть сайта.
Основные особенности компонентов версии 2.0:
  • В компонентах 2.0 могут быть разделены логика и представление. Для одной логики может быть несколько представлений, в том числе зависящих от шаблона текущего сайта.
    Логика - это сам компонент, представление - это шаблон вывода компонента.
  • Компоненты централизованно хранятся в одной папке. Это обеспечивает большую целостность и понятность структуры сайта. Папка доступна для обращений, а значит, компонент и его шаблоны могут легко подключать свои дополнительные ресурсы.
  • Компонент хранит все, что ему нужно для работы, в своей папке. Поэтому компоненты можно легко переносить между проектами. Компонент неделим.
  • Компоненты делятся на простые и комплексные. Простые служат для создания различных областей на одной странице (список новостей, топ элементов каталога, случайное фото и т.д.). А комплексные используются для создания полнофункциональных разделов сайта (полный каталог товаров, новостной раздел, форум и т.д.).
Путь к компоненту Используется в функции CMain::IncludeFile в качестве первого параметра и представляет из себя путь к основному файлу компонента относительно одного из следующих каталогов (в порядке убывания приоритета):
  • /bitrix/templates/ID шаблона сайта/
  • /bitrix/templates/.default/
  • /bitrix/modules/ID модуля/install/templates/
Где
ID шаблона сайта - идентификатор текущего шаблона сайта,
ID модуля - идентификатор модуля которому принадлежит компонент.
Включаемые области | Это произвольный текст (HTML код), являющийся частью содержимого страницы. С данным термином связана закладка "Редактировать сайт" на панели управления, при нажатии на которую, все включаемые области обрамляются рамкой с управляющими иконками в правом верхнем углу этой рамки.
Язык Это учетная запись в базе данных доступная для редактирования в административном меню "Языки" со следующими полями:
  • Идентификатор
  • Название
  • Формат даты
  • Формат времени
  • Кодировка
Как в публичной, так и административной частях, язык в первую очередь используется в работе с языковыми файлами.
В административной части язык определяет формат времени, даты, кодировку страниц (в публичной - данные параметры определяются настройками сайта).
Языковой файл Представляет из себя PHP скрипт, хранящий переводы языковых фраз на тот или иной язык. Данный скрипт состоит из массива $MESS, ключи которого - идентификаторы языковых фраз, а значения - переводы на соответстсвующий язык. Для каждого языка существует свой набор языковых файлов, хранящихся как правило в каталогах /lang/.
Языковые файлы как правило используются в административных скриптах модулей и в компонентах.
Для работы с языковыми файлами предназначен модуль "Перевод".
Шаблон страницы Это файл, хранящийся в одном из каталогов:
/bitrix/templates/ID шаблона сайта/page_templates/
/bitrix/templates/.default/page_templates/
Данный файл представляет из себя "заготовку" публичной страницы. Как правило используется при создании новой страницы в модуле "Управление структурой" (например, в HTML редакторе). Для задания порядка сортировки шаблонов страниц используется файл .content.php находящийся в одном из вышеуказанных каталогов.
Пролог

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

Для публичной части, пролог соответствующего шаблона сайта хранится в файле /bitrix/templates/ID шаблона сайта/header.php.

Для административной части - пролог храниться в файле /bitrix/modules/main/interface/prolog_admin.php.

В свою очередь пролог может быть разделен на служебную и визуальную части. В служебной части подключаются все необходимые классы, создаётся соединения с базой, создаются ряд служебных экземпляров объектов таких как $USER, $APPLICATION и т.д. В визуальной части выводится верхняя левая часть страницы.

Если в публичной части необходимо подключить неразделенный пролог, то используем следующий код:

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

Если по тем или иным причинам необходимо разделить пролог на служебную (prolog_before.php) и визуальную (prolog_after.php) части, то используем следующие коды:

require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/prolog_before.php");
...
require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/prolog_after.php");
Эпилог

В общем случае под данным термином понимается нижняя правая часть страницы.

Для публичной части, эпилог соответствующего шаблона сайта хранится в файле /bitrix/templates/ID шаблона сайта/footer.php.

Для административной части - эпилог храниться в файле /bitrix/modules/main/interface/epilog_admin.php.

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

Если в публичной части необходимо подключить неразделенный эпилог, то используем следующий код:

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");

Если по тем или иным причинам необходимо разделить эпилог на визуальную (epilog_before.php) и служебную (epilog_after.php) части, то используем следующие коды:

require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/epilog_before.php");
...
require($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/main/include/epilog_after.php");
Тело страницы | Тело страницы это часть PHP/HTML кода расположенного, в скрипте между подключениями пролога и эпилога. Тело страницы не является частью шаблона сайта и представляет из себя индивидуальное содержимое публичной либо административной страницы.
Навигационная цепочка Это элемент дизайна, предназначенный в первую очередь для улучшения навигации по сайту. Навигационная цепочка выводится как правило в визуальной части пролога и состоит из заголовков разделов сайта с соответствующими ссылками на них. Помимо заголовков разделов, добавляемых автоматически, вы также можете добавлять произвольные пункты в навигационную цепочку.
Административная часть Это множество скриптов в которых подключен административный пролог и эпилог. Их подключение подразумевает:
  • данная страница не принадлежит ни одному сайту
  • в тоже время она принадлежит какому-либо модулю
  • имеет строго определённый административный интерфейс
  • все параметры локализации данной страницы зависят от выбранного текущего языка
  • на этой странице используется дополнительная проверка прав, задаваемых в настройках соответствующего модуля
Публичная часть В общем случае, под данным термином понимается множество скриптов у которых подключен пролог и эпилог одного из шаблонов сайта. Их подключение подразумевает:
  • данная страница принадлежит какому либо сайту
  • имеет интерфейс текущего шаблона сайта
  • все параметры локализации данной страницы зависят от текущего сайта
Режим редактирования сайта | Режим, при котором текущая страница публичного раздела отображается в особом виде: выделены используемые компоненты, включаемые области, редактируемые области и т.д. Каждая такая область имеет набор кнопок для быстрого перехода к редактированию данного элемента страницы.
Индексная страница (файл) Это имя файла который будет использован веб-сервером в случае если запрашиваемый URL заканчивается на слэш и не содержит в себе имени файла. Порядок в котором будут искаться индексные страницы для различных веб-серверов задаются по разному, например:
  • Apache - в файле httpd.conf, параметр DirectoryIndex
  • IIS - в свойствах сайта, закладка "Documents" -> "Enable default content page"
К сожалению в PHP значение данного параметра недоступно, поэтому для определения индексной страницы в коде необходимо пользоваться функцией GetDirIndex.
Бюджет пользователя Синонимами данного термина можно считать "регистрация пользователя", "логин пользователя". Это запись в базе данных содержащая параметры зарегистрированного пользователя с такими обязательными полями как:
  • логин
  • пароль
  • E-Mail
А также ряд дополнительных полей содержащих личную информацию о пользователе, информацию по его работе, административные заметки.
Мета-тэг | Мета-тэг это один из элементов HTML позволяющий задать информацию о странице. Указать например, кодировку страницы, ее ключевые слова, автора, задать краткое описание страницы. Как правило содержимое мета-тэгов используется в служебных целях, например, роботами поисковых систем индексирующих сайт. Мета-тэг задается внутри тэга <head>.
Локализация | Подразумевает представление информации в переводе на соответстсвующий язык, в соответстсвующей кодировке данного языка и с использованием соответстсвующих форматов представления данных, характерных для этого языка (например, дата, время, денежных единицы, числа и т.д.).
Хост | В применении к функциям главного модуля, под данным термином понимается доменное имя или IP адрес посредством которого можно обратиться к тому или иному сайту.
Доменное имя (домен) Строго говоря, это одно из полей DNS таблицы (domain name service) содержащее в себе строго структурированное имя интернет сайта, заданное по определённым правилам. Основная задача DNS таблицы - это ассоциация доменных имен с IP адресами сайтов.
Пример доменного имени: www.bitrixsoft.ru
IP адрес Это "имя" компьютера в сети заданное по правилам протоколов TCP/IP. IP адрес состоит из четырех октетов часть из которых идентифицирует подсеть в которой находиться компьютер, а часть - непосредственно этот компьютер в рамках соответствующей подсети.
Пример IP адреса: 198.63.210.79 (этому адресу в DNS таблице соответствует доменное имя - www.bitrixsoft.ru)
Accept-Language Набор языков установленных в браузере посетителя сайта.
К примеру для MS Internet Explorer их можно выставить в меню "Tools" -> "Internet Options" -> "General" -> "Languages".
Для Mozilla Firefox: "Инструменты" -> "Настройки" -> "Основное" -> "Языки".
Время в Unix-формате | Количество секунд, прошедшее с 1 января 1970 года, с точностью до микросекунды. На сегодняшний день время в Unix-формате может фиксироваться только до 2038 года.
Права в Unix системах В Unix-подобных операционных системах (являющихся доминирующими на сегодняшний день для интернет серверов) поддерживаются три вида прав - чтение, запись и выполнение, которые присваиваются каждому файлу или директории. Права эти повторяются три раза: для владельца файла, для группы пользователей, к которой владелец принадлежит, и для всех остальных пользователей. Как правило права указываются в числовом формате:
  • 4 - чтение
  • 2 - запись
  • 1 - выполнение
Сумма этих чисел дает окончательный набор прав, например, 6 - это чтение и запись, но без выполнения, 7 - все права, 5 - чтение и выполнение.
Таким образом, например, право 764 будет означать: 7 - все права для владельца файла, 6 - чтение и запись для группы пользователей, к которой принадлежит владелец файла и 4 - чтение для всех остальных пользователей.
В PHP все права задаются в виде восьмиричных чисел, поэтому их надо задавать с обязательным указанием префикса - 0. Пример: 0755.
Путь относительно корня Путь к файлу начинающийся от каталога указанного в параметре DocumentRoot в настройках веб-сервера, заданный по правилам формирования URL-адресов.

Пример: /ru/about/index.php
Полный путь Включает в себя протокол, домен, порт и путь относительно корня к странице (каталогу).

Пример: http://www.bitrixsoft.ru/ru/about/index.php
Абсолютный путь | Абсолютный путь к файлу включает в себя DocumentRoot и путь относительно корня.
DocumentRoot Путь к корню сайта в файловой системе сервера. Задается в настройках веб-сервера, например:
  • для Apache - в файле httpd.conf, параметр DocumentRoot;
  • для IIS - в свойствах сайта, закладка "Home Directory" -> "Local Path".
Сабмит | Отправка данных HTML формы на сервер.
Сессия | Под данным термином понимается сессия PHP. Сессия может открываться в момент захода на сайт и закрывается при закрытии окна браузера. Также новая сессия открывается при авторизации пользователя, если закончить сеанс авторизации (разлогиниться) - сессия закрывается. Синонимом термина сессия можно считать один "заход на сайт".
HTML-безопасный вид Как правило данный термин применяют к тексту в котором произведены следующие замены:
Исходное | Результат
< | &lt;
> | &gt;
" | &quot;
& | &amp;

Подобные замены позволяют выводить текст внутри HTML кода, не опасаясь, что он будет интерпретирован браузером как часть этого HTML кода.
Связывание переменных | В применении к SQL-запросам для Oracle версии, под данным термином подразумевается связывание имен переменных (либо полей таблицы) с их значениями. Как правило подобная технология используется для полей типа BLOB, CLOB, LONG и т.п. предназначенных для хранения больших объемов данных.
Дамп В применении к базе данных, под данным термином подразумевается выгрузка содержимого и возможно структуры таблиц в файл в определённом формате, для их возможной дальнейшей загрузки обратно в данную, либо любую другую базу. Для каждой базы данных существуют свои утилиты позволяющие сделать дамп, например, для MySQL утилита mysqldump позволяет выгрузить в формате обычных SQL запросов, для Oracle утилита exp позволяет выгрузить в своем внутреннем формате.
В применении к переменным, дамп подразумевает отображение структуры и содержимого переменной в текстовом виде.
cron (крон) | В Unix-подобных операционных системах утилита cron позволяет организовать запуск скриптов по четко указанному расписанию.
Буферизация | Под термином "буферизация" в PHP понимается такой режим при котором весь исходящий поток данных из PHP скрипта (например, HTML код) запоминается предварительно в памяти и не отдается в "поток", т.е. не отсылается браузеру пользователя. Буферизацию в PHP можно включить с помощью функции ob_start. В дальнейшем буферизацию можно отключить, например, с использованием функции ob_end_flush, при этом все накопленные данные будут отосланы браузеру. Буферизация позволяет произвольно манипулировать исходящим потоком данных, на этом принципе основана технология отложенных функций.
Постоянное соединение (persistent) | При создании соединения с базой в памяти создаётся дескриптор данного соединения. Если соединение обычное, то после отработки скрипта это дескриптор удаляется, если соединение "постоянное" он остается и может быть использован другими процессами при необходимости. Достоинством "постоянного" соединения является то, что, как правило, времени на него требуется меньше, но в то же время есть недостаток - количество открытых "постоянных" соединений ограничивается в настройках базы данных и при превышении этого лимита посетитель не сможет зайти на сайт пока не освободятся новые соединения.
Почтовое событие Это почтовое сообщение, имеющее свой тип и отправляемое по соответствующему почтовому шаблону. Почтовое событие инициализирует поля типа почтового события конкретными значениями. Порядок расположения этих полей в письме, а также текст письма определяется почтовым шаблоном.
Для создания почтового события предназначен класс CEvent.

Используется в Почтовой системе.

Почтовый шаблон Определяет текст почтового сообщения, а также порядок расположения полей (placeholder'ов) заданных в типе почтового события.
Почтовые шаблоны доступны в административном меню "Настройки системы" -> "Почтовые шаблоны".
Для манипуляции почтовыми шаблонами предназначен класс CEventMessage.

Используется в Почтовой системе.

Тип почтового события Определяет набор специальных полей (placeholder'ов) которые могут быть использованы в почтовом шаблоне. В момент создания почтового события эти поля будут инициализированы конкретными значениями.
Для манипуляции типами почтовых событий предназначен класс CEventType.

Используется в Почтовой системе.


Структура файлов

Вся система целиком лежит в каталоге /bitrix/, в него входят следующие подкаталоги и файлы:

  • /admin/ - административные скрипты
  • /cache/ - файлы кэша
  • /help/ - система помощи
  • /images/ - изображения используемые как системой в целом, так и отдельными модулями
  • /modules/ - каталог с модулями системы, каждый подкаталог которого имеет свою строго определённую структуру
  • /php_interface/ - вспомогательный служебный каталог, в него входят следующие каталоги и файлы:
    • /include/ - подкаталог содержащий вспомогательные редактируемые скрипты различных модулей:
      • /catalog_export/ - скрипты экспорта принадлежащие модулю "Торговый каталог"
      • /statistic/ - обработчики CSV файлов содержащих события для загрузки в модуль "Статистика"
      • add_top_panel.php - файл подключаемый при выводе панели управления, в нем можно добавить произвольные кнопки для панели
    • dbconn.php - параметры соединения с базой
    • init.php - дополнительные параметры портала
    • after_connect.php - подключается сразу же после создания соединения с базой
    • dbconn_error.php - подключается при ошибке в момент создания соединения с базой
    • dbquery_error.php - подключается при ошибке в момент выполнения SQL запроса
    • /ID сайта/init.php - дополнительные параметры сайта; файл подключается сразу же после определения специальной константы c идентификатором сайта - SITE_ID
  • /templates/ - каталог с шаблонами сайтов и компонентами, в него входят следующие подкаталоги:
    • /.default/ - подкаталог с общими файлами используемыми тем или иным шаблоном по умолчанию, структура данного каталога аналогична нижеописанной структуре каталога содержащего конкретный шаблон
    • /ID шаблона сайта/ - подкаталог с шаблоном сайта, в него входят следующие подкаталоги и файлы:
      • /ID модуля/ - каталог с компонентами принадлежащими тому или иному модулю
      • /lang/ - языковые файлы принадлежащие как данному шаблону в целом, так и отдельным компонентам
      • /images/ - каталог с изображениями данного шаблона
      • /page_templates/ - каталог с шаблонами страниц и их описанием хранящимся в файле .content.php
      • header.php - пролог данного шаблона
      • footer.php - эпилог данного шаблона
      • styles.css - CSS стили шаблона
      • .тип меню.menu_template.php - шаблон вывода меню соответствующего типа
      • chain_template.php - шаблон по умолчанию для вывода навигационной цепочки
  • /tools/ - при инсталяции в этот каталог копируются дополнительные страницы, которые могут быть непосредственно использованы на любых страницах сайта: помощь, календарь, показ изображения и т.п.
  • /updates/ - каталог автоматически создаваемый системой обновлений
  • header.php - стандартный файл подключающий в свою очередь конкретный пролог текущего шаблона сайта; данный файл должен использоваться на всех страницах публичной части
  • footer.php - стандартный файл подключающий в свою очередь конкретный эпилог текущего шаблона сайта; данный файл должен использоваться на всех страницах публичной части
  • license_key.php - файл с лицензионным ключом
  • spread.php - файл используемый главным модулем для переноса куков посетителя на дополнительные домены различных сайтов
  • redirect.php - файл используемый модулем "Статистика" для фиксации событий перехода по ссылке
  • bx.php - файл по умолчанию используемый модулем "Реклама" для фиксации событий клика по баннеру
  • stop_redirect.php - файл используемый модулем "Статистика" для выдачи какого либо сообщения посетителю попавшему в стоп-лист
  • activity_limit.php - файл используемый модулем "Статистика" для выдачи сообщения роботу при превышении им лимита активности
  • rss.php - файл используемый модулем "Информационные блоки" для выдачи RSS контента

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


Права доступа

В системе "1С-Битрикс: Управление сайтом" поддерживается два уровня разграничения прав доступа:

  • Уровень 1. Доступ на файлы и каталоги.
  • Уровень 2. Права в рамках логики модуля.

Уровень 1. Доступ на файлы и каталоги.

Данный уровень прав проверяется в прологе, задается с помощью специального файла ".access.php", содержащего PHP массив следующего формата:

$PERM[файл/каталог][ID группы пользователей] = "ID права доступа";
Где
  • файл/каталог - имя файла или каталога для которых назначаются права доступа
  • ID группы пользователей - ID группы пользователей на которую распространяется данное право (допустимо также использование символа - "*", что означает - "для всех групп").
  • ID права доступа - на сегодняшний день поддерживаются следующие значения (в порядке возрастания):
    • D - запрещён (при обращении к файлу доступ будет всегда запрещён)
    • R - чтение (при обращении к файлу доступ будет разрешен)
    • U - документооборот (файл может быть отредактирован в режиме документооборота)
    • W - запись (файл может быть отредактирован непосредственно)
    • X - полный доступ (подразумевает право на "запись" и модификацию прав доступа)

В административной части сайта, при наличии модуля " >Управление структурой" права доступа можно назначать в специально предназначенной для этого форме (пункт меню "Структура сайта" > "Управление" > "Доступ").

Если пользователь принадлежит нескольким группам, то берется максимальное право из всех прав доступа заданных для этих групп.

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

Пример:

Файл /dir/.access.php

<?
   $PERM["index.php"]["2"] = "R";
   $PERM["index.php"]["3"] = "D";
?>

При попытке открытия страницы /dir/index.php пользователь принадлежащий группе ID=3 будет иметь право доступа D (запрещено), пользователь из группы ID=2 будет иметь право R (чтение). Пользователь, принадлежащий обоим группам будет иметь максимальный уровень доступа - R (чтение).

Пример:

Файл /.access.php

<?
   $PERM["admin"]["*"] = "D";
   $PERM["admin"]["1"] = "R";
   $PERM["/"]["*"] = "R";
   $PERM["/"]["1"] = "W";
?>

Файл /admin/.access.php

<?
   $PERM["index.php"]["3"] = "R";
?>

При доступе к странице /admin/index.php пользователь принадлежащий группе ID=3 будет иметь доступ, а пользователю принадлежащему группе ID=2 будет в доступе отказано. При доступе к странице /index.php все посетители будут иметь доступ.

Уровень 2. Права в рамках логики модуля.

Если речь идет об обычных статичных публичных страницах, то к ним применяется только уровень 1 доступа на файлы и каталоги.

Если пользователь имеет на файл как минимум право R ("чтение") и если данный файл является функциональной частью того или иного модуля, то проверяется 2-ой уровень прав задаваемый в настройках соответствующего модуля.

Пример:
При заходе на страницу "Список обращений" в техподдержке, администратор видит все обращения, сотрудник техподдержки - только те за которые ответственнен, а обычный пользователь - только свои обращения. Так работает право в рамках логики модуля "Техподдержка".

На сегодняшний день используются две методологии разграничения прав доступа 2-го уровня:

  • права
  • роли

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

Роли сейчас поддерживаются в двух модулях: " Техподдержка" и "Реклама". Во всех остальных модулях и везде используются права.

Пример:
  • Права. Если вы принадлежите группам для которых в модуле "Статистика" заданы права "Полный административный доступ" и например, "Просмотр статистики без финансовых показателей", то вы будете обладать максимальным правом - "Полный административный доступ".
  • Роли. Если вы принадлежите к группам для которых в модуле "Техподдержка" заданы роли "Клиент техподдержки" и "Демо-доступ", то вы одновременно будете обладать возможностями этих двух ролей. Т.е. вы сможете видеть все обращения в режиме демо-доступа и одновременно с этим можете создавать свои обращения как клиент техподдержки.


Специальные константы

  • SITE_ID
  • SITE_DIR
  • SITE_SERVER_NAME
  • SITE_CHARSET
  • FORMAT_DATE
  • FORMAT_DATETIME
  • LANGUAGE_ID
  • LANG_CHARSET
  • SITE_TEMPLATE_ID
  • START_EXEC_TIME
  • B_PROLOG_INCLUDED
  • SM_VERSION
  • SM_VERSION_DATE
  • ADMIN_SECTION
  • AUTH_404
  • HELP_FILE
  • NEED_AUTH
  • ERROR_EMAIL
  • LOG_FILENAME
  • STATISTIC_ONLY
  • NO_KEEP_STATISTIC
  • STOP_STATISTICS
  • NO_AGENT_STATISTIC
  • NOT_CHECK_PERMISSIONS
  • ONLY_EMAIL
  • BX_CRONTAB
  • BX_FILE_PERMISSIONS
  • BX_DIR_PERMISSIONS
  • SM_SAFE_MODE
  • DIRECTORY_INDEX
  • MYSQL_TABLE_TYPE
  • DBPersistent
  • BX_VALID_FILENAME_SYMBOLS
Имя константы | Тип | Описание
SITE_ID А
Т
И 		Идентификатор текущего сайта.
SITE_DIR | А | Поле "Папка сайта" в настройках сайта. Как правило используется в случае организации многосайтовости по способу 1.
SITE_SERVER_NAME | А | Поле "URL сервера" в настройках текущего сайта.
SITE_CHARSET | А | Поле "Кодировка" в настройках текущего сайта.
FORMAT_DATE | А | Для публичной части, в данной константе хранится формат даты из настроек текущего сайта. Для административной части - формат даты текущего языка.
FORMAT_DATETIME | А | Для публичной части, в данной константе хранится формат времени из настроек текущего сайта. Для административной части - формат времени текущего языка.
LANGUAGE_ID | А | Если это публичная часть, то в данной константе храниться поле "Язык" из настроек текущего сайта, если административная часть, то в данной константе храниться идентификатор текущего языка.
LANG_CHARSET | А | В данной константе содержится значение кодировки, указанной в секции Параметры формы настроек текущего сайта.
SITE_TEMPLATE_ID | А | Идентификатор текущего шаблона сайта.
START_EXEC_TIME | А | Содержит время начала работы страницы в формате возвращаемом функцией getmicrotime.
B_PROLOG_INCLUDED | А | Если подключена служебная часть пролога, то данная константа будет инициализирована значением "true". Как правило эту константу используют во включаемых файлах в целях безопасности, когда необходимо убедиться, что пролог подключен и все необходимые права проверены.
SM_VERSION | А | Текущая версия главного модуля.
SM_VERSION_DATE | А | Дата выпуска текущей версии главного модуля.
ADMIN_SECTION А
Т 		Если необходимо подключать пролог административной части, то значение данной константы - "true".
AUTH_404 Т

Данную константу необходимо инициализировать до пролога в файлах-обработчиках 404 ошибки (страница не найдена). Подобные файлы-обработчики задаются в настройках веб-сервера.

Инициализация этой константы позволяет в стандартных компонентах авторизации, регистрации, высылки забытого пароля, смены пароля поменять страницу на которую будет осуществляться сабмит соответствующей формы. Этой страницей по умолчанию является - текущая страница, если же константа инициализирована, то это будет - /SITE_DIR/auth.php.

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

Пример:
define("AUTH_404", "Y");
HELP_FILE Т Данная константа используется как правило в административных скриптах, для хранения имени файла контекстно-зависимой помощи, в случае если это имя отличается от имени данного скрипта. Ссылка на контекстно-зависимую помощь выводится в виде иконки на административной панели.
Пример:
define("HELP_FILE",
       "my_admin_script.php");
NEED_AUTH Т Если инициализировать данную константу значением "true" до подключения пролога, то будет проведена проверка на авторизованность пользователя. Если пользователь не авторизован, то ему будет предложена форма авторизации.

Пример:
define("NEED_AUTH", true);
ERROR_EMAIL Т
И 		Хранит E-Mail адрес (или группу адресов разделенных запятой), используемый функцией SendError для отправки сообщений об ошибках.

Пример:
define("ERROR_EMAIL",
       "admin@site.ru, support@site.ru");
LOG_FILENAME Т
И
С 		Хранит абсолютный путь к log-файлу, используемого функцией AddMessage2Log для записи ошибок или каких-либо сообщений.

Пример:
define("LOG_FILENAME",
       $_SERVER["DOCUMENT_ROOT"].
           "/log.txt");
STATISTIC_ONLY Т
И
С 		Как правило данная константа используется в редакции "Веб-Аналитика". Если ее не инициализировать, то в публичной части будет отсылаться HTTP заголовок:
Content-Type: text/html; charset=SITE_CHARSET

Пример:
define("STATISTIC_ONLY", true);
NO_KEEP_STATISTIC Т
И
С 		Если инициализировать данную константу каким либо значением, то это запретит сбор статистики на данной странице.

Пример:
define("NO_KEEP_STATISTIC", true);
STOP_STATISTICS Т
И
С 		Константа предназначена для отключения автоматического сбора статистики, реализованного как вызов функции CStatistics::Keep в качестве обработчика события OnBeforeProlog. Константу необходимо инициализировать до подключения пролога. Затем, при необходимости, можно использовать "ручной" сбор статистики, вызвав функцию CStatistics::Keep (с первым параметром, равным true).

Пример:
<?
// отключим автоматический
// сбор статистики
define("STOP_STATISTICS", true);
require($_SERVER["DOCUMENT_ROOT"].
        "/bitrix/header.php");

// включим сбор статистики
CStatistics::Keep(true);

...
NO_AGENT_STATISTIC Т
И
С 		Инициализация этой константы каким-либо значением приведет к запрету следующих действий модуля "Статистика", выполняемых ежедневно при помощи технологии агентов:
  • перевод на новый день;
  • очистка устаревших данных статистики;
  • отсылка ежедневного статистического отчета.
Пример:
define("NO_AGENT_STATISTIC", true);
NOT_CHECK_PERMISSIONS Т
И
С 		Если инициализировать данную константу значением "true" до подключения пролога, то это отключит проверку прав первого уровня.

Пример:
define("NOT_CHECK_PERMISSIONS", true);
ONLY_EMAIL Т
И
С 		Если на странице задана константа ONLY_EMAIL и email из настроек почтового шаблона с ее значением не совпадает, то письмо не отсылать. То есть отсылка письма будет происходить только в том случае если значение данной константы будет соответствовать адресу отправителя в настройках шаблона.

Пример:
define("ONLY_EMAIL", "admin@site.ru");
BX_CRONTAB Т
И
С 		Если данная константа инициализирована значением "true", то функция проверки агентов на запуск будет отбирать только те агенты для которых не критично количество их запусков (т.е. при добавлении этого агента параметр period=N). Как правило данная константа используется для организации запуска агентов на cron'е.

Пример:
define("NO_KEEP_STATISTIC", true);
BX_FILE_PERMISSIONS Т
И
С 		Unix-права для вновь создаваемых файлов.

Пример:
define("BX_FILE_PERMISSIONS", 0755);
BX_DIR_PERMISSIONS Т
И
С 		Unix-права для вновь создаваемых каталогов.

Пример:
define("BX_DIR_PERMISSIONS", 0755);
SM_SAFE_MODE Т
И
С 		Инициализация данной константы значением "true" позволит отключить все модули системы за исключением главного и модуля "Управление структурой".

Пример:
define("SM_SAFE_MODE", true);
DIRECTORY_INDEX Т
И
С 		Данная константа используется в функции GetDirIndex для определения индексного файла каталога.

Пример:
define("DIRECTORY_INDEX", "
    index.php
    index.html
    index.htm
    index.phtml
    default.html
    index.php3
");
MYSQL_TABLE_TYPE С Значение данной константы содержит тип таблиц создаваемый в MySQL по умолчанию: "MyISAM" или "InnoDB".

Пример:
define("MYSQL_TABLE_TYPE", "InnoDB");
DBPersistent С Если данная константа инициализирована значением "true", то будет создаваться постоянное соединение с базой.

Пример:
define("DBPersistent", true);
BX_VALID_FILENAME_SYMBOLS Т
А
С 		Определяет множество допустимых символов в имени загружаемых файлов в формате регулярных вырежений. Если установлена опция save_original_file_name (Сохранять исходные имена загружаемых файлов) и файл содержит недопустимые символы, то в зависимости от настроек опции convert_original_file_name (Автоматически заменять невалидные символы в именах загружаемых файлов) название файла будет переименовано или при загрузке файла будет выводится ошибка. По умолчанию: \x20-\x21\x2B-\x2E\x30-\x39\x41-\x5A\x5F\x61-\x7A\x7B\x7C\x7E.

Обозначения типов констант:

  • А (авто) - константа инициализируется системой в прологе автоматически
  • Т (страница) - константу можно определить на любой публичной странице до подключения пролога
  • И (инициализация) - константу можно определить в одном из следующих файлов:
    • /bitrix/php_interface/init.php - дополнительные параметры портала
    • /bitrix/php_interface/ID сайта/init.php - дополнительные параметры сайта
  • С (соединение с базой) - константу можно определить только в файле хранящим параметры соединения к базе: /bitrix/php_interface/dbconn.php


Специальные переменные

  • APPLICATION
  • USER
  • DB
  • DBType
  • DBHost
  • DBName
  • DBLogin
  • DBPassword
  • DBDebug
  • DBDebugToFile
  • clear_cache
  • clear_cache_session
  • compress
  • show_page_exec_time
  • show_include_exec_time
  • show_lang_files
  • no_keep_statistic_KEY
  • no_agent_statistic_KEY
  • key

Имя переменной | Тип | Описание
APPLICATION | Г | Глобальный объект класса CMain, предназначен для выполнения большинства общих стандартных операций (вывод заголовка, навигационной цепочки, меню и т.д.).
USER | Г | Глобальный объект класса CUser, хранит в себе данные авторизации текущего пользователя, предназначен для манипуляции параметрами текущего пользователя.
DB | Г | Глобальный объект класса CDataBase, предназначен для работы с базой данных.
DBType С Тип базы: "mysql" или "oracle".

Пример:
$DBType = "mysql";
DBHost С Для следующих типов базы данных:
  • MySQL - адрес сервера базы данных, например, - "localhost"
  • Oracle - не используется
Пример:
$DBHost = "localhost";
$DBHost = "localhost:3307";
DBName С Для следующих типов базы данных:
  • MySQL - имя базы
  • Oracle - строка соединения
Пример для MySQL:
$DBName = "bitrix";
Пример для Oracle:
$DBName = "
    (DESCRIPTION =
        (ADDRESS_LIST =
            (ADDRESS =
                (PROTOCOL = TCP)
                (HOST = 192.168.0.1)
                (PORT = 1521)
            )
        )
        (CONNECT_DATA =
            (SERVICE_NAME = BX)
        )
    )
";
DBLogin С Логин пользователя для доступа в базу данных.

Пример:
$DBLogin = "root";
DBPassword С Пароль пользователя для доступа в базу данных.

Пример:
$DBPassword = "123456";
DBDebug С
И 		Если данная переменная будет равна "true", то в случае ошибки при создании соединения с базой или в любом SQL запросе, сообщение об ошибке и полный текст этой ошибки будет отображаться в браузере. В противном случае - полный текст ошибки будет показан только администратору сайта.

Пример:
$DBDebug = true;
DBDebugToFile С
И 		Если данная переменная будет равна "true", то все SQL запросы к базе данных и время их выполнения будут записываться в лог-файл /mysql_debug.sql (или /oracle_debug.sql). Данная возможность используется как правило для получения данных о скорости выполнения SQL запросов к базе данных.

Ведение подобного лога может серьезно замедлить работу сайта, поэтому пользоваться этим стоит кратковременно.

Пример:
$DBDebugToFile = true;
clear_cache Т Если значение данной переменной - "Y", то это отключает кэширование на текущей странице.

Только для пользователей авторизованных с административными правами.

Пример:
http://www.site.ru/?clear_cache=Y
clear_cache_session Т Если значение данной переменной - "Y", то это отключает кэширование в рамках сессии. Для включения кэширования - достаточно один раз присвоить этой переменной значение "N".

Только для пользователей авторизованных с административными правами.

Пример:
http://site.ru/?clear_cache_session=Y
http://site.ru/?clear_cache_session=N
compress Т Если значение данной переменной - "Y", то внизу страницы в рамках сессии будет выведена рамка показывающая информацию по сжатию данной страницы модулем "Компрессия": размер страницы до сжатия, размер страницы после сжатия, коэфициент сжатия. Для отключения вывода данной информации - достаточно один раз присвоить этой переменной значение "N".

Пример:
http://www.site.ru/?compress=Y
http://www.site.ru/?compress=N
show_page_exec_time Т Если значение данной переменной - "Y", то внизу страницы будет выводиться время выполнения данной страницы на сервере. Данная информация будет выводиться в рамках сессии. Для отключения ее вывода - достаточно один раз присвоить этой переменной значение "N".

Данная переменная позволяет получить объективную информацию о скорости работы сайта.

Пример:
http://site.ru/?show_page_exec_time=Y
http://site.ru/?show_page_exec_time=N
show_include_exec_time Т Если значение данной переменной - "Y", то на странице будет показано время выполнения всех функций CMain::IncludeFile, подключающей как компоненты так и обычные файлы. Данная информация будет выводиться в рамках сессии. Для отключения ее вывода - достаточно один раз присвоить этой переменной значение "N".

Только для авторизованных пользователей с правами администратора сайта!

Пример:
http://site.ru/?show_include_exec_time=Y
http://site.ru/?show_include_exec_time=N
show_lang_files Т Если значение данной переменной - "Y", то внизу страницы будет выводиться список используемых на данной странице языковых файлов с возможностью поиска по ним. Данная информация будет выводиться в рамках сессии. Для отключения ее вывода - достаточно один раз присвоить этой переменной значение "N".

Данная переменная позволяет быстро найти ту или иную языковую фразу.

Пример:
http://www.site.ru/?show_lang_files=Y
http://www.site.ru/?show_lang_files=N
no_keep_statistic_KEY Т Если значение данной переменной - "Y", то это позволит отключить сбор статистики в рамках сессии. Для включения сбора статистики - достаточно один раз присвоить этой переменной значение "N". Как правило данную переменную используют для отключения сбора статистики в момент захода на сайт администратора.

KEY - лицензионный ключ хранимый в файле /bitrix/license_key.php

Пример:
http://site.ru/?no_keep_statistic_SM4-ML-PZDIO7TUMT3WP7H=Y
http://site.ru/?no_keep_statistic_SM4-ML-PZDIO7TUMT3WP7H=N
no_agent_statistic_KEY Т Если значение данной переменной - "Y", то это позволит отключить отработку агентов статистики в рамках сессии. Для включения отработки агентов в данной сесси - достаточно один раз присвоить этой переменной значение "N".

KEY - лицензионный ключ хранимый в файле /bitrix/license_key.php

Пример:
http://site.ru/?no_agent_statistic_SM4-ML-PZDIO7TUMT3WP7H=Y
http://site.ru/?no_agent_statistic_SM4-ML-PZDIO7TUMT3WP7H=N
key Данную переменную можно использовать только при вызове скрипта /bitrix/admin/phpinfo.php. Если ее значение будет равным лицензионному ключу, то вышеупомянутый скрипт отрабатает без подключения административного пролога.

Пример:
http://site.ru/bitrix/admin/phpinfo.php?key=SM4-ML-PZDIRTH

Обозначения типов переменных:

  • Г (глобальная) - переменная автоматически создаётся в служебной части пролога
  • С (соединение с базой) - переменную можно определить только в файле хранящим параметры соединения к базе: /bitrix/php_interface/dbconn.php
  • И (инициализация) - переменную можно определить в одном из следующих файлов:
    • /bitrix/php_interface/init.php - дополнительные параметры портала
    • /bitrix/php_interface/ID сайта/init.php - дополнительные параметры сайта
  • Т (страница) - переменную можно задать в параметрах страницы при открытии ее в браузере


Работа с датой и временем

Для работы с датой и временем используются следующие функции:

  • CDatabase::CharToDateFunction
  • CDatabase::DateToCharFunction
  • CDatabase::CurrentDateFunction
  • CDatabase::CurrentTimeFunction
  • CDataBase::DateFormatToPHP
  • CDataBase::FormatDate
  • ConvertDateTime
  • MakeTimeStamp
  • ConvertTimeStamp
  • CDataBase::IsDate
  • CDataBase::CompareDates
  • AddToTimeStamp
  • ParseDateTime
  • getmicrotime

При задании формата даты и времени используются следующие обозначения :

  • YYYY - год
  • MM - месяц
  • DD - день
  • HH - часы
  • MI - минуты
  • SS - секунды

Методы используемые в SQL запросах

  • CDatabase::CharToDateFunction - возвращает SQL код для преобразования строки во время формата базы данных.

    <?
$strSql = "
    SELECT
        ID
    FROM
        my_table
    WHERE
        DATE_CREATE <= ".$DB->CharToDateFunction("10.01.2003 23:59:59")."
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>

  • CDatabase::DateToCharFunction - возвращает SQL код для преобразования время из формата базы данных в строку.

    <?
$strSql = "
    SELECT
        ID,
        ".$DB->DateToCharFunction("DATE_CREATE")." DATE_CREATE
    FROM
        my_table
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>

  • CDatabase::CurrentDateFunction - возвращает SQL код для получения текущей даты.

    <?
$strSql = "
    SELECT
        ID
    FROM
        my_table
    WHERE
        DATE_CREATE<=".$DB->CurrentDateFunction()
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>

  • CDatabase::CurrentTimeFunction - возвращает SQL код для получения текущего времени в формате базы данных.

    <?
$strSql = "
    UPDATE my_table SET
         TIME_CHANGE=".$DB->CurrentTimeFunction()."
    WHERE
         ID=45
    ";
$Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
?>

Конвертация форматов

  • CDataBase::DateFormatToPHP - конвертирует формат допустимый в настройках сайта в формат принятый в PHP.

    <?
echo $DB->DateFormatToPHP("DD.MM.YYYY HH:MI:SS"); // d.m.Y H:i:s
?>

  • CDataBase::FormatDate - конвертирует время из строки одного формата в строку произвольного формата.

    <?
echo $DB->FormatDate("31.12.2005", "DD.MM.YYYY", "YYYY-MM-DD"); // 2005-12-31
?>

  • ConvertDateTime - конвертирует время из строки в формате сайта в строку произвольного формата.

    <?
echo ConvertDateTime("25.12.2003", "YYYY-MM-DD", "ru"); // 2003-12-25
?>

  • MakeTimeStamp - конвертирует время из строки в Unix-формат.

    <?
echo MakeTimeStamp("07.04.2005 11:32:00", "DD.MM.YYYY HH:MI:SS"); // 1112862720
?>

  • ConvertTimeStamp - конвертирует время из Unix-формата в строку в формате сайта.

    <?
echo ConvertTimeStamp(mktime(0, 0, 0, 10, 25, 2003), "SHORT", "ru"); // 25.10.2003
?>

Дополнительные функции

  • CDataBase::IsDate - проверяет дату заданную в виде строки на корректность.

    <?
echo $DB->IsDate("12.10.2005 22:34:15", "DD.MM.YYYY HH:MI:SS") ? "OK" : "ERROR"; // OK
echo $DB->IsDate("12.13.2005 22:34:15", "DD.MM.YYYY HH:MI:SS") ? "OK" : "ERROR"; // ERROR
echo $DB->IsDate("12.13..2005 ABS", "DD.MM.YYYY HH:MI:SS") ? "OK" : "ERROR"; // ERROR
?>

  • CDataBase::CompareDates - сравнивает между собой две даты заданные как строки.

    <?
echo $DB->CompareDates("01.01.2005", "01.01.2006"); // -1
echo $DB->CompareDates("01.01.2006", "01.01.2005"); // 1
echo $DB->CompareDates("01.01.2006", "01.01.2006"); // 0
?>

  • AddToTimeStamp - добавляет к дате в Unix-формате заданный интервал времени.

    <?
$stmp = MakeTimeStamp("07.04.2005 11:32:00", "DD.MM.YYYY HH:MI:SS");
$stmp = AddToTimeStamp(array("DD" => -1, "MM" => 1), $stmp); // 1115454720
echo date("d.m.Y H:i:s", $stmp); // 06.05.2005 11:32:00
?>

  • ParseDateTime - возвращает ассоциированный массив описывающий дату заданную в виде строки.

    <?
if ($arr = ParseDateTime("21.01.2004 23:44:15", "DD.MM.YYYY HH:MI:SS"))
{
    echo "День:    ".$arr["DD"]."<br>";    // День: 21
    echo "Месяц:   ".$arr["MM"]."<br>";    // Месяц: 1
    echo "Год:     ".$arr["YYYY"]."<br>";  // Год: 2004
    echo "Часы:    ".$arr["HH"]."<br>";    // Часы: 23
    echo "Минуты:  ".$arr["MI"]."<br>";    // Минуты: 44
    echo "Секунды: ".$arr["SS"]."<br>";    // Секунды: 15
}
else echo "Ошибка!";
?>

  • getmicrotime - возвращает текущее время в Unix-формате.

    <?
echo getmicrotime(); // 1115454720
?>


Навигационная цепочка

В этом разделе

  • Что это такое
  • Как задается
  • Вывод
  • Внешний вид
  • Примеры шаблонов
  • Дополнительные ссылки

    • Что это такое

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

    Как задается

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

    • $sSectionName - заголовок раздела;
    • $sChainTemplate - абсолютный путь к шаблону навигационной цепочки (данная переменная используется крайне редко)

    Пример файла .section.php:

    <?
$sSectionName = "О компании";
$sChainTemplate = $_SERVER["DOCUMENT_ROOT"]."/ru/about/chain_template.php";
?>

    Визуально задать заголовок раздела сайта вы можете с помощью модуля "Управление структурой" в административном меню "Структура сайта" > "Управление", зайдя в свойства того или иного раздела. Либо из публичной части сайта воспользовавшись панелью управления и кнопкой "редактирование свойств каталога".

    Помимо заголовков разделов сайта, добавляемых автоматически в навигационную цепочку, вы можете добавить произвольный пункт с помощью функции CMain::AddChainItem.

    Вывод цепочки навигации

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

    Внешний вид

    Для определения внешнего вида навигационной цепочки используется специальный PHP файл называемый "шаблоном навигационной цепочки". Путь к этому файлу вы можете задать явно при выводе навигационной цепочки, либо будет использован следующий алгоритм его поиска:

    1. Сбор пунктов навигационной цепочки ведется начиная от корня сайта и заканчивая текущим разделом. Для каждого очередного раздела подключается файл .section.php. Если в данном файле будет инициализирована переменная $sChainTemplate, то ее значение будет использовано в качестве пути к шаблону навигационной цепочки. В процессе перебора разделов, каждое последующее значение этой переменной перетирает предыдущее, таким образом, чем "глубже" раздел в иерархии разделов сайта, тем "важнее" его переменная $sChainTemplate.
    2. Если после сбора пунктов навигационной цепочки путь к шаблону не определён, то проверяется существование файла:
      /bitrix/templates/ID текущего шаблона сайта/chain_template.php
      Если такой файл существует, то путь к нему и принимается за путь к шаблону навигационной цепочки, в противном случае используется значение по умолчанию:
      /bitrix/templates/.default/chain_template.php

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

    Основными переменными используемыми в шаблоне являются:

    • $sChainProlog - HTML код выводимый перед навигационной цепочкой
    • $sChainBody - HTML код определяющий внешний вид одного пункта навигационной цепочки
    • $sChainEpilog - HTML код выводимый после навигационной цепочки
    • $strChain - HTML код всей навигационной цепочки собранный к моменту подключения шаблона
    Вышепредставленные переменные будут хранить в себе HTML код который определит внешний вид навигационной цепочки.

    Также в шаблоне будут доступны следующие дополнительные переменные:

    • $TITLE - заголовок очередного пункта навигационной цепочки
    • $LINK - ссылка на очередном пункте навигационной цепочки
    • $arCHAIN - копия массива элементов навигационной цепочки
    • $arCHAIN_LINK - ссылка на массив элементов навигационной цепочки
    • $ITEM_COUNT - количество элементов массива навигационной цепочки
    • $ITEM_INDEX - порядковый номр очередного пункта навигационной цепочки

    Примеры шаблонов

    <?
// простейший шаблон выводящий стандартную цепочку

// HTML код выводимый перед навигационной цепочкой
$sChainProlog = "";

// HTML код определяющий внешний вид одного пункта навигационной цепочки
$sChainBody = "";
if (strlen($LINK)>0)
    $sChainBody .= "<a href=\"".$LINK."\" class='chainitem'>".$TITLE."</a>";
else
    $sChainBody .= "<font class='chainitem'>".$TITLE."</font>";

// HTML код выводимый после навигационной цепочки
$sChainEpilog = "";
?>
    <?
// шаблон выводящий инвертированную навигационную цепочку без ссылок
// может быть использован например, в тэге <title>
// для повышения качества индексации сайта поисковыми системами

$sChainEpilog = "";

// если массив пунктов цепочки определён то
if (is_array($arCHAIN))
{
    // пройдемся по пунктам цепочки
    reset($arCHAIN);
    foreach($arCHAIN as $item)
    {
        // если это первый пункт то
        if (strlen($sChainEpilog)<=0)
            $sChainEpilog = $item["TITLE"];
        else // иначе
            $sChainEpilog = $item["TITLE"]." :: ".$sChainEpilog;
    }
}
?>

    Дополнительные ссылки

    • CMain::ShowNavChain
    • CMain::AddChainItem
    • CMain::GetNavChain


Меню (версия 5.х)

В этом разделе

  • Что это такое
  • Файлы меню
  • Примеры файлов меню
  • Вывод меню
  • Примеры вывода меню
  • Шаблон меню
  • Активность пункта меню
  • Примеры шаблонов меню
  • Дополнительные ссылки

    • Что это такое

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

    разделу сайта с помощью служебного PHP файла с именем .тип меню.menu.php. Данный файл располагается в соответствующем разделе сайта. В нем могут использоваться следующие стандартные переменные:

    • $sMenuTemplate - абсолютный путь к шаблону меню (данная переменная используется крайне редко)
    • $aMenuLinks - массив, каждый элемент которого описывает очередной пункт меню. Структура данного массива:

      Array
      (
          [0] => пункт меню 1
              Array
                  (
                      [0] => заголовок пункта меню
                      [1] => ссылка на пункте меню
                      [2] => массив дополнительных ссылок для подсветки пункта меню:
                          Array
                              (
                                  [0] => ссылка 1
                                  [1] => ссылка 2
                                  ...
                               )
                      [3] => массив дополнительных переменных передаваемых в шаблон меню:
                          Array
                              (
                                  [имя переменной 1] => значение переменной 1
                                  [имя переменной 2] => значение переменной 2
                                  ...
                               )
                      [4] => условие, при котором пункт меню появляется
                             это PHP выражение, которое должно вернуть "true"
                  )
          [1] => пункт меню 2
          [2] => пункт меню 3
          ...
      )

    Визуально управлять пунктами меню вы можете с помощью модуля "Управление структурой". В административном меню "Структура сайта" -> "Управление" необходимо будет выбрать нужный вам каталог, затем кликнуть по ссылке "Добавить меню" и выбрать нужный вам тип меню, при этом вам будет доступно два режима модификации меню: "упрощённый" и "расширенный".

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

    Иногда возникает задача когда нужно задать пункты меню программно (например, когда вы хотите вывести в меню разделы каталога хранящегося в модуле "Информационные блоки"). Для этого необходимо использовать служебные файлы с именем .тип меню.menu_ext.php. Эти файлы необходимо располагать в интересующем вас разделе сайта. Основная задача подобных файлов - это манипуляция массивом $aMenuLinks. Данные файлы не редактируются визуально в модуле "Управление структурой", поэтому они не смогут быть случайно перетерты при визуальном редактировании меню.

    Если вы планируете использовать файлы .тип меню.menu_ext.php, то при выводе меню с помощью функций CMain::GetMenuHtml, CMain::GetMenuHtmlEx, обратите внимание на необходимость установки второго параметра этих функцией в значение "true" (по умолчанию этот параметр равен "false").

    Если в текущем разделе сайта меню явно не задано (т.е. в этом каталоге отсутствует файл меню), то будет использовано меню первого вышестоящего раздела в котором это меню будет обнаружено, т.е. меню является иерархически наследуемым.
    К примеру посетитель находится в разделе /ru/company/about/. Для показа меню типа left файл меню будет искаться в следующей последовательности:
    1. /ru/company/about/.left.menu.php
    2. /ru/company/.left.menu.php
    3. /.left.menu.php
    Если в одном из каталогов будет найдено меню, то поиск останавливается и в последующих каталогах уже не ищется.

    Примеры файлов меню

    <?
    // пример файла .left.menu.php

    $aMenuLinks = Array(
        Array(
            "Телефоны",
            "/catalog/phone/",
            Array("/catalog/phone/index.php", "/catalog/phone/compare.php"),
            Array(),
            ""
        ),
        Array(
            "Аксессуары",
            "/catalog/accessory/",
            Array("/catalog/accessory/index.php"),
            Array(),
            ""
        ),
        Array(
            "Только для администраторов",
            "/catalog/admin/",
            Array("/catalog/admin/index.php", "/catalog/admin/edit.php"),
            Array("PARAM_1" => "Y"),
            "\$GLOBALS["USER"]->IsAdmin()"
        )
    );
    ?>
    <?
    // пример файла .left.menu_ext.php

    if (CModule::IncludeModule("iblock")):

        $CACHE_TIME = "0";
        $IBLOCK_TYPE = "catalog";   // тип инфо-блока
        $IBLOCK_ID = 22;            // ID инфо-блока
        $CACHE_TIME = 86400;        // время кэширования

        $aMenuLinksNew = array();
        $ROOT_SECTION_ID = 0;
        $CACHE_ID = __FILE__.$IBLOCK_ID;
        $obMenuCache = new CPHPCache;
        if($_GET["SECTION_ID"]>0)
            $CACHE_ADD .= "|SECTION_ID=".$_GET["SECTION_ID"];
        elseif($_GET["ID"]>0)
            $CACHE_ADD .= "|ELEMENT_ID=".$_GET["ID"];
        else
            $CACHE_ADD = "";

        // если массив закэширован то
        if($obMenuCache->InitCache($CACHE_TIME, $CACHE_ID.$CACHE_ADD, "/"))
        {
            // берем данные из кэша
            $arVars = $obMenuCache->GetVars();
            $aMenuLinksNew = $arVars["aMenuLinksNew"];
        }
        else
        {
            $CACHE_ADD = "";
            if($_GET["SECTION_ID"]>0)
            {
                $res = CIBlockSection::GetNavChain($IBLOCK_ID, $_GET["SECTION_ID"]);
                if($ar_res = $res->Fetch())
                {
                    $ROOT_SECTION_ID = $ar_res["ID"];
                    $CACHE_ADD = "|SECTION_ID=".$_GET["SECTION_ID"];
                }
            }
            elseif($_GET["ID"]>0)
            {
                $res = CIBlockElement::GetElementGroups($_GET["ID"]);
                if($ar_res = $res->Fetch())
                {
                    $CACHE_ADD = "|ELEMENT_ID=".$_GET["ID"];
                    $res = CIBlockSection::GetNavChain(
                        $IBLOCK_ID,
                        $ar_res["IBLOCK_SECTION_ID"]
                        );
                    $ar_res = $res->Fetch();
                    $ROOT_SECTION_ID = $ar_res["ID"];
                }
            }

            // иначе собираем разделы
            $rsSections = GetIBlockSectionList(
                $IBLOCK_ID,
                0,
                array("SORT" => "ASC", "ID" => "ASC"),
                false,
                array("ACTIVE"=>"Y")
                );
            while ($arSection = $rsSections->Fetch())
            {
                $aMenuLinksNew[] = array(
                    $arSection["NAME"],
                    SITE_DIR."catalog/accessory/section.php?SECTION_ID=".$arSection["ID"],
                    ($ROOT_SECTION_ID==$arSection["ID"] ? Array("/") : Array())
                );
            }
        }
        // сохраняем данные в кэше
        if($obMenuCache->StartDataCache($CACHE_TIME, $CACHE_ID.$CACHE_ADD, "/"))
        {
            $obMenuCache->EndDataCache(Array("aMenuLinksNew" => $aMenuLinksNew));
        }

        $aMenuLinks = array_merge($aMenuLinksNew, $aMenuLinks);
    endif;
    ?>

    Вывод меню

    Вывод меню осуществляется в визуальной части пролога, либо эпилога. Существует два принципиально разных способа вывода меню:

    • Способ 1. Шаблон меню подключается только один раз для всех пунктов меню. Для вывода меню этим способом используются функции:
      • CMain::GetMenuHtmlEx
      • CMenu::GetMenuHtmlEx (для использования этой функции необходимо предварительно инициализировать соответстсвующий объект класса CMenu)
    • Способ 2. Шаблон меню подключается на каждый пункт меню. Для вывода меню этим способом используются функции:
      • CMain::GetMenuHtml
      • CMenu::GetMenuHtml (для использования этой функции необходимо предварительно инициализировать соответстсвующий объект класса CMenu)

    Примеры вывода меню

    <?
    // выведем меню типа "top"
    echo $APPLICATION->GetMenuHtmlEx("top");
    ?>
    <?
    // выведем меню типа "left" с поддержкой файлов .тип меню.menu_ext.php
    echo $APPLICATION->GetMenuHtml("left", true);
    ?>
    <?
    // выводим меню типа "left"
    // с поддержкой файлов .тип меню.menu_ext.php
    // с четким указанием шаблона и
    // каталога для которого будет построено меню

    $obMenu = $APPLICATION->GetMenu(
        "left",
        true,
        "/bitrix/php_interface/".SITE_ID."/left.menu_template.php",
        SITE_DIR
        );
    echo $obMenu->GetMenuHtml();
    ?>

    Шаблон меню

    Внешний вид меню определяется шаблоном. Шаблон представляет из себя PHP файл. Путь к этому файлу вы можете задать явно в момент вывода меню, либо будет использован следующий алгоритм его поиска:

    1. Как было упомянуто выше, меню является иерархически наследуемым. Т.е. если в текущем разделе сайта меню явно не задано (т.е. в этом каталоге отсутствует файл меню), то будет использовано меню первого вышестоящего раздела в котором это меню будет обнаружено.

      К примеру посетитель находится в разделе /ru/company/about/. Для показа меню типа left файл меню будет искаться в следующей последовательности:
      1. /ru/company/about/.left.menu.php
      2. /ru/company/.left.menu.php
      3. /.left.menu.php
      Если в одном из каталогов будет найдено меню, то поиск останавливается и в последующих каталогах уже не ищется.

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

    2. Если в процессе поиска файла меню путь к шаблону меню не был определён, то проверяется существование файла:
      /bitrix/templates/ID текущего шаблона сайта/.тип меню.menu.php
      Если такой файл существует, то путь к нему и принимается за путь к шаблону меню, в противном случае используется значение по умолчанию:
      /bitrix/templates/.default/.тип меню.menu.php

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

    • При использовании способа 1 в шаблоне доступны:
      • $sMenu - HTML определяющий внешний вид всего меню
      • $arMENU_LINK - ссылка на исходный массив пунктов меню (синоним - $MENU_ITEMS)
      • $arMENU - копия массива пунктов меню, в котором каждый пункт меню в свою очередь представляет из себя массив, использующий следующие ключи:
        • TEXT - заголовок пункта меню
        • LINK - ссылка на пункте меню
        • SELECTED - активен ли пункт меню в данный момент, возможны следующие значения:
          • true - пункт меню выбран
          • false - пункт меню не выбран
        • PERMISSION - право доступа на страницу указанную в LINK для текущего пользователя, возможны следующие значения:
          • D - доступ запрещён
          • R - чтение (право просмотра содержимого файла)
          • U - документооборот (право на редактирование файла в режиме документооборота)
          • W - запись (право на прямое редактирование)
          • X - полный доступ (право на прямое редактирование файла и право на изменение прав доступа на данный файл)
        • ADDITIONAL_LINKS - массив дополнительных ссылок для подсветки меню
        • ITEM_TYPE - флаг указывающий на тип ссылки указанной в LINK, возможны следующие значения:
          • D - каталог (LINK заканчивается на "/")
          • P - страница
          • U - страница с параметрами
        • ITEM_INDEX - порядковый номер пункта меню
        • PARAMS - ассоциативный массив параметров пунктов меню
    • При использовании способа 2 в шаблоне доступны:
      • $sMenuProlog - HTML который будет добавлен перед меню
      • $sMenuEpilog - HTML который будет добавлен после меню
      • $sMenuBody - HTML определяющий внешний вид одного пункта меню
      • $arMENU_LINK - ссылка на исходный массив пунктов меню (синоним - $MENU_ITEMS)
      • $arMENU - копия массива пунктов меню (структура данного массива соответстсвует вышеописанной)
      • $TEXT - заголовок пункта меню
      • $LINK - ссылка на пункте меню
      • $SELECTED - активен ли пункт меню в данный момент, возможны следующие значения:
        • true - пункт меню выбран
        • false - пункт меню не выбран
      • $PERMISSION - право доступа на страницу указанную в $LINK для текущего пользователя, возможны следующие значения:
        • D - доступ запрещён
        • R - чтение (право просмотра содержимого файла)
        • U - документооборот (право на редактирование файла в режиме документооборота)
        • W - запись (право на прямое редактирование)
        • X - полный доступ (право на прямое редактирование файла и право на изменение прав доступа на данный файл)
      • $ADDITIONAL_LINKS - массив дополнительных ссылок для подсветки меню
      • $ITEM_TYPE - флаг указывающий на тип ссылки указанной в $LINK, возможны следующие значения:
        • D - каталог ($LINK заканчивается на "/")
        • P - страница
        • U - страница с параметрами
      • $ITEM_INDEX - порядковый номер пункта меню
      • $PARAMS - ассоциативный массив параметров пунктов меню

    Активность пункта меню

    На основе ссылки на пункте меню ($LINK) и массива дополнительных ссылок ($ADDITIONAL_LINKS) будет определяться какой пункт меню активен (выделен, подсвечен). Если пункт меню активен, то в шаблоне меню будет доступна переменная $SELECTED=true.

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

    • Ссылка на каталог ($ITEM_TYPE=D). Такие ссылки всегда заканчивается символом "/". Ссылки этого типа будут подсвечены если посетитель находится внутри каталога на любой странице, с любыми параметрами.
    • Ссылка на страницу ($ITEM_TYPE=P). Такие ссылки всегда заканчиваются именем файла страницы. Эти ссылки подсвечиваются когда посетитель находится на данной странице с любыми параметрами.
    • Ссылка на страницу с параметрами ($ITEM_TYPE=L). Такие ссылки заканчиваются именем файла страницы, знаком "?" и парами переменная=значение разделенные через знак &. Эти ссылки подсвечиваются только, когда посетитель находится на данной странице и определённые в параметрах переменные имеют соответствующее значение (порядок не имеет значения).

    Ниже представлен пример активности пункта меню (символ "X") при различных комбинациях текущей страницы и ссылки на пункте меню:

    Текущая страница | Ссылка на пункте меню
 | /dir/ | /dir/index.php | /dir/index.php?par1=val1
/dir/page.php | X |  |
/dir/index.php | X | X |
/dir/index.php?par1=val1 | X | X | X
/dir/index.php?par1=val2 | X | X |

    Ссылка на пункте меню может быть как абсолютная, так и относительная. Если ссылка относительная, то она всегда считается относительно того каталога в которой находится данный файл меню.

    Например, при следующих условиях:

    • файл меню находится в каталоге /dir/ и один из пунктов меню определён относительной ссылкой index.php
    • пользователь находится на странице /dir/subdir/index.php
    • при этом, в подкаталоге /dir/subdir/ нет своего файла меню, иначе отображался бы он (см. подробнее "Файлы меню")
    При этих уловиях данный пункт меню не будет подсвечиваться, т.к. он будет предварительно переведен в абсолютный вид - /dir/index.php относительно того каталога где находится содержащий его файл меню. Соответственно и ссылка в меню будет указывать на страницу по этому абсолютному меню.

    Примеры шаблонов меню

    Файл шаблона меню .left.menu_template.php используемого при выводе меню по способу 1 с использованием функции CMain::GetMenuHtmlEx:

    <?
    if (is_array($arMENU) && count($arMENU)>0)
    {
        $sMenu = "<table border='0' cellpadding='0' cellspacing='0' width='100%'>";

        foreach($arMENU as $arMENU_ITEM)
        {
            extract($arMENU_ITEM);

            // если ссылка на пункте меню указывает на каталог то
            if ($ITEM_TYPE=="D")
            {
                // если пункт меню активен то
                if ($SELECTED)
                    $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_folder_open.gif' width='17' border='0'></td>";
                else // иначе
                    $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_folder.gif' width='17' border='0'></td>";
            }
            else // иначе
            {
                // если пункт меню активен то
                if ($SELECTED)
                {
                    $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet.gif' width='17' border='0'></td>";
                    $strDir_d = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet_d.gif' width='17' border='0'></td>";
                }
                else // иначе
                {
                    $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet.gif' width='17' border='0'></td>";
                    $strDir_d = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet_d.gif' width='17' border='0'></td>";
                }
            }

            // если пункт меню активен то
            if ($SELECTED)
                $strtext = "leftmenuact";
            else
                $strtext = "leftmenu";

            // если параметр SEPARATOR=Y, то
            if ($PARAMS["SEPARATOR"]=="Y")
            {
                // пункт меню показывается по другому
                $strstyle = " style='background-color: #D5ECE6; border-top: 1px solid #A6D0D7; border-bottom: 1px solid #A6D0D7; padding:8;'";
                $strDir = "<img height='13' src='/bitrix/templates/demo/images/1.gif' width='17' border='0'>";
                $strtext = "leftmenu";
            }
            else
                $strstyle = " style='padding:8;'";

            // если есть доступ на страницу на которую указывает пункт меню то
            if ($PERMISSION > "D")
            {
                $sMenu .= '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr><tr>'.$strDir.'<td valign="top"'.$strstyle.' width="100%"><a href="'.$LINK.'" class="'.$strtext.'">'.$TEXT.'</a></td></tr>';
            }
            else // иначе
            {
                $sMenu .= '<td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr><tr>'.$strDir_d.'</td><td valign="top"'.$strstyle.' width="100%"><a href="'.$LINK.'" class='.$strtext.'>'.$TEXT.'</a></td></tr>';

            }
        }

        $sMenu .= '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr></table>';
    }
    ?>

    Аналогичный файл шаблона меню .left.menu_template.php,
    но используемого при выводе меню по способу 2 с использованием функции CMain::GetMenuHtml:

    <?
    $sMenuProlog = "<table border='0' cellpadding='0' cellspacing='0' width='100%'>";

    // если ссылка на пункте меню указывает на каталог то
    if ($ITEM_TYPE=="D")
    {
        // если пункт меню активен то
        if ($SELECTED)
            $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_folder_open.gif' width='17' border='0'></td>";
        else // иначе
            $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_folder.gif' width='17' border='0'></td>";
    }
    else // иначе
    {
        // если пункт меню активен то
        if ($SELECTED)
        {
            $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet.gif' width='17' border='0'></td>";
            $strDir_d = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet_d.gif' width='17' border='0'></td>";
        }
        else // иначе
        {
            $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet.gif' width='17' border='0'></td>";
            $strDir_d = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet_d.gif' width='17' border='0'></td>";
        }
    }

    // если пункт меню активен то
    if ($SELECTED)
        $strtext = "leftmenuact";
    else
        $strtext = "leftmenu";

    // если параметр SEPARATOR=Y, то
    if ($PARAMS["SEPARATOR"]=="Y")
    {
        // пункт меню показывается по другому
        $strstyle = " style='background-color: #D5ECE6; border-top: 1px solid #A6D0D7; border-bottom: 1px solid #A6D0D7; padding:8;'";
        $strDir = "<img height='13' src='/bitrix/templates/demo/images/1.gif' width='17' border='0'>";
        $strtext = "leftmenu";
    }
    else
        $strstyle = " style='padding:8;'";

    // если есть доступ на страницу на которую указывает пункт меню то
    if ($PERMISSION > "D")
    {
        $sMenuBody = '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr><tr>'.$strDir.'<td valign="top"'.$strstyle.' width="100%"><a href="'.$LINK.'" class="'.$strtext.'">'.$TEXT.'</a></td></tr>';
    }
    else // иначе
    {
        $sMenuBody = '<td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr><tr>'.$strDir_d.'</td><td valign="top"'.$strstyle.' width="100%"><a href="'.$LINK.'" class='.$strtext.'>'.$TEXT.'</a></td></tr>';

    }

    $sMenuEpilog = '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr></table>';
    ?>

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


Меню

В этом разделе

  • Что это такое
  • Файлы меню
  • Примеры файлов меню
  • Вывод меню
  • Примеры вывода меню
  • Шаблон меню
  • Пример шаблона меню

    • Что это такое

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

    Файлы меню

    Меню привязывается к разделу сайта с помощью служебного PHP файла с именем .тип меню.menu.php. Данный файл располагается в соответствующем разделе сайта. В нем могут использоваться следующие стандартные переменные:

    • $sMenuTemplate - абсолютный путь к шаблону меню (данная переменная используется крайне редко)
    • $aMenuLinks - массив, каждый элемент которого описывает очередной пункт меню. Структура данного массива:

      Array
      (
          [0] => пункт меню 1
              Array
                  (
                      [0] => заголовок пункта меню
                      [1] => ссылка на пункте меню
                      [2] => массив дополнительных ссылок для подсветки пункта меню:
                          Array
                              (
                                  [0] => ссылка 1
                                  [1] => ссылка 2
                                  ...
                               )
                      [3] => массив дополнительных переменных передаваемых в шаблон меню:
                          Array
                              (
                                  [имя переменной 1] => значение переменной 1
                                  [имя переменной 2] => значение переменной 2
                                  ...
                               )
                      [4] => условие, при котором пункт меню появляется
                             это PHP выражение, которое должно вернуть "true"
                  )
          [1] => пункт меню 2
          [2] => пункт меню 3
          ...
      )

    Визуально управлять пунктами меню вы можете с помощью модуля "Управление структурой".

    Для создания файла .тип меню.menu.php выполните следующие действия:

    • В административном разделе выберите пункт Контент -> Структура сайта -> Файлы и папки (либо название одного из сайтов системы).
    • Далее выберите нужный каталог и кликните по кнопке [image] контекстной панели.
    • В открывшейся форме можно выбрать тип меню, ввести пункты меню и установить другие параметры.
    • При этом вам будет доступно два режима модификации меню: "упрощённый" и "расширенный", переключение между которыми производится с помощью кнопок контекстной панели.

    Данный процесс можно упростить, воспользовавшись в публичной части сайта панелью управления.

    • Перейдите на закладку [image] ;
    • Воспользуйтесь кнопкой "Редактировать пункты меню" рядом с интересующим вас меню:

    Иногда возникает задача, когда нужно задать пункты меню программно (например, когда вы хотите вывести в меню разделы каталога хранящегося в модуле "Информационные блоки"). Для этого необходимо использовать служебные файлы с именем .тип меню.menu_ext.php. Эти файлы необходимо располагать в том разделе сайта, где вы хотите вывести это меню. Основная задача подобных файлов - это манипуляция массивом $aMenuLinks. Данные файлы не редактируются визуально в модуле "Управление структурой", поэтому они не смогут быть случайно перетерты при визуальном редактировании меню. При создании этого файла используйте компонент 2.0 Пункты меню (bitrix:menu.sections) [image].

    Если в текущем разделе сайта меню явно не задано (т.е. в этом каталоге отсутствует файл меню), то будет использовано меню первого вышестоящего раздела в котором это меню будет обнаружено, т.е. меню является иерархически наследуемым.
    К примеру посетитель находится в разделе /ru/company/about/. Для показа меню типа left файл меню будет искаться в следующей последовательности:
    1. /ru/company/about/.left.menu.php
    2. /ru/company/.left.menu.php
    3. /.left.menu.php
    Если в одном из каталогов будет найдено меню, то поиск останавливается и в последующих каталогах уже не ищется.

    Примеры файлов меню

    <?
    // пример файла .left.menu.php

    $aMenuLinks = Array(
      Array(
        "Каталог курсов",
        "index.php",
        Array(),
        Array(),
        ""
      ),

      Array(
        "Мои курсы",
        "mycourses.php",
        Array(),
        Array(),
        "\$GLOBALS['USER']->IsAuthorized()"
      ),

      Array(
        "Журнал обучения",
        "gradebook.php",
        Array(),
        Array(),
        "\$GLOBALS['USER']->IsAuthorized()"
      ),

      Array(
        "Анкета специалиста",
        "profile.php",
        Array(),
        Array(),
        "\$GLOBALS['USER']->IsAuthorized()"
      ),
    );
    ?>
    <?
    // пример файла .left.menu_ext.php

    if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

    global $APPLICATION;

    $aMenuLinksExt = $APPLICATION->IncludeComponent(
        "bitrix:menu.sections",
        "",
        Array(
            "ID" => $_REQUEST["ELEMENT_ID"],
            "IBLOCK_TYPE" => "books",
            "IBLOCK_ID" => "30",
            "SECTION_URL" => "/e-store/books/index.php?SECTION_ID=#ID#",
            "CACHE_TIME" => "3600"
        )
    );

    $aMenuLinks = array_merge($aMenuLinks, $aMenuLinksExt);

    ?>

    Вывод меню

    Вывод меню осуществляется в визуальной части пролога, либо эпилога. Для вывода меню используется компонент 2.0 Меню (bitrix:menu) [image].

    В настройках компонента указывается:

    • указывается шаблон компонента, определяющий внешний вид меню;
    • меню какого типа будет выводиться; указывается один из заданных в системе типов меню;
    • уровень вложенности меню;
    • тип меню для уровней ниже первого;
    • если требуется, устанавливаем опцию подключать файлы с именами вида .тип_меню.menu_ext.php.

    Примеры вызова меню

    <?
    // выведем меню типа "top"
    $APPLICATION->IncludeComponent(
        "bitrix:menu",
        "horizontal_multilevel",
        Array(
            "ROOT_MENU_TYPE" => "top",
            "MAX_LEVEL" => "3",
            "CHILD_MENU_TYPE" => "left",
            "USE_EXT" => "Y"
        )
    );
    ?>
    py.png" border="0">
    <?
    // выведем меню типа "left"
    $APPLICATION->IncludeComponent(
        "bitrix:menu",
        ".default",
        Array(
            "ROOT_MENU_TYPE" => "left",
            "MAX_LEVEL" => "1",
            "CHILD_MENU_TYPE" => "left",
            "USE_EXT" => "Y"
        )
    );?>

    Шаблон меню

    Внешний вид меню определяется шаблоном. Шаблон меню по структуре совпадает с шаблонами других компонентов 2.0. Общая информация по ним находится в разделах Шаблоны вывода и Шаблоны вывода компонента 2.0.

    Если шаблон компонента располагается в папке, то она может содержать целый набор подпапок и файлов: файл стилей, файл с Java-скриптами, файл, описывающий шаблон для редактора и т.д. Основным же среди них является файл, который и является собственно шаблоном - template.php. Расширение этого файла может быть другим (например, *.ext) и зависит от используемого движка шаблонизации. Здесь рассмотрим php шаблон.

    В php шаблоне для вывода меню используется массив $arItem - копия массива пунктов меню, в котором каждый пункт в свою очередь представляет собой массив, использующий следующие параметры:
    • TEXT - заголовок пункта меню;
    • LINK - ссылка на пункте меню;
    • SELECTED - активен ли пункт меню в данный момент, возможны следующие значения:
      • true - пункт меню выбран;
      • false - пункт меню не выбран;
    • PERMISSION - право доступа на страницу, указанную в LINK для текущего пользователя. Возможны следующие значения:
      • D - доступ запрещён;
      • R - чтение (право просмотра содержимого файла);
      • U - документооборот (право на редактирование файла в режиме документооборота);
      • W - запись (право на прямое редактирование);
      • X - полный доступ (право на прямое редактирование файла и право на изменение прав доступа на данный файл);
    • ADDITIONAL_LINKS - массив дополнительных ссылок для подсветки меню;
    • ITEM_TYPE - флаг, указывающий на тип ссылки, указанной в LINK, возможны следующие значения:
      • D - каталог (LINK заканчивается на "/");
      • P - страница;
      • U - страница с параметрами;
    • ITEM_INDEX - порядковый номер пункта меню;
    • PARAMS - ассоциативный массив параметров пунктов меню. Параметры задаются в расширенном режиме редактирования меню.

    Пример шаблона меню

    Приведем пример шаблона графического меню (на базе картинок). Адреса картинок хранятся в параметрах пункта меню, задаваемы в расширенном режиме редактирования меню.

    <?
    if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>
    <?if (!empty($arResult)):?>
        <table cellpadding="2" cellspacing="2" width="100%">
        <?foreach($arResult as $arItem):?>
        <?if ($arItem["PERMISSION"] > "D"):?>
            <tr>
            <?if ($arItem["SELECTED"]):?>
                <td><a href="<?=$arItem["LINK"]?>"><img src="<?=$arItem[PARAMS][SRC2]?>"
                width="18" height="18" border="0"></a></td>
            <?else:?>
                <td><a href="<?=$arItem["LINK"]?>"><img src="<?=$arItem[PARAMS][SRC1]?>"
                width="18" height="18" border="0"></a></td>
            <?endif?>
            </tr>
            <?endif?>
        <?endforeach?>
        </table>
    <?endif?>
    ?>


Обработка адресов

Понятие обработки адресов

Обработка адресов (UrlRewrite) применяется для того, чтобы скрипт мог отвечать не только по своему физическому, но и по любому другому указаному адресу. Например, можно задать настройки обработки адресов, чтобы скрипт в файле /fld/c.php, отвечающий по адресу

/fld/c.php?id=15

отвечал также по адресу

/catalog/15.php

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

Правила обработки

Правила обработки адресов настраиваются отдельно для каждого сайта и хранятся в корне сайта в файле urlrewrite.php. Файл содержит массив $arUrlRewrite, каждая запись которого является правилом обработки адреса. Файл urlrewrite.php имеет следующий вид:

<?
$arUrlRewrite = array(
    array(
        "CONDITION" => "#^/gallery/#",
        "RULE" => "",
        "ID" => "bitrix:photo",
        "PATH" => "/max/images/index.php",
    ),
    array(
        "CONDITION" => "#^/forum/#",
        "ID" => "bitrix:forum",
        "PATH" => "/forum/index.php",
    ),
    array(
        "CONDITION" => "#^/index/([0-9]+)/([0-9]+)/#",
        "RULE" => "mode=read&CID=$1&GID=$2",
        "ID" => "bitrix:catalog.section",
        "PATH" => "/newforum/index.php",
    ),
    array(
        "CONDITION" => "#(.+?)\\.html(.*)#",
        "RULE" => "$1.php$2",
    ),
);
?>

Каждое правило должно содержать уникальное в рамках сайта условие выполнения правила. Условие выполнения записывается в ключ "CONDITION" массива и является шаблоном Perl-совместимого регулярного выражения. Например, условие:

"CONDITION" => "#^/index/([0-9]+)/([0-9]+)/#"

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

/index/<число>/<число>/

Правило может содержать адрес физически существующего скрипта, который будет подключен при выполнении условия. Этот адрес записывается в ключ "PATH". Например, если в системе обработки адресов зарегистрировано правило:

array(
    "CONDITION" => "#^/gallery/#",
    "PATH" => "/max/images/index.php",
)

и пользователь запросил страницу:

/gallery/38.php

которая физически не существует, то система обработки адресов подключит скрипт:

/max/images/index.php

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

array(
    "CONDITION" => "#^/index/([0-9]+)/([0-9]+)/#",
    "RULE" => "mode=read&CID=$1&GID=$2",
    "PATH" => "/newforum/index.php",
)

и пользователем запрошена страница:

/index/5/48/

то для формирования адреса скрипта, который будет подключен, выполнится код:

$url = preg_replace("#^/index/([0-9]+)/([0-9]+)/#", "/newforum/index.php?mode=read&CID=$1&GID=$2", "/index/5/48/");

и будет подключен скрипт:

/newforum/index.php?mode=read&CID=5&GID=48

Если в системе обработки адресов зарегистрировано правило:

array(
    "CONDITION" => "#(.+?)\\.html(.*)#",
    "RULE" => "$1.php$2",
)

и пользователем запрошена страница:

/about/company.html?show

то для формирования адреса скрипта, который будет подключен, выполнится код:

$url = preg_replace("#(.+?)\\.html(.*)#", "$1.php$2", "/about/company.html?show");

и будет подключен скрипт:

/about/company.php?show

Правило может содержать имя компонента, который создал это правило. Это имя записывается в ключ "ID". При автоматическом пересоздании файла правил urlrewrite.php с помощью средств административной части сайта пересоздаются только правила, у которых заполнен ключ "ID". Эти правила пересоздаются на основании анализа физических файлов в папке сайта. Правила с пустым ключом "ID" при автоматическом пересоздании файла правил не изменяются.

Подключение системы обработки адресов

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

  • если у вас на веб-сервере настроена обработка ошибки 404 (например, для Apache установлена директива ErrorDocument 404 /404.php), то вы должны изменить файл /404.php, вставив в самое начало файла команду:
    include_once($_SERVER['DOCUMENT_ROOT'].'/bitrix/modules/main/include/urlrewrite.php');
  • если вы для Apache используете модуль mod_rewrite, то в его настройках вы можете указать (например, в файле .htaccess):
    <IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-l
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !/bitrix/urlrewrite.php$
    RewriteRule ^(.*)$ /bitrix/urlrewrite.php [L]
</IfModule>

Поддержка компонентов 2.0

При добавлении на страницу компонента с поддержкой ЧПУ ("человеко-понятный URL") (если файл сохраняется с помощью API), автоматически создаётся правило обработки адреса. Если страница создаётся не с помощью API, а, например, записывается через FTP, то необходимо выполнить пересоздание правил (кнопка на панели инструментов на странице настройки правил обработки адресов).

Поддержка ЧПУ включается в компоненте с помощью предопределённого входного параметра SEF_MODE. При этом в предопределённом входном параметре SEF_FOLDER устанавливается папка, в которой работает компонент. Папка может быть виртуальной (т.е. физически может не существовать). При сохранении страницы с размещённым на ней компонентом, переключенным в режим ЧПУ (параметр SEF_MODE равен Y), через стандартный интерфейс правило обработки адресов создаётся следующим образом: в ключ условия применения шаблона ("CONDITION") записывается регулярное выражение, полученое из папки в параметре SEF_FOLDER, в ключ "ID" записывается имя компонента, в ключ пути ("PATH") записывается физический адрес страницы.

Например, пусть компонент "bitrix:catalog" размещён на странице /fld/c.php и его подключение выглядит следующим образом:

$APPLICATION->IncludeComponent(
    "bitrix:catalog",
    "",
    Array(
        "SEF_MODE" => "Y",
        "SEF_FOLDER" => "/mycatalog/",
        "IBLOCK_TYPE_ID" => "catalog",
        "BASKET_PAGE_TEMPLATE" => "/personal/basket.php",
    )
);

Тогда при сохранении страницы /fld/c.php в системе обработки адресов добавится запись:

array(
    "CONDITION" => "#^/mycatalog/#",
    "RULE" => "",
    "ID" => "bitrix:catalog",
    "PATH" => "/fld/c.php",
)

Таким образом, при запросе адресов, начинающихся со строки /mycatalog/, будет подключаться скрипт /fld/c.php. В этом скрипте запрошеный адрес может быть проанализирован и выполнены требуемые действия.


Запуск мастера

1С-Битрикс: Управление сайтом Отправить отзыв по этому разделу

Мастера

  • Классы
  • Мастер создания сайта
  • Примеры
  • Запуск мастера
  • Определение шагов мастера
  • Понятие мастера
  • Структура папки мастера
  • Файл описания мастера .description.php
  • Физическое расположение мастера
  • Шаблон мастера


Понятие мастера

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

В общем случае существует 2 модели программирования мастера:

  • Фиксация по мере выполнения действий – на каждом шаге выполняется элементарная операция, которую нельзя отменить.
  • Фиксация в конце работы мастера – на каждом шаге мастера осуществляется сбор данных для операции, выполняемой в самом конце работы мастера.

Начиная с версии 6.5.2, продукт предоставляет механизм (API) для создания мастеров.


Физическое расположение мастера

Все мастера находятся в папке /bitrix/wizards/. Системные (поставляемые разработчиками продукта) мастера находятся в директории /bitrix/wizards/bitrix/. Содержимое этой папки обновляется системой SiteUpdate и не может изменяться пользователем. Пользовательские мастера могут находиться в любых других подпапках директории /bitrix/wizards/ или прямо в директории /bitrix/wizards/.

Название подпапки директории /bitrix/wizards/ образует пространство имен (namespace) мастеров. Например, все системные мастера расположены в пространстве имен bitrix. При создании пользовательских мастеров рекомендуется создать какое-либо пространство имен и размещать пользовательские мастера в нем. Полное имя мастера включает в себя пространство имен и имеет вид "пространство_имен:имя_мастера". Например, "bitrix:sale.install". Если мастер лежит вне пространства имен, то пространство имен не указывается. Например, "sale.install".

Мастера централизованно хранятся в одной папке (репозитарии). Это обеспечивает большую целостность и понятность структуры сайта. Папка доступна для запросов по HTTP протоколу, а, значит, мастер может легко подключать свои дополнительные ресурсы. Мастер хранит все, что ему нужно для работы, в своей папке. Поэтому мастера можно легко переносить между проектами. Мастер неделим.

Внимание! Файлы, к которым нельзя обращаться напрямую, должны содержать в начале следующий код:

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>


Структура папки мастера

Папка мастера может содержать следующие файлы и папки:

  • Файл wizard.php, в котором определяются все шаги мастера. Этот файл должен всегда присутствовать в папке мастера;

  • Файл .description.php, содержащий название, описание, а также ряд других характеристик мастера (см. описание файла .description.php) . Этот файл должен всегда присутствовать в папке мастера;

  • Подпапка lang, содержащая языковые сообщения (перевод) мастера. В этой папке находятся подпапки с именами, равными кодам языков. В этих подпапках находятся файлы языковых сообщений (переводов) мастера. Файл языковых сообщений для какого-либо файла мастера должен иметь такое же имя, как и файл мастера, и находиться в той же иерархии относительно папки /lang/код_языка/, в которой файл располагается относительно папки мастера. Например, языковой файл с английскими фразами для файла /wizard.php требуется располагать по пути /lang/en/wizard.php. Подпапка lang может отсутствовать, если в мастере нет зависящих от языка фраз;

  • Любые другие папки и файлы с ресурсами, необходимыми мастеру. Все ресурсы мастера должны находиться в папке мастера.


Определение шагов мастера

Чтобы создать мастер, нужно в файле wizard.php определить все шаги и их содержимое. Каждый шаг определяется классом, который обязательно должен наследоваться от класса CWizardStep. В классе шага необходимо переопределить 3 метода:

  • InitStep – вызывается при добавлении шага в мастер. Метод предназначен для инициализации свойств шага: идентификатора (ID), заголовка, подзаголовка, кнопок перехода на следующие шаги и др. В этом методе обязательно нужно определить ID шага;
  • ShowStep – вызывается в момент показа шага пользователю. Метод предназначен для определения содержимого шага: в переменную $this->content необходимо записать весь вывод шага;
  • OnPostForm – вызывается при нажатии на любую из кнопок навигации мастера. В этом методе можно проверить входные данные, вернуть ошибки, изменить текущий шаг, выполнить любые другие действия;

Методы ShowStep и OnPostForm переопределять необязательно. Метод InitStep обязательно должен присутствовать в классе, т.к. в нем с помощью функции SetStepID определяется ID шага. В случае динамического определения шагов устанавливать ID шага в InitStep необязательно.

Класс СWizardBase является оболочкой мастера и содержит методы общие для всех шагов (работа с переменными мастера, управление кнопками навигации и др.). Для каждого подключаемого мастера создаётся экземпляр класса СWizardBase. Для получения доступа к методам класса СWizardBase в теле переопределяемых функций (InitStep, ShowStep, OnPostFrom) нужно получить объект мастера с помощью метода CWizardStep::GetWizard:

$wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
$myVar = $wizard->GetVar("myVar"); //Используем метод мастера (класс CWizardBase)

Для каждого шага, добавляемого в мастер, создаётся экземпляр класса CWizardStep. В переопределяемых функциях шага методы класса CWizardStep доступны через переменную-псевдоним $this. Каждый шаг мастера сам определяет, какие кнопки навигации (Назад, Далее, Готово, Отмена) будут показаны, и на какой шаг они будут вести. Названия кнопок можно изменить по своему усмотрению. Как правило, содержимое шага представляет собой набор полей Web-формы. Для упрощения работы с элементами Web-формы класс CWizardStep содержит методы для создания текстовых полей, переключателей, флажков и др.

Пример определения шагов мастера в файле wizard.php:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MainUserFields extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("main_fields");//ID шага

        $this->SetTitle("Основные поля пользователя");//Заголовок
        $this->SetSubTitle("Введите логин, пароль и e-mail нового пользователя"); //Подзаголовок

        //Навигация
        $this->SetNextStep("success");
        $this->SetCancelStep("cancel");

        $wizard =& $this->GetWizard(); // Получаем ссылку на объект мастера
        $wizard->SetDefaultVar("active", "Y"); //Устанавливаем значение по умолчанию
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        if ($wizard->IsCancelButtonClick())
            return;

        $success = true;
        $login = $wizard->GetVar("login");
        if (strlen($login) < 3)
            $this->SetError("Логин должен быть больше 3 символов", "login");
        else
        {
            $obUser = CUser::GetList($by="id", $order="desc", Array("LOGIN_EQUAL" => $login));
            if ($obUser->Fetch())
            {
                $this->SetError("Такой логин уже существует", "login");
                $success = false;
            }
        }

        $password = $wizard->GetVar("password");
        if (strlen($password) < 6)
        {
            $this->SetError("Пароль должен быть не меньше 6 символов", "password");
            $success = false;
        }

        $email = $wizard->GetVar("email");
        if (strlen($email) < 3 || !check_email($email))
        {
            $this->SetError("Вы ввели неверный E-mail", "email");
            $success = false;
        }

        if (!$success)
            return;

        //Добавляем пользователя
        $user = new CUser;
        $arFields = Array(
            "NAME" => $wizard->GetVar("user_name"),
            "LAST_NAME" => $wizard->GetVar("user_surname"),
            "EMAIL" => $wizard->GetVar("email"),
            "LOGIN" => $wizard->GetVar("login"),
            "ACTIVE" => ($wizard->GetVar("active") == "Y" ? "Y" : "N"),
            "PASSWORD" => $wizard->GetVar("password"),
            "CONFIRM_PASSWORD" => $wizard->GetVar("password"),
        );

        $userID = $user->Add($arFields);
        if (intval($userID) > 0)
        {
            $wizard->SetVar("userID", $userID);
            CFile::Delete($photo); //Удаляем временный файл
        }
        else
            $this->SetError($user->LAST_ERROR);
    }

    function ShowStep()
    {
        $this->content .= '<table class="wizard-data-table">';

        $this->content .= '<tr><th align="right">Активен:</th><td>'.$this->ShowCheckBoxField("active", "Y").'</td></tr>';

        $this->content .= '<tr><th align="right"><span class="wizard-required">*</span>Логин (мин. 3 символа):</th><td>';
        $this->content .= $this->ShowInputField("text", "login", Array("size" => 25));
        $this->content .= '</td></tr>';

        $this->content .= '<tr><th align="right"><span class="wizard-required">*</span>Пароль (мин. 6 символов):</th><td>';
        $this->content .= $this->ShowInputField("password", "password", Array("size" => 25));
        $this->content .='</td></tr>';

        $this->content .= '<tr><th align="right"><span class="wizard-required">*</span>E-mail:</th><td>';
        $this->content .= $this->ShowInputField("text", "email", Array("size" => 25));
        $this->content .= '</td></tr>';

        $this->content .= '<tr><th align="right">Имя:</th><td>'.$this->ShowInputField("text", "user_name", Array("size" => 25)).'</td></tr>';
        $this->content .= '<tr><th align="right">Фамилия:</th><td>'.$this->ShowInputField("text", "user_surname", Array("size" => 25)).'</td></tr>';

        $this->content .= '</table>';
        $this->content .= '<br /><div class="wizard-note-box"><span class="wizard-required">*</span> Поля, обязательные для заполнения.</div>';
    }
}

class SuccessStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("success");//ID шага
        $this->SetTitle("Работа мастера успешно завершена");//Заголовок
        //Навигация
        $this->SetCancelStep("success");
        $this->SetCancelCaption("Готово");
    }

    function ShowStep()
    {
        $this->content .= "Мастер успешно добавил нового пользователя. ";

        $wizard =& $this->GetWizard();
        $userID = intval($wizard->GetVar("userID"));
        if ($userID > 0)
            $this->content .= 'Идентификатор нового пользователя
                <a target="_blank" href="/bitrix/admin/user_edit.php?ID='.$userID.'&lang='.LANGUAGE_ID.'">'.$userID.'</a>';
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Мастер прерван");
        $this->SetStepID("cancel");
        $this->SetCancelStep("cancel");
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Мастер создания нового пользователя прерван. Новый пользователь не был создан.";
    }
}
?>

После того как мы определили классы в файле wizard.php, их имена необходимо описать в файле .description.php:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мастер создания нового пользователя",
    "STEPS" => Array("MainUserFields", "SuccessStep", "CancelStep"), //Описание шагов
);

?>

Система автоматически создаст мастер и добавит в него шаги с названиями, описанные в файле .description.php.

Шаг ввода данных нового пользователя

CWizardBase) и затем добавить в него объекты шагов c помощью методов AddStep или AddSteps. Метод Display выведет мастер на экран.

<?
//Создаем мастер
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);

//Добавляем шаги
$wizard->AddStep(new MainUserFields);
$wizard->AddStep(new SuccessStep);
$wizard->AddStep(new CancelStep);

/*
Или с помощью AddSteps:
$wizard->AddSteps(Array("MainUserFields", "SuccessStep", "CancelStep"));
*/

//Выводим
$wizard->Display();
?>

Вторым параметром метод CWizardBase::AddStep может принимать ID добавляемого шага. При инициализации шага с помощью AddStep с указанным вторым параметром, в классе шага необязательно переопределять метод InitStep для установки ID шага с помощью метода SetStepID.

<?
//Создаем мастер
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);

//Добавляем шаги с указанием идентификаторов
$wizard->AddStep(new MainUserFields, "main_fields");
$wizard->AddStep(new SuccessStep, "success");
$wizard->AddStep(new CancelStep, "cancel");

//Выводим
$wizard->Display();
?>

Вы также можете динамически задать свойства мастера и шагов:

<?
//Создаем мастер
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);

//Устнавим значение по уомлчанию для поля Логин
$wizard->SetDefaultVar("login", "new_user");

$mainStep = new MainUserFields;
//Изменим надпись кнопки Далее
$mainStep->SetNextCaption("Создать пользователя");

//Добавляем шаги
$wizard->AddStep($mainStep, "main_fields");
$wizard->AddStep(new SuccessStep, "success");
$wizard->AddStep(new CancelStep, "cancel");

//Выводим
$wizard->Display();
?>


Файл описания мастера .description.php

Файл .description.php содержит название, описание, а также ряд других характеристик мастера. Этот файл должен всегда присутствовать в папке мастера. Языковой файл подключается автоматически (должен лежать в папке /lang/<язык>/.description.php относительно папки мастера).

Структура типичного файла .description.php такова:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => GetMessage("WD_TITLE"),
    "DESCRIPTION" => GetMessage("WD_TITLE_DESCR"),
    "ICON" => "images/icon.gif",
    "VERSION" => "1.0.0",
    "DEPENDENCIES" => Array(
        "main" => "6.5.0",
        "sale" => "6.0.0",
        "currency" => "6.0.0",
    ),
    "STEPS" => Array("Step0", "Step1", "Step2", "Step3", "Step4", "Step5","Install", "FinalStep", "CancelStep"),

    "TEMPLATES" => Array(
        Array("SCRIPT" => "wizard_template.php", "CLASS" => "DemoSiteTemplate"),
    ),
);
?>

В файле определяется массив $arWizardDescription, который описывает мастер. Этот массив может иметь следующие ключи:

  • "NAME" – название мастера;
  • "DESCRIPTION" – описание мастера;
  • "ICON" – иконка мастера, путь к файлу относительно папки мастера;
  • "VERSION" – версия мастера;
  • "DEPENDENCIES" – зависимости мастера от модулей. Значением этого ключа должен быть массив вида Array("ID модуля"=>"версия модуля" [, ...]);
  • "STEPS" – массив названий классов, определяющих шаги в файле wizard.php;
  • "TEMPLATES" – шаблоны мастера. Значением этого ключа должен быть массив, элементами которого должен быть массив, имеющий следующие ключи:
    • "CLASS" – имя класса, описывающего шаблон;
    • "SCRIPT" – путь к файлу, в котором определён класс шаблона относительно папки мастера;
    • "STEP" – ID шага, для которого определяется шаблон. Если ключ "STEP" не указан, шаблон будет определён для всех шагов мастера.

По умолчанию первый элемент в массиве названий классов является первым шагом мастера. Именно этот шаг появляется при запуске мастера. Изменить первый шаг мастера можно динамически с помощью метода CWizardBase::SetFirstStep.


Шаблон мастера

Для мастера системой определены два шаблона по умолчанию. Один подключается при запуске мастера из административного раздела, второй – при запуске мастера из публичной части сайта (подробнее см. запуск мастера).

Вы можете разработать собственный интерфейс, отличный от интерфейса по умолчанию. Шаблон мастера определяется классом, который обязательно должен наследоваться от класса CWizardTemplate. В этом классе необходимо переопределить метод GetLayout, который должен вернуть HTML шаблона мастера. Внутри шаблона мастера обязательно должны быть определены следующие макросы:

  • {#FORM_START#} – начало формы, макрос будет заменен тегом <form>;
  • {#FORM_END#} – конец формы, макрос будет заменен тегом </form>;
  • {#CONTENT#} – область содержимого шага, макрос будет заменен содержимым текущего шага;
  • {#BUTTONS#} – область кнопок навигации, макрос будет заменен кнопками навигации.

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

  • {#BUTTON_PREVIOUS#} - кнопка Назад;
  • {#BUTTON_NEXT#} - кнопка Далее;
  • {#BUTTON_CANCEL#} - кнопка Отмена;
  • {#BUTTON_FINISH#} - кнопка Готово.

Чтобы воспользоваться методами класса CWizardBase в теле переопределяемой функции GetLayout необходимо получить ссылку на экземпляр мастера:

<?
class MyTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
        /*
            Определение шаблона
            ...
        */
    }
}

?>

После определения класса шаблона мастера в файле .description.php в ключе "TEMPLATES" массива $arWizardDescription необходимо описать шаблон, указав название класса, файл, где находится класс, а также ID шага, для которого будет применен шаблон. Шаблон можно определить как для всех шагов мастера, так и для конкретного, указав в ключе "STEP" ID шага:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step0", "Step1", "Step2", "Install", "FinalStep", "CancelStep"),
    "TEMPLATES" => Array(
        Array("SCRIPT" => "wizard_pink.php", "CLASS" => "PinkTemplate"), //Для всех шагов шаблон PinkTemplate
        Array("SCRIPT" => "template_red.php", "CLASS" => "RedTemplate", "STEP" => "Step0"), //А для шага Step0 шаблон RedTemplate
    ),
);

?>

Особенности системных шаблонов по умолчанию и системных шагов мастера создания сайта

1. Если навигация шага содержит только кнопку Отмена, по ее нажатию системный шаблон закроет pop-up окно мастера.

2. В системных шаблонах определены следующие каскадные стили оформления:

  • wizard-data-table - применяется для оформления таблиц;
  • wizard-note-box - применяется для оформления подсказки;
  • wizard-required - выделяет текст красным цветом.
3. В системных шагах определены следующие CSS-классы:
  • wizard-license-iframe - класс для тега iframe, выводящего лицензионное соглашение;
  • wizard-iframe-container - класс для тега div, содержащий фрейм с лицензионным соглашением;
  • wizard-prev-button - класс для кнопки Назад;
  • wizard-next-button - класс для кнопки Далее;
  • wizard-finish-button - класс для кнопки Готово;
  • wizard-cancel-button - класс для кнопки Отмена.
Подробнее см. Мастер создания нового пользователя

Примеры

Пример шаблона мастера для использования его в административном разделе (высота таблицы совпадет с высотой всплывающего окошка на странице Список мастеров.)

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

//Красный шаблон мастера
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

Пример шаблона для использования в публичной части сайта

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}


Запуск мастера

Запуск мастера из административного раздела

На странице Списка мастеров (Административный раздел > Настройки > Настройки продукта > Список мастеров) в колонке Действия необходимо выбрать пункт Установить. Запустится pop-up окно c нужным мастером:

Запуск мастера из публичной части сайта

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php"); //Подключаем механизм создания мастеров
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");
$wizard = new CWizard("help:new_user");
$wizard->Install();
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>

Запуск мастера не из репозитария /bitrix/wizards/

Существует также возможность определить шаги мастера в произвольном файле.
Запуск мастера не из репозитария /bitrix/wizards/ имеет 2 ограничения:

  • Механизм мастера создания сайта работать не будет;
  • Методы класса CWizard будут недоступны в переопределяемых методах шага.
<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step2");
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1");
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetTitle("Третий шаг");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package = null);

//Добавляем шаги
$wizard->AddStep(new Step1);
$wizard->AddStep(new Step2);
$wizard->AddStep(new Step3);

//Выводим на экран
$wizard->Display();

?>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>


Создание дистрибутива с решением

Мастер создания сайта

  • Идентификаторы системных шагов
  • Общие понятия
  • Пользовательские шаги
  • Создание дистрибутива с решением
  • Структура файлов мастера создания сайта
  • Файл описания мастера создания сайта
  • Файл описания сервисов сайта .services.php
  • Файл описания типов сайта .sites.php
  • Файл описания шаблонов сайта .templates.php


Общие понятия

Мастер создания сайта – это мастер, ориентированный на развёртывание полнофункционального сайта. Типичный конструктор (мастер) сайта представляет собой следующую последовательность шагов: Выбор типа сайта -> Выбор дизайна -> Выбор сервисов -> Адаптация дизайна (изменение заголовка, логотипа сайта и т.п.). С помощью API, предоставляемого системой, можно создать мастер с любой логикой. Однако чтобы облегчить разработчику задачу по созданию именно мастера создания сайта, существует упрощённый механизм. Вместо создания шагов по выбору типа сайта, дизайна, сервисов и др. в файле wizard.php, разработчик создает описательные файлы, на основе которых "на лету" генерируются соответствующие шаги.

В общем случае, сайт в «1C-Битрикс: Управление сайтом» представляет собой:

  • шаблоны сайта;
  • компоненты;
  • публичные файлы;
  • демо-данные (информационные блоки, веб-формы, опросы и др.).

Упрощённый механизм создания мастера сайта представляет собой следующую последовательность шагов:
Приветствие -> Лицензионное соглашение -> Выбор типа сайта -> Выбор группы шаблонов -> Выбор шаблона сайта -> Выбор сервисов -> Готовность к установке -> Установка сайта -> Установка шаблона -> Установка сервисов -> Установка завершена -> Установка прервана.

  • Шаг Приветствие – первый шаг мастера;
  • Шаг Лицензионное соглашение выводит текст лицензионного соглашения и обязует пользователя с ним согласиться; данный шаг определяется файлом license.php;
  • Шаг Выбор типа сайта предлагает выбрать один тип сайта из списка, определяется файлом .sites.php;
  • Шаг Выбор группы шаблонов предлагает выбрать одну группу шаблонов сайта из списка, определяется файлом .templates.php;
  • Шаг Выбор шаблона сайта предлагает выбрать один шаблон сайта из списка, определяется файлом .templates.php и директорией templates, находящейся в папке мастера;
  • Шаг Выбор сервисов предлагает выбрать устанавливаемые на сайт сервисы, определяется файлом .services.php;
  • Шаг Готовность к установке – промежуточный шаг между шагами выбора и шагами установки, суммирует все данные, установленные пользователем в шагах выбора;
  • Шаг Установка сайта выполняет копирование файлов, зависящих от выбранного типа сайта;
  • Шаг Установка шаблона копирует выбранный шаблон в директорию /bitrix/templates/, регистрирует его в системе как шаблон по умолчанию для сайта по умолчанию, копирует дополнительные файлы, зависящие от выбранного шаблона;
  • Шаг Установка сервисов копирует файлы выбранных сервисов;
  • Шаг Установка завершена является конечным шагом мастера;
  • Шаг Установка прервана является конечным шагом мастера, переход на этот шаг осуществляется по нажатию кнопки "Отмена" в шагах выбора.

Шаги Приветствие, Готовность к установке, Установка завершена и Установка прервана всегда присутствуют в цепочке шагов мастера создания сайта. Остальные шаги могут отсутствовать. После любого шага, кроме шага Выбора группы можно добавить свои пользовательские шаги.

Физическое расположение мастера создания сайта такое же, как и у обычного мастера. Если в директории мастера есть файл wizard.php, то мастер состоит из тех шагов, которые описаны в этом файле. Если файла wizard.php нет, то считается, что это мастер создания сайта, в папке мастера ищутся файлы описания и на их основе генерируются шаги.


Структура файлов мастера создания сайта

Папка мастера создания сайта может содержать следующие файлы и папки:

  • Файл .description.php, содержащий название, описание, а также ряд других характеристик мастера. Этот файл должен всегда присутствовать в папке мастера.

  • Файл .sites.php, описывающий шаги Выбор типа сайта и Установка сайта. Тип сайта – сущность, которая может объединять группы шаблонов, шаблоны, сервисы. От выбора типа сайта может зависеть дальнейший выбор группы шаблонов, шаблонов сайта и сервисов. Этот файл может отсутствовать в папке мастера.

  • Файл .templates.php, описывающий шаги Выбор группы шаблонов, Выбор шаблона и Установка шаблона. В файле .templates.php можно описать зависимости шаблона от типа сайта, определить группы шаблонов. Этот файл может отсутствовать в папке мастера.

  • Подпапка templates, содержащая шаблоны сайта. Если в этой папке есть шаблоны, то шаги Выбор шаблона и Установка шаблона добавятся в мастер автоматически. В файле .templates.php описываются шаблоны, находящиеся в подпапке templates. Эта директория может отсутствовать в папке мастера.

  • Файл .services.php, описывающий шаги Выбор сервисов и Установка сервисов. Этот файл может отсутствовать в папке мастера. Под сервисом понимается совокупность программных модулей (публичных файлов, компонентов, данных), направленных на реализацию конкретного функционала сайта. Примерами сервисов могут быть доска объявлений, фотогалерея, каталог ссылок, каталог товаров, новости, форум и т.п.

  • Подпапка lang, содержащая языковые сообщения (перевод) мастера. В этой папке находятся подпапки с именами, равными кодам языков. В этих подпапках находятся файлы языковых сообщений (переводов) мастера. Файл языковых сообщений для какого-либо файла мастера должен иметь такое же имя, как и файл мастера и находиться в той же иерархии относительно папки /lang/код_языка/, в которой файл располагается относительно папки мастера. Например, языковой файл с английскими фразами для файла /.sites.php требуется располагать по пути /lang/en/.sites.php. Подпапка lang может отсутствовать, если в мастере нет зависящих от языка фраз;

  • Файл license.php, определяющий шаг Лицензионное соглашение. Если в директории мастера создания сайта лежит файл license.php (например, /bitrix/wizards/my_company/demo/license.php), то после шага Приветствие автоматически добавится шаг Лицензионное соглашение. В этом шаге пользователю будет предложено согласиться с лицензионным соглашением, текст которого находится в файле license.php. Файл с текстом лицензионного соглашения может зависеть от языка интерфейса мастера. Для это сначала ищется файл license_идентификатор_текущего_языка.php и если такого файла нет, текст берется из файла license.php.

  • Любые другие папки и файлы с ресурсами, необходимыми мастеру. Все ресурсы мастера должны находиться в папке мастера.


Файл описания мастера создания сайта

В файле .description.php определяется массив $arWizardDescription, который описывает характеристики мастера. Структура типичного файла .description.php такова:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Сайт компании",
    "DESCRIPTION" => "Мастер создания сайта компании",
    "ICON" => "images/icon.gif",
    "VERSION" => "1.0.3",
    "DEPENDENCIES" => Array(
        "main" => "6.0.5",
    ),

    "TEMPLATES" => Array(
        Array("SCRIPT" => "scripts/wizard_template.php", "CLASS" => "DemoSiteTemplate")
    ),

    "STEPS_SETTINGS" => Array(
        "WELCOME" => Array(
            "CONTENT" => "Добро пожаловать в мастер создания сайта компании",
        ),

        "START_INSTALL" => Array(
        "CLASS" => "MyStartInstall",
        "SCRIPT" => "scripts/start_install.php",
        ),
    )
);

?>

Массив $arWizardDescription может иметь следующие ключи:

  • "NAME" – название мастера;
  • "DESCRIPTION" – описание мастера;
  • "VERSION" – версия мастера;
  • "ICON" – иконка мастера, путь к файлу относительно папки мастера;
  • "CHARSET" - кодировка файлов мастера. Используется для создания дистрибутива с решением.
  • "DEPENDENCIES" – зависимости мастера от модулей. Значением этого ключа должен быть массив вида Array("ID модуля"=>"версия модуля" [, ...]);
  • "TEMPLATES" – шаблоны мастера. Значением этого ключа должен быть массив, элементами которого должен быть массив, имеющий следующие ключи:
    • "CLASS" – имя класса, описывающего шаблон;
    • "SCRIPT" – путь к файлу, в котором определён класс шаблона относительно папки мастера;
    • "STEP" – ID шага, для которого определяется шаблон. Если ключ "STEP" не указан, шаблон будет определён для всех шагов мастера.
  • "STEPS_SETTINGS" – настройки системных шагов. Значением этого ключа является массив, описывающий настройки системных шагов. Массив состоит из элементов следующего вида:

    "Код системного шага" => Array(
    "TITLE" => заголовок шага,
    "SUBTITLE" => подзаголовок шага,
    "CONTENT" => описание шага,
    "CLASS" => имя класса, определяющего пользовательский шаг,
    "SCRIPT" => путь к файлу, в котором определён класс CLASS и/или классы STEPS относительно папки мастера,
    "STEPS" => массив названий классов, определяющих дополнительные шаги после системных шагов Приветствие, Лицензионное соглашение, Готовность к установке, Установка завершена, Установка прервана;
    )

  • Код системного шага может принимать следующие значения:

    • WELCOME – шаг Приветствие;
    • LICENSE – шаг Лицензионное соглашение;
    • SELECT_SITE – шаг Выбор сайта;
    • SELECT_GROUP – шаг Выбор группы шаблона;
    • SELECT_TEMPLATE – шаг Выбор шаблона;
    • SELECT_SERVICE – шаг Выбор сервисов;
    • START_INSTALL – шаг Готовность к установке;
    • INSTALL_SITE – шаг Установка сайта;
    • INSTALL_TEMPLATE – шаг Установка шаблона;
    • INSTALL_SERVICE – шаг Установка сервиса;
    • FINISH – шаг Установка завершена;
    • CANCEL – шаг Установка прервана;

    Только шаги Приветствие, Готовность к установке, Установка завершена, Установка прервана можно подменить на собственные пользовательские шаги. Для этого необходимо в ключах CLASS и SCRIPT указать имя класса и путь к файлу, в котором определён класс, соответственно.


Файл описания типов сайта .sites.php

Файл .sites.php определяет шаги Выбор типа сайта и Установка сайта в цепочке шагов мастера создания сайта. Тип сайта – сущность, которая может объединять группы шаблонов, шаблоны, сервисы. От выбора типа сайта может зависеть дальнейший выбор группы шаблонов, шаблонов сайта, сервисов. Если файла .sites.php нет в папке мастера, то шаги Выбор типа сайта и Установка сайта отсутствуют.

Структура типичного файла .sites.php такова:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

$arWizardSites = Array(

    "homepage" => Array(
        "NAME" => "Сайт-визитка",
        "DESCRIPTION" => "Представляет набор страниц, создаваемых пользователем. ",
        "FILES" => Array(
            Array("FROM" => "public/homepage/", "TO" => "/"),
            Array("DELETE" => "/special_file.php"),
        ),
        "DEFAULT" => "Y",
        "INSTALL_STEPS" => Array(
            "SCRIPT" => "scripts/homepage_site.php",
            "STEPS" => Array(
                "homepagestep1" => "HomePageStep1",
                "homepagestep2" => "HomePageStep2",
                "homepagestep3" => "HomePageStep3",
            )
        ),
    ),

    "blog" => Array(
        "NAME" => "Блог",
        "DESCRIPTION" => "Публичный сетевой дневник пользователя.",
        "FILES" => Array(
            Array("FROM" => "public/blog/", "TO" => "/"),
        ),

        "SELECT_STEPS" => Array(
            "SCRIPT" => "scripts/blog_site.php",
            "STEPS" => Array(
                "blogstep1" => "BlogStep1",
                "blogstep2" => "BlogStep2",
            )
        ),
    ),

    "gallery" => Array(
        "NAME" => "Фотогалерея",
        "DESCRIPTION" => "Фотогалерея",
        "FILES" => Array(
            Array("FROM" => "public/gallery/", "TO" => "/"),
        ),
    ),

);
?>

В файле .sites.php определяется массив $arWizardSites, состоящий из элементов следующего вида:

"ID сайта" => Array(
    "NAME" => имя сайта,
    "DESCRIPTION" => описание сайта,
    "SCREENSHOT" => путь относительно папки мастера к изображению сайта,
    "PREVIEW" => путь относительно папки мастера к уменьшенной копии изображения сайта,
    "DEFAULT" => если равно "Y", то данный сайт будет выбран по умолчанию
    "SELECT_STEPS" => массив, описывающий дополнительные шаги после шага Выбор сайта
     Array(
       "SCRIPT" => путь к файлу с классами шагов относительно папки мастера
       "STEPS" => массив шагов, добавляемых в мастер
        Array(
          "ID шага 1" => "Имя класса шага 1",
          "ID шага 2" => "Имя класса шага 2",
          …
        )
    ),

    "INSTALL_STEPS" => массив, описывающий дополнительные шаги после шага Установка сайта
     Array(
      "SCRIPT" => путь к файлу с классами относительно папки мастера,
      "STEPS" => массив шагов, добавляемых в мастер
       Array(
          ID шага 1" => "Имя класса шага 1",
          ID шага 2" => "Имя класса шага 2",
          …
       )
    ),

    "FILES" => массив, описывающий файлы для копирования/удаления
     Array(
      Array(
        "FROM" => путь к каталогу (файлу) относительно папки мастера,
        содержимое которого нужно скопировать,
        "TO" => путь к файлу или папке относительно корня сайта,
        куда будут скопированы файлы,
        "REWRITE" => перезаписывать ли существующие файлы;
        необязательный параметр, по умолчанию равен "Y" (перезаписывать),
        "RECURSIVE" => копировать ли рекурсивно все подкаталоги и файлы,
        входящие в путь, указанный в параметре FROM; необязательный параметр,
        по умолчанию равен "Y" (копировать рекурсивно),
        "DELETE" => путь к папке (файлу), которую нужно удалить
      ),
      …
     )
),


Файл описания шаблонов сайта .templates.php

Файл .templates.php определяет шаги Выбор группы шаблонов, Выбор шаблона и Установка шаблона в цепочке шагов мастера создания сайта. Если в папке мастера нет файла .templates.php, то шаги Выбор группы шаблонов, Выбор шаблона и Установка шаблона отсутствуют. Группа шаблонов предоставляет возможность сгруппировать шаблоны сайта, например, по тематике или компоновке (layout).

В файле .templates.php описываются шаблоны, находящиеся в поддиректории templates папки мастера. В поддиректории templates должны находиться папки шаблонов сайта. Данные (название, описание, скриншоты шаблонов сайта) для шага Выбор шаблона берутся из файлов (description.php, screen.gif и preview.gif), находящихся в папке шаблона.

Если в поддиректории templates есть шаблоны сайтов, а файл .templates.php отсутствует, то шаги Выбор шаблона и Установка шаблона все равно добавятся в цепочку шагов мастера создания сайта.

Структура типичного файла .templates.php такова:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

$arWizardTemplates = Array(

    "GROUPS" => Array(
        "BUSINESS" => Array(
            "NAME" => GetMessage("TEMPLATE_GROUP_BUSINESS"),
            "SITE_ID" => "homepage",
            "SCREENSHOT" => "images/comp1.gif",
            "PREVIEW" => "images/comp1_prev.gif"
        ),

        "COMPUTER" => Array(
            "NAME" => "Компьютер",
            "SITE_ID" => "homepage",
            "SCREENSHOT" => "images/comp2.gif",
            "PREVIEW" => "images/comp2_prev.gif"
        ),

        "BLOGS" => Array(
            "NAME" => "Блоги",
            "SITE_ID" => "blog",
            "SCREENSHOT" => "images/comp3.gif",
            "PREVIEW" => "images/comp3_prev.gif",
            "DEFAULT" => "Y",
        ),

        "CARS" => Array(
            "NAME" => "Машины",
            "SITE_ID" => Array("blog", "homepage"),
            "SCREENSHOT" => "images/comp4.gif",
            "PREVIEW" => "images/comp4_prev.gif"
        ),
    ),

    "TEMPLATES" => Array(
        "template1" => Array(
            "GROUP_ID" => "BUSINESS",
            "INSTALL_STEPS" => Array(
                "SCRIPT" => "scripts/template1.php",
                "STEPS" => Array(
                    "step100" => "Step100",
                    "step200" => "Step200",
                )
            ),
        ),

        "template2" => Array(
            "GROUP_ID" => "BUSINESS",
        ),

        "three_columns" => Array(
            "GROUP_ID" => Array("BLOGS", "BUSINESS", "CARS", "COMPUTER"),
            "DEFAULT" => "Y",
            "FILES" => Array(
                Array("FROM" => "files/three_columns", "TO" => "/"),
            ),
            "SELECT_STEPS" => Array(
                "SCRIPT" => "three_columns.php",
                "STEPS" => Array(
                    "templatestep" => "TemplateStep",
                )
            ),
        ),

        "two_columns" => Array(
            "GROUP_ID" => "COMPUTER",
        ),
    ),

);

?>
В файле .templates.php определяется массив $arWizardTemplates, имеющий следующие ключи:
  • "GROUPS" – значением этого ключа является массив групп шаблонов. Если этот ключ не определён, шаг Выбор группы шаблонов отсутствует в цепочке шагов мастера создания сайта. Массив групп шаблонов состоит из элементов следующего вида:
    "ID группы шаблона" => Array(
      "NAME" => имя группы шаблона
      "SITE_ID" => ID сайта (одиночное значение или массив)
      "SCREENSHOT" => путь относительно папки мастера к картинке группы
      "PREVIEW" => путь относительно папки мастера к уменьшенной копии картинки группы
      "DEFAULT" => если равно "Y", то данная группа будет выбрана по умолчанию
    ),
  • "TEMPLATES" – значением этого ключа является массив шаблонов. Массив шаблонов состоит из элементов следующего вида:
    "ID шаблона" => Array(
      "GROUP_ID" => ID группы, к которой принадлежит шаблон (одиночное значение или массив)
      "SITE_ID" => ID сайта, к которому принадлежит шаблон (одиночное значение или массив)
      "DEFAULT" => если параметр равен "Y", то данный шаблон будет
      выбран по умолчанию в шаге Выбор шаблона
      "SORT" => индекс сортировки
  "REWRITE" => если параметр равен "N", то выбранный шаблон не будет перезаписывать файлы
      существующего в системе шаблона при совпадении идентификаторов;
      по умолчанию параметр равен "Y" (перезаписывать);
      "SELECT_STEPS" => массив, описывающий дополнительные шаги после шага Выбор шаблона
   Array(
     "SCRIPT" => путь к файлу с классами шагов относительно папки мастера
         "STEPS" => массив шагов, добавляемых в мастер
          Array(
            "ID шага 1" => "Имя класса шага 1",
            "ID шага 2" => "Имя класса шага 2",
            …
          )
       )
      ),
      "INSTALL_STEPS" => массив, описывающий дополнительные шаги после шага Установка шаблона
   Array(
     "SCRIPT" => путь к файлу с классами относительно папки мастера,
         "STEPS" => массив шагов, добавляемых в мастер
          Array(
            "ID шага 1" => "Имя класса шага 1",
            "ID шага 2" => "Имя класса шага 2",
            …
          )
       ),
      "FILES" => массив, описывающий файлы для копирования/удаления
      Array(
       Array(
         "FROM" => путь к каталогу (файлу) относительно папки мастера,
         содержимое которого нужно скопировать,
         "TO" => путь к файлу или папке относительно корня сайта,
         куда будут скопированы файлы
         "REWRITE" => перезаписывать ли существующие файлы;
         необязательный параметр, по умолчанию равен "Y" (перезаписывать),
         "RECURSIVE" => копировать ли рекурсивно все подкаталоги и файлы,
         входящие в путь, указанный в параметре FROM;
         необязательный параметр, по умолчанию равен "Y" (копировать рекурсивно),
         "DELETE" => путь к папке (файлу), которую нужно удалить
       ),
       …
      )
    ),


Файл описания сервисов сайта .services.php

Файл .services.php определяет шаги Выбор сервисов и Установка сервисов в цепочке шагов мастера создания сайта. Если в папке мастера нет файла .services.php, то шаги Выбор сервисов и Установка сервисов отсутствуют. Под сервисом понимается совокупность программных модулей (публичных файлов, компонентов, данных), направленных на реализацию конкретного функционала сайта. Примерами сервисов могут быть доска объявлений, фотогалерея, каталог ссылок, каталог товаров, новости, форум и т.п.

Структура типичного файла .services.php такова:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardServices = Array(
    "news" => Array(
        "NAME" => "Новости",
        "DESCRIPTON" => "Новости с поиском, рсс и разделами",
        "SITE_ID" => Array("blog","homepage"),
        "ICON" => "images/icon.gif",
        "FORM" => Array(
            "TYPE" => "radio",
            "DEFAULT" => "Y",
        ),

        "INSTALL_STEPS" => Array(
            "SCRIPT" => "scripts/news.php",
            "STEPS" => Array(
                "newsstep1" => "NewsStep1",
                "newsstep2" => "NewsStep2",
                "newsstep3" => "NewsStep3",
            )
        ),
        "FILES" => Array(
            Array("DELETE" => "/folder"),
            Array("FROM" => "files/blog_site", "TO" => "/myblog"),
        )
    ),

    "forum" => Array(
        "NAME" => "Форум",
        "ICON" => "images/icon2.gif",
        "FORM" => Array(
            "TYPE" => "radio",
        ),
        "DESCRIPTON" => "Новости с поиском, рсс и разделами",
        "SITE_ID" => Array("blog","homepage"),
        "DEFAULT" => "Y",
        "FILES" => Array(
            Array("FROM" => "news/components", "TO" => "/bitrix/components"),
            Array("FROM" => "news/public", "TO" => "/news")
        )
    ),

    "articles" => Array(
        "NAME" => "Статьи",
        "DESCRIPTON" => "Статьи",
        "SITE_ID" => Array("blog","homepage"),
        "SELECT_STEPS" => Array(
            "SCRIPT" => "scripts/articles.php",
            "STEPS" => Array(
                "article1" => "ArticleStep1",
                "article2" => "ArticleStep2",
            )
        )
    ),

    "foto" => Array(
        "NAME" => GetMessage("SERVICE_FOTO"),
        "FORM" => Array(
            "TYPE" => "checkbox",
            "DEFAULT" => "Y",
        ),
        "DESCRIPTON" => "Красивая фотогалерея на вашем сайте",
        "SITE_ID" => Array("blog","homepage"),
    ),

    "blog_components" => Array(
        "NAME" => "Компоненты Блога",
        "SITE_ID" => "blog",
        "DESCRIPTON" => "Компоненты Блога",
        "FORM" => Array(
            "TYPE" => "checkbox",
            "DEFAULT" => "Y",
        ),
    ),

    "homepage_components" => Array(
        "NAME" => "Компоненты дом. странички",
        "SITE_ID" => "homepage",
        "FORM" => Array(
            "DEFAULT" => "Y",
            "TYPE" => "checkbox"
        ),
        "DESCRIPTON" => "Компоненты дом. странички",
    ),
);

?>

В файле .services.php определяется массив $arWizardServices, состоящий из элементов следующего вида:

"ID сервиса" => Array(
  "NAME" => имя сервиса,
  "DESCRIPTON" => описание сервиса,
  "ICON" => иконка сервиса, путь к файлу относительно папки мастера,
  "SITE_ID" => ID сайта, к которому принадлежит сервис (одиночное значение или массив)
  "FORM" => массив, описывающий вид элемента Web-формы
   Array(
     "TYPE" => тип элемента Web-формы. Допустимые значения "radio" (переключатель),
     "checkbox" (флажок) и "required" (обязателен для установки).
      По умолчанию равен "checkbox" (флажок),
     "DEFAULT" => если равно "Y", данный сервис будет выбран по умолчанию,
     "GROUP" => ID группы, к которой принадлежит элемент Web-формы.
     Применяется для группировки переключателей (radio) Web-формы.
   ),
  "SELECT_STEPS" => массив, описывающий дополнительные шаги после шага Выбор сервисов
   Array(
     "SCRIPT" => путь к файлу с классами шагов относительно папки мастера
     "STEPS" => массив шагов, добавляемых в мастер
      Array(
        "ID шага 1" => "Имя класса шага 1",
        "ID шага 2" => "Имя класса шага 2",
        …
      )
   )
  "INSTALL_STEPS" => массив, описывающий дополнительные шаги после шага Установка сервиса
   Array(
     "SCRIPT" => путь к файлу с классами относительно папки мастера,
     "STEPS" => массив шагов, добавляемых в мастер
      Array(
        "ID шага 1" => "Имя класса шага 1",
        "ID шага 2" => "Имя класса шага 2",
        …
      )
   ),
  "FILES" => массив, описывающий файлы для копирования/удаления
   Array(
    Array(
      "FROM" => путь к каталогу (файлу) относительно папки мастера,
      содержимое которого нужно скопировать,
      "TO" => путь к файлу или папке относительно корня сайта,
      куда будут скопированы файлы
      "REWRITE" => перезаписывать ли существующие файлы;
      необязательный параметр, по умолчанию равен "Y" (перезаписывать),
      "RECURSIVE" => копировать ли рекурсивно все подкаталоги и файлы,
      входящие в путь, указанный в параметре FROM;
      необязательный параметр, по умолчанию равен "Y" (копировать рекурсивно),
      "DELETE" => путь к папке (файлу), которую нужно удалить
    ),
    …
   )
),


Пользовательские шаги

Несмотря на то, что последовательность шагов в мастере создания сайта фиксированная, имеется возможность вставить между стандартными шагами свои пользовательские шаги. Пользовательские шаги делятся на 2 группы: шаги выбора и шаги установки. Пользовательские шаги выбора – шаги, идущие после шагов Выбор типа сайта, Выбор шаблона, Выбор сервисов. Пользовательские шаги установки – шаги, идущие после шагов Установка сайта, Установка шаблона, Установка сервиса.

В массивах $arWizardSites, $arWizardTemplates, $arWizardServices (файлы .sites.php, .templates.php, .services.php соответственно) для описания пользовательских шагов существуют 2 ключа: "SELECT_STEPS" и "INSTALL_STEPS". Ключ "SELECT_STEPS" описывает пользовательские шаги выбора, "INSTALL_STEPS" – пользовательские шаги установки.

Типичное описание пользовательских шагов:

"SELECT_STEPS" => массив, описывающий дополнительные шаги
Array(
  "SCRIPT" => путь к файлу с классами шагов относительно папки мастера
  "STEPS" => массив шагов, добавляемых в мастер
   Array(
     "ID шага 1" => "Имя класса шага 1",
     "ID шага 2" => "Имя класса шага 2",
     …
   )
)

В файле, указанном в ключе "SCRIPT", необходимо описать (подробнее см. Определение шагов мастера) классы шагов, добавляемых в мастер создания сайта. Число добавляемых шагов неограниченно. Если количество добавляемых шагов превышает один шаг, то необходимо учитывать следующее правило описания пользовательских шагов в ключе "STEPS":

  • Первый элемент массива шагов является первым шагом цепочки пользовательских шагов. Именно на него будет ссылаться кнопка Далее в стандартных шагах.
  • Последний элемент массив является последним шагом цепочки пользовательских шагов. Именно на него будет ссылаться кнопка Назад в стандартных шагах.

Кроме того, шаги Приветствие, Готовность к установке, Установка завершена, Установка прервана можно полностью подменить на собственные пользовательские шаги. Для этого необходимо в ключах CLASS и SCRIPT массива $arWizardDescription указать имя класса и путь к файлу, в котором определён класс, соответственно. Подробнее см. файл описания мастера создания сайта .description.php.


Идентификаторы системных шагов

В пользовательских шагах мастера создания сайта часто бывает необходимо перейти (с помощью метода СWizardBase::SetCurrentStep) на произвольный системный шаг. Ниже представлена таблица идентификаторов системных шагов, которые определяются PHP-константами.

Таблица идентификаторов системных шагов
Константа | Шаг
BX_WIZARD_WELCOME_ID | Приветствие
BX_WIZARD_LICENSE_ID | Лицензионное соглашение
BX_WIZARD_SELECT_SITE_ID | Выбор типа сайта
BX_WIZARD_SELECT_GROUP_ID | Выбор группы шаблонов
BX_WIZARD_SELECT_TEMPLATE_ID | Выбор шаблона сайта
BX_WIZARD_SELECT_SERVICE_ID | Выбор сервисов сайта
BX_WIZARD_START_INSTALL_ID | Готовность к установке
BX_WIZARD_INSTALL_SITE_ID | Установка сайта
BX_WIZARD_INSTALL_TEMPLATE_ID | Установка шаблона
BX_WIZARD_INSTALL_SERVICE_ID | Установка сервисов
BX_WIZARD_FINISH_ID | Установка завершена
BX_WIZARD_CANCEL_ID | Установка прервана

Примеры использования

<?
class MyStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Мой шаг");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();
        $login = $wizard->GetVar("login");

        if ($login == "admin")
        {
            $wizard->SetCurrentStep(BX_WIZARD_START_INSTALL_ID);//Перейдем на шаг Готовность к установке
            return;
        }
    }
}
?>


Создание дистрибутива с решением

Начиная с седьмой версии дистрибутив «1С-Битрикс:Управление сайтом» представляет собой два мастера: мастер установки продукта и мастер установки демо-сайта. Первый устанавливает все модули в минимальной объеме (таблицы базы данных, агенты, события, файлы). Второй - пример сайта, демонстрирующего функциональность продукта.

Для запуска своего мастера создания сайта необходимо добавить в дистрибутив мастер с названием demo. Это мастер может находится как в собственном namespace'е (в подпапке директории /bitrix/wizards/, например, /bitrix/wizards/my_company/demo/) так и непосредственно в папке /bitrix/wizards/.

Для создания дистрибутива со своим решением необходимо выполнить следующее:

1. Изготовить мастер создания сайта, который развернет решение на сайте клиента. Мастер должен иметь название demo. В мастере может находиться лицензия решения.

2. Скачать демо версию или дистрибутив в исходных текстах нужной редакции с сайта 1С-Битрикс. Распаковать архив.

3. В папку /bitrix/wizards/<опциональная подпапка> скопировать свой мастер.

4. Если в решение включаются дополнительные модули, скопировать их в папку /bitrix/modules. Модули должны удовлетворять новым требованиям инсталлятора продукта.

5. В корне дистрибутива создать файл install.config следующей структуры:

<config>
<productName>Название продукта</productName>
<welcomeText>Текст приветствия мастера</welcomeText >
<imageLogoSrc>Путь к логотипу компании относительно корня сайта</imageLogoSrc>
<imageBoxSrc>Путь к изображению коробки продукта относительно корня сайта</imageBoxSrc>
<copyrightText>Текст копирайта</copyrightText>
<supportText> Ссылки на инструкцию по установке и техподдержку </supportText>
</config>

6. Если в этом файле описываются imageLogoSrc и imageBoxSrc, то скопировать эти картинки в указанные папки (можно и на корень). Если текст приветствия включает картинки, их тоже нужно скопировать.

7. Запаковать все файлы в архив нужного формата.

8. Если требуется создать EXE, то:

  • Скачать bitrix_win_installer.zip
  • Распаковать в любую папку
  • Скопировать все файлы проекта в папку solution
  • Запустить run.cmd
  • Изменить все необходимые параметры (если файлы не были скопированы, то указать на папку где они находятся)
  • Нажать иконку "Compile"
  • Готовый дистрибутив будет в папке output
Установка дистрибутива в кодировке UTF-8

Если пользователь устанавливает продукт в кодировке UTF-8, то файлы мастера с расширениями .php, .sql, .js, .snp, .csv конвертируются в кодировку UTF-8. По умолчанию считается, что файлы мастера находятся в кодировке windows-1251. Если файлы мастера созданы в другой кодировке, то необходимо ее прописать в ключе СHARSET массива $arWizardDescription (см. Файл описания мастера создания сайта).


Мастер создания сайта: пользовательские шаги

Примеры

  • Мастер создания нового пользователя
  • Мастер создания сайта: пользовательские шаги
  • Мастер создания сайта: установка шаблона


Мастер создания нового пользователя

Данный пример демонстрирует следующие аспекты программирования мастеров:

  • Обработку входных даннных;
  • Обработку ошибок шага;
  • Javascript-проверку входных данных;
  • Работу с элементами Web-форм;
  • Работу с переменными мастера.
<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MainUserFields extends CWizardStep
{
    function InitStep()
    {
        //ID шага
        $this->SetStepID("main_fields");

        //Заголовок
        $this->SetTitle("Основные поля пользователя");
        $this->SetSubTitle("Введите логин, пароль и e-mail нового пользователя");

        //Навигация
        $this->SetNextStep("additional_fields");
        $this->SetCancelStep("cancel");

        $wizard =& $this->GetWizard(); // Получаем ссылку на объект мастера
        $wizard->SetDefaultVar("active", "Y"); //Устанавливаем значение по умолчанию
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        if ($wizard->IsCancelButtonClick())
            return;

        $login = $wizard->GetVar("login");
        if (strlen($login) < 3)
            $this->SetError("Логин должен быть больше 3 символов", "login");
        else
        {
            $obUser = CUser::GetList($by="id", $order="desc", Array("LOGIN_EQUAL" => $login));
            if ($obUser->Fetch())
                $this->SetError("Такой логин уже существует", "login");
        }

        $password = $wizard->GetVar("password");
        if (strlen($password) < 6)
            $this->SetError("Пароль должен быть не меньше 6 символов", "password");

        $email = $wizard->GetVar("email");
        if (strlen($email) < 3 || !check_email($email))
            $this->SetError("Вы ввели неверный E-mail", "email");
    }

    function ShowStep()
    {
        $this->content .= '<table class="wizard-data-table">';

        $this->content .= '<tr><th align="right">Активен:</th><td>'.$this->ShowCheckBoxField("active", "Y").'</td></tr>';

        $this->content .= '<tr><th align="right"><span class="wizard-required">*</span>Логин (мин. 3 символа):</th><td>';
        $this->content .= $this->ShowInputField("text", "login", Array("size" => 25));
        $this->content .= '</td></tr>';

        $this->content .= '<tr><th align="right"><span class="wizard-required">*</span>Пароль (мин. 6 символов):</th><td>';
        $this->content .= $this->ShowInputField("password", "password", Array("size" => 25));
        $this->content .='</td></tr>';

        $this->content .= '<tr><th align="right"><span class="wizard-required">*</span>E-mail:</th><td>';
        $this->content .= $this->ShowInputField("text", "email", Array("size" => 25));
        $this->content .= '</td></tr>';

        $this->content .= '<tr><th align="right">Имя:</th><td>'.$this->ShowInputField("text", "user_name", Array("size" => 25)).'</td></tr>';
        $this->content .= '<tr><th align="right">Фамилия:</th><td>'.$this->ShowInputField("text", "user_surname", Array("size" => 25)).'</td></tr>';

        $this->content .= '</table>';
        $this->content .= '<br /><div class="wizard-note-box"><span class="wizard-required">*</span> Поля, обязательные для заполнения.</div>';

        $wizard =& $this->GetWizard();
        $formName = $wizard->GetFormName();
        $nextButton = $wizard->GetNextButtonID();

        $login = $wizard->GetRealName("login");
        $password = $wizard->GetRealName("password");
        $email = $wizard->GetRealName("email");

        $this->content .= <<<JS
            <script type="text/javascript">

                function CheckMainFields()
                {
                    var form = document.forms["{$formName}"];
                    if (!form)
                        return;

                    var login = form.elements["{$login}"].value;
                    var password = form.elements["{$password}"].value;
                    var email = form.elements["{$email}"].value;

                    var error = "";

                    if (login.length < 3)
                        error += "Логин должен быть больше 3 символов.\\n";

                    if (password.length < 6)
                        error += "Пароль должен быть не меньше 6 символов.\\n";

                    if (email.length < 3)
                        error += "Вы ввели неверный E-mail.\\n";

                    if (error.length > 0)
                    {
                        alert(error);
                        return false;
                    }
                }

                function AttachEvent()
                {
                    var form = document.forms["{$formName}"];
                    if (!form)
                        return;

                    var nextButton = form.elements["{$nextButton}"];
                    if (!nextButton)
                        return;

                    nextButton.onclick = CheckMainFields;

                }

                if (window.addEventListener)
                    window.addEventListener("load", AttachEvent, false);
                else if (window.attachEvent)
                    window.attachEvent("onload", AttachEvent);
                //setTimeout(AttachEvent, 500);
            </script>
JS;
    }
}

class AddtionalUserFields extends CWizardStep
{
    function InitStep()
    {
        //ID шага
        $this->SetStepID("additional_fields");

        //Заголовок
        $this->SetTitle("Дополнительные поля пользователя");
        $this->SetSubTitle("Введите дополнительные поля нового пользователя");

        //Навигация
        $this->SetPrevStep("main_fields");
        $this->SetNextStep("user_summary");
        $this->SetCancelStep("cancel");

        $wizard =& $this->GetWizard();
        $wizard->SetDefaultVar("group_id", "2");
    }

    function OnPostForm()
    {
        $this->SaveFile("photo", Array("max_file_size" => 1024*50, "extensions" => "gif,jpg,png"));
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        $this->content .= '<table class="wizard-data-table">';

        $this->content .= '<tr><th align="right">Пол:</th><td>';
        $this->content .= $this->ShowRadioField("sex", "M", Array("id" => "sex_m")).'<label for="sex_m">Мужской</lable>';
        $this->content .= $this->ShowRadioField("sex", "F", Array("id" => "sex_f")).'<label for="sex_f">Женский</lable>';
        $this->content .= '</td></tr>';

        $this->content .= '<tr><th align="right">Фото<br />(max. 50кб, <br />JPG, GIF, PNG):</th><td>';
        $this->content .= $this->ShowFileField("photo", Array("size" => 25, "max_file_size" => 1024*50));
        $this->content .= "<br />".CFile::ShowImage($wizard->GetVar("photo"), 150, 150, "border=0", "", true);
        $this->content .= '</td></tr>';

        $obGroup = CGroup::GetList($by="name", $order="asc");
        $arSelectGroup = Array();
        while ($arGroup = $obGroup->Fetch())
            $arSelectGroup[$arGroup["ID"]] = htmlspecialchars($arGroup["NAME"]);

        $this->content .= '<tr><th align="right" valign="top">Группа:</th><td>';
        $this->content .= $this->ShowSelectField("group_id[]", $arSelectGroup , Array("multiple" => "multiple", "size" => "10"));
        $this->content .= '</td></tr>';

        $this->content .= '</table>';
    }
}

class UserSummary extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("user_summary");

        //Заголовок
        $this->SetTitle("Создание пользователя");
        $this->SetSubTitle("Нажмите кнопку <i>Создать</i>, чтобы добавить нового пользователя");

        //Навигация
        $this->SetPrevStep("additional_fields");
        $this->SetNextStep("success");
        $this->SetNextCaption("Создать");
        $this->SetCancelStep("cancel");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        if (!$wizard->IsNextButtonClick())
            return;

        //Добавляем пользователя
        $user = new CUser;
        $arFields = Array(
            "NAME" => $wizard->GetVar("user_name"),
            "LAST_NAME" => $wizard->GetVar("user_surname"),
            "EMAIL" => $wizard->GetVar("email"),
            "LOGIN" => $wizard->GetVar("login"),
            "ACTIVE" => ($wizard->GetVar("active") == "Y" ? "Y" : "N"),
            "GROUP_ID" => $wizard->GetVar("group_id"),
            "PASSWORD" => $wizard->GetVar("password"),
            "CONFIRM_PASSWORD" => $wizard->GetVar("password"),
            "PERSONAL_GENDER" => $wizard->GetVar("sex")
        );

        $photo = intval($wizard->GetVar("photo"));
        if ($photo > 0)
            $arFields["PERSONAL_PHOTO"] = CFile::MakeFileArray($photo) + Array("MODULE_ID" => "main");

        $userID = $user->Add($arFields);
        if (intval($userID) > 0)
        {
            $wizard->SetVar("userID", $userID);
            CFile::Delete($photo); //Удаляем временный файл
        }
        else
            $this->SetError($user->LAST_ERROR);
    }

    function ShowStep()
    {
        $this->content .= "Текущие настройки:<br /><br />";

        $wizard =& $this->GetWizard();

        $this->content .= "<i>Логин</i>: ".htmlspecialchars($wizard->GetVar("login"))."<br />";
        $this->content .= "<i>E-mail</i>: ".htmlspecialchars($wizard->GetVar("email"))."<br />";

        $user_name = $wizard->GetVar("user_name");
        if (strlen($user_name) > 0)
            $this->content .= "<i>Имя</i>: ".htmlspecialchars($user_name)."<br />";

        $user_surname = $wizard->GetVar("user_surname");
        if (strlen($user_surname) > 0)
            $this->content .= "<i>Фамилия</i>: ".htmlspecialchars($user_surname)."<br />";

        $sex = $wizard->GetVar("sex");
        if (strlen($sex) > 0)
            $this->content .= "<i>Пол</i>: ".($sex == "M" ? "Мужской": "Женский")."<br />";

        $photo = $wizard->GetVar("photo");
        if (intval($photo) > 0)
        {
            $this->content .= "<i>Фото</i>:<br />";
            $this->content .= CFile::ShowImage($photo, 150, 150, "border=0", "", true);
        }
    }
}

class SuccessStep extends CWizardStep
{
    function InitStep()
    {
        //ID шага
        $this->SetStepID("success");

        //Заголовок
        $this->SetTitle("Работа мастера успешно завершена");

        //Навигация
        $this->SetCancelStep("success");
        $this->SetCancelCaption("Готово");
    }

    function ShowStep()
    {
        $this->content .= "Мастер успешно добавил нового пользователя. ";

        $wizard =& $this->GetWizard();
        $userID = intval($wizard->GetVar("userID"));
        if ($userID > 0)
            $this->content .= 'Идентификатор нового пользователя <a target="_blank" href="/bitrix/admin/user_edit.php?ID='.$userID.'&lang='.LANGUAGE_ID.'">'.$userID.'</a>';
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Мастер прерван");
        $this->SetStepID("cancel");
        $this->SetCancelStep("cancel");
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Мастер создания нового пользователя прерван. Новый пользователь не был создан.";
    }
}
?>

Статическое определение шагов в файле .description.php:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мастер создания нового пользователя",
    "STEPS" => Array("MainUserFields", "AddtionalUserFields", "UserSummary", "SuccessStep", "CancelStep")
);
?>

Или динамическое определение в файле wizard.php:

<?
$wizard = new CWizardBase("Мастер создания нового пользователя", $package);
$wizard->AddSteps(Array("MainUserFields", "AddtionalUserFields", "UserSummary", "SuccessStep", "CancelStep"));
$wizard->Display();
?>


Мастер создания сайта: установка шаблона

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

1. Создайте директорию my_site_master в папке /bitrix/wizards/.

2. Поместите в папку my_site_master файл .description.php со следующим содержимым:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мастер создания сайта: установка шаблона",
);

?>

3. В директории мастера создайте папку templates и скопируйте в нее несколько шаблонов сайта (например, шаблоны сайта из демо-версии).

Мастер готов. Система сама "на лету" сгенерирует необходимые шаги.
Скачать пример


Мастер создания сайта: пользовательские шаги

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

1. Скопируйте папку мастера установки шаблона в новую директорию, например, в my_site_master_pro.

2. Измените название нового мастера в файле .description.php и добавьте ключ STEPS_SETTINGS для кастомизации стандартных заголовков:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мастер создания сайта: пользовательские шаги",
    "STEPS_SETTINGS" => Array(
        "WELCOME" => Array(
            "TITLE" => "Добро пожаловать в мастер создания сайта",
            "SUBTITLE" => "Нажмите кнопку <i>Далее</i> для выбора шаблонов",
            "CONTENT" => "Данный мастер демонстрирует работу с пользовательскими шагами",
        ),

        "SELECT_TEMPLATE" => Array(
            "TITLE" => "Шаблоны вашего сайта",
        ),
    ),
);
?>

3. Кроме выбора шаблона сайта пользователю будет предоставлена возможность адаптировать дизайн: например, изменить название и заголовок. В шаблонах мастера слоган и название сайта находятся в файле include_areas/company_name.php (относительно папки шаблона):

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>
  <h1>Моя компания</h1>
    <span>Слоган компании</span>

Замените названия в этом в файле на соответствующие макросы:

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>
  <h1>#COMPANY_NAME#</h1>
    <span>#COMPANY_SLOGAN#</span>

4. Создайте файл customize.php в папке мастера со следующим содержимым:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

class CustomizeSiteData extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Данные сайта");
        $this->SetSubTitle("Настройка данных сайта");

        $wizard =& $this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "company_name" => "Моя компания",
                "company_slogan" => "Быстро. Просто. Эффективно",
            )
        );
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        $this->content .= "Укажите название вашего сайта, слоган, адрес сайта и загрузите свой логотип.
                Название, слоган и логотип будут размещены вверху на всех страницах сайта.<br /><br />";

        $this->content .= '<table class="wizard-data-table"><tr>';
        $this->content .= "<td>Название сайта (компании):</td>";
        $this->content .= "<td>".$this->ShowInputField("text", "company_name", Array("size" => "35"))."</td>";
        $this->content .= "</tr>";

        $this->content .= "<tr><td>Слоган компании:</td>";
        $this->content .= "<td>".$this->ShowInputField("text", "company_slogan", Array("size" => "35"))."</td>";
        $this->content .= "</tr>";

        $this->content .= "</table>";

    }
}

class InstallTemplateData extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Установка данных шаблона...");
        $this->SetAutoSubmit();
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $templateID = $package->GetSiteTemplateID(); //ID выбранного шаблона
        $templatePath = BX_PERSONAL_ROOT."/templates/".$templateID;

        $arReplace = Array(
            "COMPANY_NAME" => $wizard->GetVar("company_name"),
            "COMPANY_SLOGAN" => $wizard->GetVar("company_slogan"),
        );

        CWizardUtil::ReplaceMacros($_SERVER["DOCUMENT_ROOT"].$templatePath."/include_areas/company_name.php", $arReplace);
    }

    function ShowStep()
    {
        $this->content .= "Установка данных шаблона...";
    }
}
?>

Этот файл определяет 2 пользовательских шага: шаг выбора и шаг установки. Первый предлагает пользователю ввести название и слоган сайта, второй - заменяет макросы в файле include_areas/company_name.php на нужные значения.

5. Наконец, в файле .description.php необходимо описать пользовательские шаги:

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

$arWizardTemplates = Array(

    "TEMPLATES" => Array(
        "web20" => Array(
            "SELECT_STEPS" => Array(
                "SCRIPT" => "customize.php",
                "STEPS" => Array(
                    "customize_data" => "CustomizeSiteData",
                )
            ),

            "INSTALL_STEPS" => Array(
                "SCRIPT" => "customize.php",
                "STEPS" => Array(
                    "install_template_data" => "InstallTemplateData",
                )
            ),
        ),

        "xml_catalog" => Array(
            "SELECT_STEPS" => Array(
                "SCRIPT" => "customize.php",
                "STEPS" => Array(
                    "customize_data" => "CustomizeSiteData",
                )
            ),

            "INSTALL_STEPS" => Array(
                "SCRIPT" => "customize.php",
                "STEPS" => Array(
                    "install_template_data" => "InstallTemplateData",
                )
            ),
        ),

        "books" => Array(
            "SELECT_STEPS" => Array(
                "SCRIPT" => "customize.php",
                "STEPS" => Array(
                    "customize_data" => "CustomizeSiteData",
                )
            ),

            "INSTALL_STEPS" => Array(
                "SCRIPT" => "customize.php",
                "STEPS" => Array(
                    "install_template_data" => "InstallTemplateData",
                )
            ),
        ),
    )
);

?>

Пользовательские шаги у каждого шаблона могут быть разные, но в данном случае они у всех шаблонов совпадают.
Скачать пример


Классы

  • CWizard
  • CWizardStep
  • CWizardTemplate
  • CWizardUtil
  • СWizardBase


Класс CWizard

Класс CWizard позволяет запускать мастера из общего репозитария, а также поддерживает механизм мастера создания сайта. Для того чтобы использовать методы класса CWizard в теле переопределяемых функций (InitStep, ShowStep, OnPostFrom), нужно получить объект класса CWizard с помощью метода CWizardBase::GetPackage:

<?
class MyClass extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step01");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на мастер
        $package =& $wizard->GetPackage(); //Получаем ссылку на объект класса CWizard

        $this->content .= "ID мастера:".$package->GetID(); //Используем метод класса CWizard
    }
}
?>

См. также

  • Конструктор CWizard
  • CWizardBase::GetPackage
  • Физическое расположение мастеров


Конструктор СWizard

CWizard::Конструктор СWizard

CWizard(
 string wizardID
);

Создает объект класса CWizard.

Параметры функции

Параметр | Описание
wizardID | Полное имя мастера.

См. также

  • Класс CWizard
  • CWizard::Install
  • Физическое расположение мастеров

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

$wizard = new CWizard("help:condition");
$wizard->Install();

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


GetDescription

CWizard::GetDescription

array
GetDescription();

Метод возвращает массив $arWizardDescription из файла описания .description.php.

См. также

  • CWizard::GetTemplates
  • CWizard::GetTemplateGroups
  • CWizard::GetServices

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetErrors

CWizard::GetErrors

array
GetErrors();

Метод возвращает массив ошибок мастера.

См. также

  • CWizard::SetError


GetID

CWizard::GetID

string
GetID();

Метод возвращает полное имя мастера.

См. также

  • Физическое расположение мастеров
  • CWizard::GetPath

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetPath

CWizard::GetPath

string
GetPath();

Метод возвращает путь к текущему мастеру относительно корня сайта.

См. также

  • Физическое расположение мастеров
  • CWizard::GetID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetServices

CWizard::GetServices

array
GetServices(
 array arFilter = Array()
);

Если текущий мастер является мастером создания сайта, метод вернет массив сервисов по фильтру arFilter.

Параметры функции

Параметр Описание
arFilter Массив вида Array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • SITE_ID - ID типа сайта.
Необязательный параметр, по умолчанию сервисы не фильтруются.

См. также

  • Файл описания сервисов сайта .services.php
  • CWizard::GetDescription
  • CWizard::GetTemplates
  • CWizard::GetTemplateGroups

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetSiteGroupID

CWizard::GetSiteGroupID

mixed
GetSiteGroupID();

Если текущий мастер является мастером создания сайта, метод вернет ID выбранной группы шаблонов, иначе вернет null.

См. также

  • CWizard::GetSiteID
  • CWizard::GetSiteServiceID
  • CWizard::GetSiteTemplateID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetSiteID

CWizard::GetSiteID

mixed
GetSiteID();

Если текущий мастер является мастером создания сайта, метод вернет ID выбранного типа сайта, иначе вернет null.

См. также

  • CWizard::GetSiteGroupID
  • CWizard::GetSiteServiceID
  • CWizard::GetSiteTemplateID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetSiteServiceID

CWizard::GetSiteServiceID

mixed
GetSiteServiceID();

Если текущий мастер является мастером создания сайта, метод вернет массив ID выбранных сервисов, иначе вернет пустой массив Array().

См. также

  • CWizard::GetSiteID
  • CWizard::GetSiteGroupID
  • CWizard::GetSiteTemplateID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetSiteTemplateID

CWizard::GetSiteTemplateID

mixed
GetSiteTemplateID();

Если текущий мастер является мастером создания сайта, метод вернет ID выбранного шаблона сайта, иначе вернет null.

См. также

  • CWizard::GetSiteID
  • CWizard::GetSiteGroupID
  • CWizard::GetSiteServiceID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetTemplateGroups

CWizard::GetTemplateGroups

array
GetTemplateGroups(
 array arFilter = Array()
);

Если текущий мастер является мастером создания сайта, метод вернет массив групп шаблонов сайта по фильтру arFilter.

Параметры функции

Параметр Описание
arFilter Массив вида Array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • SITE_ID - ID типа сайта.
Необязательный параметр, по умолчанию группы шаблонов сайта не фильтруются.

См. также

  • Файл описания шаблонов сайта .templates.php
  • CWizard::GetDescription
  • CWizard::GetTemplates
  • CWizard::GetServices

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив групп шаблонов:<pre>".print_r($package->GetTemplateGroups(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


GetTemplates

CWizard::GetTemplates

array
GetTemplates(
 array arFilter = Array()
);

Если текущий мастер является мастером создания сайта, метод вернет массив шаблонов сайта по фильтру arFilter.

Параметры функции

Параметр Описание
arFilter Массив вида Array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • SITE_ID - ID типа сайта;
  • GROUP_ID - ID группы шаблона сайта;
Необязательный параметр, по умолчанию шаблоны сайта не фильтруются.

См. также

  • Файл описания шаблонов сайта .templates.php
  • CWizard::GetDescription
  • CWizard::GetTemplateGroups
  • CWizard::GetServices

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class MyStartInstall extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбранные параметры");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        $this->content .= "Полное имя мастера: ".$package->GetID()."<br />";
        $this->content .= "Путь к папке мастера: ".$package->GetPath()."<br />";
        $this->content .= "ID выбранного шаблона: ".$package->GetSiteTemplateID()."<br />";
        $this->content .= "ID выбранной группы шаблонов: ".$package->GetSiteGroupID()."<br />";
        $this->content .= "ID выбранного сайта: ".$package->GetSiteID()."<br />";
        $this->content .= "Массив ID сервисов: ".print_r($package->GetSiteServiceID(), true)."<br />";
        $this->content .= "Массив шаблонов мастера:<pre>".print_r($package->GetTemplates(), true)."</pre>";
        $this->content .= "Массив описания мастера:<pre>".print_r($package->GetDescription(), true)."</pre>";
        $this->content .= "Массив сервисов мастера:<pre>".print_r($package->GetServices(), true)."</pre>";
    }
}

?>


IncludeWizardLang

CWizard::IncludeWizardLang

void
IncludeWizardLang(
 string relativePath = "",
 bool lang = false
);

Метод подключает языковой файл для скрипта, путь к которому передается в параметре relativePath.

Параметры функции

Параметр | Описание
relativePath | Путь к файлу (относительно папки мастера), для которого необходимо подключить языковой файл.
lang | Идентификатор языка. Необязательный параметр, по умолчанию равен false (текущий язык).

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $package =& $wizard->GetPackage();

        //Подключаем произвольный файл переводов
        $package->IncludeWizardLang("lang.php");

        $this->SetTitle(GetMessage("TITLE"));
        $this->SetStepID("first");
    }
}
?>


Install

CWizard::Install

string
Install();

Метод запускает мастер и выводит его на экран.

См. также

  • Конструктор CWizard
  • Запуск мастера

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

$wizard = new CWizard("help:condition");
$wizard->Install();

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


SetError

CWizard::SetError

void
SetError(
 string strError,
 bool id = false
);

Метод устанавливает ошибку мастера с текстом strError и идентификатором id. Если мастер содержит ошибки, то его запуск невозможен (на экран выйдет сообщение об ошибках).

Параметры функции

Параметр | Описание
strError | Текст ошибки.
id | Идентификатор ошибки. Необязательный параметр, по умолчанию равен false.

См. также

  • CWizard::GetErrors

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

$wizard = new CWizard("help:condition");

$hour = date("G");
if ($hour < 16 || $hour >= 20)
    $wizard->SetError("Запуск мастера возможен только c 16 до 20");

$wizard->Install();

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


Класс CWizardBase

Класс СWizardBase является оболочкой мастера и содержит методы общие для всех шагов (работа с переменными мастера, управление кнопками навигации и др.). Для каждого подключаемого мастера создаётся экземпляр класса СWizardBase. Для получения доступа к методам класса СWizardBase в теле переопределяемых функций (InitStep, ShowStep, OnPostFrom) нужно получить объект мастера с помощью метода CWizardStep::GetWizard:

<?
class MyFirstStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
        $myVar = $wizard->GetVar("myVar"); //Используем метод мастера (класс CWizardBase)
    }
}
?>


Конструктор CWizardBase

СWizardBase::Конструктор CWizardBase

CWizardBase(
 string wizardName,
 object &package
);

Создает объект класса CWizardBase.

Параметры функции

Параметр | Описание
wizardName | Имя создаваемого мастера.
&package | Объект класса СWizard. В файле wizard.php определена переменная $package, которая содержит ссылку на объект класса CWizard.

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step22");
    }

}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step22");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1");
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step3");
        $this->SetPrevStep("step22");
        $this->SetTitle("Третий шаг");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3"));

//Выводим на экран
$wizard->Display();
?>


AddStep

СWizardBase::AddStep

void
AddStep(
 object &obStep,
 mixed stepID = null
);

Метод добавляет в мастер новый шаг.

Параметры функции

Параметр | Описание
&obStep | Экземпляр класса, определяющего шаг мастера.
stepID | ID добавляемого шага. Переопределяет ID шага, установленного с помощью метода SetStepID в функции InitStep. Необязательный параметр, по умолчанию равен null.

См. также

  • Определение шагов мастера
  • CWizardBase::AddSteps
  • CWizardStep::SetStepID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step22");
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2"); //Переопределяется в AddStep
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1");
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step22");
        $this->SetTitle("Третий шаг");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddStep(new Step1); // Шаг Step1 имеет ID = step1
$wizard->AddStep(new Step2, "step22"); // Шаг Step2 имеет ID = step22
$wizard->AddStep(new Step3, "step3"); // Шаг Step3 имеет ID = step3

//Выводим на экран
$wizard->Display();
?>


AddSteps

СWizardBase::AddSteps

void
AddSteps(
 array arClasses
);

Метод добавлет шаги в мастер.

Параметры функции

Параметр | Описание
arClasses | Массив с названиями классов, определяющих шаги.

См. также

  • Определение шагов мастера
  • CWizardBase::AddStep

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step22");
    }

}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step22");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1");
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step3");
        $this->SetPrevStep("step22");
        $this->SetTitle("Третий шаг");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3"));

//Выводим на экран
$wizard->Display();
?>


DisableAdminTemplate

СWizardBase::DisableAdminTemplate

void
DisableAdminTemplate();

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

См. также

  • CWizardBase::SetTemplate
  • Шаблон мастера

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step2");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1");
        $this->SetCancelStep("cancel");
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetCancelStep("cancel");
        $this->SetTitle("Третий шаг");
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

//Красный шаблон мастера
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Запретим применять системный шаблон по умолчанию
//при запуске мастера из административного раздела
$wizard->DisableAdminTemplate();

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "CancelStep"));

//Определим для всех шагов красный шаблон
$wizard->SetTemplate(new MyRedTemplate);

//Выводим на экран
$wizard->Display();
?>


Display

СWizardBase::Display

mixed
Display();

Метод выводит содержимое мастера на экран. Если с помощью метода CWizardBase::SetReturnOutput флаг возврата установлен в значение true, метод Display возвратит весь вывод мастера.

См. также

  • CWizardBase::SetReturnOutput

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step2");
    }

}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2");
        $this->SetPrevStep("step1");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2"));

//Выводим на экран
$wizard->Display();
?>

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step2");
    }

}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2");
        $this->SetPrevStep("step1");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2"));

//Устанавливаем флаг возврата
$wizard->SetReturnOutput();

//Получаем вывод мастера
$output = $wizard->Display();

/*здесь можно обработать вывод мастера*/

//Выводим на экран
echo $output;
?>


GetCancelButtonID

СWizardBase::GetCancelButtonID

string
GetCancelButtonID();

Возвращает значение атрибута name кнопки Отмена.

См. также

  • CWizardBase::SetCancelButtonID

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}
?>


GetCancelStepID

СWizardBase::GetCancelStepID

mixed
GetCancelStepID();

Возвращает ID шага, на который ссылается кнопка Отмена. Если кнопка Отмена не установлена, метод возвращает null.

См. также

  • CWizardBase::GetCancelButtonID


GetCurrentStep

СWizardBase::GetCurrentStep

object &
GetCurrentStep();

Метод возвращает ссылку на объект текущего шага.

См. также

  • CWizardBase::GetCurrentStepID
  • CWizardBase::SetCurrentStep
  • CWizardBase::SetFirstStep

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}
?>


GetCurrentStepID

СWizardBase::GetCurrentStepID

string
GetCurrentStepID();

Метод возвращает ID текущего шага.

См. также

  • CWizardBase::GetCurrentStep
  • CWizardBase::SetCurrentStep
  • CWizardBase::SetFirstStep


GetDefaultVar

СWizardBase::GetDefaultVar

mixed
GetDefaultVar(
 string varName
);

Метод возвращает значение по умолчанию для переменной varName. Если для varName значение по умолчанию не установлено, метод вернет null.

Параметры функции

Параметр | Описание
varName | Имя переменной, для которой необходимо получить значение по умолчанию. Имя переменной может быть составным, например, myvar[key].

См. также

  • CWizardBase:GetDefaultVars
  • CWizardBase:SetDefaultVar
  • CWizardBase:SetDefaultVars

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


GetDefaultVars

СWizardBase::GetDefaultVars

array
GetDefaultVars();

Метод возвращает массив со значениями по умолчанию для всех переменных.

См. также

  • CWizardBase:GetDefaultVar
  • CWizardBase:SetDefaultVar
  • CWizardBase:SetDefaultVars

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


GetFinishButtonID

СWizardBase::GetFinishButtonID

string
GetFinishButtonID();

Метод возвращает значение атрибута name кнопки Готово.

См. также

  • CWizardBase::SetFinishButtonID

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}
?>


GetFinishStepID

СWizardBase::GetFinishStepID

mixed
GetFinishStepID();

Возвращает ID шага, на который ссылается кнопка Готово. Если кнопка Готово не установлена, метод возвращает null.

См. также

  • CWizardBase::GetFinishButtonID


GetFormActionScript

СWizardBase::GetFormActionScript

string
GetFormActionScript();

Метод возвращает значение атрибута action формы мастера (тега <form>).

См. также

  • CWizardBase::SetFormActionScript


GetFormName

СWizardBase::GetFormName

string
GetFormName();

Метод возвращает значение атрибута name формы мастера (тега <form>).

См. также

  • CWizardBase::SetFormName
  • CWizardBase::GetFormActionScript

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}
?>


GetNextButtonID

СWizardBase::GetNextButtonID

string
GetNextButtonID();

Метод возвращает значение атрибута name кнопки Далее.

См. также

  • CWizardBase::SetNextButtonID

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

?>


GetNextStepID

СWizardBase::GetNextStepID

mixed
GetNextStepID();

Возвращает ID шага, на который ссылается кнопка Далее. Если кнопка Далее не установлена, метод возвращает null.

См. также

  • CWizardBase::GetNextButtonID


GetPackage

СWizardBase::GetPackage

object &
GetPackage();

Метод возвращает ссылку на объект класса CWizard.

См. также

  • Класс CWizard

Примеры использования

<?
class MyClass extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step01");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на мастер
        $package =& $wizard->GetPackage(); //Получаем ссылку на объект класса CWizard

        $this->content .= "ID мастера:".$package->GetID(); //Используем метод класса CWizard
    }
}
?>


GetPrevButtonID

СWizardBase::GetPrevButtonID

string
GetPrevButtonID();

Метод возвращает значение атрибута name кнопки Назад.

См. также

  • CWizardBase::GetPrevButtonID

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

?>


GetPrevStepID

СWizardBase::GetPrevStepID

mixed
GetPrevStepID();

Возвращает ID шага, на который ссылается кнопка Назад. Если кнопка Назад не установлена, метод возвращает null.

См. также

  • CWizardBase::GetPrevButtonID


GetRealName

СWizardBase::GetRealName

string
GetRealName(
 string varName
);

Метод возвращает имя переменной с префиксом. Имя с префиксом необходимо для того, чтобы названия переменных мастера не пересекались с названиями других переменных страницы. По умолчанию префикс для переменных мастера установлен в значение __wiz_.

Параметры функции

Параметр | Описание
varName | Имя переменной, для которой необходимо получить реальное (с префиксом) имя. Имя переменной может быть составным, например, myvar[key].

См. также

  • CWizardBase::GetVarPrefix
  • CWizardBase::SetVarPrefix


GetVar

СWizardBase::GetVar

mixed
GetVar(
 string varName,
 bool useDefault = false
);

Метод возвращает значение переменной varName. Если значение для переменной varName не установлено и параметр useDefault установлен в значение true, метод возвратит значение переменной по умолчанию, иначе возвратит null.

Параметры функции

Параметр | Описание
varName | Имя переменной, значение которой необходимо получить. Имя переменной может быть составным, например, myvar[key].
useDefault | Использовать значение по умолчанию, если значение переменной не установлено. Необязательный параметр, по умолчанию равен false (не использовать значение по умолчанию).

См. также

  • CWizardBase::GetVars
  • CWizardBase::SetVar
  • CWizardBase::UnSetVar

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


GetVarPrefix

СWizardBase::GetVarPrefix

string
GetVarPrefix();

Метод возвращает префикс для переменных мастера. Имя с префиксом необходимо для того, чтобы названия переменных мастера не пересекались с названиями других переменных страницы. По умолчанию префикс для переменных мастера установлен в значение __wiz_.

См. также

  • CWizardBase::GetRealName
  • CWizardBase::SetVarPrefix


GetVars

СWizardBase::GetVars

void
GetVars(
 bool useDefault = false
);

Метод возвращает массив значений всех переменных мастера. Если параметр useDefault установлен в значение true, то переменные, значения для которых не установлены, будут иметь значения по умолчанию.

Параметры функции

Параметр | Описание
useDefault | Устанавливать значения по умолчанию. Необязательный параметр, по умолчанию равен false.

См. также

  • CWizardBase::GetVar
  • CWizardBase::SetVar
  • CWizardBase::UnSetVar

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


GetWizardName

СWizardBase::GetWizardName

string
GetWizardName();

Метод возвращает название мастера.

См. также

  • Конструктор CWizardBase

Примеры использования

<?
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

?>


IsCancelButtonClick

СWizardBase::IsCancelButtonClick

bool
IsCancelButtonClick();

Метод возвращает true, если была нажата кнопка Отмена, иначе false.

См. также

  • CWizardBase::IsNextButtonClick
  • CWizardBase::IsPrevButtonClick
  • CWizardBase::IsFinishButtonClick

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");

        $this->SetNextStep("second");
        $this->SetPrevStep("second");
        $this->SetFinishStep("second");
        $this->SetCancelStep("second");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        $code = $wizard->GetVar("code");

        if (strlen($code) <= 0)
            return;

        if ($code == "xxx")
            $this->SetError("Вы ввели запрещённый код", "code");

        if ($wizard->IsNextButtonClick() && $code == "aaa")
            $wizard->SetCurrentStep("first");
        elseif ($wizard->IsPrevButtonClick() && $code == "bbb")
            $wizard->SetCurrentStep("third");
        elseif ($wizard->IsFinishButtonClick() && $code == "ccc")
            $wizard->SetCurrentStep("fourth");
        elseif ($wizard->IsCancelButtonClick() && $code == "ddd")
            $wizard->SetCurrentStep("first");
    }

    function ShowStep()
    {
        $this->content .= '<div class="wizard-note-box">Следующий шаг мастера зависит от введенного кода и нажатой кнопки.</div><br />';
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
        $this->content .= <<<HTML

        <br /><br />Подсказка:<br />
        <table class="wizard-data-table">
                <tr>
                    <th>Кнопка навигации</th>
                    <th>Код</th>
                    <th>Результат</th>
                </tr>
                <tr>
                    <td>Далее</td>
                    <td>aaa</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>Назад</td>
                    <td>bbb</td>
                    <td>Шаг 3</td>
                </tr>
                <tr>
                    <td>Готово</td>
                    <td>ccc</td>
                    <td>Шаг 4</td>
                </tr>
                <tr>
                    <td>Отмена</td>
                    <td>ddd</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>любая</td>
                    <td>xxx</td>
                    <td>ошибка</td>
                </tr>
                <tr>
                    <td colspan="2">любые другие значения</td>
                    <td>Шаг 2</td>
                </tr>
        </table>
HTML;
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetCancelStep("fourth");
    }
}
?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

$wizard = new CWizardBase("Мой мастер", $package);
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));
$wizard->Display();


IsFinishButtonClick

СWizardBase::IsFinishButtonClick

bool
IsFinishButtonClick();

Метод возвращает true, если была нажата кнопка Готово, иначе false.

См. также

  • CWizardBase::IsNextButtonClick
  • CWizardBase::IsPrevButtonClick
  • CWizardBase::IsCancelButtonClick

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");

        $this->SetNextStep("second");
        $this->SetPrevStep("second");
        $this->SetFinishStep("second");
        $this->SetCancelStep("second");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        $code = $wizard->GetVar("code");

        if (strlen($code) <= 0)
            return;

        if ($code == "xxx")
            $this->SetError("Вы ввели запрещённый код", "code");

        if ($wizard->IsNextButtonClick() && $code == "aaa")
            $wizard->SetCurrentStep("first");
        elseif ($wizard->IsPrevButtonClick() && $code == "bbb")
            $wizard->SetCurrentStep("third");
        elseif ($wizard->IsFinishButtonClick() && $code == "ccc")
            $wizard->SetCurrentStep("fourth");
        elseif ($wizard->IsCancelButtonClick() && $code == "ddd")
            $wizard->SetCurrentStep("first");
    }

    function ShowStep()
    {
        $this->content .= '<div class="wizard-note-box">Следующий шаг мастера зависит от введенного кода и нажатой кнопки.</div><br />';
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
        $this->content .= <<<HTML

        <br /><br />Подсказка:<br />
        <table class="wizard-data-table">
                <tr>
                    <th>Кнопка навигации</th>
                    <th>Код</th>
                    <th>Результат</th>
                </tr>
                <tr>
                    <td>Далее</td>
                    <td>aaa</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>Назад</td>
                    <td>bbb</td>
                    <td>Шаг 3</td>
                </tr>
                <tr>
                    <td>Готово</td>
                    <td>ccc</td>
                    <td>Шаг 4</td>
                </tr>
                <tr>
                    <td>Отмена</td>
                    <td>ddd</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>любая</td>
                    <td>xxx</td>
                    <td>ошибка</td>
                </tr>
                <tr>
                    <td colspan="2">любые другие значения</td>
                    <td>Шаг 2</td>
                </tr>
        </table>
HTML;
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetCancelStep("fourth");
    }
}
?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

$wizard = new CWizardBase("Мой мастер", $package);
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));
$wizard->Display();


IsNextButtonClick

СWizardBase::IsNextButtonClick

bool
IsNextButtonClick();

Метод возвращает true, если была нажата кнопка Далее, иначе false.

См. также

  • CWizardBase::IsPrevButtonClick
  • CWizardBase::IsFinishButtonClick
  • CWizardBase::IsCancelButtonClick

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");

        $this->SetNextStep("second");
        $this->SetPrevStep("second");
        $this->SetFinishStep("second");
        $this->SetCancelStep("second");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        $code = $wizard->GetVar("code");

        if (strlen($code) <= 0)
            return;

        if ($code == "xxx")
            $this->SetError("Вы ввели запрещённый код", "code");

        if ($wizard->IsNextButtonClick() && $code == "aaa")
            $wizard->SetCurrentStep("first");
        elseif ($wizard->IsPrevButtonClick() && $code == "bbb")
            $wizard->SetCurrentStep("third");
        elseif ($wizard->IsFinishButtonClick() && $code == "ccc")
            $wizard->SetCurrentStep("fourth");
        elseif ($wizard->IsCancelButtonClick() && $code == "ddd")
            $wizard->SetCurrentStep("first");
    }

    function ShowStep()
    {
        $this->content .= '<div class="wizard-note-box">Следующий шаг мастера зависит от введенного кода и нажатой кнопки.</div><br />';
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
        $this->content .= <<<HTML

        <br /><br />Подсказка:<br />
        <table class="wizard-data-table">
                <tr>
                    <th>Кнопка навигации</th>
                    <th>Код</th>
                    <th>Результат</th>
                </tr>
                <tr>
                    <td>Далее</td>
                    <td>aaa</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>Назад</td>
                    <td>bbb</td>
                    <td>Шаг 3</td>
                </tr>
                <tr>
                    <td>Готово</td>
                    <td>ccc</td>
                    <td>Шаг 4</td>
                </tr>
                <tr>
                    <td>Отмена</td>
                    <td>ddd</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>любая</td>
                    <td>xxx</td>
                    <td>ошибка</td>
                </tr>
                <tr>
                    <td colspan="2">любые другие значения</td>
                    <td>Шаг 2</td>
                </tr>
        </table>
HTML;
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetCancelStep("fourth");
    }
}
?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

$wizard = new CWizardBase("Мой мастер", $package);
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));
$wizard->Display();


IsPrevButtonClick

СWizardBase::IsPrevButtonClick

bool
IsPrevButtonClick();

Метод возвращает true, если была нажата кнопка Назад, иначе false.

См. также

  • CWizardBase::IsNextButtonClick
  • CWizardBase::IsFinishButtonClick
  • CWizardBase::IsCancelButtonClick

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");

        $this->SetNextStep("second");
        $this->SetPrevStep("second");
        $this->SetFinishStep("second");
        $this->SetCancelStep("second");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        $code = $wizard->GetVar("code");

        if (strlen($code) <= 0)
            return;

        if ($code == "xxx")
            $this->SetError("Вы ввели запрещённый код", "code");

        if ($wizard->IsNextButtonClick() && $code == "aaa")
            $wizard->SetCurrentStep("first");
        elseif ($wizard->IsPrevButtonClick() && $code == "bbb")
            $wizard->SetCurrentStep("third");
        elseif ($wizard->IsFinishButtonClick() && $code == "ccc")
            $wizard->SetCurrentStep("fourth");
        elseif ($wizard->IsCancelButtonClick() && $code == "ddd")
            $wizard->SetCurrentStep("first");
    }

    function ShowStep()
    {
        $this->content .= '<div class="wizard-note-box">Следующий шаг мастера зависит от введенного кода и нажатой кнопки.</div><br />';
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
        $this->content .= <<<HTML

        <br /><br />Подсказка:<br />
        <table class="wizard-data-table">
                <tr>
                    <th>Кнопка навигации</th>
                    <th>Код</th>
                    <th>Результат</th>
                </tr>
                <tr>
                    <td>Далее</td>
                    <td>aaa</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>Назад</td>
                    <td>bbb</td>
                    <td>Шаг 3</td>
                </tr>
                <tr>
                    <td>Готово</td>
                    <td>ccc</td>
                    <td>Шаг 4</td>
                </tr>
                <tr>
                    <td>Отмена</td>
                    <td>ddd</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>любая</td>
                    <td>xxx</td>
                    <td>ошибка</td>
                </tr>
                <tr>
                    <td colspan="2">любые другие значения</td>
                    <td>Шаг 2</td>
                </tr>
        </table>
HTML;
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetCancelStep("fourth");
    }
}
?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

$wizard = new CWizardBase("Мой мастер", $package);
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));
$wizard->Display();


SetCancelButtonID

СWizardBase::SetCancelButtonID

void
SetCancelButtonID(
 string buttonID
);

Метод устанавливает значение атрибута name кнопки Отмена.

Параметры функции

Параметр | Описание
buttonID | Значение атрибута name кнопки Отмена.

См. также

  • CWizardBase::GetCancelButtonID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


SetCurrentStep

СWizardBase::SetCurrentStep

void
SetCurrentStep(
 string stepID
);

Метод устанавливает шаг stepID текущим.

Параметры функции

Параметр | Описание
stepID | ID шага, который необходимо сделать текущим.

См. также

  • CWizardBase::SetFirstStep
  • CWizardBase::GetCurrentStep
  • CWizardBase::GetCurrentStepID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");

        $this->SetNextStep("second");
        $this->SetPrevStep("second");
        $this->SetFinishStep("second");
        $this->SetCancelStep("second");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        $code = $wizard->GetVar("code");

        if (strlen($code) <= 0)
            return;

        if ($code == "xxx")
            $this->SetError("Вы ввели запрещённый код", "code");

        if ($wizard->IsNextButtonClick() && $code == "aaa")
            $wizard->SetCurrentStep("first");
        elseif ($wizard->IsPrevButtonClick() && $code == "bbb")
            $wizard->SetCurrentStep("third");
        elseif ($wizard->IsFinishButtonClick() && $code == "ccc")
            $wizard->SetCurrentStep("fourth");
        elseif ($wizard->IsCancelButtonClick() && $code == "ddd")
            $wizard->SetCurrentStep("first");
    }

    function ShowStep()
    {
        $this->content .= '<div class="wizard-note-box">Следующий шаг мастера зависит от введенного кода и нажатой кнопки.</div><br />';
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
        $this->content .= <<<HTML

        <br /><br />Подсказка:<br />
        <table class="wizard-data-table">
                <tr>
                    <th>Кнопка навигации</th>
                    <th>Код</th>
                    <th>Результат</th>
                </tr>
                <tr>
                    <td>Далее</td>
                    <td>aaa</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>Назад</td>
                    <td>bbb</td>
                    <td>Шаг 3</td>
                </tr>
                <tr>
                    <td>Готово</td>
                    <td>ccc</td>
                    <td>Шаг 4</td>
                </tr>
                <tr>
                    <td>Отмена</td>
                    <td>ddd</td>
                    <td>Шаг 1</td>
                </tr>
                <tr>
                    <td>любая</td>
                    <td>xxx</td>
                    <td>ошибка</td>
                </tr>
                <tr>
                    <td colspan="2">любые другие значения</td>
                    <td>Шаг 2</td>
                </tr>
        </table>
HTML;
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetCancelStep("fourth");
    }
}
?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

$wizard = new CWizardBase("Мой мастер", $package);
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));
$wizard->Display();


SetDefaultVar

СWizardBase::SetDefaultVar

void
SetDefaultVar(
 string varName,
 string varValue
);

Метод устанавливает для переменной varName значение по умолчанию varValue.

Параметры функции

Параметр | Описание
varName | Имя переменной, для которой нужно установить значение по умолчанию. Имя переменной может быть составным, например, myvar[key].
varValue | Значение по умолчанию.

См. также

  • CWizardBase:SetDefaultVars
  • CWizardBase:GetDefaultVar
  • CWizardBase:GetDefaultVars

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


SetDefaultVars

СWizardBase::SetDefaultVars

void
SetDefaultVars(
 array arVars
);

Метод устанавливает переменным мастера значения по умолчанию.

Параметры функции

Параметр | Описание
arVars | Массив значений по умолчанию вида Array("имя_переменной" => "значение_по_умолчанию" [, ...]).

См. также

  • CWizardBase:SetDefaultVar
  • CWizardBase:GetDefaultVar
  • CWizardBase:GetDefaultVars

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


SetFinishButtonID

СWizardBase::SetFinishButtonID

void
SetFinishButtonID(
 string buttonID
);

Метод устанавливает значение атрибута name кнопки Готово.

Параметры функции

Параметр | Описание
buttonID | Значение атрибута name кнопки Готово.

См. также

  • CWizardBase::GetFinishButtonID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


SetFirstStep

СWizardBase::SetFirstStep

void
SetFirstStep(
 string stepID
);

Метод устанавливает шаг stepID первым в цепочке шагов мастера.

Параметры функции

Параметр | Описание
stepID | ID шага, который необходимо сделать первым в цепочке шагов мастера.

См. также

  • Файл описания мастера .description.php
  • CWizardBase::SetCurrentStep
  • CWizardBase::GetCurrentStep
  • CWizardBase::GetCurrentStepID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $wizard->SetFirstStep("second"); //Этот шаг будет первым

        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetCancelStep("fourth");
    }
}
?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Второй шаг - первый!",
    "STEPS" => Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

$wizard = new CWizardBase("Второй шаг - первый!", $package);
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));
$wizard->Display();

Несмотря на то, что шаг FirstStep указан в обоих случаях первым, при запуске мастера будет показан шаг SecondStep.


SetFormActionScript

СWizardBase::SetFormActionScript

void
SetFormActionScript(
 string actionScript
);

Метод устанавливает значение атрибута action формы мастера (тега <form>). По умолчанию атрибут action равен адресу текущей страницы.

Параметры функции

Параметр | Описание
actionScript | Значения атрибута name

См. также

  • CWizardBase::GetFormActionScript

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


SetFormName

СWizardBase::SetFormName

void
SetFormName(
 string formName
);

Метод устанавливает значение атрибута name формы мастера (тега <form>).

Параметры функции

Параметр | Описание
formName | Значение атрибута name формы мастера (тега <form>).

См. также

  • CWizardBase::GetFormName

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


SetNextButtonID

СWizardBase::SetNextButtonID

void
SetNextButtonID(
 string buttonID
);

Метод устанавливает значение атрибута name кнопки Далее.

Параметры функции

Параметр | Описание
buttonID | Значение атрибута name кнопки Далее.

См. также

  • CWizardBase::GetNextButtonID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


SetPrevButtonID

СWizardBase::SetPrevButtonID

void
SetPrevButtonID(
 string buttonID
);

Метод устанавливает значение атрибута name кнопки Назад.

Параметры функции

Параметр | Описание
buttonID | Значение атрибута name кнопки Назад.

См. также

  • CWizardBase::GetPrevButtonID

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


SetReturnOutput

СWizardBase::SetReturnOutput

void
SetReturnOutput(
 bool mode = true
);

Метод устанавливает флаг возврата в значение mode. Если флаг возврата установлен в значение true, метод CWizardBase::Display возвратит весь вывод мастера, иначе выведет содержимое мастера на экран.

Параметры функции

Параметр | Описание
mode | Флаг возврата. Необязательный параметр, по умолчанию равен true.

См. также

  • CWizardBase::Display

Примеры использования

<?
class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step2");
    }

}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2");
        $this->SetPrevStep("step1");
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2"));

//Устанавливаем флаг возврата
$wizard->SetReturnOutput();

//Получаем вывод мастера
$output = $wizard->Display();

/*здесь можно обработать вывод мастера*/

//Выводим на экран
echo $output;
?>


SetTemplate

СWizardBase::SetTemplate

void
SetTemplate(
 object &obStepTemplate,
 mixed stepID = false
);

Метод устанавливает шаблон obStepTemplate для шага stepID. Если параметр stepID не указан, шаблон устанавливается для всех шагов.

Параметры функции

Параметр | Описание
&obStepTemplate | Экземпляр класса CWizardTemplate
stepID | ID шага, для которого устанавливается шаблон. Необязательный параметр, по умолчанию равен false (шаблон применяется для всех шагов).

См. также

  • Шаблон мастера

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("step1");
        $this->SetNextStep("step2");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetStepID("step2");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1");
        $this->SetCancelStep("cancel");
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetCancelStep("cancel");
        $this->SetTitle("Третий шаг");
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

//Красный шаблон мастера
class MyRedTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        //Получаем значения атрибута name кнопок мастера
        $nextButtonID = $wizard->GetNextButtonID();
        $prevButtonID = $wizard->GetPrevButtonID();
        $cancelButtonID = $wizard->GetCancelButtonID();
        $finishButtonID = $wizard->GetFinishButtonID();

        //Получаем ссылку на объект текущего шага
        $obStep =& $wizard->GetCurrentStep();

        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        //Получим ошибки шага
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<div id="step_error">'.$strError.'</span>';
        }

        /*
            Возвращаем HTML-код шаблона, в котором обязательно
            должны быть определны следующие макросы:
                {#FORM_START#} - начало формы
                {#CONTENT#} - содержимое текущего шага
                {#BUTTONS#} - кнопки навигации
                {#FORM_END#} - конец формы
        */
        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">
            body
            {
                margin:0; padding:0; background-color: #FFDEDE;
                font-family:Verdana,Arial,helvetica,sans-serif;font-size:75%;
            }
            table {font-size:100%;}
            form {margin:0;}
            #border-box{margin:2px 2px 0 2px; border:1px dashed red;}
            #step_info
            {
                height:45px;padding:8px 30px;border-bottom:1px dashed red;
                box-sizing:border-box;-moz-box-sizing:border-box;overflow:hidden;background:#FFC4C4;
            }
            #step_title{font-weight:bold;}
            #step_description {font-size:95%; margin-left:10px;}
            #step_content {padding:20px 20px;box-sizing:border-box;-moz-box-sizing:border-box;float:left;}
            #step_buttons
            {
                height:50px; text-align:right; padding-right:20px; padding-top:5px;
                overflow:hidden; box-sizing:border-box;-moz-box-sizing:border-box;
            }
            #step_content_container { height:290px; overflow:auto;background:#fff;}
            #step_error {color:red; margin:6px;}
        </style>

        <script type="text/javascript">

            function OnLoad()
            {
                /*Установим в окошке мастера заголовок*/
                var title = self.parent.window.document.getElementById("wizard_dialog_title");
                if (title)
                    title.innerHTML = "{$wizardName}";

                /*Получаем объект формы*/
                var form = document.forms["{$formName}"];

                if (!form)
                    return;

                /*Получаем объекты кнопок*/
                var cancelButton = form.elements["{$cancelButtonID}"];
                var nextButton = form.elements["{$nextButtonID}"];
                var prevButton = form.elements["{$prevButtonID}"];
                var finishButton = form.elements["{$finishButtonID}"];

                /*Если в шаге только кнопка Отмена, то закроем окно мастера,
                    иначе запросим подтверждение*/
                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            /*Подтвержение по кнопке Отмена*/
            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            /*Закроем окошко мастера*/
            function CloseWindow()
            {
                if (self.parent.window.WizardWindow)
                    self.parent.window.WizardWindow.Close();
            }

        </script>
    </head>
    <body onload="OnLoad();">
        {#FORM_START#}
            <div id="border-box">
                <div id="step_info">
                    <div id="step_title">{$stepTitle}</div>
                    <div id="step_description">{$stepSubTitle}</div>
                </div>
                <div id="step_content_container">
                    {$strError}
                    <div id="step_content">{#CONTENT#}</div>
                </div>
            </div>
            <div id="step_buttons">{#BUTTONS#}</div>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

//Аскетичный шаблон
class AsceticTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        $formName = $wizard->GetFormName(); //имя формы
        $wizardName = $wizard->GetWizardName(); //имя мастера
        $charset = LANG_CHARSET; //текушая кодировка

        $obStep =& $wizard->GetCurrentStep();//Получаем ссылку на объект текущего шага
        $stepTitle = $obStep->GetTitle(); //Заголовок шага
        $stepSubTitle = $obStep->GetSubTitle(); //Подзаголовк шага

        return <<<HTML
<html>
    <head>
        <title>{$wizardName}</title>
        <meta http-equiv="Content-Type" content="text/html; charset={$charset}">
        <style type="text/css">body, form, table {margin:0; padding:0;}</style>
    </head>
    <body>
        {#FORM_START#}
            <table width="100%" height="375" cellpadding="8">
                <tr><td height="50">{$stepTitle}<br />{$stepSubTitle}<hr /></td></tr>
                <tr><td valign="top">{#CONTENT#}</td></tr>
                <tr><td height="50" align="right"><hr />{#BUTTONS#}</td></tr>
            </table>
        {#FORM_END#}
    </body>
</html>
HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Запретим применять системный шаблон по умолчанию
//при запуске мастера из административного раздела
$wizard->DisableAdminTemplate();

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "CancelStep"));

//Определим для всех шагов красный шаблон
$wizard->SetTemplate(new MyRedTemplate);

//А для первого шага определим аскетичный шаблон
$wizard->SetTemplate(new AsceticTemplate, "step1");

//Выводим на экран
$wizard->Display();
?>


SetVar

СWizardBase::SetVar

void
SetVar(
 string varName,
 string varValue
);

Устанавливает переменную мастера varName в значение varValue.

Параметры функции

Параметр | Описание
varName | Имя переменной, для которой нужно установить определённое значение. Имя переменной может быть составным, например, myvar[key].
varValue | Значение переменной.

См. также

  • CWizardBase::GetVar
  • CWizardBase::GetVars
  • CWizardBase::UnSetVar

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


SetVarPrefix

СWizardBase::SetVarPrefix

void
SetVarPrefix(
 string varPrefix
);

Метод устанавливает префикс для переменных мастера. Имя с префиксом необходимо для того, чтобы названия переменных мастера не пересекались с названиями других переменных страницы. По умолчанию префикс для переменных мастера установлен в значение __wiz_.

Параметры функции

Параметр | Описание
varPrefix | Префикс для переменных мастера.

См. также

  • CWizardBase::GetVarPrefix
  • CWizardBase::GetRealName

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}

class SecondStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard();
        $this->SetTitle("Второй шаг");
        $this->SetStepID("second");
        $this->SetNextStep("third");
        $this->SetPrevStep("first");
        $this->SetCancelStep("fourth");
    }
}

class ThirdStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetStepID("third");
        $this->SetNextStep("fourth");
        $this->SetCancelStep("fourth");
    }
}

class FourthStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetStepID("fourth");
        $this->SetNextStep("fourth");
    }

    function ShowStep()
    {
        $wizard =& $this->GetWizard();

        //На этом шаге форма мастера будет отправлена по адресу /index.php
        $wizard->SetFormActionScript("/index.php");
    }
}

class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

            <script type="text/javascript">

            function WizardOnLoad()
            {
                var cancelButton = document.forms["my_form"].elements["cancel_button"];
                var nextButton = document.forms["my_form"].elements["next_button"];
                var prevButton = document.forms["my_form"].elements["prev_button"];
                var finishButton = document.forms["my_form"].elements["finish_button"];

                if (cancelButton && !nextButton && !prevButton && !finishButton)
                    cancelButton.onclick = CloseWindow;
                else if(cancelButton)
                    cancelButton.onclick = ConfirmCancel;
            }

            function CloseWindow()
            {
                window.location = '/';
                return false;
            }

            function ConfirmCancel()
            {
                return (confirm("Вы действительно хотите прервать мастер?"));
            }

            WizardOnLoad();

            </script>

HTML;
    }
}

//Создаем мастер
$wizard = new CWizardBase("Работа с идентификаторами формы мастера", $package);
$wizard->SetTemplate(new MyPinkTemplate);

//Устанавливаем атрибит name форме мастера
$wizard->SetFormName("my_form");

//Устнавливаем кнопкам навигации атрибут name
$wizard->SetPrevButtonID("prev_button");
$wizard->SetNextButtonID("next_button");
$wizard->SetFinishButtonID("finish_button");
$wizard->SetCancelButtonID("cancel_button");

//Устанавливаем префикс переменным мастера
$wizard->SetVarPrefix("my_prefix_");

//Добавляем шаги
$wizard->AddSteps(Array("FirstStep", "SecondStep", "ThirdStep", "FourthStep"));

//Выводим
$wizard->Display();
?>


UnSetVar

СWizardBase::UnSetVar

void
UnSetVar(
 string varName
);

Уничтожает переменную с именем varName.

Параметры функции

Параметр | Описание
varName | Имя переменной, которую необходимо уничтожить. Имя переменной может быть составным, например, myvar[key].

См. также

  • CWizardBase::GetVar
  • CWizardBase::GetVars
  • CWizardBase::SetVar

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Множественный checkbox");
        $this->SetNextStep("step2");
        $this->SetStepID("step1");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");

        //Получаем ссылку на объект мастера
        $wizard = &$this->GetWizard();

        //Устанавливаем для переменной vote[car] значение по умолчанию
        $wizard->SetDefaultVar("vote[car]", "reno");

        //Устанавливаем значения по умолчанию нескольким переменным
        $wizard->SetDefaultVars(
            Array(
                "vote[country]" => Array("poland", "lietva"),
                "subject" => "history",
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();
        $this->content = "В каких странах вы были?<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "russia")." Россия<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "usa")." США<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "poland")." Польша<br />";
        $this->content .= $this->ShowCheckboxField("vote[country][]", "lietva")." Литва<br />";

        $this->content .= "<br />Ваши любимые марки авто?<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "bmw")." BMW<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "hyundai")." Hyundai<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "vaz")." Ваз<br />";
        $this->content .= $this->ShowCheckboxField("vote[car][]", "reno")." Рено<br />";

        $this->content .= "<br />Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        //Устанавливаем переменную myVar.
        //Значение будет доступно на следующем шаге
        $wizard->SetVar("myVar", Array("AAA", "BBB", "CCC"));
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        //Настройки шага
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetPrevStep("step1");
        $this->SetNextStep("step3");
        $this->SetStepID("step2");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменная vote[car]: ".print_r($wizard->GetVar("vote[car]"), true)."<br />";
        $this->content .= "Значение по умолчанию для vote[car]: ".print_r($wizard->GetDefaultVar("vote[car]"), true)."<br />";
        $this->content .= "Значение всех переменных мастера:";
        $this->content .= "<pre>".print_r($wizard->GetVars(), true)."</pre>";

    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step2");
        $this->SetNextStep("step4");
        $this->SetStepID("step3");
        $this->SetCancelStep("final");
        $this->SetFinishStep("step4");
        $this->SetTitle("Множественный select с дефолтными значениями");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "operation[os]" => Array("windows"),
                "mathematics[twoandwo]" => Array("four", "twotwo"),
            )
        );
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        //Уничтожаем переменную myVar
        $wizard->UnSetVar("myVar");

        $this->content = "Какая ОС стоит на вашем рабочем компьютере?<br />";
        $this->content .= $this->ShowSelectField(
            "operation[os][]",
            Array(
                "linux" => "Linux",
                "windows" => "Windows",
                "freebsd" => "FreeBSD",
                "macos" => "MacOS",
                "dos" => "MS DOS",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 2+2?<br />";

        $this->content .= $this->ShowSelectField(
            "mathematics[twoandwo][]",
            Array(
                "four" => "Четыре",
                "five" => "Пять",
                "twotwo" => "Двадцать два",
                "two_plus_two" => "Два плюс Два",
            ),
            Array("multiple" => "multiple")
        );
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetPrevStep("step3");
        $this->SetStepID("step4");
        $this->SetTitle("Шаг отладки");
        $this->SetSubTitle("Смотрим переменные");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $wizard = &$this->GetWizard();

        $this->content .= "Переменные мастера с учётом дефолтных значений:";
        $this->content .= "<pre>".print_r($wizard->GetVars($useDefault = true), true)."</pre>";
    }
}

class FinalStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("final");
        $this->SetTitle("Финиш");
        $this->SetCancelStep("final");
    }

    function ShowStep()
    {
        $this->content = "Последний шаг";
    }
}
?>

Описание классов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Дефотные значения",
    "STEPS" => Array("Step1", "Step15", "Step2", "Step3", "Step4", "Step5", "FinalStep"),
);

?>


GetWizardSteps

СWizardBase::GetWizardSteps

array
GetWizardSteps();

Метод возвращает ассоциативный массив шагов мастера вида ID шага => объект шага (экземплер класса CWizardStep).

См. также

  • СWizardBase::GetCurrentStep
  • СWizardBase::GetCurrentStepID

Примеры использования

<?
class WizardTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        //Сгенерируем меню мастера
        $wizard =& $this->GetWizard();
        $arSteps = $wizard->GetWizardSteps();
        $currentStep = $wizard->GetCurrentStepID();

        $currentSuccess = false;
        $stepNumber = 1;

        foreach ($arSteps as $stepID => $stepObject)
        {
            if ($stepID == $currentStep)
            {
                $class = 'class="selected"';
                $currentSuccess = true;
            }
            elseif ($currentSuccess)
                $class = '';
            else
                $class = 'class="done"';

            $strNavigation .= '
            <tr '.$class.'>
                <td class="menu-number">'.$stepNumber.'</td>
                <td class="menu-name">'.$stepObject->GetTitle().'</td>
                <td class="menu-end"></td>
            </tr>
            <tr class="menu-separator">
                <td colspan="3"></td>
            </tr>';

            $stepNumber++;
        }

        if (strlen($strNavigation) > 0)
            $strNavigation = '<table width="100%" cellpadding="0" cellspacing="0" id="menu">'.$strNavigation.'</table>';
    }
}
?>


Класс CWizardStep

Для каждого шага, добавляемого в мастер, создаётся экземпляр класса CWizardStep. В переопределяемых функциях (InitStep, ShowStep, OnPostFrom) шага методы класса CWizardStep доступны через переменную-псевдоним $this.

<?
class MyFirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг мастера");
    }
}
?>


GetErrors

CWizardStep::GetErrors

array
GetErrors();

Метод возвращает массив ошибок шага.

См. также

  • CWizardStep::SetError

Примеры использования

<?
class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

HTML;
    }
}
?>


GetStepID

CWizardStep::GetStepID

mixed
GetStepID();

Метод возвращает ID шага. Если ID для шага не установлен, метод возвратит null.

См. также

  • CWizardStep::SetStepID


GetSubTitle

CWizardStep::GetSubTitle

string
GetSubTitle();

Метод возвращает подзаголовок шага.

См. также

  • CWizardStep::SetSubTitle
  • CWizardStep::SetTitle
  • CWizardStep::GetTitle

Примеры использования

<?
class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

HTML;
    }
}
?>


GetTitle

CWizardStep::GetTitle

string
GetTitle();

Метод возвращает заголовок шага.

См. также

  • CWizardStep::SetTitle
  • CWizardStep::SetSubTitle
  • CWizardStep::GetSubTitle

Примеры использования

<?
class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

HTML;
    }
}
?>


GetWizard

CWizardStep::GetWizard

object &
GetWizard();

Метод возвращает ссылку на объект мастера.

Примеры использования

<?
class MyFirstStep extends CWizardStep
{
    function InitStep()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
        $myVar = $wizard->GetVar("myVar"); //Используем метод мастера (класс CWizardBase)
    }
}
?>


InitStep

CWizardStep::InitStep

void
InitStep();

Переопределяемый метод шага. Метод вызывается при добавлении шага в мастер. Метод предназначен для инициализации свойств шага: идентификатора (ID), заголовка, подзаголовка, кнопок перехода на следующие шаги и др. В этом методе обязательно нужно определить ID шага.

См. также

  • Определение шагов мастера
  • CWizardStep::OnPostForm
  • CWizardStep::ShowStep

Примеры использования

<?
class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}
?>


IsAutoSubmit

CWizardStep::IsAutoSubmit

bool
IsAutoSubmit();

Метод возвращает значение флага автоматической отправки.

См. также

  • CWizardStep::SetAutoSubmit


OnPostForm

CWizardStep::OnPostForm

void
OnPostForm();

Переопределяемый метод шага. Метод вызывается при нажатии на любую из кнопок навигации мастера. В этом методе можно проверить входные данные, вернуть ошибки, изменить текущий шаг, выполнить любые другие действия.

См. также

  • Определение шагов мастера
  • CWizardStep::InitStep
  • CWizardStep::ShowStep

Примеры использования

<?
class FirstStep extends CWizardStep
{
    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        $code = $wizard->GetVar("code");

        if (strlen($code) <= 0)
            return;

        if ($code == "xxx")
            $this->SetError("Вы ввели запрещённый код", "code");

        if ($wizard->IsNextButtonClick() && $code == "aaa")
            $wizard->SetCurrentStep("first");
        elseif ($wizard->IsPrevButtonClick() && $code == "bbb")
            $wizard->SetCurrentStep("third");
        elseif ($wizard->IsFinishButtonClick() && $code == "ccc")
            $wizard->SetCurrentStep("fourth");
        elseif ($wizard->IsCancelButtonClick() && $code == "ddd")
            $wizard->SetCurrentStep("first");
    }
}
?>


SaveFile

CWizardStep::SaveFile

int
SaveFile(
 string name,
 array arRestriction = Array()
);

Метод сохраняет файл в системе. В случае удачной загрузки метод возвратит ID добавленного файла.

Параметры функции

Параметр | Описание
name | Имя поля для загрузки файла на сервер.
arRestriction Массив ограничений на загружаемый файл вида Array("вид_ограничения" => "значение_ограничения" [,...]). Вид ограничения может принимать следующие значения:
  • max_file_size - максимальный размер загружаемого файла в байтах;
  • max_width - максимальная ширина загружаемой картинки в пикселях;
  • max_height - максимальная высота загружаемой картинки в пикселях;
  • extensions - допустимые расширения загружаемого файла через запятую.
  • make_preview - если параметр установлен в значение Y, то метод создаст уменьшенную копию загружаемого файла с максимальной шириной max_width и максимальной высотой max_height. По умолчанию параметр равен N.
Необязательный параметр, по умолчанию ограничений нет.

См. также

  • CWizardStep::ShowFileField
  • CWizardUtil::CopyFile
  • CWizardUtil::CreateThumbnail

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Загрузка файла");
        $this->SetStepID("step");

        $this->SetNextStep("step");
        $this->SetFinishStep("step");

        $this->SetNextCaption("Загрузить");
        $this->SetFinishCaption("Скопировать");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        if ($wizard->IsNextButtonClick())
            $this->SaveFile("file", Array("max_file_size" => 20*1024, "extensions" => "gif,jpg,png"));
        elseif($wizard->IsFinishButtonClick())
        {
            $fileID = $wizard->GetVar("file");
            if (intval($fileID) > 0)
                CWizardUtil::CopyFile($fileID, "/upload_picture.gif");
        }
    }

    function ShowStep()
    {
        $this->content .= "Загрузить файл:".$this->ShowFileField("file", Array("max_file_size" => 20*1024, "size" => "25"));
    }

}
?>


SetAutoSubmit

CWizardStep::SetAutoSubmit

void
SetAutoSubmit(
 bool autoSubmit = true
);

Метод устанавливает флаг автоматической отправки в значение autoSubmit. Если у шага флаг автоматической отправки установлен в значение true, то в системных шаблонах мастера кнопка Далее будет нажата автоматически.

Параметры функции

Параметр | Описание
autoSubmit | Значение флага автоматической отправки. Необязательный параметр, по умолчанию равен true.

См. также

  • CWizardStep::IsAutoSubmit

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetCancelCaption

CWizardStep::SetCancelCaption

void
SetCancelCaption(
 string caption
);

Метод устанавливает текстовую надпись caption кнопке Отмена.

Параметры функции

Параметр | Описание
caption | Надпись кнопки Отмена.

См. также

  • CWizardStep::SetNextCaption
  • CWizardStep::SetPrevCaption
  • CWizardStep::SetFinishCaption

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetCancelStep

CWizardStep::SetCancelStep

void
SetCancelStep(
 string stepID
);

Метод определяет кнопку Отмена, ведущую на шаг stepID.

Параметры функции

Параметр | Описание
stepID | ID шага, на который ведет кнопка Отмена.

См. также

  • CWizardStep::SetStepID
  • CWizardStep::SetPrevStep
  • CWizardStep::SetNextStep
  • CWizardStep::SetFinishStep

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetError

CWizardStep::SetError

void
SetError(
 string strError,
 bool id = false
);

Метод устанавливает ошибку шага с текстом strError и идентификатором id. Если шаг содержит ошибки, то переход по кнопкам навигации не осуществляется.

Параметры функции

Параметр | Описание
strError | Текст ошибки.
id | Идентификатор ошибки. Необязательный параметр, по умолчанию равен false.

См. также

  • CWizardStep::GetErrors

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Проверка данных");
        $this->SetNextStep("step");
        $this->SetFinishStep("step");
        $this->SetStepID("step");
    }

    function OnPostForm()
    {
        $wizard = &$this->GetWizard();
        if ($wizard->IsNextButtonClick() || $wizard->IsFinishButtonClick())
        {
            $your_name = $wizard->GetVar("your_name");
            $your_surname = $wizard->GetVar("your_surname");

            if (strlen($your_name)<=0)
                $this->SetError("Вы не указали имя", "your_name");

            if (strlen($your_surname)<=0)
                $this->SetError("Вы не указали фамилию", "your_surname");
        }
    }

    function ShowStep()
    {
        $this->content .= "Имя: ".$this->ShowInputField("text", "your_name")."<br />";
        $this->content .= "Фамилия: ".$this->ShowInputField("text", "your_surname")."<br />";
        $this->content .= "О себе:<br />".$this->ShowInputField("textarea", "about_text", Array("cols" => "25", "rows" => "5"))."<br /><br />";
    }
}

?>


SetFinishCaption

CWizardStep::SetFinishCaption

void
SetFinishCaption(
 string caption
);

Метод устанавливает текстовую надпись caption кнопке Готово.

Параметры функции

Параметр | Описание
caption | Надпись кнопки Готово.

См. также

  • CWizardStep::SetNextCaption
  • CWizardStep::SetPrevCaption
  • CWizardStep::SetCancelCaption

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetFinishStep

CWizardStep::SetFinishStep

void
SetFinishStep(
 string stepID
);

Метод определяет кнопку Готово, ведущую на шаг stepID.

Параметры функции

Параметр | Описание
stepID | ID шага, на который ведет кнопка Готово.

См. также

  • CWizardStep::SetStepID
  • CWizardStep::SetPrevStep
  • CWizardStep::SetNextStep
  • CWizardStep::SetCancelStep

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetNextCaption

CWizardStep::SetNextCaption

void
SetNextCaption(
 string caption
);

Метод устанавливает текстовую надпись caption кнопке Далее.

Параметры функции

Параметр | Описание
caption | Надпись кнопки Далее.

См. также

  • CWizardStep::SetPrevCaption
  • CWizardStep::SetCancelCaption
  • CWizardStep::SetFinishCaption

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetNextStep

CWizardStep::SetNextStep

void
SetNextStep(
 string stepID
);

Метод определяет кнопку Далее, ведущую на шаг stepID.

Параметры функции

Параметр | Описание
stepID | ID шага, на который ведет кнопка Далее.

См. также

  • CWizardStep::SetStepID
  • CWizardStep::SetPrevStep
  • CWizardStep::SetFinishStep
  • CWizardStep::SetCancelStep

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetPrevCaption

CWizardStep::SetPrevCaption

void
SetPrevCaption(
 string caption
);

Метод устанавливает текстовую надпись caption кнопке Назад.

Параметры функции

Параметр | Описание
caption | Надпись кнопки Назад.

См. также

  • CWizardStep::SetNextCaption
  • CWizardStep::SetCancelCaption
  • CWizardStep::SetFinishCaption

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetPrevStep

CWizardStep::SetPrevStep

void
SetPrevStep(
 string stepID
);

Метод определяет кнопку Назад, ведущую на шаг stepID.

Параметры функции

Параметр | Описание
stepID | ID шага, на который ведет кнопка Назад.

См. также

  • CWizardStep::SetStepID
  • CWizardStep::SetNextStep
  • CWizardStep::SetFinishStep
  • CWizardStep::SetCancelStep

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetStepID

CWizardStep::SetStepID

void
SetStepID(
 string stepID
);

Метод устанавливает идентификатор stepID текущему шагу.

Параметры функции

Параметр | Описание
stepID | ID шага.

См. также

  • CWizardStep::GetStepID
  • CWizardStep::SetPrevStep
  • CWizardStep::SetNextStep
  • CWizardStep::SetFinishStep
  • CWizardStep::SetCancelStep

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetSubTitle

CWizardStep::SetSubTitle

void
SetSubTitle(
 string stepSubTitle
);

Метод устанавливает подзаголовок шага.

Параметры функции

Параметр | Описание
stepSubTitle | Подзаголовок шага.

См. также

  • CWizardStep::GetSubTitle
  • CWizardStep::SetTitle
  • CWizardStep::GetTitle

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


SetTitle

CWizardStep::SetTitle

void
SetTitle(
 string title
);

Метод устанавливает заголовок шага.

Параметры функции

Параметр | Описание
title | Заголовок шага.

См. также

  • CWizardStep::GetTitle
  • CWizardStep::SetSubTitle
  • CWizardStep::GetSubTitle

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step1 extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("step1"); //ID шага

        $this->SetTitle("Первый шаг"); //Заголовок шага
        $this->SetSubTitle("Шаг приветствие"); //Подзаголовок шага

        $this->SetNextStep("step2"); //Кнопка Далее, ведущая на второй шаг
        $this->SetFinishStep("step4"); //Кнопка Готово, ведущая на 4ый шаг
        $this->SetCancelStep("cancel"); //Кнопк Отмена, ведущая на шаг Отмены
    }

    function ShowStep()
    {
        //Содержимое шага
        $this->content .= "Шаг 1";
    }
}

class Step2 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Второй шаг");
        $this->SetSubTitle("Свои надписи к кнопкам");

        $this->SetStepID("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step3");
        $this->SetPrevStep("step1"); //Кнопка Назад, ведущая на первый шаг
        $this->SetCancelStep("cancel");

        //Изменим надписи к кнопкам
        $this->SetPrevCaption("Назад к шагу 1");
        $this->SetNextCaption("Вперед");
        $this->SetFinishCaption("Финиш");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 2";
    }
}

class Step3 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Третий шаг");
        $this->SetSubTitle("Автосабмит");

        //В системных шаблонах кнопка Далее нажмется автоматически
        $this->SetAutoSubmit();

        $this->SetStepID("step3");
        $this->SetPrevStep("step2");
        $this->SetFinishStep("step4");
        $this->SetNextStep("step4");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 3";
    }
}

class Step4 extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Четвертый шаг");
        $this->SetSubTitle("Финиш");

        $this->SetStepID("step4");
        $this->SetPrevStep("step3");
        $this->SetCancelStep("cancel");
    }

    function ShowStep()
    {
        $this->content .= "Шаг 4";
    }
}

class CancelStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetStepID("cancel");

        //В системном шаблоне по уомлчанию
        //JS-обработчик закроет окно мастера,
        //т.к. кнопка отмена одна на странице шага
        $this->SetCancelStep("cancel");

        //Изменим надпись кнопке Отмена
        $this->SetCancelCaption("Закрыть");
    }

    function ShowStep()
    {
        $this->content .= "Отмена";
    }
}

?>

Статическое определение шагов в файле .description.php

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

$arWizardDescription = Array(
    "NAME" => "Мой мастер",
    "STEPS" => Array("Step1", "Step2", "Step3", "Step4", "CancelStep"),
);
?>

Или динамическое определение шагов в файле wizard.php

<?
//Создаем мастер
$wizard = new CWizardBase("Мой мастер", $package);

//Добавляем шаги
$wizard->AddSteps(Array("Step1", "Step2", "Step3", "Step4", "CancelStep"));

//Выводим на экран
$wizard->Display();
?>


ShowCheckboxField

CWizardStep::ShowCheckboxField

string
ShowCheckboxField(
 string name,
 string value,
 array arAttributes = Array()
);

Метод возвращает HTML-код переключателя с множественным вариантом выбора ответа (<input type="checkbox" />).

Параметры функции

Параметр | Описание
name | Имя поля переключателя (значение атрибута name тега input).
value | Значение поля переключателя (значение атрибута value тега input).
arAttributes | Массив дополнительных атрибутов переключателя вида Array("имя_атрибута" => "значение" [, ...]). Необязательный параметр, по умолчанию дополнительных атрибутов нет.

См. также

  • CWizardStep::ShowFileField
  • CWizardStep::ShowHiddenField
  • CWizardStep::ShowInputField
  • CWizardStep::ShowRadioField
  • CWizardStep::ShowSelectField

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Множественный checkbox c дефолтными значениями");
        $this->SetStepID("step");
        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "subject" => Array("math", "programming"),
                "education" => "university",
            )
        );
    }

    function ShowStep()
    {
        $this->content = "Какие науки Вас интересуют?<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "math")." Математика<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "history")." История<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "programming")." Программирование<br />";
        $this->content .= $this->ShowCheckboxField("subject[]", "physics")." Физика<br />";

        $this->content .= "<br />Ваше образование?<br />";
        $this->content .= $this->ShowCheckboxField("education[]", "elementary")." Начальное<br />";
        $this->content .= $this->ShowCheckboxField("education[]", "highschool")." Среднее<br />";
        $this->content .= $this->ShowCheckboxField("education[]", "university")." Высшее<br />";
        $this->content .= $this->ShowCheckboxField("education[]", "college")." Среднее специальное<br />";
    }
}
?>


ShowFileField

CWizardStep::ShowFileField

string
ShowFileField(
 string name,
 array arAttributes = Array()
);

Метод возвращает HTML-код поля для загрузки файла на сервер (<input type="file" />).

Параметры функции

Параметр | Описание
name | Имя поля (значение атрибута name тега input).
arAttributes Массив дополнительных атрибутов вида Array("имя_атрибута" => "значение" [, ...]). Имя атрибута может принимать следующие значения:
  • max_file_size - максимальный размер загружаемого файла. Метод дополнительно вернет HTML-код скрытого поля MAX_FILE_SIZE;
  • show_file_info - показывать информацию о файле (размер, высота, ширина). По умолчанию параметр равен "Y" (показывать);
  • Любые другие HTML-атрибуты тега input.
Необязательный параметр, по умолчанию дополнительных атрибутов нет.

См. также

  • CWizardStep::SaveFile
  • CWizardUtil::CopyFile
  • CWizardStep::ShowCheckboxField
  • CWizardStep::ShowdHiddenField
  • CWizardStep::ShowInputField
  • CWizardStep::ShowRadioField
  • CWizardStep::ShowSelectField

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Загрузка файла");
        $this->SetNextStep("step");
        $this->SetStepID("step");
    }

    function OnPostForm()
    {
        $this->SaveFile("file", Array("max_file_size" => 20*1024, "extensions" => "gif,jpg,png"));
    }

    function ShowStep()
    {
        $this->content .= "Загрузить файл:".$this->ShowFileField("file", Array("max_file_size" => 20*1024, "size" => "25"));
    }

}
?>


ShowHiddenField

CWizardStep::ShowHiddenField

string
ShowHiddenField(
 string name,
 string value,
 array arAttributes = Array()
);

Метод возвращает HTML-код скрытого поля (<input type="hidden" />).

Параметры функции

Параметр | Описание
name | Имя скрытого поля (значение атрибута name тега input).
value | Значение скрытого поля (значение атрибута value тега input).
arAttributes | Массив дополнительных атрибутов вида Array("имя_атрибута" => "значение" [, ...]). Необязательный параметр, по умолчанию дополнительных атрибутов нет.

См. также

  • CWizardStep::ShowCheckboxField
  • CWizardStep::ShowFileField
  • CWizardStep::ShowInputField
  • CWizardStep::ShowRadioField
  • CWizardStep::ShowSelectField


ShowInputField

CWizardStep::ShowInputField

string
ShowInputField(
 string type,
 string name,
 array arAttributes = Array()
);

Метод возвращает HTML-код текстового поля.

Параметры функции

Параметр | Описание
type Тип текстого поля. Может принимать следующие значения:
  • text - однострочное текстовое поле;
  • textarea - многострочное текстовое поле;
  • password - текстовое поле для ввода пароля.
name | Имя текстового поля.
arAttributes | Массив дополнительных атрибутов вида Array("имя_атрибута" => "значение" [, ...]). Необязательный параметр, по умолчанию дополнительных атрибутов нет.

См. также

  • CWizardStep::ShowCheckboxField
  • CWizardStep::ShowFileField
  • CWizardStep::ShowHiddenField
  • CWizardStep::ShowRadioField
  • CWizardStep::ShowSelectField

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("ShowInputField");
        $this->SetStepID("step");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVar("your_name", "Default name");
    }

    function ShowStep()
    {
        $this->content .= "Имя: ".$this->ShowInputField("text", "your_name", Array("size" => "20"))."<br />";
        $this->content .= "Фамилия: ".$this->ShowInputField("text", "your_surname", Array("size" => "20"))."<br />";
        $this->content .= "О себе:<br />".$this->ShowInputField("textarea", "about", Array("rows" => "10", "cols" => "15"))."<br />";
    }
}
?>


ShowRadioField

CWizardStep::ShowRadioField

string
ShowRadioField(
 string name,
 string value,
 array arAttributes = Array()
);

Метод возвращает HTML-код переключателя с единственным вариантом выбора ответа (<input type="radio" />).

Параметры функции

Параметр | Описание
name | Имя поля переключателя (значение атрибута name тега input).
value | Значение поля переключателя (значение атрибута value тега input).
arAttributes | Массив дополнительных атрибутов переключателя вида Array("имя_атрибута" => "значение" [, ...]). Необязательный параметр, по умолчанию дополнительных атрибутов нет.

См. также

  • CWizardStep::ShowCheckboxField
  • CWizardStep::ShowFileField
  • CWizardStep::ShowHiddenField
  • CWizardStep::ShowInputField
  • CWizardStep::ShowSelectField

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Выбор установки");
        $this->SetNextStep("step");
        $this->SetStepID("step");
    }

    function OnPostForm()
    {
        $wizard = &$this->GetWizard();
        $install_type = $wizard->GetVar("install_type");
        $wizard->SetVar("result", $install_type);
    }

    function ShowStep()
    {
        $this->content = "Выберите что-нибудь?<br />";
        $this->content .= $this->ShowRadioField("install_type", "create_user")." Регистрация пользователя<br />";
        $this->content .= $this->ShowRadioField("install_type", "create_iblock")." Создание инфоблока<br />";

        $wizard = &$this->GetWizard();
        $this->content .= "Вы выбрали: ".$wizard->GetVar("result");
    }
}
?>


ShowSelectField

CWizardStep::ShowSelectField

string
ShowSelectField(
 string name,
 array arValues = Array(),
 array arAttributes = Array()
);

Метод выводит HTML-код выпадающего списка с одиночным выбором (<select></select>). Для выпадающего списка с множественным выбором необходимо в массиве arAttributes указать атрибут multiple (Array("multiple" => "multiple")).

Параметры функции

Параметр | Описание
name | Имя поля выпадающего списка (значение атрибута name тега select).
arValues | Массив элементов списка вида Array("значение_элемента" => "заголовок_элемента" [, ...]). Необязательный параметр.
arAttributes | Массив дополнительных атрибутов списка вида Array("имя_атрибута" => "значение" [, ...]). Необязательный параметр, по умолчанию дополнительных атрибутов нет.

См. также

  • CWizardStep::ShowCheckboxField
  • CWizardStep::ShowFileField
  • CWizardStep::ShowHiddenField
  • CWizardStep::ShowInputField
  • CWizardStep::ShowRadioField

Примеры использования

Мастер создания нового пользователя

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Множественный select");
        $this->SetStepID("step");

        $wizard = &$this->GetWizard();
        $wizard->SetDefaultVars(
            Array(
                "server[soft]" => Array("php", "js"),
            )
        );
    }

    function ShowStep()
    {

        $this->content = "Какие технологии используются в вашей компании?<br />";
        $this->content .= $this->ShowSelectField(
            "server[soft][]",
            Array(
                "php" => "PHP",
                "mysql" => "MySQL",
                "apache" => "Apache",
                "js" => "Javascript",
                "html" => "Html",
            ),
            Array("multiple" => "multiple")
        );

        $this->content .= "<br /><br />Сколько будет 1+1?<br />";

        $this->content .= $this->ShowSelectField(
            "math[oneandone][]",
            Array(
                "2" => "2",
                "11" => "11",
                "10" => "10",
                "16" => "16",
            ),
            Array("multiple" => "multiple", "size" => "3")
        );

    }

}

?>


ShowStep

CWizardStep::ShowStep

void
ShowStep();

Переопределяемый метод шага. Метод вызывается в момент показа шага пользователю. Метод предназначен для определения содержимого шага: в переменную $this->content необходимо записать весь вывод шага.

См. также

  • Определение шагов мастера
  • CWizardStep::InitStep
  • CWizardStep::OnPostForm

Примеры использования

<?
class FirstStep extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Первый шаг");
        $this->SetStepID("first");
        $this->SetNextStep("second");
        $this->SetCancelStep("fourth");
    }

    function ShowStep()
    {
        $this->content .= "Введите код: ".$this->ShowInputField("text", "code", Array("size" => "15"));
    }
}
?>


Класс CWizardTemplate

Класс CWizardTemplate является оболочкой для шаблона мастера. Для каждого шаблона создаётся экземпляр класса CWizardTemplate. Чтобы воспользоваться методами класса CWizardBase в теле переопределяемой функции GetLayout, необходимо получить ссылку на экземпляр мастера:

<?
class MyTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
        /*
            Определение шаблона
            ...
        */
    }
}

?>


GetLayout

CWizardTemplate::GetLayout

string
GetLayout();

Переопределяемый метод. Метод должен вернуть HTML-вывод шаблона мастера. Внутри шаблона мастера обязательно должны быть определены следующие макросы:

  • {#FORM_START#} – начало формы, макрос будет заменен тегом <form>;
  • {#FORM_END#} – конец формы, макрос будет заменен тегом </form>;
  • {#CONTENT#} – область содержимого шага, макрос будет заменен содержимым текущего шага;
  • {#BUTTONS#} – область кнопок навигации, макрос будет заменен кнопками навигации.

См. также

  • Шаблон мастера

Примеры использования

<?
class MyPinkTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard();
        $obStep =& $wizard->GetCurrentStep();

        $wizardName = htmlspecialcharsEx($wizard->GetWizardName());

        //Получаем ошибки
        $arErrors = $obStep->GetErrors();
        $strError = "";
        if (count($arErrors) > 0)
        {
            foreach ($arErrors as $arError)
                $strError .= $arError[0]."<br />";

            $strError = '<tr><td style="padding-top: 10px; padding-left: 20px; color:red;">'.$strError.'</td></tr>';
        }

        //Заголовок и подзаголовок
        $stepTitle = $obStep->GetTitle();
        $stepSubTitle = $obStep->GetSubTitle();

        return <<<HTML

            {#FORM_START#}
            <table style="border:2px outset #D4D0C8; background-color: #FFDEDE;" border="0" cellpadding="0" cellspacing="0" height="370" width="100%">
                <tr>
                    <td style="background-color: #142F73" height="1"><span style="color:white; font-weight:bold; text-align:left; padding-left: 2px;">{$wizardName}</span></td>
                </tr>

                <tr>
                    <td style="height: 60px; border-bottom:2px groove  #aca899; background-color: #FFC4C4; padding: 8px;" valign="top">
                        <div style="padding-top: 5px; padding-left: 20px;"><b>{$stepTitle}</b></div>
                        <div style="padding-left: 40px;">{$stepSubTitle}</div>
                    </td>
                </tr>

                {$strError}

                <tr>
                    <td style="padding: 20px; padding-left: 28px;padding-right: 28px;" valign="top" id="wizard-content-area">{#CONTENT#}</td>
                </tr>

                <tr>
                    <td style="background-color: #FFC4C4; height: 40px; border-top:2px groove #ffffff; padding-right: 15px;" align="right">{#BUTTONS#}</td>
                </tr>
            </table>
            {#FORM_END#}

HTML;
    }
}
?>


GetWizard

CWizardTemplate::GetWizard

object &
GetWizard();

Метод возвращает ссылку на объект мастера.

См. также

Примеры использования

<?
class MyTemplate extends CWizardTemplate
{
    function GetLayout()
    {
        $wizard =& $this->GetWizard(); //Получаем ссылку на объект мастера
        /*
            Определение шаблона
            ...
        */
    }
}

?>


Класс CWizardUtil

Класс CWizardUtil инкапсулирует вспомогательные методы, полезные при разработке мастеров.


CopyFile

CWizardUtil::CopyFile

bool
CopyFile(
 string fileID,
 string destPath,
 bool deleteAfterCopy = true
);

Метод создает копию зарегистрированного файла, указанного в параметре fileID, в файле с именем destPath. Метод возвращает true при успешном копировании, иначе false.

Параметры функции

Параметр | Описание
fileID | ID файла, предназначенного для копирования.
destPath | Путь к файлу, относительно корня сайта, в который нужно скопировать.
deleteAfterCopy | Удалить ли файл из системы после того, как копирования будет завершено. Необязательный параметр, по умолчанию равен true (удалять).

См. также

  • CWizardStep::SaveFile
  • CWizardStep::ShowFileField

Примеры использования

<?
if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

class Step extends CWizardStep
{
    function InitStep()
    {
        $this->SetTitle("Загрузка файла");
        $this->SetStepID("step");

        $this->SetNextStep("step");
        $this->SetFinishStep("step");

        $this->SetNextCaption("Загрузить");
        $this->SetFinishCaption("Скопировать");
    }

    function OnPostForm()
    {
        $wizard =& $this->GetWizard();

        if ($wizard->IsNextButtonClick())
            $this->SaveFile("file", Array("max_file_size" => 20*1024, "extensions" => "gif,jpg,png"));
        elseif($wizard->IsFinishButtonClick())
        {
            $fileID = $wizard->GetVar("file");
            if (intval($fileID) > 0)
                CWizardUtil::CopyFile($fileID, "/upload_picture.gif");
        }
    }

    function ShowStep()
    {
        $this->content .= "Загрузить файл:".$this->ShowFileField("file", Array("max_file_size" => 20*1024, "size" => "25"));
    }

}
?>


CopyWizard

CWizardUtil::CopyWizard

bool
CopyWizard(
 string wizardName,
 string newName
);

Метод создает копию мастера wizardName с новым именем newName. Метод возвращает true при успешном копировании, иначе false.

Параметры функции

Параметр | Описание
wizardName | Имя мастера, который необходимо скопировать.
newName | Новое имя мастера.

См. также

  • CWizardUtil::DeleteWizard

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

$success = CWizardUtil::CopyWizard("help:new_user", "nm:sd2");
if ($success)
    echo "Мастер успешно скопирован";
else
    echo "Произошла ошибка копирования мастера";

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


DeleteWizard

CWizardUtil::DeleteWizard

bool
DeleteWizard(
 string wizardName
);

Метод удаляет мастер с именем wizardName. Метод возвращает true при успешном удалении, иначе false.

Параметры функции

Параметр | Описание
wizardName | Имя мастера, который необходимо удалить.

См. также

  • CWizardUtil::CopyWizard

Примеры использования

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

<?
$success = CWizardUtil::DeleteWizard("nm:sd2");
if ($success)
    echo "Мастер успешно удален";
else
    echo "Произошла ошибка удаления мастера";

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


GetRepositoryPath

CWizardUtil::GetRepositoryPath

string
GetRepositoryPath();

Метод возвращает путь к папке (репозитарию) мастеров относительно корня сайта.


ReplaceMacros

CWizardUtil::ReplaceMacros

void
ReplaceMacros(
 string filePath,
 array arReplace,
 bool skipSharp = false
);

Метод заменяет в файле filePath макросы на заданные в arReplace значения.

Параметры функции

Параметр | Описание
filePath | Абсолютный путь к файлу, в котором нужно заменить макросы. Имя макроса в файле filePath должно быть обрамлено символом #.
arReplace | Массив замен вида Array("имя_макроса" => "замена" [, ...]).
skipSharp | Игнорировать в имени макроса символ #. По умолчанию равен false - не игнорировать.

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

/*
Файл /test_replace.txt:

Ваше имя:#NAME#
Название компании:#COMPANY#
*/

CWizardUtil::ReplaceMacros(
 $_SERVER["DOCUMENT_ROOT"]."/test_replace.txt",
 Array(
    "NAME" => "Леопольд",
    "COMPANY" => "1C-Bitrix",
 )
);

/*
Файл /test_replace.txt после выполнения CWizardUtil::ReplaceMacros:

Ваше имя:Леопольд
Название компании:1C-Bitrix
*/

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


CreateThumbnail

CWizardUtil::CreateThumbnail

bool
CreateThumbnail(
 string sourcePath,
 string previewPath,
 int maxWidth,
 int maxHeight
);

Метод создает уменьшенную копию изображения sourcePath.

Параметры функции

Параметр | Описание
sourcePath | Абсолютный путь к исходному изображению, для которого необходимо сделать уменьшенную копию.
previewPath | Абсолютный путь к файлу, в который будет сохранена уменьшенная копия изображения.
maxWidth | Максимальная ширина уменьшенного изображения.
maxHeight | Максимальная высота уменьшенного изображения.

См. также

  • CWizardStep::SaveFile

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/classes/general/wizard.php");

$success = CWizardUtil::CreateThumbnail($_SERVER["DOCUMENT_ROOT"]."/big.gif",$_SERVER["DOCUMENT_ROOT"]."/small.gif", 100, 100);

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


Введение

В данном разделе представлена общая информация по технологиям и принципам заложенным в систему:

  • Агенты - технология позволяющая запускать PHP функции с заданной периодичностью.
  • Почтовая система - позволяет отправлять E-Mail письма с использованием заранее заданных почтовых шаблонов.
  • Кеширование - позволяет кешировать ресурсоемкие куски кода, при этом заметно увеличивая производительность сайта.
  • Отложенные функции - технология позволяющая задавать некоторые элементы страницы (заголовок, дополнительные пункты навигационной цепочки, мета-тэги, кнопки в панель управления, CSS стили) непосредственно в теле страницы.
  • Перенос посетителей - технология позволяющая синхронизировать по мере возможности набор cookie для разных сайтов, имеющих разные доменные имена и принадлежащие одному порталу.
  • Панель управления - технология позволяющая облегчить администрирование сайта.


Агенты

Агенты - это технология, позволяющая запускать произвольные PHP функции (агенты) с заданной периодичностью.

В самом начале загрузки каждой страницы (непосредственно перед событием OnPageStart) система автоматически проверяет, есть ли агент, который нуждается в запуске и в случае необходимости - исполняет его.

Временная точность запуска агентов напрямую зависит от равномерности и плотности посещаемости сайта. Если вам необходимо организовать запуск каких либо PHP функций в абсолютно точно заданное время, то необходимо воспользоваться стандартной утилитой cron, предоставляемой большинством хостингов.

Для того чтобы агент выполнился в заданное время, его необходимо зарегистрировать в системе при помощи метода CAgent::AddAgent. Удалить регистрацию агента можно с помощью функции CAgent::RemoveAgent.

Если функция-агент принадлежит модулю, то перед ее выполнением, этот модуль будет автоматически подключаться, а именно будет подключаться файл /bitrix/modules/ID модуля/include.php, в этом случае необходимо убедиться, что функция-агент будет доступна после подключения этого файла.

Если функция-агент не принадлежит ни одному из модулей, то ее необходимо разместить в файле /bitrix/php_interface/init.php. Данный файл автоматически подключается в прологе.

Особенности создания функций-агентов:

  • В функции-агенте не доступен глобальный объект $USER класса CUser. Поэтому если предполагается использование этого объекта, то в начале функции необходимо разместить следующий код:

    global $USER;
if (!is_object($USER)) $USER = new CUser;
  • В качестве возвращаемого значения функция-агент должна вернуть PHP код который будет использован при следующем запуске данной функции.

Примеры использования

<?
// добавим агент модуля "Статистика"
CAgent::AddAgent(
    "CStatistic::CleanUpStatistics_2();", // имя функции
    "statistic",                          // идентификатор модуля
    "N",                                  // агент не критичен к кол-ву запусков
    86400,                                // интервал запуска - 1 сутки
    "07.04.2005 20:03:26",                // дата первой проверки на запуск
    "Y",                                  // агент активен
    "07.04.2005 20:03:26",                // дата первого запуска
    30);
?>
<?
// добавим агент модуля "Техподдержка"
CAgent::AddAgent(
    "CTicket::AutoClose();",  // имя функции
    "support",                // идентификатор модуля
    "N",                      // агент не критичен к кол-ву запусков
    86400,                    // интервал запуска - 1 сутки
    "",                       // дата первой проверки - текущее
    "Y",                      // агент активен
    "",                       // дата первого запуска - текущее
    30);
?>
<?
// добавим произвольный агент не принадлежащий ни одному модулю
CAgent::AddAgent("My_Agent_Function();");
?>

<?
// файл /bitrix/php_interface/init.php

function My_Agent_Function()
{
   // выполняем какие-либо действия
   return "My_Agent_Function();";
}
?>
<?
// добавим произвольный агент принадлежащий модулю
// с идентификатором my_module

CAgent::AddAgent(
   "CMyModule::Agent007(1)",
   "my_module",
   "Y",
    86400);
?>

<?
// данный агент будет запущен ровно 7 раз с периодичностью раз в сутки,
// после чего будет удален из таблицы агентов.

Class CMyModule
{
   function Agent007($cnt=1)
   {
      echo "Hello!";
      if($cnt>=7)
         return "";
      return "CMyModule::Agent007(".($cnt+1).")";
   }
}
?>

См. также

Класс CAgent


Почтовая система

Почтовая система - это технология предназначенная для работы с E-Mail сообщениями на сайте.

Работа с почтовой системой состоит из следующих этапов:

  1. Создание типа почтового события. Тип почтового события может быть создан только с использованием функции CEventType::Add.
  2. Создание почтового шаблона. Создание почтового шаблона доступно в административном меню "Почтовые шаблоны", а также при использовании функции CEventMessage::Add.
  3. Создание почтового события. Почтовое событие может быть создано только функцией CEvent::Send.

В конце выполнения каждой страницы, будет автоматически вызвана функция CEvent::CheckEvents, основные задачи которой:

  1. выбрать из таблицы b_event необработанные почтовые события
  2. сгенерировать по ним E-Mail сообщения (письма)
  3. отправить их
  4. записать результат их отправки в таблицу b_event в поле SUCCESS_EXEC, используя одно из следующих обозначений:
    • Y - все письма по всем почтовым шаблонам были успешно отправлены
    • F - все письма по всем почтовым шаблонам не смогли быть отправлены
    • P - часть писем отправлена успешно, часть писем - безуспешно
    • 0 - почтовые шаблоны не были найдены
    • N - почтовое событие ещё не обрабатывалось функцией CEvent::CheckEvents

На отсылку писем можно повлиять изменяя следующие настройки главного модуля:

  • Конвертировать символы новой строки Unix формата в Windows формат при отправке email
  • Конвертировать 8-битные символы в заголовке письма
  • E-Mail адрес или список адресов через запятую на который будут дублироваться все исходящие сообщения
  • Дублировать E-Mail адрес в заголовок
  • Отправлять в письме идентификаторы почтового события и шаблона

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

Пример создания типа почтового события

<?
$obEventType = new CEventType;
$obEventType->Add(array(
    "EVENT_NAME"    => "ADV_BANNER_STATUS_CHANGE",
    "NAME"          => "Изменился статус баннера",
    "SITE_ID"       => "ru",
    "DESCRIPTION"   => "
        #ID# - ID баннера
        #CONTRACT_ID# - ID контракта
        #TYPE_SID# - ID типа
        "
    ));
?>

Пример создания почтового шаблона

<?
$arr["ACTIVE"]      = "Y";
$arr["EVENT_NAME"]  = "ADV_BANNER_STATUS_CHANGE";
$arr["SITE_ID"]     = array("ru","en");
$arr["EMAIL_FROM"]  = "admin@site.ru";
$arr["EMAIL_TO"]    = "admin@site.ru";
$arr["BCC"]         = "";
$arr["SUBJECT"]     = "Изменен статус баннера #ID#";
$arr["BODY_TYPE"]   = "text";
$arr["MESSAGE"]     = "
Внимание! Статус баннера # #ID# изменен.
Тип баннера - #TYPE_SID#
ID контракта - #CONTRACT_ID#
";
$obTemplate = new CEventMessage;
$obTemplate->Add($arr);
?>

Пример создания почтового события

<?
$arFields = array(
    "ID"          => 124,
    "CONTRACT_ID" => 1,
    "TYPE_SID"    => "LEFT"
    );
CEvent::Send("ADV_BANNER_STATUS_CHANGE", array("ru", "en"), $arFields);
?>

См. также

  • Класс CEvent
  • Класс CEventMessage
  • Класс CEventType
  • Настройки главного модуля


Кеширование

Кеширование - это технология позволяющая кешировать результаты работы редко обновляемых и ресурсоемких кусков кода (например, активно работающих с базой данных).

Для реализации этого созданы два класса:

  • CPageCache - для кеширования HTML
  • CPHPCache - для кеширования HTML и PHP переменных

Результаты кеширования сохраняются в виде файлов в каталоге /bitrix/cache/. Если время кеширования не истекло, то вместо ресурсоемкого кода будет подключен предварительно созданный файл кеша.

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

Пример кеширования HTML

<?
// создаем объект
$obCache = new CPageCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$IBLOCK_TYPE.$USER->GetUserGroupString();

// инициализируем буферизирование вывода
if($obCache->StartDataCache($life_time, $cache_id, "/")):

    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;

    // записываем предварительно буферизированный вывод в файл кеша
    $obCache->EndDataCache();

endif;
?>

В данном примере, метод CPageCache::StartDataCache проверит наличие неистекшего и валидного файла кеша. Если такой файл существует, то он будет подключен и выведен на экран, в противном случае будет включена буферизация. Результаты буферизации будут записаны в файл кеша методом CPageCache::EndDataCache.

В первом параметре метода CPageCache::StartDataCache задается интервал времени в секундах, в течении которого файл кеша будет считаться валидным и не истекшим (интервал времени отсчитывается с момента создания файла кеша).

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

Например:

  • Если на результат выполнения кешируемого кода может повлиять авторизация текущего пользователя, то к идентификатору необходимо добавить результат выполнения функции CUser::GetUserGroupString, возвращающей строку c ID групп текущего пользователя.
  • Если в кешируемом коде вы используете постраничную навигацию, то в данный идентификатор обязательно нужно включить результат работы функции CDBResult::NavStringForCache.
  • При использовании сортировки необходимо также помнить, что в идентификатор необходимо включить значения переменных хранящих в себе поле по которому идет сортировка и порядок сортировки (например, $by.$sort).

Пример кеширования HTML и PHP переменных

<?
// создаем объект
$obCache = new CPHPCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$SECTION_ID.$USER->GetUserGroupString();

// если кеш есть и он ещё не истек то
if($obCache->InitCache($life_time, $cache_id, "/") :
    // получаем закешированные переменные
    $vars = $obCache->GetVars();
    $SECTION_TITLE = $vars["SECTION_TITLE"];
else :
    // иначе обращаемся к базе
    $arSection = GetIBlockSection($SECTION_ID);
    $SECTION_TITLE = $arSection["NAME"];
endif;

// добавляем пункт меню в навигационную цепочку
$APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

// начинаем буферизирование вывода
if($obCache->StartDataCache()):

    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;

    // записываем предварительно буферизированный вывод в файл кеша
    // вместе с дополнительной переменной
    $obCache->EndDataCache(array(
        "SECTION_TITLE"    => $SECTION_TITLE
        ));
endif;
?>

Отличие данного примера от предыдущего заключается в том, что помимо HTML также кешируется PHP переменная $SECTION_TITLE. Структура и тип кешируемых PHP переменных могут быть произвольными. Метод CPHPCache::InitCache выполняет проверку на наличие неистекшего и валидного файла кеша. Если данный файл найден, то происходит его подключение, при этом все закешированные переменные будут доступны после использования метода CPHPCache::GetVars. Метод CPHPCache::EndDataCache, помимо буферизированного HTML кода, записывает в файл кеша также PHP переменные.

Для отключения кеширования на одной странице, необходимо авторизоваться с административными правами и вызвать эту страницу с параметром &clear_cache=Y. Если, авторизовавшись с административными правами, вызвать любую страницу с параметром &clear_cache_session=Y, то кеш будет отключен для всех страниц, которые будут просмотрены в рамках сессии. Файлы кеша можно удалить в административной части на странице настроек главного модуля.

См. также

  • Класс CPageCache
  • Класс CPHPCache


Отложенные функции

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

Данная технология была создана в первую очередь для использования в компонентах, которые как правило выводятся в теле страницы, но при этом внутри них могут быть заданы заголовок страницы, добавлен пункт в навигационную цепочку, добавлена кнопка в панель управления и т.д. и т.п.

Примечание: Технология отложенных функций используется только в публичной части. В административной части она не используется.

Алгоритм работы данной технологии:

  1. любой исходящий поток из PHP скрипта буферизируется
  2. как только в коде встречается одна из следующих функций:
    • CMain::ShowTitle
    • CMain::ShowCSS
    • CMain::ShowNavChain
    • CMain::ShowProperty
    • CMain::ShowMeta
    • CMain::ShowPanel
    либо другая функция обеспечивающая откладывание выполнения какой либо функции (отложенной), то:
    1. весь буферизированный до этого контент запоминается в очередном элементе стека A
    2. в стек A добавляется пустой элемент, который в дальнейшем будет заполнен результатом выполнения отложенной функции
    3. имя отложенной функции запоминается в стеке B
    4. буфер очищается и буферизация снова включается
    Таким образом существует стек A, в котором находится весь контент страницы разбитый на части. В этом же стэке есть пустые элементы предназначенные для их дальнейшего заполнения результатами отложенных функций.
    Также существует стек B, в котором запоминаются имена и параметры отложенных функции в порядке их следования в коде.

  3. в конце страницы в служебной части эпилога выполняются следующие действия:
    1. все отложенные функции из стека B начинают выполняться одна за другой
    2. результаты их выполнения вставляются в специально предназначенные для этого места в стек A
    3. весь контент из стека A "склеивается" (конкатенируется) и выводится на экран

Таким образом, данная технология позволяет фрагментировать весь контент страницы, разбивая его на части с помощью специальных функций обеспечивающих временное откладывание выполнения других функций (отложенных функций). В конце страницы все отложенные функции выполняются одна за другой и результаты их выполнения вставляются в отведенные для этого места внутри фрагментированного контента страницы. Затем весь контент склеивается и выводится в поток (отправляется браузеру посетителя сайта).

При использовании этой технологии необходимо учитывать, что над результатами работы функций обеспечивающих откладывание других функций нельзя выполнять какие либо действия, например:

$page_title = $APPLICATION->ShowTitle(); // эта функция ничего не возвращает
if (strlen($page_title)<=0) $page_title = "Заголовок страницы по умолчанию";
echo $page_title;
Данный код не будет работать по той причине, что все отложенные функции выполняются в самом конце страницы, в служебной части эпилога.

Группы функций задействованные в данной технологии:

Имя функции обеспечивающей откладывание Выполнение какой функции откладывается Дополнительные связанные функции
CMain::ShowTitle CMain::GetTitle CMain::SetTitle
CMain::ShowCSS CMain::GetCSS CMain::SetTemplateCSS
CMain::SetAdditionalCSS
CMain::ShowNavChain CMain::GetNavChain CMain::AddChainItem
CMain::ShowProperty CMain::GetProperty CMain::SetPageProperty
CMain::SetDirProperty
CMain::ShowMeta CMain::GetMeta CMain::SetPageProperty
CMain::SetDirProperty
CMain::ShowPanel CMain::GetPanel CMain::AddPanelButton

См. также

  • CMain::AddBufferContent


Перенос посетителей

Система "1С-Битрикс: Управление сайтом" позволяет создать несколько сайтов и организовать их управление. Особенностями данной многосайтовой системы являются:

  • единые права на все сайты
  • единый набор бюджетов пользователей на все сайты
  • единая система ведения статистики на все сайты
  • и т.п.
Исходя из этого, становится актуальной задача распознать одного и того же посетителя приходящего на разные сайты c разными доменными именами. Речь конечно же идет о сайтах созданных в рамках одного портала.

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

Теперь постараемся объяснить на примере суть проблемы:

  • При первом заходе посетителя на сайт A, ему выдаются ряд идентификаторов используемых разными модулями (например, идентификатор посетителя в модуле статистики или идентификатор покупателя в модуле интернет-магазина и т.д.), которые запоминаются в хранимых cookie принадлежащих сайту A.
  • Когда посетитель в следующий раз возвращается на этот же сайт A, он будет "узнан" благодаря информации хранимой в cookie принадлежащих сайту A.
  • Теперь представим, что этот же посетитель пришел на сайт B. Возникает задача "узнать" его как посетителя в недавнем прошлом сайта A. Под термином "узнать" здесь понимается - получить идентификаторы, выданные ему на сайте A. Проблема осложняется тем, что если доменное имя сайта B отличается от доменного имени сайта A, то информация хранимая в cookie принадлежащих сайту A не может быть получена при заходе посетителя на сайт B. Также есть обратная проблема - cookie устанавливаемые с сайта A (и на этот же сайт A) не могут быть установлены на сайт B. Такова политика безопасности браузеров.

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

Алгоритм работы этой технологии можно описать так:

  • Когда посетитель заходит на сайт A, идентификаторы, выдаваемые ему, будут сохраняться в cookie с помощью функции CMain::set_cookie, основная задача которой не только установить cookie для текущего сайта A, но и запомнить данные этого cookie для дальнейшего распостранения его на другие сайты B, C, D.
  • В конце визуальной части эпилога вызывается функция CMain::ShowSpreadCookieHTML. Данная функция выводит набор IFRAME'ов в каждом из которых вызывается скрипт /bitrix/spread.php с того домена на который необходимо установить cookie. Таким образом для сайтов B, C, D будет создано три IFRAME'а, в каждом из которых будет вызван скрипт http://доменное имя сайта/bitrix/spread.php. В параметрах этого скрипта будет передана необходимая информация для установки cookie. Эта информация передается в зашифрованном виде и подписана зашифрованным лицензионным ключом этого портала. В результате получится, что cookie установленный на сайте A, будет скопирован (перенесен) на другие сайты - B, C, D.
  • Аналогично происходит и для других сайтов. Если посетитель зайдя на сайт B получит какой либо идентификатор который необходимо сохранить в cookie, то этот идентификатор будет также сохранен и для других сайтов A, C, D. Таким образом мы добиваемся единого набора cookie для всех сайтов одного портала.

Использование данной технологии позволяет в модуле "Статистика" подсчитывать уникальных посетителей для всего портала. В модуле "Реклама, баннеры" - позволяет корректно учитывать количество показов одного баннера одному посетителю. Другие модули также активно используют данную технологию.

См. также

  • Сайты
  • CMain::set_cookie
  • CMain::get_cookie
  • CMain::ShowSpreadCookieHTML


Административная панель (до версии 7.0)

Административная панель управления - это HTML-код, который может быть выведен авторизованному пользователю при наличии у него достаточных прав на операции, представленные на панели управления. HTML-код представляет из себя область с кнопками, в самом вверху страницы, каждая из которых предназначена для той или иной операции.

В публичной части панель выводится с помощью функции CMain::ShowPanel. Данная функция использует технологию отложенных функций, что позволяет добавлять кнопки в панель непосредственно в теле страницы.

Добавить кнопку в панель можно с помощью функции CMain::AddPanelButton. Эту же функцию можно использовать в скрипте /bitrix/php_interface/include/add_top_panel.php, который автоматически будет подключен при выводе панели.

Панель не является неотъемлемой и обязательной частью системы "1C-Битрикс: Управление сайтом", но она является удобным способом администрирования сайта. На сегодняшний день поддерживаются следующие стандартные кнопки, каждая из которых выполняет ту или иную операцию:

  • - создание нового каталога в модуле "Управление структурой"
  • - редактирование свойств каталога в модуле "Управление структурой"
  • - создание новой страницы в текущем разделе (модуль "Управление структурой")
  • - редактирование текущей страницы в модуле "Управление структурой"
  • - создание новой страницы через модуль "Документооборот"
  • - редактирование текущей страницы через модуль "Документооборот"
  • - перейти в историю редактирования текущей страницы в модуле "Документооборот"
  • - создание нового информационного блока в модуле "Информационные блоки"
  • - редактирование информационного блока в модуле "Информационные блоки"
  • - создание нового раздела в модуле "Информационные блоки"
  • - редактирование раздела в модуле "Информационные блоки"
  • - создание нового элемента в модуле "Информационные блоки"
  • - редактирование элемента в модуле "Информационные блоки"
  • - перейти в историю редактирования элемента в модуле "Информационные блоки"
  • - по нажатии в новом окне строит график посещаемости страницы. Модуль "Статистика"
  • - отображает статистику переходов по ссылкам с данной страницы. Модуль "Статистика"
  • - позволяет обновить закешированные данные на странице
  • - позволяет отобразить/скрыть отладочную информацию на странице: названия используемых компонентов, время выполнения запросов и т.д.
  • - переход в публичный раздел из административного раздела или из режима редактирования сайта
  • - переход в режим редактирования сайта, т.е. будут отображены включаемые области, компоненты 1.0 и 2.0, редактируемые области. Каждая из областей имеет свой набор управляющих кнопок:
    • - редактировать параметры компонента (независимо от версии) в форме в публичной части
    • - редактировать код компонента 1.0 в виде php с копированием из папки модуля в папку шаблона сайта
    • - копировать шаблон компонента 2.0 из папки компонента в один из шаблонов сайта (настраивается по желанию в выводимой форме)
    • - отображается после копирования шаблона компонента 2.0 в один из шаблонов сайта. Позволяет перейти к редактированию текущей страницы шаблона. Для включаемой области позволяет перейти к редактированию содержимого данной включаемой области
    • - позволяет очистить кеш данного компонента
    • - редактировать текущий баннер в модуле "Реклама, баннеры"
    • - перейти к списку баннеров в модуле "Реклама, баннеры"
    • - редактировать пункты меню
  • - перейти в административный раздел
  • - закончить сеанс (logout)

См. также

  • CMain::ShowPanel
  • CMain::AddPanelButton
  • CMain::IncludeFile
  • CMain::IncludeString
  • CMain::GetShowIncludeAreas


Внешняя авторизация

Иногда для авторизации (проверки имени входа и пароля) пользователя бывает необходимо использовать свои алгоритмы проверки и(или) внешние БД для хранения пользователей. Например, уже имеется база пользователей и необходимо дать им возможность авторизовываться на сайте под управлением CMS. В таких случаях, иногда, можно просто перенести всех пользователей в БД CMS, используя API функции, но зачастую это просто невозможно по двум причинам. Первая - пароли пользователей во внешней БД не хранятся в открытом виде, хранится только хэш от них, поэтому после переноса пользователи не смогут авторизоваться по причине несовпадения пароля. Вторая причина заключается в том, что иногда необходимо чтобы база пользователей была единой, т.е. пароли пользователей хранились на одном удаленном сервере и использовались для проверки в нескольких местах, в том числе и в CMS.

Для решения таких задач в "1С-Битрикс: Управление сайтом", реализована возможность добавить к стандартной встроенной системе авторизации свою внешнюю. Для этого необходимо реализовать несколько шагов, которые разберем на примере внешней авторизации, используя БД пользователей популярного форума PHP BB.

Для начала создадим файл, например, /bitrix/php_interface/scripts/phpbb.php. В этом классе будет размещён класс с внешним обработчиком, назовем его __PHPBB2Auth:

class __PHPBB2Auth
{
}

Для того чтобы во время попытки авторизоваться вызвалась наша функция, необходимо установить обработчик события OnUserLoginExternal, который будет вызываться автоматически каждый раз при вводе пользователем имени входа и пароля, перед встроенной проверкой. Для этого в файле /bitrix/php_interface/init.php воспользуемся функцией AddEventHandler:

AddEventHandler(
     "main",
     "OnUserLoginExternal",
     Array("__PHPBB2Auth", "OnUserLoginExternal"),
     100,
     $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
);

В качестве обработчика мы указали метод нашего класса __PHPBB2Auth::OnUserLoginExternal. Обработчик события OnUserLoginExternal принимает в качестве параметра ссылку на массив с полями для проверки:

define("PHPBB2_TABLE_PREFIX", "phpbb_");
function OnUserLoginExternal(&$arArgs)
{
    $table_user = PHPBB2_TABLE_PREFIX."users";
    $table_user_group = PHPBB2_TABLE_PREFIX."user_group";
    extract($arArgs);

    global $DB, $USER, $APPLICATION;

    $strSql = "SELECT * FROM ".
              $table_user.
              " WHERE username='".
              $DB->ForSQL($login).
              "' AND user_password='".
              $DB->ForSql(md5($password))."'";
    $dbRes = $DB->Query($strSql);
    if($arRes = $dbRes->Fetch())
    {
        if($arRes['user_active']!='0')
        {
            // имя пользователя и пароль подошел
        }
    }
}

После того как имя входа и пароль проверены по алгоритму PHPBB, необходимо создать внешнего пользователя во внутренней БД, чтобы к нему можно было привязывать внутренние объекты (новости, голосования и т.п.). Для этого воспользуемся методом CUser::GetList с фильтром по имени входа и коду внешнего источника. Если такой пользователь не существует - создадим его, если существует - обновим информацию о нем.

$arFields = Array(
    "LOGIN" => $login,
    "NAME" => $login,
    "PASSWORD" => $password,
    "EMAIL" => $arRes['user_email'],
    "ACTIVE" => "Y",
    "EXTERNAL_AUTH_ID"=>"PHPBB2",
    "LID" => SITE_ID
    );
$oUser = new CUser;
$res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$login, "EXTERNAL_AUTH_ID"=>"PHPBB2"));
if(!($ar_res = $res->Fetch()))
    $ID = $oUser->Add($arFields);
else
{
    $ID = $ar_res["ID"];
    $oUser->Update($ID, $arFields);
}
if($ID>0)
{
   // можно авторизовывать
   return $ID;
}

Теперь у нас есть идентификатор пользователя в нашей БД и можно его вернуть из функции обработчика чтобы этот пользователь был авторизован системой, но новый пользователь будет анонимным, т.к. не привязан ни к одной из групп. Воспользуемся привязкой в базе PHPBB, чтобы перенести ее в нашу БД до авторизации.

$USER->SetParam("PHPBB2_USER_ID", $arRes['user_id']);
$groups_map = Array(
    /*'PhpBB2 Group ID' => 'Local Group ID',*/
     '2' => '1'
    );

$user_groups = Array();
$dbUserGroup = $DB->Query('SELECT * FROM '.$table_user_group.' WHERE user_id='.$arRes['user_id']);
while($arUserGroup = $dbUserGroup->Fetch())
    $user_groups[] = $arUserGroup['group_id'];

if(count($user_groups)>0)
{
    $arUserGroups = CUser::GetUserGroup($ID);
    foreach($groups_map as $ext_group_id => $group_id)
    {
        if(in_array($ext_group_id, $user_groups))
            $arUserGroups[] = $group_id;
        else
        {
            $arUserGroupsTmp = Array();
            foreach($arUserGroups as $grid)
                if($grid != $group_id)
                    $arUserGroupsTmp[] = $grid;
            $arUserGroups = $arUserGroupsTmp;
        }
    }
    CUser::SetUserGroup($ID, $arUserGroups);
}

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

$arArgs["store_password"] = "N";
return $ID;

Для того чтобы зарегистрировать новую внешнюю проверку авторизации в системе, необходимо обработать событие OnExternalAuthList. Добавим в файл /bitrix/php_interface/init.php соответствующий вызов:

AddEventHandler(
     "main",
     "OnExternalAuthList",
     Array("__PHPBB2Auth", "OnExternalAuthList"),
     100,
     $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
     );

Функция обработчик должна вернуть массив из набора обработчиков с полямим ID и NAME.

function OnExternalAuthList()
{
    return Array(
        Array("ID"=>"PHPBB2", "NAME"=>"PhpBB2")
        );
}

Теперь на странице редактирования пользователя появится выпадающий список со списком внешних источников авторизации. Приведем полный текст файла /bitrix/php_interface/scripts/phpbb.php. В нем дополнительно реализован обратный механизм: при авторизации пользователя в нашей системе он автоматически авторизуется на форуме.

<?
define("PHPBB2_TABLE_PREFIX", "phpbb_");

class __PHPBB2Auth
{
    function OnUserLoginExternal(&$arArgs)
    {
        ////////// <settings> ////////////
        $table_user = PHPBB2_TABLE_PREFIX."users";
        $table_user_group = PHPBB2_TABLE_PREFIX."user_group";
        $groups_map = Array(
            /*'PhpBB2 Group ID' => 'Local Group ID',*/
            '2' => '1'
            );
        ////////// </settings> ////////////
        extract($arArgs);

        global $DB, $USER, $APPLICATION;

        $strSql = "SELECT * FROM ".
                  $table_user.
                  " WHERE username='".
                  $DB->ForSQL($login).
                  "' AND user_password='".
                  $DB->ForSql(md5($password))."'";
        $dbRes = $DB->Query($strSql);
        if($arRes = $dbRes->Fetch())
        {
            if($arRes['user_active']!='0')
            {
                $arFields = Array(
                    "LOGIN" => $login,
                    "NAME" => $login,
                    "PASSWORD" => $password,
                    "EMAIL" => $arRes['user_email'],
                    "ACTIVE" => "Y",
                    "EXTERNAL_AUTH_ID"=>"PHPBB2",
                    "LID" => SITE_ID
                    );
                $oUser = new CUser;
                $res = CUser::GetList($O, $B,
                                      Array("LOGIN_EQUAL_EXACT"=>$login,
                                            "EXTERNAL_AUTH_ID"=>"PHPBB2"));
                if(!($ar_res = $res->Fetch()))
                    $ID = $oUser->Add($arFields);
                else
                {
                    $ID = $ar_res["ID"];
                    $oUser->Update($ID, $arFields);
                }

                if($ID>0)
                {
                    $USER->SetParam("PHPBB2_USER_ID", $arRes['user_id']);

                    $user_groups = Array();
                    $dbUserGroup = $DB->Query('SELECT * FROM '.
                                              $table_user_group.
                                              ' WHERE user_id='.$arRes['user_id']);
                    while($arUserGroup = $dbUserGroup->Fetch())
                        $user_groups[] = $arUserGroup['group_id'];

                    if(count($user_groups)>0)
                    {
                        $arUserGroups = CUser::GetUserGroup($ID);
                        foreach($groups_map as $ext_group_id => $group_id)
                        {
                            if(in_array($ext_group_id, $user_groups))
                                $arUserGroups[] = $group_id;
                            else
                            {
                                $arUserGroupsTmp = Array();
                                foreach($arUserGroups as $grid)
                                    if($grid != $group_id)
                                        $arUserGroupsTmp[] = $grid;
                                $arUserGroups = $arUserGroupsTmp;
                            }
                        }
                        CUser::SetUserGroup($ID, $arUserGroups);
                    }
                    $arArgs["store_password"] = "N";

                    return $ID;
                }
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"PHPBB2", "NAME"=>"PhpBB2 Board")
            );
    }

    function OnAuthorize(&$arArgs)
    {
        extract($arArgs);

        global $DB, $APPLICATION, $USER;
        $user_id = $USER->GetParam("PHPBB2_USER_ID");
        if($user_id<=0)
            return;
        $table_user = PHPBB2_TABLE_PREFIX."users";
        $table_sessions = PHPBB2_TABLE_PREFIX."sessions";
        $table_config = PHPBB2_TABLE_PREFIX."config";

        $dbConfig = $DB->Query("SELECT * FROM ".
                               $table_config.
                               " WHERE config_name
                                 IN ('cookie_name', 'cookie_path', 'cookie_domain', 'cookie_secure')");
        while($arConfig = $dbConfig->Fetch())
            ${$arConfig['config_name']} = $arConfig['config_value'];

        if (isset($HTTP_COOKIE_VARS[$cookie_name . '_sid']) ||
            isset($HTTP_COOKIE_VARS[$cookie_name . '_data']))
            $session_id = isset($HTTP_COOKIE_VARS[$cookie_name . '_sid']) ?
                               $HTTP_COOKIE_VARS[$cookie_name . '_sid'] : '';

        $ip_sep = explode('.', $_SERVER['REMOTE_ADDR']);
        $user_ip = sprintf('%02x%02x%02x%02x', $ip_sep[0], $ip_sep[1], $ip_sep[2], $ip_sep[3]);
        $current_time = time();
        $sql =
            "UPDATE ".$table_sessions." SET ".
            "    session_user_id = ".$user_id.", ".
            "    session_start = ".$current_time.", ".
            "    session_time = ".$current_time.", ".
            "    session_page = 0, ".
            "    session_logged_in = 1 ".
            "WHERE session_id = '".$DB->ForSQL($session_id)."' ".
            "    AND session_ip = '".$user_ip."'";

        $r = $DB->Query($sql);
        if($r->AffectedRowsCount()<=0)
        {
            $session_id = md5(uniqid($user_ip));
            $sql =
                "INSERT INTO ".
                $table_sessions.
                "(session_id, session_user_id, session_start, session_time, session_ip, session_page, session_logged_in)".
                "VALUES ('".$session_id."', ".$user_id.", ".$current_time.", ".$current_time.", '".$user_ip."', 0, 1)";
            $DB->Query($sql);
        }

        $sql =
            "UPDATE ".$table_user." SET ".
            "    user_session_time = ".$current_time.", ".
            "    user_session_page = 0, ".
            "    user_lastvisit = ".$current_time." ".
            "WHERE user_id = ".$user_id;

        $DB->Query($sql);

        $sessiondata = Array('userid' => $user_id);

        setcookie($cookie_name.'_data',
                  serialize($sessiondata),
                  $current_time + 31536000,
                  $cookie_path,
                  $cookie_domain, $cookie_secure);
        setcookie($cookie_name.'_sid',
                  $session_id, 0, $cookie_path,
                  $cookie_domain, $cookie_secure);
    }
}
?>

Следующие строки необходимо добавить в /bitrix/php_interface/init.php:

<?
AddEventHandler(
    "main",
    "OnUserLoginExternal",
    Array("__PHPBB2Auth", "OnUserLoginExternal"),
    100,
    $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
    );

AddEventHandler(
    "main",
    "OnExternalAuthList",
    Array("__PHPBB2Auth", "OnExternalAuthList"),
    100,
    $_SERVER['DOCUMENT_ROOT'].'/bitrix/php_interface/scripts/phpbb.php'
    );

AddEventHandler(
    "main",
    "OnAfterUserAuthorize",
    Array("__PHPBB2Auth", "OnAuthorize"),
    100
    );
?>

В качестве примера ещё один скрипт внешней авторизации - для форума Invision Power Board:

<?
define("IPB_TABLE_PREFIX", "ibf_");
define("IPB_VERSION", "2");

AddEventHandler("main", "OnUserLoginExternal", Array("__IPBAuth", "OnUserLoginExternal"));
AddEventHandler("main", "OnExternalAuthList", Array("__IPBAuth", "OnExternalAuthList"));

class __IPBAuth
{
    function OnUserLoginExternal(&$arArgs)
    {
        extract($arArgs);

        ////////// <settings> ////////////
        $table_user = IPB_TABLE_PREFIX."members";
        $table_converge = IPB_TABLE_PREFIX."members_converge";
        $groups_map = Array(
            /*'IPB Group ID' => 'Local Group ID',*/
            '4' => '1'
            );
        ////////// </settings> ////////////

        global $DB, $USER, $APPLICATION;

        if(IPB_VERSION == '1')
        {
            $strSql = "SELECT * FROM ".$table_user." WHERE name='".$DB->ForSql($login)."' AND password='".md5($password)."'";
        }
        else
        {
            $strSql =
                "SELECT t1.* ".
                "FROM ".$table_user." t1, ".$table_converge." t2 ".
                "WHERE t1.name='".$DB->ForSql($login)."' ".
                "    AND t1.email = t2.converge_email ".
                "    AND t2.converge_pass_hash = MD5(CONCAT(MD5(t2.converge_pass_salt), '".md5($password)."'))";
        }

        $dbAuthRes = $DB->Query($strSql);
        if($arAuthRes = $dbAuthRes->Fetch())
        {
            $arFields = Array(
                "LOGIN" => $login,
                "NAME" => $arAuthRes['title'],
                "PASSWORD" => $password,
                "EMAIL" => $arAuthRes['email'],
                "ACTIVE" => "Y",
                "EXTERNAL_AUTH_ID"=>"IPB",
                "LID" => SITE_ID
                );

            $oUser = new CUser;
            $res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$login, "EXTERNAL_AUTH_ID"=>"IPB"));
            if(!($ar_res = $res->Fetch()))
                $ID = $oUser->Add($arFields);
            else
            {
                $ID = $ar_res["ID"];
                $oUser->Update($ID, $arFields);
            }

            if($ID>0)
            {
                $USER->SetParam("IPB_USER_ID", $arAuthRes['id']);

                $user_group = $arAuthRes['mgroup'];
                $arUserGroups = CUser::GetUserGroup($ID);
                foreach($groups_map as $ext_group_id => $group_id)
                {
                    if($ext_group_id==$user_group)
                        $arUserGroups[] = $group_id;
                    else
                    {
                        $arUserGroupsTmp = Array();
                        foreach($arUserGroups as $grid)
                            if($grid != $group_id)
                                $arUserGroupsTmp[] = $grid;
                        $arUserGroups = $arUserGroupsTmp;
                    }
                }
                CUser::SetUserGroup($ID, $arUserGroups);
                $arArgs["store_password"] = "N";

                return $ID;
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"IPB", "NAME"=>"Invision Power Board")
            );
    }
}
?>

Для того чтобы данный скрипт начал работать, его необходимо подключить в /bitrix/php_interface/init.php.

См. также

  • AddEventHandler
  • OnUserLoginExternal
  • OnExternalAuthList
  • Обработка событий


Обработка событий

Иногда бывает необходимо повлиять на ход выполнения какой-нибудь API функции. Но если ее изменить, то эти изменения будут утеряны при очередном обновлении. Для таких случаем и разработана система событий. В ходе выполнения некоторых API функций, в определённых точках установлены вызовы определённых функций, так называемых обработчиков события.

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

Теперь подробнее о регистрации функций-обработчиков:

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

Пример

// функции обработчики модуля компрессии подключаются дважды - в начале и в конце каждой страницы
RegisterModuleDependences("main", "OnPageStart", "compression", "CCompress", "OnPageStart", 1);
RegisterModuleDependences("main", "OnAfterEpilog", "compression", "CCompress", "OnAfterEpilog");

// инсталлятор модуля рекламы регистирует пустой обработчик
// при возникновении события OnBeforeProlog модуль рекламы будет просто подключаться на каждой странице
// что сделает возможным выполнять его API функции без предварительного подключения в теле страницы
RegisterModuleDependences("main", "OnBeforeProlog", "advertising");

AddEventHandler - функция предназначена для регистрации произвольных обработчиков, которые не расположены в модулях. Ее необходимо вызывать до возникновения события на тех страницах где требуется его обработать. Например, если событие нужно обработать на всех страницах где оно возникает, то функцию можно вызвать в /bitrix/php_interface/init.php.

Пример

// регистрация обработчика в /bitrix/php_interface/init.php
AddEventHandler("main", "OnBeforeUserLogin", "MyOnBeforeUserLoginHandler");
function MyOnBeforeUserLoginHandler($arFields)
{
   if(strtolower($arFields["LOGIN"])=="guest")
   {
       global $APPLICATION;
       $APPLICATION->throwException("Пользователь с именем входа Guest не может быть авторизован.");
       return false;
   }
}

Как правило, события делятся по месту возникновения и назначению на следующие группы:
- предназначенные для отмены дальнейшего выполнения метода, например, событие OnBeforeDeleteUser позволяет отменить удаление пользователя при заданных условиях (наличие критических связанных объектов), событие OnBeforeUserLogin - запретить авторизацию пользователю.
- позволяющие выполниться в определённых методах, при завершении их исполнения, например, OnAfterUserLogin - после проверки имени входа и пароля, событие OnUserDelete - перед непосредственным удалением пользователя из БД, позволяет удалить связанные объекты.
- возникающие во время исполнения страницы, для того чтобы включить свой код в определённые места на странице, например, OnBeforeProlog (подробнее см. порядок выполнения страниц).

Подробнее о месте возникновения и возможностей применения смотрите в описании каждого события.

См. также

  • AddEventHandler
  • RegisterModuleDependences
  • Взаимодействие модулей
  • Список событий главного модуля
  • Порядок выполнения страниц


Административная панель

Административная панель управления - это HTML-код, который может быть выведен авторизованному пользователю при наличии у него достаточных прав на операции, представленные на панели управления. HTML-код представляет из себя область с кнопками, в самом вверху страницы, каждая из которых предназначена для той или иной операции.

Подключение панели осуществляется с помощью функции CMain::ShowPanel. Данная функция использует технологию отложенных функций, что позволяет добавлять кнопки в панель непосредственно в теле страницы.

Добавить кнопку в панель можно с помощью функции CMain::AddPanelButton. Эту же функцию можно использовать в скрипте /bitrix/php_interface/include/add_top_panel.php, который автоматически будет подключен при выводе панели.

Административная панель поддерживает 4 режима работы системы. Из них три - это режимы работы публичного раздела сайта, а четвертый - это переход в административный раздел:

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


Введение

Введение

Система "1С-Битрикс: Управление сайтом" поставляется в различных редакциях. Каждая редакция представляет из себя комбинацию стандартных модулей. При этом у вас есть возможность создать свой собственный модуль. Количество модулей в системе не ограничено.

Данный раздел посвящен созданию своего собственного модуля. Помимо этого раздела вы можете познакомиться со статьями посвященными разработке под "1С-Битрикс: Управление сайтом", в том числе и разработке модулей.

Оглавление раздела

  • Структура файлов - описание структуры обязательных файлов модуля
  • Административные скрипты - описание схемы работы скриптов модуля в административной части
  • Административное меню - описание схемы работы административного меню модуля
  • Языковые файлы - описание схемы расположения языковых файлов и их подключения в административных скриптах и компонентах модуля
  • Описание модуля - описание класса используемого системой для взаимодействия с модулем (инсталляции, деинсталляции, получение списка прав и т.п.)
  • Инсталляция - описание обязательных действий при инсталляции
  • Деинсталляция - описание обязательных действий при деинсталляции
  • Параметры модуля - описана технология хранения и манипуляции параметрами модуля
  • Взаимодействие модулей - описана технология явного взаимодействия модулей и их взаимодействие посредством событий
  • Идентификаторы - таблица идентификаторов стандартных модулей


Структура файлов

Структура обязательных файлов модуля:

  • /bitrix/modules/ID модуля/ - корневой каталог модуля
    • /admin/ - каталог с административными скриптами модуля
      • menu.php - файл с административным меню модуля
    • /classes/ - скрипты с классами модуля
      • /general/ - классы модуля не зависящие от используемой базы данных
      • /mysql/ - классы модуля предназначенные для работы только с MySQL
      • /oracle/ - классы модуля предназначенные для работы только с Oracle
    • /lang/ID языка/ - каталог с языковыми файлами скриптов модуля
      • /install/ - каталог с файлами используемыми для инсталляции и деинсталляции модуля
        • /admin/ - каталог со скриптами подключающими административные скрипты модуля (вызывающие скрипты)
          • /db/ - каталог с SQL скриптами для инсталляции/деинсталляции базы данных
            • /mysql/ - SQL скрипты для инсталляции/деинсталляции таблиц в MySQL
            • /oracle/ - SQL скрипты для инсталляции/деинсталляции таблиц в Oracle
          • /images/ - каталог с изображениями используемыми модулем; после инсталляции модуля они должны быть скопированы в каталог /bitrix/images/ID модуля/
            • /templates/ - каталог с компонентами модуля
              • /ID модуля/ - каталог с основными файлами компонент
              • /lang/ID языка/ID модуля/ - в данном каталоге находятся языковые файлы компонент модуля
            • index.php - файл с описанием модуля
          • include.php - данный файл подключается в тот момент когда речь идет о подключении модуля в коде, в нем должны находиться включения всех файлов с библиотеками функций и классов модуля
            • default_option.php - содержит массив с именем $ID модуля_default_option, в котором заданы значения по умолчанию для параметров модуля
              • options.php - данный файл подключается на странице настройки параметров модулей в административном меню "Настройки"
                • prolog.php - файл должен подключаться во всех административных скриптах модуля, помимо всего прочего в нем должны быть определены следующие две константы:
                  ADMIN_MODULE_NAME - идентификатор модуля;
                  ADMIN_MODULE_ICON - HTML код для большой иконки модуля выводимой над заголовком страницы.


Административные скрипты

Административные скрипты - это скрипты используемые модулем в административной части системы. Они должны располагаться в каталоге /bitrix/modules/ID модуля/admin/.

Необходимо учитывать, что напрямую в браузере административные скрипты нельзя вызывать (как в общем-то и любые скрипты каталога /bitrix/modules/). Поэтому для их вызова используются дополнительные одноименные скрипты находящиеся в каталоге /bitrix/admin/ (назовем их вызывающие скрипты). Они как правило состоят только из подключения одноименного административного скрипта:

<?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/ID модуля/admin/имя скрипта");
?>

При инсталляции модуля, вызывающие скрипты должны быть скопированы из каталога /bitrix/modules/ID модуля/install/admin/ в каталог /bitrix/admin/.

В момент деинсталляции модуля вызывающие скрипты должны быть удалены из каталога /bitrix/admin/.

Необходимо учитывать, что вызывающие скрипты всех инсталлированных модулей находятся в одном каталоге /bitrix/admin/, поэтому во избежание дублирования, желательно давать им имена начинающиеся с какого-либо префикса характерного только для соответствующего модуля.

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

  • ADMIN_MODULE_NAME - идентификатор вашего модуля (см. для примера идентификаторы стандартных модулей)
  • ADMIN_MODULE_ICON - HTML код для большой иконки модуля выводимой над заголовком страницы
Они необходимы для формирования иконки над заголовком страницы.

Пример определения таких констант:

define("ADMIN_MODULE_NAME", "statistic");
define("ADMIN_MODULE_ICON", "<a href=\"stat_list.php?lang=".LANGUAGE_ID."\">
<img src=\"/bitrix/images/statistic/statistic.gif\"
width=\"48\" height=\"48\" border=\"0\" alt=\"".GetMessage("STAT_MODULE_TITLE")."\"
title=\"".GetMessage("STAT_MODULE_TITLE")."\"></a>");


Административное меню

Меню административной части выводиться стандартной функцией CMain::GetMenuHtmlEx.

Шаблон меню храниться в файле:

/bitrix/modules/main/interface/.left.menu_template.php

Основным файлом собирающим пункты меню является:

/bitrix/modules/main/interface/.left.menu.php
В нем происходит перебор всех файлов /bitrix/modules/ID модуля/admin/menu.php. В каждом таком файле содержиться определение массива $aModuleMenuLinks, содержащего пункты меню соответствующего модуля. Все эти массивы затем будут объеденены в стандартный массив $arMenuSections, содержащий информацию о всех пунктах меню (см. подробнее в разделе "Меню").

Структура массива $aModuleMenuLinks:

Array
(
    [0] => Array
        (
            [0] => заголовок пункта меню
            [1] => ссылка на пункте меню
            [2] => Array
                (
                    [0] => дополнительный ссылка для подсветки пункта меню 1
                    [1] => дополнительный ссылка для подсветки пункта меню 2
                    ...
                    [N] =>  дополнительный ссылка для подсветки пункта меню N
                )
            [3] => Array
                (
                    [ALT] => текст всплывающей подсказки на пункте меню
                    [SECTION_ID] => уникальный идентификатор раздела меню,
                                    принимает значение равное ID модуля,
                                    либо одно из следующих:
                                       FAVORITE - раздел "Избранное"
                                       GENERAL - раздел "Пользователи"
                                       MAIN - раздел "Настройки системы"

                    [SEPARATOR] => "Y" - пункт меню является заголовком раздела меню
                    [SORT] => сортировка раздела меню
                              относительно других разделов меню (только если SEPARATOR=Y)
                    [ICON] => ссылка на маленькую иконку используемую
                              в заголовке раздела меню (только если SEPARATOR=Y)
                    [BIG_ICON] => ссылка на большую иконку для использование
                                  на странице "Рабочий стол" (только если SEPARATOR=Y)
                    [INDEX_PAGE] => ссылка на иконке BIG_ICON (только если SEPARATOR=Y)
                )

        )
    [1] => Array( -//- )
    [2] => Array( -//- )
    ...
    [M] => Array( -//- )
)

Пример файла /bitrix/modules/support/admin/menu.php определяющего меню модуля "Техподдержка":

<?
// подключим языковой файл
IncludeModuleLangFile(__FILE__);

// определим права текущего пользователя
$SUP_RIGHT = $APPLICATION->GetGroupRight("support");

// если доступ не запрещён то
if($SUP_RIGHT>"D")
{
    // добавляем пункты меню в зависимости от прав

    $aModuleMenuLinks[] = Array(
            GetMessage("SUP_M_SUPPORT"),
            "",
            Array(),
            Array(
                "SEPARATOR"  => "Y",
                "SORT"       => 1000,
                "ICON"       => "/bitrix/images/support/mnu_support.gif",
                "BIG_ICON"   => "/bitrix/images/support/support.gif",
                "INDEX_PAGE" => "/bitrix/admin/ticket_desktop.php?lang=".LANGUAGE_ID."&set_default=Y"
                )
            );

    if ($SUP_RIGHT>="T")
    {
        $aModuleMenuLinks[] = Array(
                GetMessage("SUP_M_REPORT_TABLE"),
                "/bitrix/admin/ticket_desktop.php?lang=".LANGUAGE_ID."&set_default=Y",
                Array("/bitrix/admin/ticket_desktop.php"),
                Array("ALT"=>GetMessage("SUP_M_REPORT_TABLE_ALT"))
                );
    }

    $aModuleMenuLinks[] = Array(
            GetMessage("SUP_M_TICKETS"),
            "/bitrix/admin/ticket_list.php?lang=".LANGUAGE_ID."&set_default=Y",
            Array(
                "/bitrix/admin/ticket_list.php",
                "/bitrix/admin/ticket_edit.php",
                "/bitrix/admin/ticket_message_edit.php"
                ),
            Array("ALT"=>GetMessage("SUP_M_TICKETS_ALT"))
            );

    if ($SUP_RIGHT>="T")
    {
        $aModuleMenuLinks[] = Array(
                GetMessage("SUP_M_REPORT_GRAPH"),
                "/bitrix/admin/ticket_report_graph.php?lang=".LANGUAGE_ID."&set_default=Y",
                Array("/bitrix/admin/ticket_report_graph.php"),
                Array("ALT"=>GetMessage("SUP_M_REPORT_GRAPH_ALT"))
                );
    }

    if ($SUP_RIGHT>="V")
    {
        $aModuleMenuLinks[] = Array(
                GetMessage("SUP_M_CATEGORY"),
                "/bitrix/admin/ticket_dict_list.php?lang=".LANGUAGE_ID."&find_type=C&set_filter=Y",
                Array(
                    "/bitrix/admin/ticket_dict_edit.php?find_type=C",
                    "/bitrix/admin/ticket_dict_list.php?find_type=C"
                    )
                );
    }
}
?>

Если вы не пишете свой модуль и возникла необходимость добавить произвольный пункт в административное меню, то необходимо в файле /bitrix/admin/.left.menu.php, инициализировать массив $aMenuLinks соответствующими значениями.

Пример файла /bitrix/admin/.left.menu.php добавляющего произвольный пункт меню:

<?
// добавим пункт меню "Импорт техники" в раздел "Информ. блоки"
$aMenuLinks = Array(
    Array(
        "Импорт техники",
        "/bitrix/admin/equipment_import.php?lang=ru",
        Array(),
        Array(
            "ALT" => "Импорт техники из dbf файлов",
            "SECTION_ID" => "iblock",
            "SORT" => "100"
        )
    )
);
?>

См. также

  • Меню
  • CMain::GetMenuHtmlEx


Языковые файлы

Для административных скриптов модуля языковые файлы должны располагаться в каталоге:

/bitrix/modules/ID модуля/lang/ID языка/

Особенностью их расположения внутри этого каталога является то, что они должны располагаться строго по тому же пути относительно каталога /bitrix/modules/ID модуля/, что одноименные файлы в которых они подключаются. В этом случае подключение языковых файлов может осуществляться только функцией IncludeModuleLangFile.

К примеру для скрипта:

/bitrix/modules/ID модуля/admin/body/my_script.php

языковой файл должен быть:

/bitrix/modules/ID модуля/lang/ID языка/admin/body/my_script.php

И подключаться кодом:

IncludeModuleLangFile(__FILE__);


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

Каждый модуль должен быть корректно описан в системе для того, чтобы система знала, как с этим модулем работать. Некорректно описаные модули могут привести к полной или частичной неработоспособности системы (например, может не работать система обновлений).

Основным файлом используемым системой для манипуляции модулем является /bitrix/modules/ID модуля/install/index.php. Основное назначение этого файла - это размещение в нем класса с именем совпадающем с ID модуля.

Обязательные методы этого класса:

  • DoInstall - запускается при нажатии кнопки "Установить" в административном меню "Модули", осуществляет инсталляцию модуля (о функции см. подробнее CModule::DoInstall)
  • DoUninstall - запускается при нажатии кнопки "Удалить" в административном меню "Модули", осуществляет деинсталляцию модуля (о функции см. подробнее CModule::DoUninstall)

Необязательный метод этого класса:

  • GetModuleRightList - возвращает список уникальных прав (или ролей) модуля (о функции см. подробнее CModule::GetModuleRightList)

Обязательные свойства объекта этого класса:

  • MODULE_ID - хранит ID модуля
  • MODULE_VERSION - текущая версия модуля в формате XX.XX.XX
  • MODULE_VERSION_DATE - строка содержащая дату версии модуля; дата должна быть задана в формате YYYY-MM-DD HH:MI:SS
  • MODULE_NAME - имя модуля
  • MODULE_DESCRIPTION - описание модуля
  • MODULE_GROUP_RIGHTS - если задан метод GetModuleRightList, то данное свойство должно содержать "Y"

Пример файла с описанием модуля "Веб-формы"

<?
global $MESS;
$PathInstall = str_replace("\\", "/", __FILE__);
$PathInstall = substr($PathInstall, 0, strlen($PathInstall)-strlen("/index.php"));
IncludeModuleLangFile($PathInstall."/install.php");
include($PathInstall."/version.php");
if(class_exists("form")) return;
Class form extends CModule
{
    var $MODULE_ID = "form";
    var $MODULE_VERSION;
    var $MODULE_VERSION_DATE;
    var $MODULE_NAME;
    var $MODULE_DESCRIPTION;
    var $MODULE_GROUP_RIGHTS = "Y";

    function form()
    {
        $this->MODULE_VERSION = FORM_VERSION;
        $this->MODULE_VERSION_DATE = FORM_VERSION_DATE;
        $this->MODULE_NAME = GetMessage("FORM_MODULE_NAME");
        $this->MODULE_DESCRIPTION = GetMessage("FORM_MODULE_DESCRIPTION");
    }

    function DoInstall()
    {
        global $DB, $APPLICATION, $step;
        $FORM_RIGHT = $APPLICATION->GetGroupRight("form");
        if ($FORM_RIGHT=="W")
        {
            $step = IntVal($step);
            if($step<2)
                $APPLICATION->IncludeAdminFile(GetMessage("FORM_INSTALL_TITLE"),
                $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/install/step1.php");
            elseif($step==2)
                $APPLICATION->IncludeAdminFile(GetMessage("FORM_INSTALL_TITLE"),
                $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/install/step2.php");
        }
    }

    function DoUninstall()
    {
        global $DB, $APPLICATION, $step;
        $FORM_RIGHT = $APPLICATION->GetGroupRight("form");
        if ($FORM_RIGHT=="W")
        {
            $step = IntVal($step);
            if($step<2)
                $APPLICATION->IncludeAdminFile(GetMessage("FORM_UNINSTALL_TITLE"),
                $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/install/unstep1.php");
            elseif($step==2)
                $APPLICATION->IncludeAdminFile(GetMessage("FORM_UNINSTALL_TITLE"),
                $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/install/unstep2.php");
        }
    }

    function GetModuleRightList()
    {
        global $MESS;
        $arr = array(
            "reference_id" => array("D","R","W"),
            "reference" => array(
                GetMessage("FORM_DENIED"),
                GetMessage("FORM_OPENED"),
                GetMessage("FORM_FULL"))
            );
        return $arr;
    }
}
?>

См. также

  • Права доступа в рамках логики модуля
  • CModule::DoInstall
  • CModule::DoUninstall
  • CModule::GetModuleRightList
  • CMain::IncludeAdminFile


Инсталляция

Инсталляция модуля в административном интерфейсе осуществляется в меню "Модули" нажатием кнопки "Установить". При этом будет вызван метод DoInstall класса с именем совпадающем с ID модуля. Этот класс дожен быть описан в файле /bitrix/modules/ID модуля/install/index.php (см. подробнее Описание модуля).

В процессе инсталляции модуля должны быть выполнены в обязательном порядке:

  • Регистрация модуля, которая осуществляется с помощью функции RegisterModule
  • Если модуль обладает административными скриптами, то для их вызова в каталог /bitrix/admin/ должны быть скопированы вызывающие скрипты.
  • Все изображения, используемые модулем, должны быть скопированы в каталог /bitrix/images/ID модуля/.

См. также

  • Описание модуля
  • Структура файлов модуля
  • RegisterModule
  • RegisterModuleDependences
  • CAgent::AddAgent
  • COption::SetOptionString
  • CDataBase::RunSQLBatch
  • CopyDirFiles


Деинсталляция

Деинсталляция модуля в административном интерфейсе осуществляется в меню "Модули" нажатием кнопки "Удалить". При этом будет вызван метод DoUninstall класса с именем совпадающем с ID модуля. Этот класс дожен быть описан в файле /bitrix/modules/ID модуля/install/index.php (см. подробнее Описание модуля).

В процессе деинсталляции модуля должны быть выполнены в обязательном порядке:

  • Удаление регистрационной записи модуля, которая осуществляется с помощью функции UnRegisterModule
  • Если модуль обладает административными скриптами, то вызывающие их скрипты должны быть удалены из каталога /bitrix/admin/.
  • Все изображения, используемые модулем, должны быть удалены из каталога /bitrix/images/ID модуля/.

См. также

  • Описание модуля
  • Структура файлов модуля
  • UnRegisterModule
  • UnRegisterModuleDependences
  • CAgent::RemoveModuleAgents
  • COption::RemoveOption
  • CDataBase::RunSQLBatch
  • DeleteDirFiles


Параметры модуля

Параметры модуля доступны в административном интерфейсе в меню "Настройки". При выборе модуля на данной странице, система подключает файл /bitrix/modules/ID модуля/options.php, предназначенный для управления параметрами модуля, назначения прав на модуль и т.п.

Параметры модуля хранятся в базе данных.

Для работы с параметрами модуля предназначен класс COption, со следующими методами:

  • COption::SetOptionString - установка строковых параметров
  • COption::SetOptionInt - установка числовых параметров
  • COption::GetOptionString - получение строковых параметров
  • COption::GetOptionInt - получение числовых параметров
  • COption::RemoveOption - удаление параметра

При получении параметров модуля, может использоваться значение по умолчанию, задаваемое в файле /bitrix/modules/ID модуля/default_option.php. В данном файле определяется массив $ID модуля_default_option, хранящий значения по умолчанию.

Пример файла /bitrix/modules/ID модуля/default_option.php

<?
$support_default_option = array(
    "SUPPORT_DIR"                => "#SITE_DIR#support/",
    "SUPPORT_MAX_FILESIZE"       => "100",
    "ONLINE_INTERVAL"            => "900",
    "DEFAULT_VALUE_HIDDEN"       => "N",
    "NOT_IMAGE_EXTENSION_SUFFIX" => "_",
    "NOT_IMAGE_UPLOAD_DIR"       => "support/not_image",
    "DEFAULT_AUTO_CLOSE_DAYS"    => "7"
    );
?>

Пример использования

<?
// установим строковый параметр
COption::SetOptionString("my_module_id", "MY_PARAMETER_ID", "VALUE");

// получим строковый параметр
$value = COption::GetOptionString("my_module_id", "MY_PARAMETER_ID", "DEFAULT_VALUE");
?>

См. также

  • COption
  • Параметры страницы


Взаимодействие модулей

Модули могут взаимодействовать между собой двумя способами: явно (прямым вызовом) и скрыто (через систему событий).

Явное взаимодействие

Явное взаимодействие подразумевает:

  • Подключение модуля с помощью функции CModule::IncludeModule
  • Непосредственный вызов метода класса или функции модуля

Пример явного взаимодействия:

<?
// подключаем модуль mymodule
if (CModule::IncludeModule("mymodule"))
{
    // выполним его метод
    CMyModuleClass::DoIt();
}
?>

Взаимодействие через события

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

Опишем схему работы с событиями. Тот модуль который инициирует событие, в том месте кода где это событие происходит, должен выполнить следующее:

  • Собрать все зарегистрированные обработчики с помощью функции GetModuleEvents.
  • Выполнить их по одному с помощью функции ExecuteModuleEvent, обрабатывая соответстсвующим образом возвращаемые обработчиками значения.
В свою очередь, модуль который хочет выполнить какие либо действия на это событие должен:
  • Зарегистрировать в момент инсталляции свой обработчик. Регистрация осуществляется с помощью функции RegisterModuleDependences.
  • Соответственно необходимо иметь эту функцию-обработчик и убедиться, что скрипт, в котором эта функция находится, подключается в файле /bitrix/modules/ID модуля/include.php.

Таким образом событие - это какое либо произвольное действие, в момент выполнения которого (до или после) собираются все обработчики этого события и выполняются по одному.

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

Список событий главного модуля доступен в разделе "События".

Пример взаимодействия через события:

<?
// регистрация обработчика:
// когда в модуле init_module возникнет событие OnSomeEvent
// будет вызван метод CMyModuleClass::Handler модуля handler_module

RegisterModuleDependences(
    "init_module", "OnSomeEvent",
    "handler_module", "CMyModuleClass", "Handler"
    );
?>
<?
// произвольная функция модуля init_module
// в которой генерируется событие

function MyFunction()
{
    // здесь располагается произвольный код
    // представляющий из себя событие

    // далее следует сбор зарегистрированных обработчиков
    $rsHandlers = GetModuleEvents("anothermodule", "OnSomeEvent");
    while($arHandler = $rsHandlers->Fetch())
    {
        // и их выполнение по одному
        if(!ExecuteModuleEvent($arHandler, $param1, $param2))
        {
            // если обработчик вернет false,
            // то например, вернем надпись "I can't do it..."
            return "I can't do it...";
        }
    }
    return "I have done it!";
}
?>
<?
// обработчик

class CMyModuleClass
{
    function Handler($param1, $param2)
    {
        if($param1=="delete all")
            return false;
        return true;
    }
}
?>


Идентификаторы модулей

Таблица идентификаторов стандартных модулей:

Идентификатор | Имя
main | Главный модуль.
fileman | Управление структурой.
iblock | Информационные блоки.
sale | Интернет-магазин.
currency | Валюты.
catalog | Торговый каталог.
form | Веб-формы.
workflow | Документооборот.
statistic | Статистика.
advertising | Реклама, баннеры.
support | Техподдержка.
mail | Почта.
vote | Опросы, голосования.
forum | Форум.
subscribe | Подписка, рассылки.
translate | Перевод.
ldap | AD/LDAP
search | Поиск.
compression | Компрессия.
blog | Блоги.
photogallery | Фотогалерея 2.0.
learning | Обучение.
webservice | Веб-сервисы.


Сайты

Введение

Продукт "1С-Битрикс: Управление сайтом" поддерживает многосайтовость, т.е. на базе одного экземпляра продукта можно создавать и поддерживать неограниченное количество сайтов. Синонимом термина "экземпляр продукта" может служить термин "портал". Портал состоит из одного и более сайтов.

Строго говоря, сайт - это совокупность таких понятий как:

  • учетная запись в базе данных - создаётся в административном меню "Сайты", включает в себя следующие основные параметры:
    • идентификатор - набор символов идентифицирующий сайт
    • доменное имя - одно или более доменное имя сайта
    • папка сайта - путь к каталогу в котором будет храниться публичная часть сайта
    • язык сайта
    • формат даты
    • формат времени
    • URL - протокол и доменное имя по умолчанию (например, "http://www.site.ru")
    • DocumentRoot - если многосайтовость организована по способу 2, то в данном параметре должен храниться путь в файловой системе сервера к корню сайта
    • условия подключения шаблонов - каждый сайт может иметь один или более шаблонов для отображения скриптов своей публичной части, каждый такой шаблон может быть подключен по тому или иному условию
  • публичная часть - совокупность скриптов (страниц) лежащих в "папке сайта" и принадлежащих этому сайту
  • настройки - каждый модуль может иметь ряд настроек связанных с сайтом, например, у модуля "Информационные блоки" эти настройки представляют из себя привязку информационного блока к тому или иному сайту, у модуля "Техподдержка" - привязку статуса, категории и т.п. к сайту.

В публичной части, ID текущего сайта хранится в константе SITE_ID.

Оглавление раздела

  • Многосайтовость - способы организации многосайтовости
  • Шаблоны сайта - описание структуры шаблона сайта и способов его подключения к сайту


Многосайтовость

Возможности многосайтовой версии

Технически многосайтовая версия продукта может работать в двух конфигурационных режимах:

  • Способ 1. Продукт и все сайты работают под управлением одной копии веб-сервера Apache.
  • Способ 2. Каждый сайт работает под управлением отдельной копии веб-сервера Apache или отдельного виртуального веб-сервера.

Дистрибутив программного продукта поставляется сконфигурированным для работы по первому способу.

Обе конфигурации будут рассмотрены на примере создания многосайтовой системы, состоящей из двух сайтов:

  • www.site1.com - корпоративный сайт компании
  • www.site2.com - Интернет-магазин компании

Способ 1. Один веб-сервер для всех сайтов.

В первом способе работы мы располагаем одним веб-сервером Apache, DocumentRoot которого настроен на каталог /home/www/allsites/.

Установим программный продукт "1С-Битрикс: Управление сайтом" в этот каталог.

Каждый сайт в первом способе конфигурации должен быть размещён в отдельном подкаталоге внутри единого каталога, например:

  • /home/www/allsites/s1/
  • /home/www/allsites/s2/

Имена каталогов s1, s2 можно выбирать любыми, например, shop и company, или en и de соответственно. Возможен так же вариант, когда один из сайтов располагается в корневом каталоге (например, /home/www/allsites/), а второй сайт в подкаталоге (например, /home/www/allsites/s2/).

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

В конфигурационном файле httpd.conf веб-сервера Apache это будет соответствовать примерно следующей записи:

<VirtualHost *:80>
    ServerAdmin admin@site1.com
    DocumentRoot "/home/www/allsites/"
    ServerName www.site1.com
    ErrorLog logs/allsite.log
    CustomLog logs/allsite.log  common
</VirtualHost>

Обратите внимание, что параметр DocumentRoot имеет значение /home/www/allsites/ и явно указывает на каталог, в котором установлен продукт. Для двух сайтов параметр DocumentRoot будет иметь одно и тоже значение.

Строка <VirtualHost *:80> указывает на то, что веб-сервер будет отвечать на любое доменное имя по любому IP адресу. Т.е. при соответствующей настройке DNS сервера, веб-сервер будет отвечать по любому из имен www.site1.com или www.site2.com.

Следующий шаг в настройке данной конфигурации - правильное конфигурирование сайтов в программном продукте.

Настройка сайтов выполняется в административном разделе системы в административном пункте меню "Настройки системы" - "Сайты".

Выбираем "Изменить" параметры сайта #1 (www.site1.com) и указываем в них:

  • Название: site1
  • Доменное имя: www.site1.com
  • Папка сайта: /s1/
  • URL сервера: www.site1.com
  • Название сайта: Корпоративный сайт компании "Название компании"
  • Путь к корневой папке веб-сервера для этого сайта: оставить пустым

Если DNS настроен таким образом что ваш сайт отвечает на адрес http://site1.com, то в поле Доменное имя желательно указывать без www. Можно перечислить в этом поле с новой строки любое число доменных имен, по которым вы хотите, чтобы отвечал сайт (или уже отвечает).

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

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

В параметре "Папка сайта" необходимо указывать путь относительно корня к каталогу в котором расположена публичная часть сайта. А "Путь к корневой папке веб-сервера для этого сайта" не используется в данном способе настройки многосайтовости и должен быть пустым для всех сайтов.

Аналогично настроим параметры сайта #2 (www.site2.com):

  • Название: site2
  • Доменное имя: site2.com
  • Папка сайта: /s2/
  • URL сервера: www.site2.com
  • Название сайта: Интернет-магазин компании "Название компании"
  • Путь к корневой папке веб-сервера для этого сайта: оставить пустым

Конфигурация почти готова к работе. Осталось настроить механизм выбора сайта на главной странице портала в файле /index.php.

Посетитель каждого из сайтов, заходя по адресу http://www.site1.com или http://www.site2.com, попадает фактически на страницу /index.php лежащую в каталоге указанную в параметре DocumentRoot настроек веб-сервера. В многосайтовой конфигурации роль этого файла немного меняется, и в нем необходимо разместить уже не содержимое индексной страницы корня одного из сайтов, а PHP код осуществляющий выбор одного из сайтов в зависимости от текущего доменного имени.

При решении данной задачи могут быть использованы следующие функции класса CMainPage:

  • CMainPage::GetSiteByHost - возвращает ID сайта, определяя его по текущему доменному имени.
  • CMainPage::GetSiteByAcceptLanguage - возвращает ID сайта, определяя его по переменной Accept-Language в настройках браузера пользователя.
  • CMainPage::GetIncludeSitePage - возвращает абсолютный путь на индексную страницу папки указанного сайта, для дальнейшего его подключения.
  • CMainPage::RedirectToSite - перенаправляет на индексную страницу папки указанного сайта.

Пример индексной страницы портала состоящего из нескольких сайтов, когда сайт определяется по текущему доменному имени:

<?
// подключим файл с классом CMainPage
require($_SERVER['DOCUMENT_ROOT']."/bitrix/modules/main/include/mainpage.php");

// получим идентификатор текущего сайта по доменному имени
$site_id = CMainPage::GetSiteByHost();

// получим абсолютный путь к индексной странице папки сайта
$page = CMainPage::GetIncludeSitePage($site_id);

// если сайт определён и определена индексная страница то
if(strlen($site_id)>0 && strlen($page)>0)
{
    // подключим страницу
    require_once($page);
}
else // иначе если сайт не определён то
{
    require($_SERVER['DOCUMENT_ROOT']."/bitrix/header.php");
    // далее можно разместить код который будет отображаться если
    // сайт ранее не был определён
    ?>

    <?require($_SERVER['DOCUMENT_ROOT']."/bitrix/footer.php");
}
?>

Представленный выше пример кода определяет доменное имя, по которому пришел посетитель, используя функцию CMainPage::GetSiteByHost, сверяет это доменное имя с именами, указанными в настройках сайтов в поле "Доменное имя" для определения ID сайта и производит включение в тело документа индексной страницы из папки соответствующего сайта, используя функцию CMainPage::GetIncludeSitePage.

В нашем примере это будет означать, что посетителю, пришедшему по адресу http://www.site1.com будет, без редиректа, прямо в теле текущей страницы, представлена страница /s1/index.php. А посетителю, пришедшему по адресу http://www.site2.com - страница /s2/index.php.

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

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

Пример индексной страницы портала состоящего из нескольких сайтов, когда сайт определяется по установленным в браузере посетителя языкам:

<?
// подключим файл с классом CMainPage
require($_SERVER['DOCUMENT_ROOT']."/bitrix/modules/main/include/mainpage.php");

// получим идентификатор сайта по Accept-Language
$site_id = CMainPage::GetSiteByAcceptLanguage();

// если сайт определён то
if(strlen($site_id)>0)
{
    // перенаправим на индексную страницу сайта
    CMainPage::RedirectToSite($site_id);
}
else // иначе если сайт не определён то
{
    require($_SERVER['DOCUMENT_ROOT']."/bitrix/header.php");
    // далее можно разместить код который будет отображаться если
    // сайт ранее не был определён
    ?>

    <?require($_SERVER['DOCUMENT_ROOT']."/bitrix/footer.php");
}
?>

В представленном выше примере кода функция CMainPage::GetSiteByAcceptLanguage проверяет, какие языки установлены в настройках браузера посетителя, сравнивает с ID языка сайта и возвращает наиболее подходящий сайт.

После того как сайт будет определён, функция CMainPage::RedirectToSite выполнит редирект (302 ответ веб-сервера) и переведет пользователя на индексную страницу папки указанного сайта, например, по адресу http://www.site1.com/s1/ или http://www.site2.com/s2/.

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

Способ 2. Отдельный веб-сервер для каждого сайта.

Для работы второго способа нам потребуется произвести специальную настройку веб-сервера и программного продукта.

Будем использовать для примера конфигурацию из двух сайтов:

  • www.site1.com - корпоративный сайт компании
  • www.site2.com - интернет-магазин компании

Для каждого сайта надо сконфигурировать отдельный виртуальный веб-сервера Apache. Если разместить сайты в соответствующих каталогах на диске:

  • /home/www/site1/
  • /home/www/site2/

В конфигурационном файле httpd.conf веб-сервера Apache это будет соответствовать примерно следующей двум записям, каждая из которых описывает свой "виртуальный сервер" (в терминологии принятой в Apache):

<VirtualHost *:80>
    ServerAdmin admin@site1.com
    DocumentRoot "/home/www/site1/"
    ServerName site1.com
    ServerAlias *.site1.com
    ErrorLog logs/site1.log
    CustomLog logs/site1.log  common
</VirtualHost>
<VirtualHost *:80>
    ServerAdmin admin@site2.com
    DocumentRoot "/home/www/site2/"
    ServerName site2.com
    ServerAlias *.site2.com
    ErrorLog logs/site2.log
    CustomLog logs/site2.log  common
</VirtualHost>

Обратите внимание, что параметр DocumentRoot для каждого сайта указывает в разный каталог на диске, в котором должен быть размещён соответствующий сайт.

Строки <VirtualHost *:80> указывают на то, что веб-сервер будет отвечать на любом IP адресе, но переменная ServerAlias говорит о том, что каждый из сайтов будет отвечать только по определённому доменному имени.

Т.е. доменное имя www.site1.com будет обрабатываться одним веб-сервером Apache который работает с каталогом /home/www/site1/, а www.site2.com - другим веб-сервером, работающим с каталогом /home/www/site1/.

Возможен так же вариант конфигурирования для разных IP адресов. Ниже приведен пример конфигурации Apache для двух разных IP адресов:

<VirtualHost 192.168.0.1:80>
    ServerAdmin admin@site1.com
    DocumentRoot "/home/www/site1/"
    ServerName site1.com
    ErrorLog logs/site1.log
    CustomLog logs/site1.log  common
    Options +FollowSymLinks
</VirtualHost>
<VirtualHost 192.168.0.2:80>
    ServerAdmin admin@site2.com
    DocumentRoot "/home/www/site2/"
    ServerName site2.com
    ErrorLog logs/site2.log
    CustomLog logs/site2.log  common
    Options +FollowSymLinks
</VirtualHost>

В этом случае при соответствующей настройке DNS для разных доменных имен, каждый "виртуальный сервер" (в терминологии Apache) будет работать на отдельном IP адресе и отвечать только по определённому доменному имени.

Следующий шаг - это установка продукта для данной конфигурации (зеленым цветом приведены примеры для установки на UNIX системы):

  1. установите программный продукт "Битрикс: Управление сайтом 4.0" сначала в каталог первого сайта /home/www/site1/
  2. создайте каталог /home/www/shared/, в котором будут располагаться общие для всех сайтов файлы:
    mkdir /home/www/shared
  3. перенесите весь каталог /home/www/site1/bitrix/ в /home/www/shared/bitrix/:
    mv /home/www/site1/bitrix /home/www/shared/bitrix
  4. перенесите весь каталог /home/www/site1/upload/ в /home/www/shared/upload/:
    mv /home/www/site1/upload /home/www/shared/upload
  5. создайте символическую связь для каталога /bitrix/ в каждом из сайтов:
    1. ln -s /home/www/shared/bitrix /home/www/site1/
    2. ln -s /home/www/shared/upload /home/www/site1/
    3. ln -s /home/www/shared/bitrix /home/www/site2/
    4. ln -s /home/www/shared/upload /home/www/site2/
  6. убедитесь, что веб-сервер (Apache, IIS) имеет право на запись в каталог /home/www/shared/ (это необходимо будет для работы системы обновлений и загрузки графических файлов)
  7. разместите публичную часть второго сайта в каталог /home/www/site2/

Для создания символических связей в Windows необходимо воспользоваться дополнительными программами, например, Far Manager или Junction от Sysinternals.

Следующий шаг в настройке данной конфигурации - правильное конфигурирование сайтов в программном продукте.

Настройка сайтов выполняется в административном разделе системы в административном пункте меню "Настройки системы" - "Сайты".

Выбираем "Изменить" параметры сайта #1 (www.site1.com) и указываем в них:

  • Название: site1
  • Доменное имя: www.site1.com
  • Папка сайта: /s1/
  • URL сервера: www.site1.com
  • Название сайта: Корпоративный сайт компании "Название компании"
  • Путь к корневой папке веб-сервера для этого сайта: /home/www/site1/

Если DNS настроен таким образом что ваш сайт отвечает на адрес http://site1.com, то в поле Доменное имя желательно указывать без www. Можно перечислить в этом поле с новой строки любое число доменных имен, по которым вы хотите, чтобы отвечал сайт (или уже отвечает).

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

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

Аналогично настроим параметры сайта #2 (www.site2.com):

  • Название: site2
  • Доменное имя: site2.com
  • Папка сайта: /s2/
  • URL сервера: www.site2.com
  • Название сайта: Интернет-магазин компании "Название компании"
  • Путь к корневой папке веб-сервера для этого сайта: /home/www/site2/

Обратите внимание, что для двух сайтов в параметре "Папка сайта" указано одинаковое значение - "/". Это связано с тем, что сайты обслуживаются разными "виртуальными серверами" (в терминологии Apache) у которых для размещения файлов использован разный каталог.

Также необходимо обратить на параметр "Путь к корневой папке веб-сервера для этого сайта". Для разных сайтов у него своё значение взятое из параметра DocumentRoot настроек соответствующего "виртуального сервера" (см. выше пример части файла httpd.cnf настроек Apache).

Необходимо иметь в виду что при организации многосайтовости по данному способу, вы можете использовать как виртуальные сервера одной инсталляции Apache, так и просто разные инсталляции Apache. Аналогично и для других веб-серверов: IIS, EServ и т.д.

Конфигурация готова к работе.

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

Заключение

Представленные рекомендации позволяют сконфигурировать программный продукт "1С-Битрикс: Управление сайтом" для работы в многосайтовом режиме.

С точки зрения программного продукта, оба способа равноценны. Первый способ в основном рекомендуется, если вы используете виртуальный хостинг или испытываете сложности с конфигурированием веб-сервера. Второй способ работы рекомендуется, если вы используете выделенный сервер или на разделяемом хостинге можете настроить раздельные веб-сервера. Использование второго способа так же позволяет исключить из URL-ов на сайте лишний подкаталоги /s1/ или /s2/ и начинать формирование URL адресов прямо от каталога /.


Шаблон сайта

Синонимом термина "шаблон сайта" можно считать - "дизайн сайта", "скин сайта". Для показа одного сайта можно использовать несколько различных шаблонов. Строго говоря, в шаблон сайта входят:

  • учетная запись в базе данных - создаётся в административном меню "Шаблоны сайта"
  • набор файлов в каталоге /bitrix/templates/ID шаблона сайта/
    где ID шаблона сайта - поле "ID" в форме редактирования шаблона сайта (административный пункт меню "Шаблоны сайта"); ниже представлена структура данного каталога:
    • header.php - пролог данного шаблона
    • footer.php - эпилог данного шаблона
    • styles.css - CSS стили шаблона
    • .тип меню.menu_template.php - шаблон вывода меню соответствующего типа
    • chain_template.php - шаблон по умолчанию для вывода навигационной цепочки
    • /ID модуля/ - каталог с компонентами принадлежащими тому или иному модулю
    • /lang/ - языковые файлы принадлежащие как данному шаблону в целом, так и отдельным компонентам
    • /images/ - каталог с изображениями данного шаблона сайта
    • /page_templates/ - каталог с шаблонами страниц и их описанием хранящимся в файле .content.php
    • а также ряд других вспомогательных произвольных файлов входящих в данный шаблон

Применить тот или иной шаблон к сайту можно в административном меню "Сайты", в настройках сайта, раздел "Внешний вид":

$_REQUEST["print"]=="Y" Если свойство раздела "phone" равно "Y"

$APPLICATION->GetDirProperty("phone")=="Y"
Если текущий раздел равен "/ru/catalog/phone/"
$APPLICATION->GetCurDir()=="/ru/catalog/phone/"
Если текущий пользователь - администратор
$USER->IsAdmin()


Введение

Введение

Язык - это учетная запись в базе данных доступная для редактирования в административном меню "Языки" со следующими полями:

  • Идентификатор
  • Название
  • Формат даты
  • Формат времени
  • Кодировка

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

В административной части язык определяет формат времени, даты, кодировку страниц. В публичной части - данные параметры определяются настройками сайта.

Оглавление раздела

  • Кодировки - таблица кодировок и идентификаторов языков
  • Формат даты и времени - таблица форматов даты и времени, общеупотребительных в различных странах
  • Языковые файлы - описание основных функций и принципов работы с языковыми файлами


Кодировки

При задании кодировки языка и выбора его идентификатора используются следующие аббревиатуры и константы.

Язык | Идентификатор | Кодировка
Russian | ru | iso-8859-5, windows-1251, koi8-r
English | en | iso-8859-1, windows-1252
Afrikaans | af | iso-8859-1, windows-1252
Albanian | sq | iso-8859-1, windows-1252
Arabic | ar | iso-8859-6
Basque | eu | iso-8859-1, windows-1252
Bulgarian | bg | iso-8859-5
Byelorussian | be | iso-8859-5
Catalan | ca | iso-8859-1, windows-1252
Croatian | hr | iso-8859-2, windows-1250
Czech | cs | iso-8859-2
Danish | da | iso-8859-1, windows-1252
Dutch | nl | iso-8859-1, windows-1252
Esperanto | eo | iso-8859-3
Estonian | et | iso-8859-15
Faroese | fo | iso-8859-1, windows-1252
Finnish | fi | iso-8859-1, windows-1252
French | fr | iso-8859-1, windows-1252
Galician | gl | iso-8859-1, windows-1252
German | de | iso-8859-1, windows-1252
Greek | el | iso-8859-7
Hebrew | iw | iso-8859-8
Hungarian | hu | iso-8859-2
Icelandic | is | iso-8859-1, windows-1252
Irish | ga | iso-8859-1, windows-1252
Italian | it | iso-8859-1, windows-1252
Japanese | ja | shift_jis, iso-2022-jp, euc-jp
Korean | ko | euc-kr
Latvian | lv | iso-8859-13, windows-1257
Lithuanian | lt | iso-8859-13, windows-1257
Macedonian | mk | iso-8859-5, windows-1251
Maltese | mt | iso-8859-3
Norwegian | no | iso-8859-1, windows-1252
Polish | pl | iso-8859-2
Portuguese | pt | iso-8859-1, windows-1252
Romanian | ro | iso-8859-2
Scottish | gd | iso-8859-1, windows-1252
Serbian cyrillic | sr | iso-8859-5, windows-1251
Serbian latin | sr | iso-8859-2, windows-1250
Slovak | sk | iso-8859-2
Slovenian | sl | iso-8859-2, windows-1250
Spanish | es | iso-8859-1, windows-1252
Swedish | sv | iso-8859-1, windows-1252
Turkish | tr | iso-8859-9, windows-1254
Ukrainian | uk | iso-8859-5


Формат даты и времени

В таблице сведены основные форматы даты и времени, используемые в разных странах.

Страна/язык | Формат даты | Формат времени | Пример даты | Пример времени
Россия | DD.MM.YYYY | HH:MI:SS | 26.01.1993 | 18:24:00
США | MM-DD-YYYY | HH:MI:SS | 01-26-1993 | 18:24:00
Международный английский | DD-MM-YYYY | HH:MI:SS | 26-01-1993 | 18:24:00
Великобритания | DD/MM/YYYY | HH:MI:SS | 26/01/1993 | 18:24:00
Германия | DD.MM.YYYY | HH:MI:SS | 26.01.1993 | 18:24:00
Бельгия | DD/MM/YYYY | HH:MI:SS | 26/01/1993 | 18:24:00
Бразилия | DD/MM/YYYY | HH:MI:SS | 26/01/1993 | 18:24:00
Венгрия | YYYY-MM-DD | HH:MI:SS | 1993-01-26 | 18:24:00
Дания | DD-MM-YYYY | HH.MI.SS | 26-01-1993 | 18.24.00
Италия | DD/MM/YYYY | HH.MI.SS | 26/01/1993 | 18.24.00
Испания | DD/MM/YYYY | HH:MI:SS | 26/01/1993 | 18:24:00
Канада (франц.) | YYYY-MM-DD | HH:MI:SS | 1993-01-26 | 18:24:00
Латинская Америка | DD/MM/YYYY | HH:MI:SS | 26/01/1993 | 18:24:00
Нидерланды | DD-MM-YYYY | HH:MI:SS | 26-01-1993 | 18:24:00
Норвегия | DD.MM.YYYY | HH:MI:SS | 26.01.1993 | 18:24:00
Польша | YYYY-MM-DD | HH:MI:SS | 1993-01-26 | 18:24:00
Португалия | DD-MM-YYYY | HH:MI:SS | 26-01-1993 | 18:24:00
Сербия/Югославия | DD.MM.YYYY | HH.MI.SS | 26.01.1993 | 18.24.00
Словакия | YYYY-MM-DD | HH:MI:SS | 1993-01-26 | 18:24:00
Словения | YYYY-MM-DD | HH:MI:SS | 1993-01-26 | 18:24:00
Финляндия | YYYY-MM-DD | HH.MI.SS | 1993-01-26 | 18.24.00
Франция | DD.MM.YYYY | HH:MI:SS | 26.01.1993 | 18:24:00
Чехия | YYYY-MM-DD | HH:MI:SS | 1993-01-26 | 18:24:00
Швейцария | DD.MM.YYYY | HH,MI,SS | 26.01.1993 | 18,24,00
Швеция | YYYY-MM-DD | HH.MI.SS | 1993-01-26 | 18.24.00


Языковые файлы

Языковой файл представляет из себя PHP скрипт, хранящий переводы языковых фраз на тот или иной язык. Данный скрипт состоит из массива $MESS, ключи которого - идентификаторы языковых фраз, а значения - переводы на соответствующий язык.

Пример языкового файла для русского языка:

<?
$MESS ['SUP_SAVE'] = "Сохранить";
$MESS ['SUP_APPLY'] = "Применить";
$MESS ['SUP_RESET'] = "Сбросить";
$MESS ['SUP_EDIT'] = "Изменить";
$MESS ['SUP_DELETE'] = "Удалить";
?>

Пример языкового файла для английского языка:

<?
$MESS ['SUP_SAVE'] = "Save";
$MESS ['SUP_APPLY'] = "Apply";
$MESS ['SUP_RESET'] = "Reset";
$MESS ['SUP_EDIT'] = "Change";
$MESS ['SUP_DELETE'] = "Delete";
?>

Для каждого языка существует свой набор языковых файлов, хранящихся в подкаталогах /lang/ (подробнее см. структура файлов системы, структура файлов модуля).

Языковые файлы как правило используются в административных скриптах модулей или в компонентах и в зависимости от этого подключаются одной из следующих функций:

  • IncludeModuleLangFile - в административных скриптах
  • IncludeTemplateLangFile - в компонентах

Для удобства поиска и дальнейшей модификации языковых фраз можно пользоваться параметром страницы show_lang_files=Y, позволяющим быстро найти и исправить ту или иную языковую фразу в модуле "Перевод".


Введение

Оглавление раздела:

  • Структура страницы - описаны способы подключения пролога и эпилога страницы
  • Шаблоны страницы - описание алгоритма формирования списка шаблонов страницы при создании новой страницы в модуле "Управление статикой"
  • Порядок выполнения - описан порядок выполнения страницы
  • Свойства и мета-теги - описание принципов работы со свойствами страницы (раздела), а также принципов работы со тэгом <meta> с помощью свойств страницы (раздела)
  • Параметры страницы - описание понятия "параметр страницы" и принципов работы с ним


Структура страницы

В системе "1С-Битрикс: Управление сайтом" страница представляет из себя PHP файл, состоящий из пролога, тела страницы и эпилога.

В общем случае структура страницы выглядит как:

<?
// подключение пролога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
?>
тело страницы
<?
// подключение эпилога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>

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

  • заголовок страницы (выводится функцией CMain::ShowTitle)
  • навигационная цепочка (выводится функцией CMain::ShowNavChain)
  • CSS стили (выводятся функцией CMain::ShowCSS)
  • мета-теги (выводятся функцией CMain::ShowMeta)
  • и др.
Принципиальной особенностью данной технологии является то, что она позволяет отложить исполнение некоторых функций, выполняя их в эпилоге, а результаты их выполнения подставляя в вышележащий код.

Но есть ряд задач, которые не могут быть решены с помощью технологии отложенных функций. Это относится к случаям когда необходимо производить какие-либо действия в прологе над значениями, которые в предыдущем примере задавались бы в теле страницы (например, свойства страницы). В этом случае возникает необходимость разбить пролог на служебную и визуальную части и эти значения задавать между ними. Достигается это следующим образом:

<?
// подключение служебной части пролога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

// здесь можно задать например, свойство страницы
// с помощью функции $APPLICATION->SetPageProperty
// и обработать затем его в визуальной части эпилога

// подключение визуальной части пролога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?>
Содержимое страницы
<?
// подключение эпилога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>

В служебной части пролога происходит подключение к базе, отработка агентов, инициализация служебных констант, проверка прав уровня 1, подключение необходимых модулей, исполнение обработчиков событий OnPageStart, OnBeforeProlog, а также ряд других необходимых действий. Особенностью служебной части пролога является то, что она не выводит никаких данных (не посылает header браузеру).

В визуальной части пролога происходит подключение файла /bitrix/templates/ID шаблона сайта/header.php, где ID шаблона сайта - идентификатор текущего шаблона сайта. Данный файл хранит левую верхнюю часть текущего шаблона сайта.

В свою очередь и эпилог может быть разбит на визуальную и служебную части:

<?
// подключение служебной части пролога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

// подключение визуальной части пролога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");

?>
Содержимое страницы
<?

// подключение визуальной части эпилога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_before.php");

// подключение служебной части эпилога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_after.php");
?>

В визуальной части эпилога происходит подключение файла /bitrix/templates/ID шаблона сайта/footer.php, где ID шаблона сайта - идентификатор текущего шаблона сайта. Данный файл хранит правую нижнюю часть текущего шаблона сайта. Помимо этого - выводится ряд невидимых IFRAME'ов используемых технологией переноса посетителей.

В служебной части эпилога происходит отправка почтовых сообщений, исполнение обработчиков события OnAfterEpilog, отключение от базы, а также ряд других служебных действий.

Зачастую возникают задачи когда нет необходимости в подключении визуальной частей пролога и эпилога. В этом случае достаточно подключить служебные части пролога и эпилога:

<?
// подключение служебной части пролога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
?>
тело страницы
<?
// подключение служебной части эпилога
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_after.php");
?>

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

См. также

  • Порядок выполнения страницы


Шаблоны страницы

Шаблон страницы - это PHP файл, содержимое которого соответствует правилам формирования структуры страницы. Шаблоны страниц могут быть использованы при создании новой страницы в модуле "Управление статикой".

Шаблоны страниц хранятся в каталогах:

  • /bitrix/templates/.default/page_templates/
  • /bitrix/templates/ID шаблона сайта/page_templates/

В каждом таком каталоге могут находиться непосредственно сами файлы шаблонов страниц, а также служебный файл .content.php, основная задача которого - хранить описания и порядок сортировки шаблонов страниц. Эта информация хранится в массиве $TEMPLATES структура которого представлена ниже:

Array
(
    [имя файла] => Array
        (
            [name] => заголовок шаблона страницы
            [sort] => индекс сортировки
        )

)

При формировании списка шаблонов страниц используется следующий алгоритм:

  1. получаем ID шаблона сайта для текущего сайта который подключается без PHP условия
  2. последовательно подключаем файлы:
    1. /bitrix/templates/.default/page_templates/.section.php
    2. /bitrix/templates/ID шаблона сайта/page_templates/.section.php
    В каждом из этих файлов будет описан свой массив $TEMPLATES. После подключения этих файлов, мы будем иметь объединенный массив $TEMPLATES. Далее для каждого элемента этого массива, представляющего из себя описание одного шаблона страницы, выполняем следующее:
    1. проверяем физическое существование шаблона страницы
    2. если существует, то добавляем его в список шаблонов
  3. сортируем полученный список шаблонов по индексу сортировки (см. выше структуру массива $TEMPLATES)

См. также

  • Структура страницы


Порядок выполнения страницы

Ниже представлен порядок выполнения страницы, структура которой соответствует правилам описанным в разделе "Структура страницы":

№ | Операция | Определяемые константы и переменные | Примечание
1. Служебная часть пролога
1.1 | Подключение /bitrix/php_interface/dbconn.php |  | Подключаемый файл должен содержать определения переменных для соединения с базой данных, констант для отладки и прав доступа.
1.2 | Соединение с базой данных | $DB | В случае ошибки соединения будет подключен файл /bitrix/php_interface/dbconn_error.php.
1.3 | Подключение /bitrix/php_interface/after_connect.php |  | Подключаемый файл может содержать операции, необходимые для выполнения сразу после соединения с БД.
1.4 | Определение текущего сайта | $APPLICATION, SITE_ID, SITE_DIR, SITE_SERVER_NAME, SITE_CHARSET, FORMAT_DATE, FORMAT_DATETIME, LANGUAGE_ID, Определяются все классы и функции Главного модуля. | Если к этому моменту определена константа с кодом сайта SITE_ID , то сайт не будет определяться по текущей папке и доменному имени, а все остальные константы будут определены для этого сайта.
1.5 | Подключение /bitrix/php_interface/init.php |  | Может содержать в себе инициализацию обработчиков событий, подключение дополнительных функций - общие для всех сайтов.
1.6 | Подключение /bitrix/php_interface/ID сайта/init.php |  | Содержит параметры, определения функций для конкретного сайта.
1.7 | Проверка агентов |  | В агентах нельзя пользоваться переменными $USER, $_SESSION и всех остальных, которые определяются ниже.
1.8 | Событие OnPageStart |  |
1.9 | Открытие сессии | Все сессионные переменные $_SESSION |
1.10 | Определение пользователя, авторизация пользователя, завершение сеанса, регистрация (в зависимости от параметров в запросе) | $USER |
1.11 | Определение текущего шаблона сайта | SITE_TEMPLATE_ID |
1.12 | Событие OnBeforeProlog |  |
1.13 | Проверка прав доступа уровня 1 |  | В случае если прав недостаточно, то выводится форма авторизации и страница завершает выполнение.
1.14 | Начало буфферизации вывода |  | После начала буферизации можно делать вывод, до установки куков и наоборот, устанавливать куки после вывода в поток.
1.15 | Событие OnProlog |  |
2. Визуальная часть пролога
2.1 | Подключение /bitrix/templates/ID шаблона сайта/header.php |  |
3. Тело страницы
4. Визуальная часть эпилога
4.1 | Подключение /bitrix/templates/ID шаблона сайта/footer.php |  |
4.2 | Вызов функции CMain::ShowSpreadCookieHTML |  | Данная функция выводит набор невидимых IFRAME'ов используемых в технологии переноса посетителей
5. Служебная часть эпилога
5.1 | Событие OnEpilog |  |
5.2 | Завершение буферизации страницы |  | Завершение и вывод в поток буффера инициализированного в п. 1.14
5.3 | Отправка E-Mail писем |  | Подробнее о E-Mail письмах можно прочитать в разделе "Почтовая система"
5.4 | Событие OnAfterEpilog |  |
5.5 | Завершение соединения с базой данных | Переменная $DB больше недоступна |

См. также

  • Структура страницы


Свойства страниц и мета-теги

В системе "1С-Битрикс: Управление сайтом" поддерживаются свойства раздела и свойства страницы.

Свойства раздела хранятся в файле .section.php соответствующего каталога (раздела сайта).

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

В работе со свойствами используются следующие функции:

  • CMain::SetPageProperty
  • CMain::SetDirProperty
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirProperty
  • CMain::GetDirPropertyList

Для работы с мета-тегами используются свойства страницы и раздела. Для работы с ними используются следующие функции:

  • CMain::ShowMeta
  • CMain::GetMeta

Методы установки свойств

  • CMain::SetPageProperty - устанавливает свойство страницы.

    <?
$APPLICATION->SetPageProperty("keywords", "веб, разработка, программирование");
?>

  • CMain::SetDirProperty - устанавливает свойство раздела.

    <?
$APPLICATION->SetDirProperty("keywords", "дизайн, веб, сайт");
?>

Показ свойства

  • CMain::ShowProperty - выводит свойство страницы или свойство раздела с использованием технологии отложенных функций.

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title><?$APPLICATION->ShowProperty("page_title")?></title>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
...

Получение значения свойства

  • CMain::GetProperty - возвращает свойство страницы или свойство раздела.

    <?
$keywords = $APPLICATION->GetProperty("keywords");
if (strlen($keywords)>0) echo $keywords;
?>

  • CMain::GetPageProperty - возвращает свойство страницы.

    <?
$keywords = $APPLICATION->GetPageProperty("keywords");
if (strlen($keywords)>0) echo $keywords;
?>

  • CMain::GetPagePropertyList - возвращает массив всех свойств страницы.

    <?
$arProp = $APPLICATION->GetPagePropertyList();
foreach($arProp as $key=>$value)
    echo '<meta name="'.$key.'" content="'.htmlspecialchars($value).'">';
?>

  • CMain::GetDirProperty - возвращает свойство раздела.

    <?
$keywords = $APPLICATION->GetDirProperty("keywords");
if (strlen($keywords)>0) echo $keywords;
?>

  • CMain::GetDirPropertyList - возвращает массив свойств раздела, собранных рекурсивно до корня сайта.

    <?
$arProp = $APPLICATION->GetDirPropertyList();
foreach($arProp as $key=>$value)
    echo '<meta name="'.$key.'" content="'.htmlspecialchars($value).'">';
?>

Работа с мета-тегами

  • CMain::ShowMeta - выводит свойство страницы или свойство раздела обрамляя их HTML-тегом <meta> с использованием технологии отложенных функций.

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<?$APPLICATION->ShowMeta("keywords_prop", "keywords")?>
<?$APPLICATION->ShowMeta("description_prop", "description")?>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
...

  • CMain::GetMeta - возвращает свойство страницы или свойство раздела обрамляя их HTML-тегом <meta>.

    <?
$meta_keywords = $APPLICATION->GetMeta("keywords_prop", "keywords");
if (strlen($meta_keywords)>0) echo $meta_keywords;
?>


Параметры страницы

Параметры страницы предназначены для передачи параметров в функции модулей для изменения их стандартного поведения. Например, при необходимости отключить запоминание последней страницы в сессии (при использовании постраничной навигации) или изменить стандартный формат вывода даты в функциях модуля "Информационные блоки".

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

Для работы с параметрами страницы предназначен класс CPageOption, со следующими методами:

  • CPageOption::SetOptionString - установка строковых параметров
  • CPageOption::SetOptionInt - установка числовых параметров
  • CPageOption::GetOptionString - получение строковых параметров
  • CPageOption::GetOptionInt - получение числовых параметров
  • CPageOption::RemoveOption - удаление параметра

Параметры страницы поддерживаемые стандартными модулями:

ID модуля | Название | Параметр | Описание | Значение по умолчанию
main | Главный модуль | nav_page_in_session | Если значение - "Y", то в сессии будет запоминаться последняя открытая страница в постраничной навигации, если значение "N" - не будет. | Y
iblock | Информационные блоки | FORMAT_ACTIVE_DATES | Если значение - "FULL", то даты относящиеся к элементу информационного блока (поля "ACTIVE_FROM" и "ACTIVE_TO") будут возвращаться в полном формате (вместе со временем), если значение "SHORT", то - в кратком формате (без времени). | SHORT

Примеры использования:

<?
CPageOption::SetOptionString("main", "nav_page_in_session", "N");
?>
<?
CPageOption::SetOptionString("iblock", "FORMAT_ACTIVE_DATES", "FULL");
?>

См. также

  • CPageOption
  • Параметры модулей


HTTP POST запросы

Компоненты 2.0

  • HTTP POST запросы
  • Замечания по массивам $arParams и $arResult
  • Кеширование в компоненте
  • Комплексные компоненты
  • Модификация результата result_modifier.php
  • Общие понятия
  • Поиск шаблона компонента
  • Пользовательские движки шаблонизации
  • Псевдонимы входящих переменных
  • Структура комплексного компонента
  • Структура папки компонента
  • Структура шаблона комплексного компонента
  • Структура шаблона обычного компонента
  • Файл описания компонента .description.php
  • Файл параметров компонента .parameters.php
  • Физическое размещение компонентов
  • Человекопонятные URL
  • Шаблоны вывода


Общие понятия

Компоненты 2.0::Общие понятия

Понятие компонента

Компоненты являются блоками, с помощью которых строится публичная часть сайта. Они в полной мере реализуют паттерн проектирования Carrier Rider Mapper.

Carrier
Носитель любой информации к которой могут иметь доступ несколько клиентов одновременно.
Rider
Rider - (Reader либо Writer) - объекты, посредством которых Carrier предоставляет доступ к хранимой в нём информации. Клиенты считывают и записывают информацию хранимую в Carrier исключительно только посредством объектов типа Reader и Writer. Таким образом, Reader и Writer - интерфейсы доступа к информации.
Mapper
Mapper - (Scanner либо Formatter) - объекты обёртки над Reader либо Writer соответственно. Мапперы отвечают за преобразование форматов данных в удобные для клиентов форматы.

Поток информации от носителя к клиенту (считывание): Carrier -> Reader -> Scanner -> Client.

Поток информации от клиента к носителю (запись): Carrier <- Writer <- Formatter <- Client.

Введение прослойки мапперов между Carrier-Rider и клиентами позволяет соединять один и тот же Carrier-Rider с разными типами клиентов посредством соответствующих (разных) мапперов.

Компоненты позволяют повторно использовать единожды написанный и отлаженный код в рамках одного сайта или на разных сайтах. Визуальные средства среды "1С-Битрикс: Управление сайтом" позволяют размещать и настраивать компоненты без написания кода. Поставляемые с продуктом системные компоненты регулярно обновляются.

Основные особенности компонентов 2.0

  • В компонентах 2.0 могут быть разделены логика и представление. Для одной логики может быть несколько представлений, в том числе зависящих от шаблона текущего сайта. Представление (шаблон вывода) может быть написано на любом шаблонном языке, который можно подключить из PHP. Например, шаблоны могут быть на PHP, Smarty, XSL и т.д. Нет необходимости изменять логику компонента для изменения особенностей его показа. Шаблон вывода существенно проще, чем компонент в целом.

    Логика - это сам компонент, представление - это шаблон вывода компонента.
  • Компоненты централизованно хранятся в одной папке. Это обеспечивает большую целостность и понятность структуры сайта. Папка доступна для обращений, а значит, компонент и его шаблоны могут легко подключать свои дополнительные ресурсы.

    Внимание!
    Файлы, к которым нельзя обращаться напрямую, должны содержать в начале следующий код:

    <?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>

  • Компонент хранит все, что ему нужно для работы, в своей папке. Поэтому компоненты можно легко переносить между проектами. Компонент неделим.
  • Комплексные компоненты (например, компонент «Форум» или «Каталог») имеют следующие особенности.
    • Нет необходимости создавать множество страниц для того, чтобы разместить на них все требуемые подкомпоненты. Следовательно, нет необходимости отдельно настраивать для каждого из этих подкомпонентов общие (пересекающиеся) свойства.
    • Нет необходимости устанавливать сложные взаимосвязи между подкомпонентами. Например, нет необходимости для страницы со списком сообщений темы форума настраивать, как эта страница может указать на страницу списка тем форума, а как на страницу профиля посетителя.
    • В компонент (даже с кастомизироваными шаблонами вывода) можно добавить новую страницу. Например, если на форуме появится страница (подкомпонент) по выводу 10 посетителей с самым высоким рейтингом, то эта страница станет доступной и в публичной части.
    • Можно сменить шаблон вывода всего комплексного компонента одним действием, а не настраивать вывод каждого из подкомпонентов.


Комплексные компоненты

Компоненты 2.0::Комплексные компоненты

Определение

Обычные (простые, одностраничные) компоненты создают какую-либо область на одной конкретной странице. Например, компонент показа новости по ее коду создает на одной конкретной странице (той, где он размещён) область, в которой показывает заголовок, текст и прочие параметры новости.

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

MVC

Комплексные компоненты построены с использованием паттерна проектирования MVC (Model View Controller), в котором модель данных приложения, пользовательский интерфейс и управляющая логика разделены на три отдельных части так, что модификация одной из частей оказывает минимальное воздействие на другие части.

  • Model (модель) в данном случае - это ядро системы. Model представляет собой данные и бизнес-логику, отвечает на запросы View.
  • View (представление) - это простые компоненты (на самом деле все чуть сложнее, но для начала можно понимать именно так). View отображает данные пользователю, запрашивает данные у Model, посылает действия пользователя в Controller (как правило через HTTP запрос).
  • Controller (контроллер) - это комплексный компонент. Controller на основании действий пользователя и ответа Model выбирает соответствующий View.
            •

    Алгоритм работы паттерна MVC примерно таков:

    • на основании действий пользователя Controller (контроллер) определяет, какое View (представление) должно быть показано пользователю, и отдает управление этому View (представлению);
    • View (представление) запрашивает необходимые ему данные у Model (модели), получает эти данные и выводит их соответствующим образом пользователю;
    • пользователь с помощью каких-либо элементов управления, которые ему предоставил View (представление), посылает новый запрос в Controller (контроллер).

    Алгоритм работы паттерна MVC в применении к комплексным компонентам таков:

    • на основании действий пользователя (как правило, HTTP запрос) комплексный компонент (controller) определяет, какая страница (view) должна быть показана пользователю, и подключает свой шаблон компонента для этой страницы;
    • шаблон страницы (view) подключает обычные компоненты, настраивая необходимым образом их свойства;
    • обычные компоненты выполняют свою работу: запрашивают данные у ядра (model), форматируют их и выводят посетителю, а так же предоставляют пользователю различные элементы управления (ссылки, формы, кнопки и т.п.);
    • пользователь с помощью каких-либо элементов управления, посылает новый запрос (как правило HTTP запрос) комплексному компоненту (controller).

    Пример

    Расмотрим упрощённый пример работы комплексного компонента новостей. Пусть у нас есть обычные компоненты: список новостей и детальной новости (последний принимает во входных параметрах код новости, которую нужно показать).

    Раздел новостей можно организовать, например, разместив на странице index.php компонент списка новостей, а на странице news.php - компонент детальной новости. При этом у компонента списка новостей нужно настроить входные параметры так, чтобы он мог формировать ссылки на страницу детальной новости (с кодом новости), а у компонента детальной новости нужно настроить входные параметры так, чтобы он мог формировать ссылку на страницу списка новостей. Для того, чтобы задать ссылку на страницу детальной новости, нужно задать путь к этой странице, а так же название параметра, в котором будет передаваться код новости для показа. То же название параметра нужно задать и во входных параметрах компонента детальной новости, чтобы он знал, где брать код новости для показа. Даже в данном максимально упрощённом случае настройки не так просты. А если это набор из десятков компонентов форума?

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

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

    Таким образом реализуется паттерн MVC:

    • на комплексный компонент новостей (controller) приходит HTTP запрос (действия пользователя);
    • комплексный компонент новостей (controller) проверяет, установлен ли через HTTP запрос код новости и подключает из своего шаблона страницу списка новостей или страницу детальной новости (view);
    • подключенная страница, в свою очередь, подключает соответствующий обычный компонент, устанавливая при этом его входные параметры соответствующим образом;
    • обычный компонент выполняет свою работу: запрашивает данные у ядра (model), форматирует их и выводит посетителю, а также отображает элементы управления (ссылки, формы, кнопки и т.п.);
    • пользователь с помощью элементов управления посылает новый HTTP запрос на комплексный компонент новостей (controller);
    • процедура повторяется по мере надобности.


Физическое размещение компонентов

Компоненты 2.0::Физическое размещение компонентов

Физическое размещение

Все компоненты находятся в папке /bitrix/components/. Системные компоненты находятся в папке /bitrix/components/bitrix/. Содержимое этой папки обновляется системой обновлений и не может изменяться пользователями.

Внимание!
Изменение содержимого папки системных компонентов /bitrix/components/bitrix/ может привести к непредсказуемым последствиям.

Пользовательские компоненты могут находиться в любых других подпапках папки /bitrix/components/ или прямо в папке /bitrix/components/.

Именование

Название подпапки директории /bitrix/components/ образует пространство имен (namespace) компонентов. Например, все системные компоненты расположены в пространстве имен bitrix. При создании пользовательских компонентов рекомендуется создать какое-либо пространство имен и размещать пользовательские компоненты в нем.

Например, существует системный компонент catalog, который расположен в пространстве имен bitrix. Если необходим пользовательский компонент catalog, который имеет другую функциональность, не реализуемую с помощью шаблона системного компонента, то рекомендуется создать некоторое пространство имен (подпапку) в папке /bitrix/components/ (например, mycompany) и расположить пользовательский компонент catalog в этом пространстве имен. Таким образом будут доступны два компонента catalog, но лежащие в разных пространствах имен: «bitrix:catalog» и «mycompany:catalog».

Имена компонентов имеют вид «идентификатор1.идентификатор2....».Например, «catalog», «catalog.list», «catalog.section.element» и т.п. Рекомендуется строить имена иерархически, начиная с общего понятия и заканчивая конкретным назначением компонента. Например, компонент, показывающий список товаров данной группы, может называться «catalog.section.elements». Полное имя компонента – это имя компонента с указанием простанства имен. Полное имя имеет вид «пространство_имен:имя_компонента». Например, «bitrix:catalog.list». Если компонент лежит вне пространства имен, то пространство имен не указывается. Например, «catalog.section».


Структура папки компонента

Компоненты 2.0::Структура папки компонента

Папка компонента может содержать следующие подпапки и файлы.

Дочерние папки

Папка | Назначение
help | В папке help расположены файлы помощи компонента. Здесь находятся подпапки с именами, равными кодам языков. В них, в свою очередь, находятся файлы index.php, которые являются главными файлами помощи данного компонента для данного языка (и, возможно, другие файлы). Например, путь к файлу помощи для английского языка будет иметь вид /help/en/index.php (относительно папки компонента). Внимание! В файлах помощи обязательно должна быть описана структура массива, в котором компонент возвращает данные шаблону. Подпапка help может отсутствовать.
install | Здесь располагаются скрипты инсталляции и удаления компонента. Скрипт инсталляции должен иметь имя install.php, а скрипт для деинсталляции – uninstall.php. Подпапка install может отсутствовать.
lang | Папка lang содержит подпапки с именами, равными кодам языков, в которых находятся файлы языковых сообщений (переводов) компонента. Рекомендуется называть файл языковых сообщений для какого-либо файла компонента так же, как называется компонент и помещать его в той же иерархии относительно папки /lang/код_языка/, в которой файл распологается относительно папки компонента. Например, языковой файл с английскими фразами для файла /install/uninstall.php рекомендуется распологать по пути /lang/en/install/uninstall.php. Подпапка lang может отсутствовать, если в компоненте нет зависящих от языка фраз.
templates | Здесь содержатся шаблоны вывода (отображения) компонента. Подпапка templates может отсутствовать, если у компонента нет шаблонов вывода.

Файлы

Файл | Назначение
component.php | Содержит логику (код) компонента. Этот файл должен всегда присутствовать в папке компонента.
.description.php | Содержит название, описание компонента и его положение в дереве логического размещения (для редактора). Этот файл должен всегда присутствовать в папке компонента.
.parameters.php | Содержит описание входных параметров компонента для редактора. Если у компонента есть входные параметры, то этот файл должен присутствовать в папке компонента.
Любые другие папки и файлы с ресурсами, необходимыми компоненту. Все ресурсы компонента должны находиться в папке компонента.


Файл описания компонента .description.php

Компоненты 2.0::Файл описания компонента .description.php

В файле .description.php содержится описание компонента. Это описание применяется для работы с компонентом из среды БУС (например, в визуальном редакторе), а также при работе в режиме редактирования сайта. При работе самого компонента (при обращении к странице, на которой расположен компонент) описание не используется и файл .description.php не подключается.

Файл .description.php должен находиться в папке компонента. Языковой файл подключается автоматически (должен лежать в папке /lang/<язык>/.description.php относительно папки компонента).

Структура типичного файла .description.php такова:

<?
$arComponentDescription = array(
   "NAME" => GetMessage("COMP_NAME"),
   "DESCRIPTION" => GetMessage("COMP_DESCR"),
   "ICON" => "/images/icon.gif",
   "PATH" => array(
      "ID" => "content",
      "CHILD" => array(
         "ID" => "catalog",
         "NAME" => "Каталог товаров"
      )
   ),
   "AREA_BUTTONS" => array(
      array(
         'URL' => "javascript:alert('Это кнопка!!!');",
         'SRC' => '/images/button.jpg',
         'TITLE' => "Это кнопка!"
      ),
   ),
   "CACHE_PATH" => "Y",
   "COMPLEX" => "Y"
);
?>

Как видно, в файле определяется массив $arComponentDescription, который описывает компонент. Этот массив может иметь следующие ключи:

  • "NAME" - название компонента;
  • "DESCRIPTION" - описание компонента;
  • "ICON" - путь к пиктограмме компонента относительно папки компонента. Значок компонента используется в среде БУС (например, в визуальном редакторе);
  • "PATH" - расположение компонента в виртуальном дереве компонента в визуальном редакторе. Значением этого элемента должен быть массив, имеющий ключи:
    • "ID" - код ветки дерева;
    • "NAME" - название ветки дерева;
    • "CHILD" - дочерняя или подчиненная ветка. В элементе с ключом "CHILD" может быть задана подчиненная ветка дерева с той же структурой, что и родительская ветка.
    Дерево ограничено тремя уровнями. Как правило, строится двухуровневое дерево и компоненты располагаются на втором уровне. Следующие служебные названия первого уровня зарезервированы и не могут быть использованы: "content" (контент), "service" (сервисы), "communication" (общение), "e-store" (магазин), "utility" (служебные).

    Если ключ "PATH" не задан, то компонент не будет присутствовать в визуальном редакторе;
  • "AREA_BUTTONS" - пользовательские кнопки, которые показываются для компонента в режиме редактирования сайта;
  • "CACHE_PATH" - если значение равно "Y", отображается кнопка очистки кэша компонента в режиме редактирования сайта (предполагается, что кэш лежит по стандартному пути: /<код сайта>/<относительный путь к компоненту>). Если равно не пустой отличной от "Y" строке, отображается кнопка очистки кэша компонента в режиме редактирования сайта (кэш лежит по пути, равному значению с ключом "CACHE_PATH" - для нестандартных путей);
  • "COMPLEX" - элемент должен иметь значение "Y" для комплексного компонента, для простых компонентов не имеет значения.


Файл параметров компонента .parameters.php

Компоненты 2.0::Файл параметров компонента .parameters.php

В файле .parameters.php содержится описание входных параметров компонента. Это описание применяется для работы с компонентом из среды БУС (например, в визуальном редакторе), а так же при работе в режиме редактирования сайта. При работе самого компонента (при обращении к странице, на которой расположен компонент) описание не используется и файл .parameters.php не подключается.

Данные .parameters.php нужны исключительно для создания формы ввода свойств компонента в среде БУС (например, в визуальном редакторе).

Файл .parameters.php должен находиться в папке компонента. Языковой файл подключается автоматически (должен лежать в папке /lang/<язык>/.parameters.php, относительно папки компонента).

Структура типичного файла .parameters.php такова.

<?
CModule::IncludeModule("iblock");

$dbIBlockType = CIBlockType::GetList(
   array("sort" => "asc"),
   array("ACTIVE" => "Y")
);
while ($arIBlockType = $dbIBlockType->Fetch())
{
   if ($arIBlockTypeLang = CIBlockType::GetByIDLang($arIBlockType["ID"], LANGUAGE_ID))
      $arIblockType[$arIBlockType["ID"]] = "[".$arIBlockType["ID"]."] ".$arIBlockTypeLang["NAME"];
}

$arComponentParameters = array(
   "GROUPS" => array(
      "SETTINGS" => array(
         "NAME" => GetMessage("SETTINGS_PHR")
      ),
      "PARAMS" => array(
         "NAME" => GetMessage("PARAMS_PHR")
      ),
   ),
   "PARAMETERS" => array(
      "IBLOCK_TYPE_ID" => array(
         "PARENT" => "SETTINGS",
         "NAME" => GetMessage("INFOBLOCK_TYPE_PHR"),
         "TYPE" => "LIST",
         "ADDITIONAL_VALUES" => "Y",
         "VALUES" => $arIblockType,
         "REFRESH" => "Y"
      ),
      "BASKET_PAGE_TEMPLATE" => array(
         "PARENT" => "PARAMS",
         "NAME" => GetMessage("BASKET_LINK_PHR"),
         "TYPE" => "STRING",
         "MULTIPLE" => "N",
         "DEFAULT" => "/personal/basket.php",
         "COLS" => 25
      ),
      "SET_TITLE" => array(),
      "CACHE_TIME" => array(),
      "VARIABLE_ALIASES" => array(
         "IBLOCK_ID" => array(
            "NAME" => GetMessage("CATALOG_ID_VARIABLE_PHR"),
         ),
         "SECTION_ID" => array(
            "NAME" => GetMessage("SECTION_ID_VARIABLE_PHR"),
         ),
      ),
      "SEF_MODE" => array(
         "list" => array(
            "NAME" => GetMessage("CATALOG_LIST_PATH_TEMPLATE_PHR"),
            "DEFAULT" => "index.php",
            "VARIABLES" => array()
         ),
         "section1" => array(
            "NAME" => GetMessage("SECTION_LIST_PATH_TEMPLATE_PHR"),
            "DEFAULT" => "#IBLOCK_ID#",
            "VARIABLES" => array("IBLOCK_ID")
         ),
         "section2" => array(
            "NAME" => GetMessage("SUB_SECTION_LIST_PATH_TEMPLATE_PHR"),
            "DEFAULT" => "#IBLOCK_ID#/#SECTION_ID#",
            "VARIABLES" => array("IBLOCK_ID", "SECTION_ID")
         ),
      ),
   )
);
?>

В файле определяется массив $arComponentParameters, который описывает входные параметры компонента. Если необходимо, производится выборка каких-либо дополнительных данных. Например, для формирования выпадающего списка типов информационных блоков (входной параметр IBLOCK_TYPE_ID) выбираются все активные типы.

Массив $arComponentParameters имеет следующие ключи:

  • "GROUPS" - значением этого ключа является массив групп параметров компонента. Параметры в визуальных средствах среды БУС (например, в визуальном редакторе) группируются. Группы в среде БУС располагаются в том порядке, в котором заданы в файле. Массив групп параметров компонента состоит из элементов следующего вида
    "код группы" => array(
    "NAME" => "название группы на текущем языке"
    )
  • "PARAMETERS" - значением этого ключа является массив параметров компонента. В каждой группе параметров параметры располагаются в том порядке, в котором заданы в файле. Массив обычных параметров компонента состоит из элементов следующего вида
    "код параметра" => array(
    "PARENT" => "код группы, которой принадлежит параметр",
    "NAME" => "название параметра на текущем языке",
    "TYPE" => "тип элемента управления, в котором будет устанавливаться параметр",
    * * *
    )

Существуют особые параметры, которые стандартизованы и которые нет необходимости описывать полностью. Достаточно указать, что они есть. Например,

"SET_TITLE" => array(),
"CACHE_TIME" => array(),

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

Если компонент может работать в режиме ЧПУ или переопределять переменные, которые приходят из HTTP запроса, необходимо среди параметров указать ещё два особых параметра:

  • "VARIABLE_ALIASES" - массив, описывающий переменные, которые компонент может получать из HTTP запроса. Каждый элемент массива имеет вид:
    "внутреннее название переменной" => array(
  "NAME" => "название переменной на текущем языке",
)
  • "SEF_MODE" - массив, описывающий шаблоны путей в режиме ЧПУ. Каждый элемент массива имеет вид:
    "код шаблона пути" => array(
    "NAME" => "название шаблона пути на текущем языке",
    "DEFAULT" => "шаблон пути по-умолчанию",
    "VARIABLES" => "массив внутренних названий переменных, которые могут использоваться в шаблоне"
)


Замечания по массивам $arParams и $arResult

Компоненты 2.0::Замечания по массивам $arParams и $arResult

$arParams

$arParams - предопределённая для компонента переменная, представляющая собой массив входных параметров компонента. Ключами в этом массиве являются названия параметров, а значениями - их значения.

Перед подключением компонента ко всем значениям параметров применяется функция htmlspecialcharsEx.

Исходные значения параметров сохраняются в этом же массиве с теми же ключами, но с префиксом "~". Например, $arParams["NAME"] - входной параметр, к которому применена функция htmlspecialcharsEx, а $arParams["~NAME"] - исходный входной параметр.

Переменная $arParams является псевдонимом для члена класса компонента, поэтому все изменения этой переменной отражаются и на этом члене класса. В начале кода компонента должна быть произведена проверка входных параметров, инициализация не установленных параметров, приведение к нужному типу (например, IntVal()). Все эти изменения входных параметров будут доступны и в шаблоне, то есть, параметры будут проверены и максимально безопасны. Дублирование подготовки параметров в шаблоне компонента не требуется.

$arResult

$arResult - предопределённая для компонента переменная, в которую набирается результат работы компонента для передачи в шаблон. Перед подключением файла компонента эта переменная инициализируется пустым массивом array().

Переменная $arResult является псевдонимом для члена класса компонента, поэтому все изменения этой переменной отражаются и на этом члене класса. Явно передавать в шаблон эту переменную не следует, это делают внутренние механизмы класса компонента.

Псевдонимы в PHP

Псевдонимы (references) в PHP служат для того, чтобы к одним и тем же данным можно было обратиться по разным именам. Если переменные $arParams и $arResult изменены некоторым образом в коде компонента, то они будут доступны измененными и в шаблоне.

При этом нужно учитывать следующие нюансы.

  • Если в компоненте написать код:
    $arParams = & $arSomeArray;
    то переменная $arParams будет отвязана от члена класса компонента и привязана к массиву $arSomeArray. В этом случае, дальнейшие изменения $arParams не попадут в шаблон компонента.
  • Если в компоненте написать код:
    unset($arParams);
    то это так же разорвет связь между $arParams и соответствующим членом класса компонента.


Кеширование в компоненте

Компоненты 2.0::Кеширование в компоненте

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

Встроенная поддержка кеширования

В компонентах 2.0 есть встроенная поддержка типичного алгоритма кеширования. Структура компонента с использованием встроенной поддержки кеширования будет примерно такова

// Проверка и инициализация входных параметров
if ($arParams["ID"] <= 0)
   $arParams["ID"] = 10;

// Если нет валидного кеша (то есть нужно запросить
// данные и сделать валидный кеш)
if ($this->StartResultCache())
{
   // Запрос данных и заполнение $arResult
   $arResult = array(
      "ID" => rand(1, 100)
   );

   for ($i = 0; $i < 5; $i++)
      $arResult["FIELDS"][] = rand(1, 100);

   // Если выполнилось какое-то условие, то кешировать
   // данные не надо
   if ($arParams["ID"] < 10)
      $this->AbortResultCache();

   // Подключить шаблон вывода
   $this->IncludeComponentTemplate();
}

// Установить заголовок страницы с помощью отложенной
// функции
$APPLICATION->SetTitle($arResult["ID"]);
Пояснения

Метод StartResultCache имеет следующее описание:

bool $this->StartResultCache($cacheTime = False, $additionalCacheID = False, $cachePath = False)
где:
  • $cacheTime - время кеширования (если False, подставляется IntVal($arParams["CACHE_TIME"]) ).
  • $additionalCacheID - определяет дополнительные зависимости кеша помимо текущего сайта SITE_ID, имени компонента, пути в файлу и входных параметров $arParams (если False, кеш зависит только от указанных параметров).
  • $cachePath - путь к файлу кеша (если False, подставляется "/".SITE_ID.<путь к компоненту относительно bitrix/components>).

Если есть валидный кеш, метод отправляет на экран его содержимое, заполняет $arResult и возвращает False; если нет валидного кеша, возвращается True.

Если кеш зависит не только от сайта, входных параметров, имени компонента и пути к текущему сайту, но и от других параметров - эти параметры в виде строки нужно передать в метод вторым параметром. Например, если кеш зависит ещё от групп пользователей, в которые входит текущий посетитель, то условие нужно написать следующим образом:

if ($this->StartResultCache(false, $USER->GetGroups()))
{
   // Валидного кэша нет. Выбираем данные из
   // базы в $arResult
}

Если в результате выборки данных (в случае отсутствия валидного кеша) выяснилось, что кешировать данные не надо, то нужно вызвать метод:

$this->AbortResultCache();
Например, если выяснилось, что новости с таким ID нет, то нужно прервать кеширование и выдать сообщение, что такой новости нет. Если кеширование не прерывать, то злоумышленники смогут забить кешем все отведенное сайту дисковое пространство вызывая страницу с произвольными (в том числе и не существующими) ID.

Метод:

$this->IncludeComponentTemplate();
подключает шаблон компонента и сохраняет в кеш-файл вывод и массив результатов $arResult. Все изменения $arResult и вывод после вызова метода подключения шаблона не будут сохранены в кеш.

Если при исполнении кода компонента мы не вошли в тело условия:

if ($this->StartResultCache())
значит, для данного компонента, страницы и входных параметров есть валидный кеш. После вызова этого метода, HTML из кеша отправлен на вывод и мы имеем заполненный массив $arResult. Здесь можно выполнить некоторые действия; например, установить заголовок страницы с помощью отложенных функций.

Если при выполнении некоторых условий нужно очистить кеш компонента (например, компонент знает, что данные изменились), можно воспользоваться методом:

$this->ClearResultCache($additionalCacheID = False, $cachePath = False)
Параметры этого метода соответствуют одноименным параметрам метода StartResultCache.

Сложное кеширование

Если компоненту требуется какое-либо особое кеширование, которое не может быть выполнено с помощью встроенной поддержки кеширования, можно использовать стандартный класс CPHPCache. Структура компонента с использованием класса CPHPCache будет примерно такова

// Проверка и инициализация входных параметров
if ($arParams["ID"] <= 0)
   $arParams["ID"] = 10;

$arParams["CACHE_TIME"] = IntVal($arParams["CACHE_TIME"]);
$CACHE_ID = SITE_ID."|".$APPLICATION->GetCurPage()."|";

// Кеш зависит только от подготовленных параметров без "~"
foreach ($this->arParams as $k => $v)
   if (strncmp("~", $k, 1))
      $CACHE_ID .= ",".$k."=".$v;
$CACHE_ID .= "|".$USER->GetGroups();

$cache = new CPageCache;
if ($cache->StartDataCache($arParams["CACHE_TIME"],
                           $CACHE_ID,
                           "/".SITE_ID.$this->GetRelativePath()))
{
   // Запрос данных и формирование массива $arResult
   $arResult = array("a" => 1, "b" => 2);

   // Подключение шаблона компонента
   $this->IncludeComponentTemplate();

   $templateCachedData = $this->GetTemplateCachedData();

   $cache->EndDataCache(
      array(
         "arResult" => $arResult,
    "templateCachedData" => $templateCachedData
      )
   );
}
else
{
   extract($cache->GetVars());
   $this->SetTemplateCachedData($templateCachedData);
}
Пояснения

Кеш должен зависеть только от подготовленных параметров (тех, которые инициализированы нужным образом, приведены к нужному типу (например, с помощью IntVal) и т.д). В массиве $arParams содержатся как подготовленные параметры, так и исходные параметры (с тем же ключом, но с префиксом "~"). Если кеш будет зависеть от неподготовленных параметров, злоумышленники смогут забить кешем все отведенное сайту дисковое пространство вызывая страницу с ID равными "8a", "8b", ... (которые после IntVal() дадут 8).

Метод:

$this->IncludeComponentTemplate()

не запрашивает данные из базы. Однако, его тоже лучше включить в кешируемую область, так как он производит определённые дисковые операции.

Перед вызовом метода завершения кеширования и сохранения кеша (метод EndDataCache) необходимо запросить у шаблона параметры, которые должны быть использованы даже в том случае, если сам шаблон не подключается и данные берутся из кеша. В текущей реализации такими параметрами являются стили css шаблона, которые подключаются отложенными функциями, а значит, не попадают в кеш. Структура возвращаемых шаблоном данных не документируется и не имеет значения для компонента. Это просто некие данные, которые нужно положить в кеш, а затем взять из кеша и вернуть в шаблону.

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

$this->SetTemplateCachedData($templateCachedData);
Этот метод должен быть вызван в той области компонента, которая выполняется в случае наличия валидного кеша. В параметрах ему должны быть переданы те данные, которые шаблон просил сохранить.


Структура комплексного компонента

Компоненты 2.0::Структура комплексного компонента

Комплексный компонент служит для организации целого раздела сайта (форум, каталог и т.п.). Для вывода данных он подключает обычные компоненты. По сути, он является контроллером (менеджером) простых компонентов. Комплексный компонент определяет на основании HTTP запроса страницу, которую требуется вывести посетителю, и подключает шаблон этой страницы.

Пример кода комплексного компонента:

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?><?

$arDefaultUrlTemplates404 = array(
   "list" => "index.php",
   "element" => "#ELEMENT_ID#.php"
);

$arDefaultVariableAliases404 = array();

$arDefaultVariableAliases = array();

$arComponentVariables = array("IBLOCK_ID", "ELEMENT_ID");

$SEF_FOLDER = "";
$arUrlTemplates = array();

if ($arParams["SEF_MODE"] == "Y")
{
   $arVariables = array();

    $arUrlTemplates =
        CComponentEngine::MakeComponentUrlTemplates($arDefaultUrlTemplates404,
                                                    $arParams["SEF_URL_TEMPLATES"]);
    $arVariableAliases =
        CComponentEngine::MakeComponentVariableAliases($arDefaultVariableAliases404,
                                                       $arParams["VARIABLE_ALIASES"]);

   $componentPage = CComponentEngine::ParseComponentPath(
      $arParams["SEF_FOLDER"],
      $arUrlTemplates,
      $arVariables
   );

   if (StrLen($componentPage) <= 0)
      $componentPage = "list";

   CComponentEngine::InitComponentVariables($componentPage,
                                            $arComponentVariables,
                                            $arVariableAliases,
                                            $arVariables);

   $SEF_FOLDER = $arParams["SEF_FOLDER"];
}
else
{
   $arVariables = array();

    $arVariableAliases =
       CComponentEngine::MakeComponentVariableAliases($arDefaultVariableAliases,
                                                      $arParams["VARIABLE_ALIASES"]);
    CComponentEngine::InitComponentVariables(false,
                                             $arComponentVariables,
                                             $arVariableAliases, $arVariables);

   $componentPage = "";
   if (IntVal($arVariables["ELEMENT_ID"]) > 0)
      $componentPage = "element";
   else
      $componentPage = "list";

}

$arResult = array(
   "FOLDER" => $SEF_FOLDER,
   "URL_TEMPLATES" => $arUrlTemplates,
   "VARIABLES" => $arVariables,
   "ALIASES" => $arVariableAliases
);

$this->IncludeComponentTemplate($componentPage);
?>

В начале кода определяются массивы:

  • $arDefaultUrlTemplates404 - для задания путей по умолчанию для работы в ЧПУ режиме. Каждый элемент массива является шаблоном пути и задается в виде:
    "код шаблона пути" => "шаблон пути"
    В шаблоне пути могут быть использованы конструкции вида "#слово#", которые при формировании реального пути заменяются на значения соответствующих переменных. Например, для шаблона пути:
    "element" => "#ELEMENT_ID#.php"
    реальный путь будет иметь вид 195.php или 7453.php. Шаблоны путей могут иметь параметры, например:
    "element" => "#IBLOCK_ID#/#ELEMENT_ID#.php?SECTION_ID=#SECTION_ID#"
    Должны быть заданы все шаблоны путей, в которыми работает компонент.
  • $arDefaultVariableAliases404 - для задания псевдонимов по умолчанию переменных в режиме ЧПУ. Как правило, этот массив пуст (используются реальные имена переменных). В случае, если необходимо, чтобы в HTTP запросе (в адресе) переменная называлась по другому, можно задать псевдоним этой переменной, а при работе компонента восстанавливать значение переменной из псевдонима. Если для какого-либо шаблона пути нужно задать псевдоним для одной или более переменных, то в этом массиве должен появиться элемент вида:
    "код шаблона пути" => array(
    "название переменной 1" => "псевдоним переменной 1",
    "название переменной 2" => "псевдоним переменной 2",
    * * *
    )
    Например, если требуется, чтобы ссылка на страницу детальной информации об элементе инфоблока (например, карточки товара) имела вид:
    "/<мнемонический код инфоблока>/.php?SID=<код группы элементов>"
    то шаблон пути можно задать в виде:
    "element" => "#IBLOCK_ID#/#ELEMENT_ID#.php?SID=#SECTION_ID#"
    а в массиве $arDefaultVariableAliases404 задать псевдоним для переменной SECTION_ID в виде:
    "element" => array(
    "SECTION_ID" => "SID"
    )
    В этом случае ссылки (адреса) будут формироваться с параметром SID, а в компонентах будет установлена переменная SECTION_ID.
  • $arDefaultVariableAliases - для задания псевдонимов по умолчанию переменных в режиме не ЧПУ. Как правило, этот массив пуст, то есть используются реальные имена переменных. В случае, если необходимо, чтобы в HTTP запросе (в адресе) переменная называлась по другому, можно задать псевдоним этой переменной, а при работе компонента восстанавливать значение переменной из псевдонима. Если для какой-либо переменной нужно задать псевдоним, то в этом массиве должен появиться элемент вида:
    "название переменной" => "псевдоним переменной"
    Например, если название переменной в компоненте SECTION_ID, но требуется, чтобы в ссылках использовалась переменная SID, то псевдоним для SECTION_ID можно задать в виде
    "SECTION_ID" => "SID"
    В этом случае, ссылки (адреса) будут формироваться с параметром SID, а в компонентах будет установлена переменная SECTION_ID. Все эти массивы или их части могут быть переопределены с помощью входных параметров компонента (при вызове компонента). Например, во входном параметре SEF_URL_TEMPLATES в ЧПУ режиме может быть задан массив:
    "SEF_URL_TEMPLATES" => array(
    "element" => "#IBLOCK_CODE#/#ELEMENT_ID#.php?GID=#SECTION_ID#"
    )
    а во входном параметре VARIABLE_ALIASES может быть задан параметр:
    "VARIABLE_ALIASES" => array(
    "element" => array(
    "SECTION_ID" => "GID",
    ),
)
    Тогда в адресах (ссылках) пути будут иметь вид типа /phone/3425.php?GID=28, а в компоненте из них будут восстанавливаться переменные IBLOCK_CODE = phone, ELEMENT_ID = 3425 и SECTION_ID = 28.
  • $arComponentVariables - для задания списка переменных, которые компонент может принимать в HTTP запросе и которые могут иметь псевдонимы. Каждый элемент массива является именем переменной.

Входной параметр с предопределённым именем SEF_MODE может иметь два значения: Y и N. Если $arParams["SEF_MODE"] равен Y, значит компонент работает в режиме ЧПУ, иначе - нет.

Входной параметр с предопределённым именем SEF_FOLDER имеет смысл в том случае, если компонент работает в режиме ЧПУ. В этом случае он содержит путь, по которому работает компонент. Путь может быть виртуальным (т.е. физически он может не существовать). Например, компонент из примера может лежать в файле /fld/n.php, при этом он работает в режиме ЧПУ и входной параметр SEF_FOLDER равен /company/news/. Тогда компонент будет откликаться на запросы по адресам /company/news/index.php, /company/news/25.php и т.п.

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

  • CComponentEngine::MakeComponentUrlTemplates
    array
CComponentEngine::MakeComponentUrlTemplates($arDefaultUrlTemplates404,
                                            $arParams["SEF_URL_TEMPLATES"]);
    Метод объединяет массив по умолчанию шаблонов путей и шаблоны путей, которые были переданы во входных параметрах компонента в один массив. При этом, если в $arParams["SEF_URL_TEMPLATES"] определён шаблон какого-либо пути, то он переопределяет шаблон по умолчанию этого пути.
  • CComponentEngine::MakeComponentVariableAliases
    array
CComponentEngine::MakeComponentVariableAliases($arDefaultVariableAliases404,
                                               $arParams["VARIABLE_ALIASES"]);
    Метод объединяет массив по умолчанию псевдонимов переменных и псевдонимы переменных, которые были переданы во входных параметрах компонента в один массив. При этом, если псевдоним некоторой переменной определён и в массиве по умолчанию, и во входных параметрах, то возвращается псевдоним из входных параметров.
  • CComponentEngine::ParseComponentPath
    string
CComponentEngine::ParseComponentPath($arParams["SEF_FOLDER"],
                                     $arUrlTemplates, $arVariables);
    Метод на основании параметра $arParams["SEF_FOLDER"] и массива шаблонов путей (который вернул метод MakeComponentUrlTemplates) определяет, какому шаблону пути соответствует запрошенный адрес. Если шаблон был найден, возвращается его код, иначе возвращается пустая строка. Кроме того, в переменной $arVariables возвращается массив переменных компонента, который был восстановлен из шаблона пути без параметров. Например, если массив шаблонов путей (который получился из массива $arDefaultUrlTemplates404 после переопределения всех или части шаблонов через входные параметры компонента) имеет вид:
    $arUrlTemplates = array(
    "list" => "index.php",
    "element" => "#IBLOCK_ID#/#ELEMENT_ID#.php?SID=#SECTION_ID#"
);
    Если входной параметр SEF_FOLDER равен /company/news/, а запрошенный адрес равен /company/news/15/7653.php?SID=28, то метод ParseComponentPath вернет строку "element" (код соответствующего шаблона), а массив $arVariables будет иметь вид:
    $arVariables = array(
    "IBLOCK_ID" => 15,
    "ELEMENT_ID" => 7653
)
  • CComponentEngine::InitComponentVariables
    CComponentEngine::InitComponentVariables($componentPage,
                                         $arComponentVariables,
                                         $arVariableAliases,
                                         $arVariables);
    где:
    • $componentPage - код шаблона, который вернул метод ParseComponentPath и которому соответствует запрошенный адрес;
    • $arComponentVariables - массив переменных, которые компонент может принимать в HTTP запросе и которые могут иметь псевдонимы;
    • $arVariableAliases - массив псевдонимов (который вернул метод MakeComponentVariableAliases).

    Метод восстанавливает переменные из $_REQUEST c учётом их возможных псевдонимов и возвращает их в переменной $arVariables. Например, если для кода, приведенного выше, в массиве $arVariableAliases есть запись вида

    "element" => array(
    "SECTION_ID" => "SID",
)
    то метод InitComponentVariables в параметре $arVariables вернет массив вида
    $arVariables = array(
    "IBLOCK_ID" => 15,
    "ELEMENT_ID" => 7653,
    "SECTION_ID" => 28
)
    Здесь методом InitComponentVariables был инициализирован третий элемент массива. Первые два были инициализированы методом ParseComponentPath в примере выше. В случае работы компонента не в режиме ЧПУ, в метод InitComponentVariables первым параметром передается значение False.

В случае работы компонента в режиме ЧПУ на основании кода шаблона пути и переменных из HTTP запроса (а в случае не-ЧПУ адресов, только на основании переменных из HTTP запроса) компонент определяет, какая страница из шаблона компонента должна подключится, и передает ее имя в вызов метода:

$this->IncludeComponentTemplate($componentPage);

На страницах шаблона комплексного компонента подключаются обычные компоненты и настраиваются их входные параметры на основании входных параметров комплексного компонента, некоторых вычисляемых значений и констант. Например, страница "element" шаблона компонента из примера (файл типа /templates/.default/list.php относительно папки компонента) может иметь вид типа:

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>
<?$APPLICATION->IncludeComponent(
   "bitrix:news.detail",
   "",
   Array(
      "IBLOCK_ID" => $arParams["IBLOCK_ID"],
      "ELEMENT_ID" => $arResult["VARIABLES"]["ELEMENT_ID"],
      "SECTION_ID" => $arResult["VARIABLES"]["SECTION_ID"],
      "CACHE_TIME" => $arParams["CACHE_TIME"],
   ),
   $component
);?>
Последний параметр $component в подключении компонента - объект, представляющий текущий компонент. Он передается в вызов подключения компонента. Таким образом, подключаемый компонент будет знать, что он подключается из комплексного компонента. Соответственно, он сможет пользоваться ресурсами комплексного компонента, вызывать его методы и т.п.


Шаблоны вывода

Компоненты 2.0::Шаблоны вывода

Шаблоны компонента делятся на системные и пользовательские.

Системные шаблоны поставляются вместе с компонентом и лежат в подпапке templates папки компонента.

Пользовательские шаблоны компонента – шаблоны, которые изменены под нужды конкретного сайта. Пользовательские шаблоны компонентов должны лежать в папках шаблонов сайтов (т.е. в /bitrix/templates/шаблон_сайта/).

Шаблоны компонента определяются своими именами. Шаблон по умолчанию имеет имя .default. Если не указывается имя шаблона, вызывается шаблон по умолчанию. Остальные шаблоны могут называться произвольно, например table.

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

Каждый шаблон компонента является неделимым целым. Если требуется изменить системный шаблон компонента под конкретный сайт, то этот шаблон компонента нужно целиком скопировать в папку шаблона сайта.

Например, у компонента bitrix:catalog.section.element есть системный шаблон table, который лежит в подпапке templates папки компонента (в папке /bitrix/components/bitrix/catalog.section.element/templates/ относительно корня сайта). Если этот шаблон компонента требуется изменить под конкретный сайт, то папку этого шаблона table следует скопировать в папку /bitrix/templates/шаблон_сайта/components/bitrix/catalog.section.element/ и изменить по своему усмотрению.


Структура шаблона обычного компонента

Компоненты 2.0::Структура шаблона обычного компонента

Папка шаблона простого компонента может содержать следующие подпапки и файлы:

  • Подпапка lang, в которой расположены файлы языковых сообщений (переводов) шаблона компонента. В этой папке находятся подпапки с именами, равными кодам языков. В этих подпапках находятся файлы языковых сообщений (переводов) шаблона компонента. Файл языковых сообщений для какого-либо файла шаблона компонента должен иметь такое же имя, как и файл компонента и находиться в той же иерархии относительно папки /lang/код_языка/, в которой файл располагается относительно папки шаблона. Например, языковой файл с английскими фразами для файла /index.php требуется располагать по пути /lang/en/index.php. Подпапка lang может отсутствовать, если в шаблоне компонента нет зависящих от языка фраз.
  • Файл result_modifier.php, который подключается непосредственно перед подключением шаблона компонента. Этот файл получает на вход массив результатов работы компонента $arResult и массив параметров вызова компонента $arParams. Таким образом можно, например, изменить массив результатов работы компонента под конкретный шаблон. Например, системный компонент полностью подходит для сайта, за исключением того, что он не возвращает какое-то дополнительное поле. Прямым решением этой проблемы будет создание пользовательского компонента. Однако, кроме затрат на создание, здесь будет следующий минус: компонент не будет обновляться, а значит не будут исправляться ошибки и добавляться новый функционал. Чтобы избавиться от этих недостатков, можно создать файл result_modifier.php в шаблоне компонента и дописать в массив $arResult дополнительное поле. Могут быть и другие варианты использования этого файла. Файл result_modifier.php может отсутствовать.
  • Файл style.css, который определяет стили, необходимые данному шаблону. Он применяется в том случае, если шаблону нужны не стандартные, в рамках сайта, стили. Файл style.css подключается автоматически, если он есть в папке шаблона. Этот файл может отсутствовать.
  • Файл script.js, который определяет подключает ява-скрипты, необходимые данному шаблону, добавлением строки типа <script src=".../script.js" type="text/javascript"></script>. Файл script.js подключается автоматически, если он есть в папке шаблона. Этот файл может отсутствовать.
  • Файл .description.php, который содержит название и описание шаблона для редактора. Этот файл может отсутствовать.
  • Файл .parameters.php, который содержит описание входных параметров шаблона для редактора. Этот файл может отсутствовать.
  • Файл template.ext, который и является собственно шаблоном. Расширение ext зависит от того, какой движок шаблонизации нужно подключать. По умолчанию расширение равно php. Этот файл должен обязательно присутствовать.
  • Любые другие папки и файлы с ресурсами, необходимыми шаблону компонента. Например, папка image, содержащая изображения, необходимые шаблону.


Структура шаблона комплексного компонента

Компоненты 2.0::Структура шаблона комплексного компонента

Папка шаблона комплексного компонента может содержать следующие подпапки и файлы.

  • Подпапку lang, в которой расположены файлы языковых сообщений (переводов) шаблона компонента. В этой папке находятся подпапки с именами, равными кодам языков. В этих подпапках находятся файлы языковых сообщений (переводов) шаблона компонента. Файл языковых сообщений для какого-либо файла шаблона компонента должен иметь такое же имя, как и файл компонента и находиться в той же иерархии относительно папки /lang/код_языка/, в которой файл распологается относительно папки шаблона. Например, языковой файл с английскими фразами для файла /section.php требуется распологать по пути /lang/en/section.php. Подпапка lang может отсутствовать, если в шаблоне компонента нет зависящих от языка фраз.
  • Файл result_modifier.php, который подключается непосредственно перед подключением шаблона компонента. Этот файл получает на вход массив результатов работы компонента $arResult и массив параметров вызова компонента $arParams. Таким образом можно, например, изменить массив результатов работы компонента под конкретный шаблон.
  • Файл style.css, который определяет стили, необходимые данному шаблону. Он применяется в том случае, если шаблону нужны не стандартные, в рамках сайта, стили. Файл style.css подключается автоматически, если он есть в папке шаблона. Этот файл может отсутствовать.
  • Файл script.js, который определяет подключает ява-скрипты, необходимые данному шаблону, добавлением строки типа <script src=".../script.js" type="text/javascript"></script>. Файл script.js подключается автоматически, если он есть в папке шаблона. Этот файл может отсутствовать.
  • Файл .description.php, который содержит название и описание шаблона для редактора. Этот файл может отсутствовать.
  • Файл .parameters.php, который содержит описание входных параметров шаблона для редактора. Этот файл может отсутствовать.
  • Файлы название_страницы.ext, который являются шаблонами страниц комплексного компонента. Расширение ext зависит от того, какой движок шаблонизации нужно подключать. По умолчанию расширение равно php. Для каждой страницы комплексного компонента должен присутствовать файл название_страницы.ext.
  • Шаблоны простых компонентов, которые входят в состав комплексного. Эти шаблоны располагаются в папках вида /пространство_имен/название_простого_компонента/ относительно папки шаблона комплексного компонента.
  • Любые другие папки и файлы с ресурсами, необходимыми шаблону компонента. Например, папка image, содержащая изображения, необходимые шаблону.

Простые компоненты, входящие в состав комплексного, подключаются на шаблонах страниц комплексного компонента.


Модификация результата result_modifier.php

Компоненты 2.0::Модификация результата result_modifier.php

Если в папке шаблона есть файл result_modifier.php, то он вызывается перед подключением шаблона. В этом файле можно изменить результат работы компонента произвольным образом.

В файле result_modifier.php можно запросить дополнительные данные и занести их в массив результатов работы компонента $arResult. Это может оказаться полезным, если требуется вывести на экран какие-либо дополнительные данные, но не хочется кастомизировать компонент и отказываться от его поддержки и обновлений.

В файле result_modifier.php можно переформатировать результат работа компонента $arResult для более удобного использования в шаблоне.


Поиск шаблона компонента

Компоненты 2.0::Поиск шаблона компонента

Применяется следующий алгоритм поиска подходящего шаблона для компонента.

  1. Берется папка /bitrix/templates/текущий_шаблон_сайта/components/. В этой папке в пути /пространство_имен_компонента/название_компонента/ проверяется последовательно наличие файла или папки с именем шаблона. Если таковых нет, то проверяется наличие файла имя_шаблона.ext, где в качестве ext берутся последовательно все доступные расширения всех установленых на сайте движков шаблонизации. Если шаблон найден, то алгоритм завершается.
  2. Если на шаге 1 шаблон не найден, то берется папка /bitrix/templates/.default/components/. И применяется алгоритм, описанный в шаге 1. Если шаблон найден, то алгоритм завершается.
  3. Если на шаге 2 шаблон не найден, то производится поиск среди системных (т.е. поставляемых с компонентом) шаблонов.

Если имя шаблона не задано, то ищется шаблон с именем «.default».

Если шаблон задан именем папки, то в случае простого компонента в этой папке ищется файл template.ext, а в случае комплексного - название_страницы.ext. Расширение ext сначала принимается равным php, а затем расширениям других доступных на сайте движков шаблонизации.

Например, требуется показать компонент «bitrix:catalog.list» с помощью шаблона «table». Пусть на сайте, кроме стандартного движка шаблонизации (файлы с расширением php), доступен так же движок Smarty (файлы с расширением tpl). Система проверит сначала папку /bitrix/templates/текущий_шаблон_сайта/components/bitrix/catalog.list/ на наличие файла или папки с именем table. Если таковых нет, система проверит указанную выше папку на наличие файлов table.php и table.tpl. Если ничего не найдено, система изучит папки /bitrix/templates/.default/components/bitrix/catalog.list/ и /bitrix/components/bitrix/catalog.list/templates/.

Если папка компонента найдена, в этой папке сначала ищется файл template.php, а если template.php не найден, ищется template.tpl. Если шаблон задан в виде «table/template.php», то сразу берется указанный файл.

Если простой компонент вызывается в составе комплексного, то шаблон простого компонента сначала ищется в составе шаблона комплексного компонента, а потом (если не найден) в собственных шаблонах.


Пользовательские движки шаблонизации

Компоненты 2.0::Пользовательские движки шаблонизации

Компоненты могут работать с любыми движками шаблонизации, которые могут быть подключены их PHP. Для того, чтобы добавить новый движок шаблонизации на сайт, необходимо определить (или дополнить) глобальную переменную $arCustomTemplateEngines в файле /bitrix/php_interface/init.php. В этой переменной содержится ассоциативный массив, каждый элемент которого имеет вид:

"код_шаблонизатора" => array(
    "templateExt" => array("расширение1"[, "расширение2"...]),
    "function" => "имя_функции_подключения_движка"
    )
где:
  • "код_шаблонизатора" - произвольное уникальное в рамках сайта слово;
  • "расширениеN" - расширение файла, который должен обрабатываться этим движком шаблонизации;
  • "имя_функции_подключения_движка" - имя функции, которая будет вызываться, если шаблон компонента имеет указанное расширение. Функцию можно разместить в этом же файле /bitrix/php_interface/init.php.

Например, если на сайте, кроме стандартного движка шаблонизации (PHP), требуется использовать Smarty, то в файл /bitrix/php_interface/init.php необходимо добавить следующий код:

global $arCustomTemplateEngines;
$arCustomTemplateEngines = array(
    "smarty" => array(
        "templateExt" => array("tpl"),
        "function" => "SmartyEngine"
    ),
);

Тогда, при подключении шаблона с расширением tpl, будет запускаться не стандартный движок PHP, а функция SmartyEngine, которая должна подключить движок Smarty.

Синтаксис функций подключения движков:

function имя_функции_подключения_движка($templateFile,
                                        $arResult,
                                        $arParams,
                                        $arLangMessages,
                                        $templateFolder,
                                        $parentTemplateFolder,
                                        $template)
где:
  • $templateFile – путь к файлу шаблона относительно корня сайта;
  • $arResult – массив результатов работы компонента;
  • $arParams – массив входных параметров компонента;
  • $arLangMessages – массив языковых сообщений (переводов) шаблона;
  • $templateFolder – путь к папке шаблона относительно корня сайта (если шаблон лежит не в папке, то эта переменная пуста);
  • $parentTemplateFolder - путь относительно корня сайта к папке шаблона комплексного компонента, в составе которого подключается данный компонент (если компонент подключается самостоятельно, то эта переменная пуста);
  • $template – объект шаблона.

Код функции подключения движка шаблонизации зависит от подключаемого движка.

Пример подключения движка Smarty

В файл /bitrix/php_interface/init.php необходимо добавить код:

global $arCustomTemplateEngines;
$arCustomTemplateEngines = array(
    "smarty" => array(
        "templateExt" => array("tpl"),
        "function" => "SmartyEngine"
    )
);

function SmartyEngine($templateFile,
                      $arResult,
                      $arParams,
                      $arLangMessages,
                      $templateFolder,
                      $parentTemplateFolder,
                      $template)
{
    if (!defined("SMARTY_DIR"))
        define("SMARTY_DIR", "<абсолютный путь к движку Smarty>/libs/");

    require_once('<абсолютный путь к движку Smarty>/libs/Smarty.class.php');

    $smarty = new Smarty;

    $smarty->compile_dir = "<абсолютный путь к движку Smarty>/templates_c/";
    $smarty->config_dir = "<абсолютный путь к движку Smarty>/configs/";
    $smarty->template_dir = "<абсолютный путь к движку Smarty>/templates/";
    $smarty->cache_dir = "<абсолютный путь к движку Smarty>/cache/";

    $smarty->compile_check = true;
    $smarty->debugging = false;

    $smarty->assign("arResult", $arResult);
    $smarty->assign("arParams", $arParams);
    $smarty->assign("MESS", $arLangMessages);
    $smarty->assign("templateFolder", $templateFolder);
    $smarty->assign("parentTemplateFolder", $parentTemplateFolder);

    $smarty->display($_SERVER["DOCUMENT_ROOT"].$templateFile);
}

Строку "<абсолютный путь к движку Smarty>" нужно везде заменить на абсолютный путь к системе Smarty. Подробности по установке Smarty на сайт содержатся в его справочной системе.

В массиве $arCustomTemplateEngines регистрируется Smarty. В функции SmartyEngine инициализируются его параметры в соответствии с требованиями Smarty (см. систему помощи Smarty). Далее, в Smarty передаются переменные результатов работы компонента, входных параметров, языковых сообщений и т.д. В конце вызывается метод обработки и показа шаблона Smarty.

Это упрощённый пример с акцентом на подключении. Для реального сайта он может быть изменен под конкретные нужды, могут быть задействованы вспомогательные механизмы Smarty типа фильтров и т.п. Например, для того, чтобы не создавать объект Smarty при каждом подключении шаблона, можно изменить код функции SmartyEngine следующим образом:

global $smarty;
$smarty = null;

function SmartyEngine($templateFile,
                      $arResult,
                      $arParams,
                      $arLangMessages,
                      $templateFolder,
                      $parentTemplateFolder,
                      $template)
{
    if (!defined("SMARTY_DIR"))
        define("SMARTY_DIR", "<абсолютный путь к движку Smarty>/libs/");

    global $smarty;
    if (!isset($smarty) || !is_object($smarty))
    {
        require_once('<абсолютный путь к движку Smarty>/libs/Smarty.class.php');

        $smarty = new Smarty;

        $smarty->compile_dir = "<абсолютный путь к движку Smarty>/templates_c/";
        $smarty->config_dir = "<абсолютный путь к движку Smarty>/configs/";
        $smarty->template_dir = "<абсолютный путь к движку Smarty>/templates/";
        $smarty->cache_dir = "<абсолютный путь к движку Smarty>/cache/";

        $smarty->compile_check = true;
        $smarty->debugging = false;
    }
    else
    {
        $smarty->clear_all_assign();
    }

    $smarty->assign("arResult", $arResult);
    $smarty->assign("arParams", $arParams);
    $smarty->assign("MESS", $arLangMessages);
    $smarty->assign("templateFolder", $templateFolder);
    $smarty->assign("parentTemplateFolder", $parentTemplateFolder);

    $smarty->display($_SERVER["DOCUMENT_ROOT"].$templateFile);
}

Пример подключения движка XML/XSLT

global $arCustomTemplateEngines;
$arCustomTemplateEngines = array(
    "xslt" => array(
        "templateExt" => array("xsl"),
        "function" => "XSLTEngine"
    ),
);

function CreateXMLFromArray($xDoc, $xNode, $ar)
{
    foreach($ar as $key=>$val)
    {
        if(!is_string($key) || strlen($key)<=0)
            $key = "value";

        $xElement = $xDoc->createElement($key);
        if(is_array($val))
        {
            CreateXMLFromArray($xDoc, $xElement, $val);
        }
        else
        {
            $xElement->appendChild($xDoc->createTextNode(iconv(SITE_CHARSET, "utf-8", $val)));
        }
        $xNode->appendChild($xElement);
    }
    return $xNode;
}

function XSLTEngine($templateFile,
                    $arResult,
                    $arParams,
                    $arLangMessages,
                    $templateFolder,
                    $parentTemplateFolder,
                    $template)
{
    $arResult["PARAMS"] = array(
        "templateFolder" => $templateFolder,
        "parentTemplateFolder" => $parentTemplateFolder,
        "arParams" => $arParams,
        "arLangMessages" => $arLangMessages
    );

    $xDoc = new DOMDocument("1.0", SITE_CHARSET);
    $xRoot = $xDoc->createElement('result');
    CreateXMLFromArray($xDoc, $xRoot, $arResult);
    $xDoc->appendChild($xRoot);

    $xXsl = new DOMDocument();
    $xXsl->load($_SERVER["DOCUMENT_ROOT"].$templateFile);

    $xProc = new XSLTProcessor;
    $xProc->importStyleSheet($xXsl);

    echo $xProc->transformToXML($xDoc);
}


Человекопонятные URL

Компоненты 2.0::Человекопонятные URL

В комплексные компоненты встроена функция генерации ЧПУ (т.н. человекопонятные URL). Оригинальное английское название таких ссылок — SEF URL (Search Engines Friendly URL).

У комплексного компонента всегда есть входной параметр SEF_MODE, который может принимать значения Y и N.

Если параметр SEF_MODE равен N - значит, компонент работает с физическими ссылками и все параметры передает через стандартные параметры HTTP запроса. Например:

/fld/cat.php?IBLOCK_ID=12&SECTION_ID=371

Если параметр SEF_MODE равен Y, компонент генерирует и обрабатывает ссылки на основании шаблонов. Например, он может понять и обработать ссылку:

/catalog/section/371.php?IBLOCK_ID=12

даже если сам он лежит в файле /fld/cat.php.

Если параметр SEF_MODE равен Y, то у компонента должен так же присутствовать параметр SEF_FOLDER, который должен содержать путь до папки, с которой работает компонент. Этот путь может как совпадать с физическим путём, так и не совпадать. Например, в компоненте «bitrix:catalog», подключенном в файле /fld/cat.php, могут быть установлены параметры SEF_MODE = Y и SEF_FOLDER=/catalog/. Тогда компонент будет откликаться на запросы по пути /catalog/.... По умолчанию редактор должен устанавливать текущий физический путь к редактируемому файлу.

У комплексного компонента, который может работать в режиме SEF, должен быть определён набор шаблонов путей по умолчанию. Например, в комплексном компоненте «bitrix:catalog» может быть определён следующий массив:

$arDefaultUrlTemplatesSEF = array(
    "list" => "index.php",
    "section" => "section.php?IBLOCK_ID=#IBLOCK_ID#&SECTION_ID=#SECTION_ID#",
    "element" => "element.php?ELEMENT_ID=#ELEMENT_ID#"
);

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

При сохранении страницы с компонентом, работающим в SEF режиме, в редакторе создаётся или обновляется запись в системе urlrewrite. Например, при сохранении файла /fld/cat.php, в котором лежит компонент «bitrix:catalog», переключенный в SEF режим с параметром SEF_FOLDER=/catalog/, в системе urlrewrite создаётся или обновляется запись типа:

array(
    "CONDITION" => "#^/catalog/#",
    "ID" => "bitrix:catalog",
    "PATH" => "/fld/cat.php"
),

В CONDITION записывается значение параметра SEF_FOLDER, обрамленное символами «#^» и «#», в ID записывается название компонента, а в PATH записывается физический путь к файлу, который сохраняется. Если запись с таким PATH и ID уже есть, что она обновляется, если нет - добавляется.

В run-time при запросе физически не существующей страницы механизм urlrewrite производит поиск соответствующей записи по CONDITION и передает управление на страницу PATH.

Компонент на странице PATH на основании шаблонов путей выясняет запрашиваемую страницу и восстанавливает переменные, спрятанные в пути.

Внимание!
Обязательное требование к набору шаблонов путей данного компонента - уникальность каждого шаблона пути без учета параметров и переменных. Это должно проверяться при сохранении страницы в визуальном редакторе. Другими словами, набор шаблонов путей
"section" => "section/#SECTION_ID#.php?IBLOCK_ID=#IBLOCK_ID#",
"element" => "element/#ELEMENT_ID#.php"
является допустимым, а набор шаблонов путей
"section" => "#SECTION_ID#.php?IBLOCK_ID=#IBLOCK_ID#",
"element" => "#ELEMENT_ID#.php"
допустимым не является.


Псевдонимы входящих переменных

Компоненты 2.0::Псевдонимы входящих переменных

Каждый компонент имеет набор переменных, в которых он принимает извне коды или другие атрибуты запрашиваемых данных. Например, компонент bitrix:catalog.section имеет переменные IBLOCK_ID и SECTION_ID, в которых он принимает и обрабатывает коды каталога и группы товаров соответственно.

Все компоненты, которые входят в состав комплексного компонента, должны иметь единообразный набор переменных. Например, комплексный компонент bitrix:catalog и все обычные компоненты (bitrix:catalog.list, bitrix:catalog.section и т.д.), которыми он управляет, работают с переменными IBLOCK_ID, SECTION_ID, ELEMENT_ID и пр.

Если пользователь при размещении комплексного компонента на странице хочет переопределить переменные компонента, то он среди входящих параметров компонента должен задать параметр VARIABLE_ALIASES.

При подключении компонента в режиме SEF этот параметр должен имет вид:

"VARIABLE_ALIASES" => array(
    "list" => array(),
    "section" => array(
        "IBLOCK_ID" => "BID",
        "SECTION_ID" => "ID"
    ),
    "element" => array(
        "SECTION_ID" => "SID",
        "ELEMENT_ID" => "ID"
    ),
)

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

При подключении компонента не в режиме SEF этот параметр должен иметь вид:

"VARIABLE_ALIASES" => array(
    "IBLOCK_ID" => "BID",
    "SECTION_ID" => "GID",
    "ELEMENT_ID" => "ID",
)

Пример 1

Пусть требуется, чтобы компонент bitrix:catalog, лежащий в файле /fld/cat.php, работал с путями:

/catalog/index.php (для списка каталогов)
/catalog/section/код_группы.php?ID=код_каталога (для группы товаров)
/catalog/product/код_товара.php?ID=код_группы (для детальной информации о товаре)

Во входящих параметрах подключения компонента должны быть установлены следующие параметры:

"SEF_MODE" => "Y",
"SEF_FOLDER" => "/catalog/",
"SEF_URL_TEMPLATES" => array(
    "list" => "index.php",
    "section" => "section/#SECTION_ID#.php?ID=#IBLOCK_ID#",
    "element" => "element/#ELEMENT_ID#.php?ID=#SECTION_ID#"
),
"VARIABLE_ALIASES" => array(
    "list" => array(),
    "section" => array(
        "IBLOCK_ID" => "ID"
    ),
    "element" => array(
        "SECTION_ID" => "ID",
    ),
)

Пример 2

Пусть требуется, чтобы компонент bitrix:catalog, лежащий в файле /fld/cat.php, работал с путями

/fld/cat.php (для списка каталогов)
/fld/cat.php?BID=код_каталога&SID=код_группы (для группы товаров)
/fld/cat.php?ID=код_товара&SID=код_группы (для детальной информации о товаре)

Во входящих параметрах подключения компонента должны быть установлены следующие параметры:

"SEF_MODE" => "N",
"VARIABLE_ALIASES" => array(
    "IBLOCK_ID" => "BID",
    "SECTION_ID" => "SID",
    "ELEMENT_ID" => "ID",
)


HTTP POST запросы

Компоненты 2.0::HTTP POST запросы

Если на сайте не существующие страницы обрабатываются с помощью опции ErrorDocument (ErrorDocument 404 /404.php), то при отправке HTTP POST запроса на несуществующую страницу данные POST запроса будут потеряны. Поэтому, такие запросы нужно направлять на скрипты, которые физически сущестуют.

Один из способов организации ЧПУ в компонентах 2.0 предполагает использование опции ErrorDocument. Для компонентов 2.0 существует унифицированное решение, которое при написании компонентов и шаблонов компонентов позволяет не заботиться о том, осуществляется ли поддержка ЧПУ с помощью опции ErrorDocument или mod_rewrite.

При написании в шаблонах компонентов форм, отправляющих данные методом POST, в качестве action необходимо указывать константу POST_FORM_ACTION_URI:

<form method="post" action="<?=POST_FORM_ACTION_URI?>">
    * * *
</form>

В этом случае при работе с использованием опции ErrorDocument POST-запрос будет направлен на физически существующий скрипт, а в остальных случаях - по текущему адресу. При этом для компонента не будет разницы, вызван ли он POST- или GET-запросом. Все необходимые переменные будут соответствующим образом установлены.


Введение

Компонент является частью того или иного модуля и представляет из себя логически завершенный код, хранящийся в одном файле, принимающий ряд параметров, выполняющий ряд действий и выводящий какой либо результат (например, в виде HTML кода).

В понятие "компонент" входят следующие элементы:

  • основной файл - PHP скрипт, реализующий логику компонента
  • языковые файлы - используются для представления результата на различных языках
  • описание - используется HTML редактором для визуального управления компонентом и его параметрами

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


Основной файл компонента

Компоненты 1.0::Основной файл компонента

В этом разделе

  • Что это такое
  • Подключение
  • Создание
  • Дополнительные ссылки
    •

    Что это такое

    Основной файл компонента - это PHP файл реализующий логику компонента. В свою очередь основной файл может использовать языковые файлы для перевода своих сообщений на различные языки.

    Подключение

    Подключение компонента осуществляется через подключение основного файла при помощи функции CMain::IncludeFile:

    • В первом параметре данной функции необходимо указать путь к основному файлу компонента относительно нижеследующих каталогов в порядке убывания приоритета:
      1. /bitrix/templates/ID текущего шаблона сайта/ - каталог с текущим шаблоном сайта
      2. /bitrix/templates/.default/ - каталог с шаблоном сайта используемым по умолчанию
      3. /bitrix/modules/ID модуля/install/templates/ - каталог модуля
      Таким образом у компонента может быть несколько копий основного файла, но только одна из этих копий будет выбрана для подключения в тот или иной момент. Подобная схема позволяет:
      1. создавать уникальные для каждого шаблона сайта наборы компонент
      2. создавать общие для всех шаблонов сайта наборы компонент
      3. создавать стандартный набор компонент для каждого модуля, пополняя его через систему обновлений
    • Во втором параметре данной функции необходимо указать массив параметров передаваемых в компонент. Подробнее см. "Особенности создания".

    Пример подключения компонента
    <?
// компонент выводящий детально элемент инфо-блока
$APPLICATION->IncludeFile(
    "iblock/catalog/element.php",              // путь к основному файлу компонента
    Array(                                     // массив параметров компонента

        "IBLOCK_TYPE"       => "catalog",      // Тип инфо-блока
        "IBLOCK_ID"         => "21",           // Инфо-блок
        "ELEMENT_ID"        => $_REQUEST["ID"],// ID элемента
        "SECTION_URL"       => "section.php",  // URL ведущий на страницу с содержимым раздела
        "arrFIELD_CODE"     => Array(          // Поля
             "DETAIL_TEXT",
             "DETAIL_PICTURE"),
        "arrPROPERTY_CODE"  => Array(          // Свойства
             "YEAR",
             "STANDBY_TIME",
             "TALKTIME",
             "WEIGHT",
             "STANDART",
             "SIZE",
             "BATTERY",
             "SCREEN",
             "WAP",
             "VIBRO",
             "VOICE",
             "PC",
             "MORE_PHOTO",
             "MANUAL"),
        "CACHE_TIME"        => "3600",         // Время кэширования (сек.)

        )
    );
?>

    Создание

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

    1. Первый способ заключается в использовании второго параметра функции CMain::IncludeFile. В этом параметре можно передавать ассоциативный массив, который в основном файле компонента будет доступен под именем $arParams. Помимо этого, массив $arParams будет преобразован в набор переменных с именами равными ключам и значениями равными значениям соответствующих ключей этого массива (подробнее см. стандартную PHP функцию extract).
    2. Второй способ заключается в передаче параметров в компонент через глобальные массивы переменных. Данный способ передачи параметров в компонент не отличается от подобной передачи параметров в обычную PHP функцию. Вы можете использовать как стандартные PHP массивы
      • $GLOBALS
      • $_REQUEST
      • $_GET
      • $_POST
      • $_SERVER
      • и т.д.
      так и свои собственные массивы, предварительно объявляя их глобальными перед подключением компонента.

      По умолчанию глобальными в функции CMain::IncludeFile объявлены следующие переменные:

      • $APPLICATION
      • $USER
      • $DB
      • $MESS
      • $DOCUMENT_ROOT

    Особенность, связанная с сужением области видимости переменных внутри основного файла компонента, накладывает определённые условия на использование некоторых функций. Это касается функцией, результатом работы которых является инициализация глобальных переменных. Если в дальнейшем мы хотим эти глобальные переменные использовать внутри основного файла компонента, то мы должны к ним обращаться либо через стандартный PHP массив $GLOBALS, либо объявлять их глобальными с помощью стандартной PHP директивы global, перед их использованием. В основном это касается таких функций как:

    • InitFilterEx
    • DelFilterEx
    • InitSorting
    • CDataBase::InitTableVarsForEdit
    • CDataBase::PrepareFields
    • CDBResult::NavNext

    Пример основного файла компонента
    <?
/**************************************************************************
                Компонент для вывода элемента инфо-блока
                iblock/catalog/element.php
***************************************************************************/

if (CModule::IncludeModule("iblock")):

    IncludeTemplateLangFile(__FILE__);

    /*************************************************************************
                Инициализируем начальные параметры компонента
    *************************************************************************/

    /*
    $IBLOCK_TYPE        = $arParams["IBLOCK_TYPE"];       // тип инфо-блока
    $IBLOCK_ID          = $arParams["IBLOCK_ID"];         // ID инфо-блока
    $ELEMENT_ID         = $arParams["ELEMENT_ID"];        // ID элемента
    $SECTION_URL        = $arParams["SECTION_URL"];       // URL ведущий на страницу с содержимым раздела
    $arrFIELD_CODE      = $arParams["arrFIELD_CODE"];     // массив кодов полей
    $arrPROPERTY_CODE   = $arParams["arrPROPERTY_CODE"];  // массив кодов свойств
    $CACHE_TIME         = $arParams["CACHE_TIME"];        // время кэширования (сек.)
    */

    $arrFIELD_CODE = (is_array($arrFIELD_CODE)) ? $arrFIELD_CODE : array();
    $arrPROPERTY_CODE = (is_array($arrPROPERTY_CODE)) ? $arrPROPERTY_CODE : array();
    $ELEMENT_ID = intval($ELEMENT_ID);

    /*************************************************************************
                                Работа с кэшем
    *************************************************************************/

    $obCache = new CPHPCache;
    $CACHE_ID = __FILE__.md5(serialize($arParams).$USER->GetGroups());
    if($obCache->InitCache($CACHE_TIME, $CACHE_ID, "/"))
    {
        $arVars = $obCache->GetVars();
        $ELEMENT_NAME    = $arVars["ELEMENT_NAME"];
        $IBLOCK_ID        = $arVars["IBLOCK_ID"];
        $SECTION_ID        = $arVars["SECTION_ID"];
        $SECTION_NAME    = $arVars["SECTION_NAME"];
        $KEYWORDS        = $arVars["KEYWORDS"];
        $DESCRIPTION    = $arVars["DESCRIPTION"];
        $arrPath        = $arVars["arrPath"];
        $found = "Y";
    }
    else
    {
        if ($ELEMENT_ID>0)
        {
            $arSelect = array(
                "ID",
                "NAME",
                "IBLOCK_ID",
                "IBLOCK_SECTION_ID"
                );
            if ($rsElement = GetIBlockElementListEx($IBLOCK_TYPE, false, false, array(), false, array("ID" => $ELEMENT_ID), $arSelect))
            {
                if ($obElement = $rsElement->GetNextElement())
                {
                    $found = "Y";
                    $arElement = $obElement->GetFields();
                    $arProperty = $obElement->GetProperties();
                    $KEYWORDS = $arProperty["KEYWORDS"]["VALUE"];
                    $DESCRIPTION = $arProperty["DESCRIPTION"]["VALUE"];
                    $ELEMENT_NAME = $arElement["NAME"];
                    $IBLOCK_ID = $arElement["IBLOCK_ID"];
                    $SECTION_ID = $arElement["IBLOCK_SECTION_ID"];
                    if ($rsSection = CIBlockSection::GetByID($SECTION_ID))
                    {
                        $arSection = $rsSection->Fetch();
                        $SECTION_NAME = $arSection["NAME"];
                    }
                }
            }

            $arrPath = array();
            $rsPath = GetIBlockSectionPath($IBLOCK_ID, $SECTION_ID);
            while($arPath=$rsPath->GetNext()) $arrPath[] = array("ID" => $arPath["ID"], "NAME" => $arPath["NAME"]);
        }
    }

    // если элемент найден то
    if ($found=="Y"):

        $APPLICATION->SetPageProperty("keywords", $KEYWORDS);
        $APPLICATION->SetPageProperty("description", $DESCRIPTION);

        CIBlock::ShowPanel($IBLOCK_ID, $ELEMENT_ID, $SECTION_ID, $IBLOCK_TYPE);
        $APPLICATION->SetTitle($ELEMENT_NAME);
        if (is_array($arrPath))
        {
            while(list($key, $arS) = each($arrPath))
            {
                if ($SECTION_ID==$arS["ID"]) $SECTION_NAME = $arS["NAME"];
                $APPLICATION->AddChainItem($arS["NAME"], $SECTION_URL."SECTION_ID=".$arS["ID"]);
            }
        }

        CIBlockElement::CounterInc($ELEMENT_ID);

        if($obCache->StartDataCache()):

            $arSelect = array(
                "ID",
                "IBLOCK_ID",
                "IBLOCK_SECTION_ID",
                "DETAIL_TEXT_TYPE",
                "PREVIEW_TEXT_TYPE",
                "DETAIL_PICTURE",
                "PREVIEW_PICTURE",
                );
            $arSelect = array_merge($arSelect, $arrFIELD_CODE);
            if ($rsElement = GetIBlockElementListEx($IBLOCK_TYPE, false, false, array(), false, array("ID" => $ELEMENT_ID), $arSelect)) :

                if ($obElement = $rsElement->GetNextElement()) :

                    $arElement = $obElement->GetFields();
                    $arProperty = $obElement->GetProperties();

                    /****************************************************************
                                            HTML форма
                    ****************************************************************/
                    ?>
                    <table width="70%" border="0" cellspacing="0" cellpadding="7">
                        <tr>
                            <?
                            if (in_array("PREVIEW_PICTURE", $arrFIELD_CODE))
                            {
                                $image = intval($arElement["PREVIEW_PICTURE"])>0 ? $arElement["PREVIEW_PICTURE"] : $arElement["DETAIL_PICTURE"];
                            }
                            if (in_array("DETAIL_PICTURE", $arrFIELD_CODE))
                            {
                                $image = intval($arElement["DETAIL_PICTURE"])>0 ? $arElement["DETAIL_PICTURE"] : $arElement["PREVIEW_PICTURE"];
                            }
                            ?>
                        </tr>
                    </table>

                    <?if (strlen($arElement["PREVIEW_TEXT"])>0):?>
                    <font class="text"><p><?=$arElement["PREVIEW_TEXT"]?></p></font>
                    <?endif;?>

                    <?if (strlen($arElement["DETAIL_TEXT"])>0):?>
                    <font class="text"><p><?
                    echo ($arElement["DETAIL_TEXT_TYPE"]=="html") ? $arElement["DETAIL_TEXT"] : TxtToHTML($arElement["~DETAIL_TEXT"]);
                    ?></p></font>
                    <?endif;

                endif;
            endif;

            $obCache->EndDataCache(array(
                "ELEMENT_NAME"    => $ELEMENT_NAME,
                "IBLOCK_ID"        => $IBLOCK_ID,
                "SECTION_ID"    => $SECTION_ID,
                "SECTION_NAME"    => $SECTION_NAME,
                "KEYWORDS"        => $KEYWORDS,
                "DESCRIPTION"    => $DESCRIPTION,
                "arrPath"        => $arrPath
                ));
        endif;
    else:
            ShowError(GetMessage("CATALOG_ELEMENT_NOT_FOUND"));
    endif;
endif;
?>

    Дополнительные ссылки

    • CMain::IncludeFile


Языковые файлы компонента

Компоненты 1.0::Языковые файлы компонента

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

  1. Сначала языковой файл будет искаться в каталоге

    /bitrix/templates/ID текущего шаблона сайта/lang/ID языка/путь к компоненту

  2. Если файл не найден, он будет искаться в каталоге

    /bitrix/templates/.default/lang/ID языка/путь к компоненту

  3. Затем если файл не найден, он будет искаться в каталоге

    /bitrix/modules/ID модуля/install/templates/lang/ID языка/путь к компоненту

Определение термина "путь к компоненту" можно посмотреть здесь.

См. также

  • Что такое "Языковые файлы"
  • IncludeTemplateLangFile


Описание компонента

Компоненты 1.0::Описание компонента

В этом разделе

  • Что это такое
  • Структура
  • Пример
  • Языковые файлы
  • Дополнительно
    •

    Что это такое

    Для визуального управления компонентом и его параметрами в HTML редакторе необходимо создать так называемое описание компонента.

    Описание компонента представляет из себя PHP файл с именем .description.php, который может располагаться в одном из следующих каталогов (или их подкаталогах):

    • /bitrix/templates/.default/ID модуля/ - каталог с шаблоном сайта используемым по умолчанию
    • /bitrix/modules/ID модуля/install/templates/ID модуля/ - каталог модуля

    Структура файла .description.php

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

    • $sSectionName - заголовок модуля для выпадающего списка модулей
    • $iSort - сортировка заголовка модуля в выпадающем списке
    • $arCurrentValues - массив текущих значений параметров компонента
    • $arTemplateDescription - массив описывающий список компонентов и их параметров, со следующей структурой:

Array
(
  [уникальный ID разделителя 1] => массив описывающий разделитель 1:
    Array
      (
        ["SEPARATOR"] => "Y"
        ["NAME"] => заголовок разделителя
        ["DESCRIPTION"] => описание разделителя
      )
  [относительный путь к компоненту 1] => массив описывающий компонент 1 и его параметры:
    Array
      (
        ["PARENT"] => ID разделителя в группу которого попадает данный компонент
        ["NAME"] => заголовок компонента (обязательный)
        ["DESCRIPTION"] => описание компонента
        ["ICON"] => путь от корня к иконке компонента
        ["PARAMS"] => массив описывающий множество параметров компонента:
          Array
            (
              [код параметра 1] => массив описывающий параметр 1:
                Array
                  (
                    ["NAME"] => название параметра

                    ["TYPE"] => тип поля ввода для значения параметра, допустимые значения:
                      "STRING" - однострочное текстовое поле
                      "LIST" - список

                    ["SIZE"] => если TYPE="LIST" (список), то здесь можно задать
                      количество строк списка видимых без скролирования

                    ["VALUES"] => если TYPE="LIST" (список), то здесь необходимо указать
                      массив элементов этого списка в виде:
                      Array
                        (
                          ["код элемента 1"] => значение элемента 1
                          ["код элемента 2"] => значение элемента 2
                          ["код элемента 3"] => значение элемента 3
                          ...
                        )
                    ["ADDITIONAL_VALUES"] => если TYPE="LIST" (список), то значение данного
                       параметра равное "N" отключает дополнительное поле для ручного ввода
                       значения списка
                    ["MULTIPLE"] => если равно "Y", то значение параметра
                      это массив с произвольным количество элементов
                    ["COLS"] => количество столбцов в полях для ввода
                    ["ROWS"] => количество строк в полях для ввода
                    ["DEFAULT"] => значение параметра по умолчанию
                    ["CNT"] => количество полей для ввода значений параметра компонента
                    ["REFRESH"] => если равно "Y", то рядом с полем ввода параметра будет
                      доступна кнопка перезагружающая страницу с параметрами компонента
                      (обычно используется когда значения параметров компонента зависят
                      друг от друга, например, при выборе типа инфо-блока меняется список
                      доступных блоков)
                  )
              [код параметра 2] => массив описывающий параметр 2
              [код параметра 3] => массив описывающий параметр 3
              ...
            )
      )
  [относительный путь к компоненту 2] => массив описывающий компонент 2 и его параметры
  [относительный путь к компоненту 3] => массив описывающий компонент 3 и его параметры
  [уникальный ID разделителя 2] => массив описывающий разделитель 2
  ...
)
      В вышеописанной структуре:
      • уникальный ID разделителя - произвольный набор символов уникальный в рамках всех компонентов выбранного модуля
      • относительный путь к компоненту - путь к основному файлу компонента относительно каталога в котором находится данный файл .description.php

    Пример файла .description.php

    Иногда возникает необходимость в дополнительном программировании файла .description.php. Например, когда необходимо получить список инфо-блоков или список веб-форм. В этом случае необходимо подчеркнуть, что данный файл не скреплен никакими рамками и ограничениями. В нем могут использоваться все доступные модули и функции системы.

    <?
// файл /bitrix/modules/iblock/install/templates/iblock/catalog/.description.php

IncludeTemplateLangFile(__FILE__);
if (!CModule::IncludeModule("iblock")) return;

/**************************************************************************************
                    Инициализация необходимых массивов
**************************************************************************************/

// получим массив типов инфо-блоков - $arIblockType
$rsType = CIBlockType::GetList(array("sort"=>"asc"), array("ACTIVE"=>"Y"));
while ($arr=$rsType->Fetch())
{
    if($ar=CIBlockType::GetByIDLang($arr["ID"], LANGUAGE_ID))
        $arIblockType[$arr["ID"]] = "[".$arr["ID"]."] ".$ar["NAME"];
}

// получим массив инфо-блоков - $arIblock
$rsIblock = CIBlock::GetList(
    Array("sort" => "asc"),
    Array("TYPE" => $arCurrentValues["IBLOCK_TYPE"], "ACTIVE"=>"Y")
    );
while($arr=$rsIblock->Fetch()) $arIblock[$arr["ID"]] = "[".$arr["ID"]."] ".$arr["NAME"];

// получим массив свойств инфо-блоков - $arProperty
$rsProp = CIBlockProperty::GetList(
    Array("sort"=>"asc", "name"=>"asc"),
    Array("ACTIVE"=>"Y", "IBLOCK_ID"=>$arCurrentValues["IBLOCK_ID"])
    );
while ($arr=$rsProp->Fetch())
{
    $arProperty[$arr["CODE"]] = "[".$arr["CODE"]."] ".$arr["NAME"];
}

/**************************************************************************************
                    Разделитель "Каталог товаров"
**************************************************************************************/

$arTemplateDescription = Array(
    ".separator" =>
        Array(
            "NAME"        => GetMessage("T_IBLOCK_DESC_CAT"),
            "DESCRIPTION" => "",
            "SEPARATOR"   => "Y",
        )
    );

/**************************************************************************************
                    Детальный просмотр элемента каталога
**************************************************************************************/

$arTemplateDescription["element.php"] = array(
    "PARENT"       => ".separator",
    "NAME"         => GetMessage("IBLOCK_ELEMENT_TEMPLATE_NAME"),
    "DESCRIPTION"  => GetMessage("IBLOCK_ELEMENT_TEMPLATE_DESCRIPTION"),
    "ICON"         => "/bitrix/images/iblock/components/cat_detail.gif",
    "PARAMS" => array(
        "IBLOCK_TYPE" => array(
            "NAME"              => GetMessage("IBLOCK_TYPE"),
            "TYPE"              => "LIST",
            "ADDITIONAL_VALUES" => "Y",
            "VALUES"            => $arIblockType,
            "REFRESH"           => "Y"
            ),
        "IBLOCK_ID" => array(
            "NAME"              => GetMessage("IBLOCK_IBLOCK"),
            "TYPE"              => "LIST",
            "ADDITIONAL_VALUES" => "Y",
            "VALUES"            => $arIblock,
            "REFRESH"           => "Y"
            ),
        "ELEMENT_ID" => array(
            "NAME"              => GetMessage("IBLOCK_ELEMENT_ID"),
            "TYPE"              => "STRING",
            "DEFAULT"           => '={$_REQUEST["ID"]}'
            ),
        "SECTION_URL" => array(
            "NAME"              => GetMessage("IBLOCK_SECTION_URL"),
            "TYPE"              => "STRING",
            "DEFAULT"           => "section.php"
            ),
        "LINK_IBLOCK_TYPE" => array(
            "NAME"              => GetMessage("IBLOCK_LINK_IBLOCK_TYPE"),
            "TYPE"              => "LIST",
            "ADDITIONAL_VALUES" => "Y",
            "VALUES"            => $arIblockType,
            "REFRESH"           => "Y"
            ),
        "arrFIELD_CODE" => array(
            "NAME"              => GetMessage("IBLOCK_FIELD"),
            "TYPE"              => "LIST",
            "MULTIPLE"          => "Y",
            "ADDITIONAL_VALUES" => "N",
            "VALUES" => array(
                "NAME"           => GetMessage("IBLOCK_NAME"),
                "PREVIEW_TEXT"   => GetMessage("IBLOCK_PREVIEW_TEXT"),
                "DETAIL_TEXT"    => GetMessage("IBLOCK_DETAIL_TEXT"),
                "DETAIL_PICTURE" => GetMessage("IBLOCK_DETAIL_PICTURE"),
                )
            ),
        "arrPROPERTY_CODE" => array(
            "NAME"              => GetMessage("IBLOCK_PROPERTY"),
            "TYPE"              => "LIST",
            "MULTIPLE"          => "Y",
            "ADDITIONAL_VALUES" => "N",
            "VALUES"            => $arProperty
            ),
        "CACHE_TIME" => array(
            "NAME"              => GetMessage("IBLOCK_CACHE_TIME"),
            "TYPE"              => "STRING",
            "DEFAULT"           => "3600"
            ),
        )
    );
?>

    Языковые файлы

    Для подключения языковых файлов внутри файла .description.php необходимо пользоваться функцией IncludeTemplateLangFile.

    В вышепредставленном примере файл описания имеет следующий путь:

    /bitrix/modules/iblock/install/templates/iblock/catalog/.description.php.

    В нем языковой файл подключается командой:

    IncludeTemplateLangFile(__FILE__);
    Соответственно языковой файл должен быть один из (в порядке убывания приоритета):
    • /bitrix/templates/ID текущего шаблона сайта/lang/ID языка/iblock/catalog/.description.php
    • /bitrix/templates/.default/lang/ID языка/iblock/catalog/.description.php
    • /bitrix/modules/iblock/install/templates/lang/ID языка/iblock/catalog/.description.php

    Дополнительно

    Обязательным условием описания компонентов является наличие одного из файлов:

    /bitrix/templates/.default/ID модуля/.description.php

    /bitrix/modules/ID модуля/install/templates/ID модуля/.description.php

    В котором будет инициализирована переменная $sSectionName, содержащая заголовок модуля для выпадающего списка модулей в     HTML-редакторе. Если такого файла не окажется, то в выпадающем списке модулей не появится соответствующий пункт.

    Если при модификации параметров компонента возникла необходимость задать PHP код, то сделать можно это конструкцией "={...}".

    Например:

    ={$_REQUEST["BID"]}

    ={(isset($_REQUEST["BID"]) ? $_REQUEST["BID"] : "15")}


Создание раздела панели управления

В данном разделе мы разберем создание раздела панели управления на примере раздела "Подписка".

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

Также дополнительно рассмотрим создание собственных обработчиков закладок в форму добавления/редактирования элементов, а также конфигурацию административного меню модуля.


Конфигурация административного меню модуля

В данном разделе описывается управление главным административным меню.

Основная структура

Для каждого модуля параметры меню задаются файлом /bitrix/каталог_модуля/admin/menu.php. Результатом работы этого файла должен стать описательный массив меню модуля. Возможности API позволяют создать древовидное меню с любым уровнем вложенности, а также, с динамической подгрузкой отдельных ветвей.

Файл menu.php должен вернуть ассоциативный массив следующей структуры:

Ключ | Описание
parent_menu Идентификатор раздела меню. Имеет смысл только для элемента верхнего уровня дерева меню модуля. Может принимать одно из следующих значений:
  • global_menu_content - раздел "Контент"
  • global_menu_services - раздел "Сервисы"
  • global_menu_store - раздел "Магазин"
  • global_menu_statistics - раздел "Веб-аналитика"
  • global_menu_settings - раздел "Настройки"
sort | Относительный "вес" пункта меню для сортировки.
url | Ссылка пункта меню. При переходе пользователем на страницу с таким URL данный пункт меню будет подсвечен.
more_url | Список дополнительных URL, по которым данный пункт меню должен быть подсвечен.
text | Текст ссылки пункта меню.
title | Текст всплывающей подсказки пункта меню.
icon | CSS-класс иконки пункта меню.
page_icon | CSS-класс иконки пункта меню для вывода на странице индекса (класс увеличенной иконки).
module_id | Идентификатор модуля, к которому относится меню.
dynamic | Флаг, показывающий, должна ли ветвь, начинающаяся с текущего пункта, подгружаться динамически.
items_id | Идентификатор ветви меню. Используется для динамического обновления ветви.
items | Список дочерних пунктов меню. Представляет собой массив, каждый элемент которого является ассоциативным массивом аналогичной структуры.

Пример использования

Листинг файла menu.php модуля Веб-форм (простое меню без динамической подгрузки).

<?
IncludeModuleLangFile(__FILE__); // в menu.php точно так же можно использовать языковые файлы

if($APPLICATION->GetGroupRight("form")>"D") // проверка уровня доступа к модулю веб-форм
{
  // сформируем верхний пункт меню
  $aMenu = array(
    "parent_menu" => "global_menu_services", // поместим в раздел "Сервис"
    "sort"        => 100,                    // вес пункта меню
    "url"         => "form_list.php?lang=".LANGUAGE_ID,  // ссылка на пункте меню
    "text"        => GetMessage("FORM_MENU_MAIN"),       // текст пункта меню
    "title"       => GetMessage("FORM_MENU_MAIN_TITLE"), // текст всплывающей подсказки
    "icon"        => "form_menu_icon", // малая иконка
    "page_icon"   => "form_page_icon", // большая иконка
    "items_id"    => "menu_webforms",  // идентификатор ветви
    "items"       => array(),          // остальные уровни меню сформируем ниже.
  );

  // далее выберем список веб-форм и добавим для каждой соответствующий пункт меню
  require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/include.php");
  $z = CForm::GetMenuList(array("LID"=>LANGUAGE_ID));
  while ($zr=$z->GetNext())
  {
    if (strlen($zr["MENU"]) > 0)
    {
      // массив каждого пункта формируется аналогично
      $aMenu["items"][] =  array(
        "text" => $zr["MENU"],
        "url"  => "form_result_list.php?lang=".LANGUAGE_ID."&WEB_FORM_ID=".$zr["ID"],
        "icon" => "form_menu_icon",
        "page_icon" => "form_page_icon",
        "more_url"  => array(
            "form_view.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_list.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_edit.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_print.php?WEB_FORM_ID=".$zr["ID"],
            "form_result_view.php?WEB_FORM_ID=".$zr["ID"]
            ),
        "title" => GetMessage("FORM_RESULTS_ALT")
       );
    }
  }

  // если нам нужно добавить ещё пункты - точно так же добавляем элементы в массив $aMenu["items"]
  // ............

  // вернем полученный список
  return $aMenu;
}
// если нет доступа, вернем false
return false;
?>

Динамическая подгрузка ветвей меню.

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

  1. установить у пункта меню, начинающего динамическую ветвь параметр "dynamic"=>true;
  2. установить у пункта меню, начинающего динамическую ветвь значение параметра "items_id" и идентификатор модуля;
  3. добавить проверку флага "группа элементов открыта" при создании элементов ветви, предполагающие динамическую подгрузку.

Последний пункт представляет собой проверку метода CAdminMenu::IsSectionActive(). Поскольку скрипт, формирующий меню, выполняется в контексте экземпляра класса CAdminMenu, то достаточно осуществить проверку $this->IsSectionActive(), в качестве параметра указав значение параметра "items_id" требуемой ветви.

Приведем в качестве примера то же самое меню модуля Веб-форм, но уже с динамической подгрузкой списка форм:

<?
IncludeModuleLangFile(__FILE__); // в menu.php точно так же можно использовать языковые файлы

if($APPLICATION->GetGroupRight("form")>"D") // проверка уровня доступа к модулю веб-форм
{
  // верхний пункт меню оставим без изменений
  $aMenu = array(
    "parent_menu" => "global_menu_services", // поместим в раздел "Сервис"
    "sort"        => 100,                    // вес пункта меню
    "url"         => "form_list.php?lang=".LANGUAGE_ID,  // ссылка на пункте меню
    "text"        => GetMessage("FORM_MENU_MAIN"),       // текст пункта меню
    "title"       => GetMessage("FORM_MENU_MAIN_TITLE"), // текст всплывающей подсказки
    "icon"        => "form_menu_icon", // малая иконка
    "page_icon"   => "form_page_icon", // большая иконка
    "items_id"    => "menu_webforms",  // идентификатор ветви
    "items"       => array(),          // остальные уровни меню сформируем ниже.
  );

  // сформируем пункты меню, которые будут подгружаться динамически
  $arFormsList = array();
  if (
    method_exists($this, "IsSectionActive") // для поверки совместимости
    &&
    $this->IsSectionActive("menu_webforms_list") // если активна секция меню с идентфикатором "menu_webforms_list"
    ||
    // можно также добавить любые свои условия. например, показывать эту ветвь на всех страницах,
    // где определена константа FORM_MENU_OPEN со значением 1
    defined('FORM_MENU_OPEN') && FORM_MENU_OPEN == 1)
  {

    // далее выполним ту же самую выборку, что и в простом варианте, но элементы будем сохранять в отдельный массив.
    require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/include.php");
    $z = CForm::GetMenuList(array("LID"=>LANGUAGE_ID));
    while ($zr=$z->GetNext())
    {
      if (strlen($zr["MENU"]) > 0)
      {
        // массив каждого пункта формируется аналогично
        $arFormsList[] =  array(
          "text" => $zr["MENU"],
          "url"  => "form_result_list.php?lang=".LANGUAGE_ID."&WEB_FORM_ID=".$zr["ID"],
          "icon" => "form_menu_icon",
          "page_icon" => "form_page_icon",
          "more_url"  => array(
              "form_view.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_list.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_edit.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_print.php?WEB_FORM_ID=".$zr["ID"],
              "form_result_view.php?WEB_FORM_ID=".$zr["ID"]
              ),
          "title" => GetMessage("FORM_RESULTS_ALT")
         );
      }
    }
  }

  // теперь сформируем корень динамической ветви меню. обратите внимание на выделенные параметры.

  $aMenu["items"][] = array(
    "text" => GetMessage("FORM_RESULTS_ALL"),
    "url" => "form_result_list.php?lang=".LANGUAGE_ID,
    "title" => GetMessage("FORM_RESULTS_ALL_ALT"),

    "dynamic" => true,                  // !!!!!!!!!!!!!!!!!!!!!!!!!
    "module_id" => "form",              // !!!!!!!!!!!!!!!!!!!!!!!!!
    "items_id" => "menu_webforms_list", // !!!!!!!!!!!!!!!!!!!!!!!!!
    "items" => $arFormsList,            // !!!!!!!!!!!!!!!!!!!!!!!!!

  );

  // если нам нужно добавить ещё пункты - точно так же добавляем элементы в массив $aMenu["items"]
  // ............

  // вернем полученный список
  return $aMenu;
}
// если нет доступа, вернем false
return false;
?>


Создание списка элементов

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

Принципы работы

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

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

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

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

Начало

Прежде чем присупить к разбору функционала страницы, проведем "предварительную подготовку". Для начала создадим файл /bitrix/modules/subscribe/rubric_admin.php следующей структуры:

<?
// подключим все необходимые файлы:
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_before.php"); // первый общий пролог

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/include.php"); // инициализация модуля
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/prolog.php"); // пролог модуля

// подключим языковой файл
IncludeModuleLangFile(__FILE__);

// получим права доступа текущего пользователя на модуль
$POST_RIGHT = $APPLICATION->GetGroupRight("subscribe");
// если нет прав - отправим к форме авторизации с сообщением об ошибке
if ($POST_RIGHT == "D")
    $APPLICATION->AuthForm(GetMessage("ACCESS_DENIED"));
?>
<?
// здесь будет вся серверная обработка и подготовка данных
?>
<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php"); // второй общий пролог
?>
<?
// здесь будет вывод страницы
?>
<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_admin.php");?>

Это и есть "костяк страницы", обозначенный на схеме.

Далее, создадим языковой файл, например, /bitrix/modules/subscribe/lang/ru/rubric_admin.php для русского языка. В файле будем определять все языковые сообщения в виде элементов массива: $MESS['идентификатор_сообщения'] = "текст_сообщения";

Затем, поскольку с изначальными параметрами установки БУС каталог /bitrix/modules/ недоступен посредством HTTP-протокола, создадим файл /bitrix/admin/rubric_admin.php:

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/admin/rubric_admin.php");
?>

Теперь наш файл доступен по ссылке http://mysite.ru/bitrix/admin/rubric_admin.php.

Фунционал страницы

Как видно из схемы, весь функционал страницы условно можно разделить на несколько составных частей:

  • Обработка и подготовка данных
    • Создание экземпляров необходимых для работы классов
    • Обработка действий над элементами списка
    • Конфигурация и обработка фильтра списка элементов
    • Выборка из БД (если требуется) и подготовка к выводу элементов списка
    • Задание параметров таблицы элементов (в т.ч., сортировка)
  • Вывод данных
    • Конфигурация и вывод административного меню
    • Вывод фильтра
    • Вывод списка

В процессе работы нам потребуются экземпляры следующих классов:

Класс | Описание
CAdminList | Основной класс для работы со списками элементов в административной панели.
CAdminResult | Расширение класса CDBResult, предназначенное для работы со списками элементов в скриптах административных страниц.
CAdminSorting | Работа с сортировками списка.
CAdminFilter | Работа с фильтром списка.
Обработка и подготовка данных

Для начала, создадим экземпляры классов CAdminList и CAdminSorting:

$sTableID = "tbl_rubric"; // ID таблицы
$oSort = new CAdminSorting($sTableID, "ID", "desc"); // объект сортировки
$lAdmin = new CAdminList($sTableID, $oSort); // основной объект списка
Фильтр результатов

В нашем примере фильтр результатов будет состоять из следующих параметров:

  • Поиск по идентификатору рассылки
  • Выборка по активности рассылки
  • Выборка по публикации рассылки
  • Выборка активности рассылки

Предварительная работа с фильтром осуществляется следующим образом:

// проверку значений фильтра для удобства вынесем в отдельную функцию
function CheckFilter()
{
    global $FilterArr, $lAdmin;
    foreach ($FilterArr as $f) global $$f;

    /*
       здесь проверяем значения переменных $find_имя и, в случае возникновения ошибки,
       вызываем $lAdmin->AddFilterError("текст_ошибки").
    */

    return count($lAdmin->arFilterErrors) == 0; // если ошибки есть, вернем false;
}

// опишем элементы фильтра
$FilterArr = Array(
    "find_id",
    "find_lid",
    "find_active",
    "find_visible",
    "find_auto",
    );

// инициализируем фильтр
$lAdmin->InitFilter($FilterArr);

// если все значения фильтра корректны, обработаем его
if (CheckFilter())
{
    // создадим массив фильтрации для выборки CRubric::GetList() на основе значений фильтра
    $arFilter = Array(
        "ID"		=> $find_id,
        "LID"		=> $find_lid,
        "ACTIVE"	=> $find_active,
        "VISIBLE"	=> $find_visible,
        "AUTO"		=> $find_auto,
    );
}
Обработка действий над элементами

Над элементами списка можно совершать два типа действий:

  • Редактирование элементов непосредственно на странице списка
  • Групповые и одиночные действия на элементами

Определить, что произведены действия над элементами списка можно проверив значения CAdminList::EditAction() и CAdminList::GroupAction(). Не забудьте добавить проверку прав в обоих вариантах (в данном случае - проверка наличия прав на запись для модуля подписки - $POST_RIGHT=="W").

Пример:

// сохранение отредактированных элементов
if($lAdmin->EditAction() && $POST_RIGHT=="W")
{
    // пройдем по списку переданных элементов
    foreach($FIELDS as $ID=>$arFields)
    {
        if(!$lAdmin->IsUpdated($ID))
            continue;

        // сохраним изменения каждого элемента
        $DB->StartTransaction();
        $ID = IntVal($ID);
        $cData = new CRubric;
        if(($rsData = $cData->GetByID($ID)) && ($arData = $rsData->Fetch()))
        {
            foreach($arFields as $key=>$value)
                $arData[$key]=$value;
            if(!$cData->Update($ID, $arData))
            {
                $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".$cData->LAST_ERROR, $ID);
                $DB->Rollback();
            }
        }
        else
        {
            $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
            $DB->Rollback();
        }
        $DB->Commit();
    }
}

// обработка одиночных и групповых действий
if(($arID = $lAdmin->GroupAction()) && $POST_RIGHT=="W")
{
    // если выбрано "Для всех элементов"
    if($_REQUEST['action_target']=='selected')
    {
        $cData = new CRubric;
        $rsData = $cData->GetList(array($by=>$order), $arFilter);
        while($arRes = $rsData->Fetch())
            $arID[] = $arRes['ID'];
    }

    // пройдем по списку элементов
    foreach($arID as $ID)
    {
        if(strlen($ID)<=0)
            continue;
           $ID = IntVal($ID);

        // для каждого элемента совершим требуемое действие
        switch($_REQUEST['action'])
        {
        // удаление
        case "delete":
            @set_time_limit(0);
            $DB->StartTransaction();
            if(!CRubric::Delete($ID))
            {
                $DB->Rollback();
                $lAdmin->AddGroupError(GetMessage("rub_del_err"), $ID);
            }
            $DB->Commit();
            break;

        // активация/деактивация
        case "activate":
        case "deactivate":
            $cData = new CRubric;
            if(($rsData = $cData->GetByID($ID)) && ($arFields = $rsData->Fetch()))
            {
                $arFields["ACTIVE"]=($_REQUEST['action']=="activate"?"Y":"N");
                if(!$cData->Update($ID, $arFields))
                    $lAdmin->AddGroupError(GetMessage("rub_save_error").$cData->LAST_ERROR, $ID);
            }
            else
                $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
            break;
        }

    }
}
Выборка элементов

Выборка списка элементов ничем не отличается от выборки в компоненте или на странице, за исключением того, что из результата выборки нужно сформировать экземпляр класса CAdminResult.

// выберем список рассылок
$cData = new CRubric;
$rsData = $cData->GetList(array($by=>$order), $arFilter);

// преобразуем список в экземпляр класса CAdminResult
$rsData = new CAdminResult($rsData, $sTableID);

// аналогично CDBResult инициализируем постраничную навигацию.
$rsData->NavStart();

// отправим вывод переключателя страниц в основной объект $lAdmin
$lAdmin->NavText($rsData->GetNavPrint(GetMessage("rub_nav")));
Подготовка списка элементов к выводу

Для того, чтобы сформировать таблицу элементов, нужно, во-первых, сформировать массив заголовков таблицы, а, во-вторых, отправить список в основной объект $lAdmin. Первое осуществляется посредством вызова метода СAdminList::AddHeaders(), которому передается массив колонок таблицы. Каждая колонка описывается массивом, содержащим следующие ключи:

Ключ | Описание
id | Идентификатор колонки.
content | Заголовок колонки.
sort | Значение параметра GET-запроса для сортировки.
default | Параметр, показывающий, будет ли колонка по умолчанию отображаться в списке (true|false)

Пример:

$lAdmin->AddHeaders(array(
  array(  "id"    =>"ID",
    "content"  =>"ID",
    "sort"     =>"id",
    "default"  =>true,
  ),
  array(  "id"    =>"NAME",
    "content"  =>GetMessage("rub_name"),
    "sort"     =>"name",
    "default"  =>true,
  ),
  array(  "id"    =>"LID",
    "content"  =>GetMessage("rub_site"),
    "sort"     =>"lid",
    "default"  =>true,
  ),
  array(  "id"    =>"SORT",
    "content"  =>GetMessage("rub_sort"),
    "sort"     =>"sort",
    "align"    =>"right",
    "default"  =>true,
  ),
  array(  "id"    =>"ACTIVE",
    "content"  =>GetMessage("rub_act"),
    "sort"     =>"act",
    "default"  =>true,
  ),
  array(  "id"    =>"VISIBLE",
    "content"  =>GetMessage("rub_visible"),
    "sort"     =>"visible",
    "default"  =>true,
  ),
  array(  "id"    =>"AUTO",
    "content"  =>GetMessage("rub_auto"),
    "sort"     =>"auto",
    "default"  =>true,
  ),
  array(  "id"    =>"LAST_EXECUTED",
    "content"  =>GetMessage("rub_last_exec"),
    "sort"     =>"last_executed",
    "default"  =>true,
  ),
));

Передача списка элементов в основной объект осуществляется следующим образом:

  1. Вызываем CAdminList::AddRow(). Результат метода - ссылка на пустой экземпляр класса CAdminListRow
  2. Формируем поля строки, используя следующие методы класса CAdminListRow:
    • AddField - значение ячейки будет отображаться в заданном виде при просмотре и при редактировании списка
    • AddViewField - при просмотре списка значение ячейки будет отображаться в заданном виде
    • AddEditField - при редактировании списка значение ячейки будет отображаться в заданном виде
    • AddCheckField - значение ячейки будет редактироваться в виде чекбокса
    • AddSelectField - значение ячейки будет редактироваться в виде выпадающего списка
    • AddInputField - значение ячейки будет редактироваться в виде текстового поля с заданным набором атрибутов
    • AddCalendarField - значение ячейки будет редактироваться в виде поля для ввода даты
  3. Формируем контекстное меню для строки (CAdminListRow::AddActions())

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

Контекстное меню элемента задается массивом, элементы которого представлюят собой ассоциативные массивы со следующим набором ключей:

Ключ | Описание
ICON | Имя CSS-класса с иконкой действия.
DISABLED | Флаг "пункт меню заблокирован" (true|false).
DEFAULT | Флаг "пункт меню является действием по умолчанию" (true|false). При двойном клике по строке сработает действие по умолчанию.
TEXT | Название пункта меню.
TITLE | Текст всплывающей подсказки пункта меню.
ACTION | Действие, производимое по выбору пункта меню (Javascript).
SEPARATOR | Вставка разделителя {true|false}. При значении, равном true, остальные ключи пункта меню будут проигнорированы.

Пример:

while($arRes = $rsData->NavNext(true, "f_")):

  // создаем строку. результат - экземпляр класса CAdminListRow
  $row =& $lAdmin->AddRow($f_ID, $arRes);

  // далее настроим отображение значений при просмотре и редаткировании списка

  // параметр NAME будет редактироваться как текст, а отображаться ссылкой
  $row->AddInputField("NAME", array("size"=>20));
  $row->AddViewField("NAME", '<a href="rubric_edit.php?ID='.$f_ID.'&lang='.LANG.'">'.$f_NAME.'</a>');

  // параметр LID будет редактироваться в виде выпадающего списка языков
  $row->AddEditField("LID", CLang::SelectBox("LID", $f_LID));

  // параметр SORT будет редактироваться текстом
  $row->AddInputField("SORT", array("size"=>20));

  // флаги ACTIVE и VISIBLE будут редактироваться чекбоксами
  $row->AddCheckField("ACTIVE");
  $row->AddCheckField("VISIBLE");

  // параметр AUTO будет отображаться в виде "Да" или "Нет", полужирным при редактировании
  $row->AddViewField("AUTO", $f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"));
  $row->AddEditField("AUTO", "<b>".($f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"))."</b>");

  // сформируем контекстное меню
  $arActions = Array();

  // редактирование элемента
  $arActions[] = array(
    "ICON"=>"edit",
    "DEFAULT"=>true,
    "TEXT"=>GetMessage("rub_edit"),
    "ACTION"=>$lAdmin->ActionRedirect("rubric_edit.php?ID=".$f_ID)
  );

  // удаление элемента
  if ($POST_RIGHT>="W")
    $arActions[] = array(
      "ICON"=>"delete",
      "TEXT"=>GetMessage("rub_del"),
      "ACTION"=>"if(confirm('".GetMessage('rub_del_conf')."')) ".$lAdmin->ActionDoGroup($f_ID, "delete")
    );

  // вставим разделитель
  $arActions[] = array("SEPARATOR"=>true);

  // проверка шаблона для автогенерируемых рассылок
  if (strlen($f_TEMPLATE)>0 && $f_AUTO=="Y")
    $arActions[] = array(
      "ICON"=>"",
      "TEXT"=>GetMessage("rub_check"),
      "ACTION"=>$lAdmin->ActionRedirect("template_test.php?ID=".$f_ID)
    );

  // если последний элемент - разделитель, почистим мусор.
  if(is_set($arActions[count($arActions)-1], "SEPARATOR"))
    unset($arActions[count($arActions)-1]);

  // применим контекстное меню к строке
  $row->AddActions($arActions);

endwhile;

Для завершения подготовки таблицы остается добавить к ней "резюме" и настроить групповые операции над элементами.

Резюме таблицы формируется в виде массива, элементами которого являются ассоциативные массивы с ключами "title" - название параметра - и "value" - значение параметра. Кроме того, ассоциативный массив может содержать элемент с ключом "counter" и значением true. В этом случае, элемент резюме будет счетчиком отмеченных элементов таблицы и значение будет динамически изменяться. Прикрепляется резюме вызовом метода CAdminList::AddFooter().

Список возможных групповых операций задается в виде массива элементов вида "идентификатор_операции"=>"название_операции" и прикрепляется к таблице вызовом CAdminList::AddGroupActionTable(). Про обработку групповых действий см. выше.

Пример:

// резюме таблицы
$lAdmin->AddFooter(
  array(
    array("title"=>GetMessage("MAIN_ADMIN_LIST_SELECTED"), "value"=>$rsData->SelectedRowsCount()), // кол-во элементов
    array("counter"=>true, "title"=>GetMessage("MAIN_ADMIN_LIST_CHECKED"), "value"=>"0"), // счетчик выбранных элементов
  )
);

// групповые действия
$lAdmin->AddGroupActionTable(Array(
  "delete"=>GetMessage("MAIN_ADMIN_LIST_DELETE"), // удалить выбранные элементы
  "activate"=>GetMessage("MAIN_ADMIN_LIST_ACTIVATE"), // активировать выбранные элементы
  "deactivate"=>GetMessage("MAIN_ADMIN_LIST_DEACTIVATE"), // деактивировать выбранные элементы
  ));
Задание параметров административного меню

Также можно задать административное меню, которое обычно отображается над таблицей со списком (только если у текущего пользователя есть права на редактирование). Административное формируется в виде массива, элементами которого являются ассоциативные массивы с ключами:

Ключ | Описание
TEXT | Текст пункта меню.
TITLE | Текст всплывающей подсказки пункта меню.
LINK | Ссылка на кнопке.
LINK_PARAM | Дополнительные параметры ссылки (напрямую подставляются в тэг <A>).
ICON | CSS-класс иконки действия.
HTML | Задание пункта меню напрямую HTML-кодом.
SEPARATOR | Разделитель между пунктами меню (true|false).
NEWBAR | Новый блок элементов меню (true|false).
MENU | Создание выпадающего подменю. Значение задается аналогично контекстному меню строки таблицы.

Прикрепляется контекстное меню вызовом CAdminList::AddAdminContextMenu().

Пример:

// сформируем меню из одного пункта - добавление рассылки
$aContext = array(
  array(
    "TEXT"=>GetMessage("POST_ADD"),
    "LINK"=>"rubric_edit.php?lang=".LANG,
    "TITLE"=>GetMessage("POST_ADD_TITLE"),
    "ICON"=>"btn_new",
  ),
);

// и прикрепим его к списку
$lAdmin->AddAdminContextMenu($aContext);
Завершение подготовки

На этом подготовка списка завершена. Для того, чтобы обработать альтернтативные методы вывода списка (обновление посредством AJAX, вывод в формате Excel) вызовем метод CAdminList::CheckListMode():

// альтернативный вывод
$lAdmin->CheckListMode();

И в завершение непосредственно перед стандартным выводом, установим заголовок страницы:

// установим заголовок страницы
$APPLICATION->SetTitle(GetMessage("rub_title"));
Вывод данных

Как видно на схеме, подготовку страницы и основной вывод необходимо разделить подключением административного файла prolog_admin_after.php:

// не забудем разделить подготовку данных и вывод
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");

Выше было сказано, что вывод данных можно разбить на 2 части - вывод фильтра и вывод списка.

Вывод фильтра

Для вывода фильтра требуется сперва создать экземпляр класса CAdminFilter, передав ему список полей, а затем сформировать форму фильтра "вручную".

Пример:

// создадим объект фильтра
$oFilter = new CAdminFilter(
  $sTableID."_filter",
  array(
    "ID",
    GetMessage("rub_f_site"),
    GetMessage("rub_f_active"),
    GetMessage("rub_f_public"),
    GetMessage("rub_f_auto"),
  )
);
?>
<form name="find_form" method="get" action="<?echo $APPLICATION->GetCurPage();?>">
<?$oFilter->Begin();?>
<tr>
  <td><?="ID"?>:</td>
  <td>
    <input type="text" name="find_id" size="47" value="<?echo htmlspecialchars($find_id)?>">
  </td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_site").":"?></td>
  <td><input type="text" name="find_lid" size="47" value="<?echo htmlspecialchars($find_lid)?>"></td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_active")?>:</td>
  <td>
    <?
    $arr = array(
      "reference" => array(
        GetMessage("POST_YES"),
        GetMessage("POST_NO"),
      ),
      "reference_id" => array(
        "Y",
        "N",
      )
    );
    echo SelectBoxFromArray("find_active", $arr, $find_active, GetMessage("POST_ALL"), "");
    ?>
  </td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_public")?>:</td>
  <td><?echo SelectBoxFromArray("find_visible", $arr, $find_visible, GetMessage("POST_ALL"), "");?></td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_auto")?>:</td>
  <td><?echo SelectBoxFromArray("find_auto", $arr, $find_auto, GetMessage("POST_ALL"), "");?></td>
</tr>
<?
$oFilter->Buttons(array("table_id"=>$sTableID,"url"=>$APPLICATION->GetCurPage(),"form"=>"find_form"));
$oFilter->End();
?>
</form>

Вывод таблицы

Ну и вполне логично, что после всех вышеприведенных подготовительных операций вывод списка осуществляется очень просто:

// выведем таблицу списка элементов
$lAdmin->DisplayList();

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


Пример создания списка элементов

Описание создания административной страницы со списком можно увидеть здесь.

Пример

<?
// подключим все необходимые файлы:
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_before.php"); // первый общий пролог

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/include.php"); // инициализация модуля
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/prolog.php"); // пролог модуля

// подключим языковой файл
IncludeModuleLangFile(__FILE__);

// получим права доступа текущего пользователя на модуль
$POST_RIGHT = $APPLICATION->GetGroupRight("subscribe");
// если нет прав - отправим к форме авторизации с сообщением об ошибке
if ($POST_RIGHT == "D")
    $APPLICATION->AuthForm(GetMessage("ACCESS_DENIED"));

$sTableID = "tbl_rubric"; // ID таблицы
$oSort = new CAdminSorting($sTableID, "ID", "desc"); // объект сортировки
$lAdmin = new CAdminList($sTableID, $oSort); // основной объект списка

// ******************************************************************** //
//                           ФИЛЬТР                                     //
// ******************************************************************** //

// *********************** CheckFilter ******************************** //
// проверку значений фильтра для удобства вынесем в отдельную функцию
function CheckFilter()
{
  global $FilterArr, $lAdmin;
  foreach ($FilterArr as $f) global $$f;

  // В данном случае проверять нечего.
  // В общем случае нужно проверять значения переменных $find_имя
  // и в случае возниконовения ошибки передавать ее обработчику
  // посредством $lAdmin->AddFilterError('текст_ошибки').

  return count($lAdmin->arFilterErrors)==0; // если ошибки есть, вернем false;
}
// *********************** /CheckFilter ******************************* //

// опишем элементы фильтра
$FilterArr = Array(
  "find",
  "find_type",
  "find_id",
  "find_lid",
  "find_active",
  "find_visible",
  "find_auto",
  );

// инициализируем фильтр
$lAdmin->InitFilter($FilterArr);

// если все значения фильтра корректны, обработаем его
if (CheckFilter())
{
  // создадим массив фильтрации для выборки CRubric::GetList() на основе значений фильтра
  $arFilter = Array(
    "ID"    => ($find!="" && $find_type == "id"? $find:$find_id),
    "LID"    => $find_lid,
    "ACTIVE"  => $find_active,
    "VISIBLE"  => $find_visible,
    "AUTO"    => $find_auto,
  );
}

// ******************************************************************** //
//                ОБРАБОТКА ДЕЙСТВИЙ НАД ЭЛЕМЕНТАМИ СПИСКА              //
// ******************************************************************** //

// сохранение отредактированных элементов
if($lAdmin->EditAction() && $POST_RIGHT=="W")
{
  // пройдем по списку переданных элементов
  foreach($FIELDS as $ID=>$arFields)
  {
    if(!$lAdmin->IsUpdated($ID))
      continue;

    // сохраним изменения каждого элемента
    $DB->StartTransaction();
    $ID = IntVal($ID);
    $cData = new CRubric;
    if(($rsData = $cData->GetByID($ID)) && ($arData = $rsData->Fetch()))
    {
      foreach($arFields as $key=>$value)
        $arData[$key]=$value;
      if(!$cData->Update($ID, $arData))
      {
        $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".$cData->LAST_ERROR, $ID);
        $DB->Rollback();
      }
    }
    else
    {
      $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
      $DB->Rollback();
    }
    $DB->Commit();
  }
}

// обработка одиночных и групповых действий
if(($arID = $lAdmin->GroupAction()) && $POST_RIGHT=="W")
{
  // если выбрано "Для всех элементов"
  if($_REQUEST['action_target']=='selected')
  {
    $cData = new CRubric;
    $rsData = $cData->GetList(array($by=>$order), $arFilter);
    while($arRes = $rsData->Fetch())
      $arID[] = $arRes['ID'];
  }

  // пройдем по списку элементов
  foreach($arID as $ID)
  {
    if(strlen($ID)<=0)
      continue;
       $ID = IntVal($ID);

    // для каждого элемента совершим требуемое действие
    switch($_REQUEST['action'])
    {
    // удаление
    case "delete":
      @set_time_limit(0);
      $DB->StartTransaction();
      if(!CRubric::Delete($ID))
      {
        $DB->Rollback();
        $lAdmin->AddGroupError(GetMessage("rub_del_err"), $ID);
      }
      $DB->Commit();
      break;

    // активация/деактивация
    case "activate":
    case "deactivate":
      $cData = new CRubric;
      if(($rsData = $cData->GetByID($ID)) && ($arFields = $rsData->Fetch()))
      {
        $arFields["ACTIVE"]=($_REQUEST['action']=="activate"?"Y":"N");
        if(!$cData->Update($ID, $arFields))
          $lAdmin->AddGroupError(GetMessage("rub_save_error").$cData->LAST_ERROR, $ID);
      }
      else
        $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
      break;
    }
  }
}

// ******************************************************************** //
//                ВЫБОРКА ЭЛЕМЕНТОВ СПИСКА                              //
// ******************************************************************** //

// выберем список рассылок
$cData = new CRubric;
$rsData = $cData->GetList(array($by=>$order), $arFilter);

// преобразуем список в экземпляр класса CAdminResult
$rsData = new CAdminResult($rsData, $sTableID);

// аналогично CDBResult инициализируем постраничную навигацию.
$rsData->NavStart();

// отправим вывод переключателя страниц в основной объект $lAdmin
$lAdmin->NavText($rsData->GetNavPrint(GetMessage("rub_nav")));

// ******************************************************************** //
//                ПОДГОТОВКА СПИСКА К ВЫВОДУ                            //
// ******************************************************************** //

$lAdmin->AddHeaders(array(
  array(  "id"    =>"ID",
    "content"  =>"ID",
    "sort"    =>"id",
    "align"    =>"right",
    "default"  =>true,
  ),
  array(  "id"    =>"NAME",
    "content"  =>GetMessage("rub_name"),
    "sort"    =>"name",
    "default"  =>true,
  ),
  array(  "id"    =>"LID",
    "content"  =>GetMessage("rub_site"),
    "sort"    =>"lid",
    "default"  =>true,
  ),
  array(  "id"    =>"SORT",
    "content"  =>GetMessage("rub_sort"),
    "sort"    =>"sort",
    "align"    =>"right",
    "default"  =>true,
  ),
  array(  "id"    =>"ACTIVE",
    "content"  =>GetMessage("rub_act"),
    "sort"    =>"act",
    "default"  =>true,
  ),
  array(  "id"    =>"VISIBLE",
    "content"  =>GetMessage("rub_visible"),
    "sort"    =>"visible",
    "default"  =>true,
  ),
  array(  "id"    =>"AUTO",
    "content"  =>GetMessage("rub_auto"),
    "sort"    =>"auto",
    "default"  =>true,
  ),
  array(  "id"    =>"LAST_EXECUTED",
    "content"  =>GetMessage("rub_last_exec"),
    "sort"    =>"last_executed",
    "default"  =>true,
  ),
));

while($arRes = $rsData->NavNext(true, "f_")):

  // создаем строку. результат - экземпляр класса CAdminListRow
  $row =& $lAdmin->AddRow($f_ID, $arRes);

  // далее настроим отображение значений при просмотре и редаткировании списка

  // параметр NAME будет редактироваться как текст, а отображаться ссылкой
  $row->AddInputField("NAME", array("size"=>20));
  $row->AddViewField("NAME", '<a href="rubric_edit.php?ID='.$f_ID.'&lang='.LANG.'">'.$f_NAME.'</a>');

  // параметр LID будет редактироваться в виде выпадающего списка языков
  $row->AddEditField("LID", CLang::SelectBox("LID", $f_LID));

  // параметр SORT будет редактироваться текстом
  $row->AddInputField("SORT", array("size"=>20));

  // флаги ACTIVE и VISIBLE будут редактироваться чекбоксами
  $row->AddCheckField("ACTIVE");
  $row->AddCheckField("VISIBLE");

  // параметр AUTO будет отображаться в виде "Да" или "Нет", полужирным при редактировании
  $row->AddViewField("AUTO", $f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"));
  $row->AddEditField("AUTO", "<b>".($f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"))."</b>");

  // сформируем контекстное меню
  $arActions = Array();

  // редактирование элемента
  $arActions[] = array(
    "ICON"=>"edit",
    "DEFAULT"=>true,
    "TEXT"=>GetMessage("rub_edit"),
    "ACTION"=>$lAdmin->ActionRedirect("rubric_edit.php?ID=".$f_ID)
  );

  // удаление элемента
  if ($POST_RIGHT>="W")
    $arActions[] = array(
      "ICON"=>"delete",
      "TEXT"=>GetMessage("rub_del"),
      "ACTION"=>"if(confirm('".GetMessage('rub_del_conf')."')) ".$lAdmin->ActionDoGroup($f_ID, "delete")
    );

  // вставим разделитель
  $arActions[] = array("SEPARATOR"=>true);

  // проверка шаблона для автогенерируемых рассылок
  if (strlen($f_TEMPLATE)>0 && $f_AUTO=="Y")
    $arActions[] = array(
      "ICON"=>"",
      "TEXT"=>GetMessage("rub_check"),
      "ACTION"=>$lAdmin->ActionRedirect("template_test.php?ID=".$f_ID)
    );

  // если последний элемент - разделитель, почистим мусор.
  if(is_set($arActions[count($arActions)-1], "SEPARATOR"))
    unset($arActions[count($arActions)-1]);

  // применим контекстное меню к строке
  $row->AddActions($arActions);

endwhile;

// резюме таблицы
$lAdmin->AddFooter(
  array(
    array("title"=>GetMessage("MAIN_ADMIN_LIST_SELECTED"), "value"=>$rsData->SelectedRowsCount()), // кол-во элементов
    array("counter"=>true, "title"=>GetMessage("MAIN_ADMIN_LIST_CHECKED"), "value"=>"0"), // счетчик выбранных элементов
  )
);

// групповые действия
$lAdmin->AddGroupActionTable(Array(
  "delete"=>GetMessage("MAIN_ADMIN_LIST_DELETE"), // удалить выбранные элементы
  "activate"=>GetMessage("MAIN_ADMIN_LIST_ACTIVATE"), // активировать выбранные элементы
  "deactivate"=>GetMessage("MAIN_ADMIN_LIST_DEACTIVATE"), // деактивировать выбранные элементы
  ));

// ******************************************************************** //
//                АДМИНИСТРАТИВНОЕ МЕНЮ                                 //
// ******************************************************************** //

// сформируем меню из одного пункта - добавление рассылки
$aContext = array(
  array(
    "TEXT"=>GetMessage("POST_ADD"),
    "LINK"=>"rubric_edit.php?lang=".LANG,
    "TITLE"=>GetMessage("POST_ADD_TITLE"),
    "ICON"=>"btn_new",
  ),
);

// и прикрепим его к списку
$lAdmin->AddAdminContextMenu($aContext);

// ******************************************************************** //
//                ВЫВОД                                                 //
// ******************************************************************** //

// альтернативный вывод
$lAdmin->CheckListMode();

// установим заголовок страницы
$APPLICATION->SetTitle(GetMessage("rub_title"));

// не забудем разделить подготовку данных и вывод
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");

// ******************************************************************** //
//                ВЫВОД ФИЛЬТРА                                         //
// ******************************************************************** //

// создадим объект фильтра
$oFilter = new CAdminFilter(
  $sTableID."_filter",
  array(
    "ID",
    GetMessage("rub_f_site"),
    GetMessage("rub_f_active"),
    GetMessage("rub_f_public"),
    GetMessage("rub_f_auto"),
  )
);
?>
<form name="find_form" method="get" action="<?echo $APPLICATION->GetCurPage();?>">
<?$oFilter->Begin();?>
<tr>
  <td><b><?=GetMessage("rub_f_find")?>:</b></td>
  <td>
    <input type="text" size="25" name="find" value="<?echo htmlspecialchars($find)?>" title="<?=GetMessage("rub_f_find_title")?>">
    <?
    $arr = array(
      "reference" => array(
        "ID",
      ),
      "reference_id" => array(
        "id",
      )
    );
    echo SelectBoxFromArray("find_type", $arr, $find_type, "", "");
    ?>
  </td>
</tr>
<tr>
  <td><?="ID"?>:</td>
  <td>
    <input type="text" name="find_id" size="47" value="<?echo htmlspecialchars($find_id)?>">
  </td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_site").":"?></td>
  <td><input type="text" name="find_lid" size="47" value="<?echo htmlspecialchars($find_lid)?>"></td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_active")?>:</td>
  <td>
    <?
    $arr = array(
      "reference" => array(
        GetMessage("POST_YES"),
        GetMessage("POST_NO"),
      ),
      "reference_id" => array(
        "Y",
        "N",
      )
    );
    echo SelectBoxFromArray("find_active", $arr, $find_active, GetMessage("POST_ALL"), "");
    ?>
  </td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_public")?>:</td>
  <td><?echo SelectBoxFromArray("find_visible", $arr, $find_visible, GetMessage("POST_ALL"), "");?></td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_auto")?>:</td>
  <td><?echo SelectBoxFromArray("find_auto", $arr, $find_auto, GetMessage("POST_ALL"), "");?></td>
</tr>
<?
$oFilter->Buttons(array("table_id"=>$sTableID,"url"=>$APPLICATION->GetCurPage(),"form"=>"find_form"));
$oFilter->End();
?>
</form>

<?
// выведем таблицу списка элементов
$lAdmin->DisplayList();
?>

<?
// завершение страницы
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_admin.php");
?>


Создание формы редактирования

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

Принципы работы

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

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

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

Разберем создание формы редактирования в административном интерфейсе. В качестве примера будем использовать административную страницу модуля "Подписка, рассылки".

Начало

Для начала создадим файл bitrix/modules/subscribe/rubric_edit.php следующей структуры:

<?
// подключим все необходимые файлы:
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_before.php"); // первый общий пролог

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/include.php"); // инициализация модуля
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/prolog.php"); // пролог модуля

// подключим языковой файл
IncludeModuleLangFile(__FILE__);

// получим права доступа текущего пользователя на модуль
$POST_RIGHT = $APPLICATION->GetGroupRight("subscribe");
// если нет прав - отправим к форме авторизации с сообщением об ошибке
if ($POST_RIGHT == "D")
    $APPLICATION->AuthForm(GetMessage("ACCESS_DENIED"));
?>
<?
// здесь будет вся серверная обработка и подготовка данных
?>
<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php"); // второй общий пролог
?>
<?
// здесь будет вывод страницы с формой
?>
<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_admin.php");?>

Это и есть "костяк страницы", обозначенный на схеме.

Далее, создадим языковой файл, например, /bitrix/modules/subscribe/lang/ru/rubric_edit.php для русского языка. В файле будем определять все языковые сообщения в виде элементов массива: $MESS['идентификатор_сообщения'] = "текст_сообщения";

Затем, поскольку с изначальными параметрами установки БУС каталог /bitrix/modules/ недоступен посредством HTTP-протокола, создадим файл /bitrix/admin/rubric_edit.php:

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/admin/rubric_edit.php");
?>

Теперь наш файл доступен по ссылке http://mysite.ru/bitrix/admin/rubric_edit.php.

Фунционал страницы

Как видно из схемы, весь функционал страницы условно можно разделить на несколько составных частей:

  • Обработка и подготовка данных
    • Обработка и сохранение изменений
    • Выборка и подготовка данных для формы
    • Настройка интерфейса закладок и параметров административного меню страницы
  • Вывод данных
    • Вывод административного меню страницы
    • Вывод сообщений об ошибках
    • Вывод формы редактирования с метками закладок

В процессе работы нам потребуются экземпляры следующих классов:

Класс | Описание
CAdminTabControl | Класс для вывода формы, разбитой на страницы с динамически переключаемыми закладками.
CAdminMessage | Класс для работы с административными сообщениями.
CAdminContextMenu | Класс для работы с панелями административного меню действий.
Обработка и подготовка данных
Настройка интерфейса закладок

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

Ключ | Описание
DIV | Уникальный идентификатор закладки.
TAB | Текст, помещаемый на закладку.
TITLE | Описание страницы, к которой ведет закладка.
ICON | CSS-класс иконки, выводимой рыдом с описанием страницы.
ONSELECT | JavaScript-сценарий, который будет выполнен при переключении на закладку.

Далее, нужно создать экземпляр класса CAdminTabControl и передать ему эту структуру.

$aTabs = array(
  array("DIV" => "edit1", "TAB" => GetMessage("rub_tab_rubric"), "ICON"=>"main_user_edit", "TITLE"=>GetMessage("rub_tab_rubric_title")),
  array("DIV" => "edit2", "TAB" => GetMessage("rub_tab_generation"), "ICON"=>"main_user_edit", "TITLE"=>GetMessage("rub_tab_generation_title")),
);
$tabControl = new CAdminTabControl("tabControl", $aTabs);
Обработка и сохранение изменений

Сначала, определим несколько переменных, которые нам понадобятся впоследствии:

$ID = intval($ID);		// идентификатор редактируемой записи
$message = null;		// сообщение об ошибке
$bVarsFromForm = false; // флаг "Данные получены с формы", обозначающий, что выводимые данные получены с формы, а не из БД.

Необходимость сохранения изменений мы определим по следующим параметрам:

  • Страница вызвана методом POST
  • Среди входных данных есть идентификаторы кнопок "Сохранить" и "Применить"

Если эти условия сооблюдены и пройдены проверки безопасности, можно сохранять переданные скрипту данные:

if(
    $REQUEST_METHOD == "POST" // проверка метода вызова страницы
    &&
    ($save!="" || $apply!="") // проверка нажатия кнопок "Сохранить" и "Применить"
    &&
    $POST_RIGHT=="W"          // проверка наличия прав на запись для модуля
    &&
    check_bitrix_sessid()     // проверка идентификатора сессии
)
{
  $rubric = new CRubric;

  // обработка данных формы
  $arFields = Array(
    "ACTIVE"         => ($ACTIVE <> "Y" ? "N" : "Y"),
    "NAME"           => $NAME,
    "SORT"           => $SORT,
    "DESCRIPTION"    => $DESCRIPTION,
    "LID"            => $LID,
    "AUTO"           => ($AUTO <> "Y" ? "N" : "Y"),
    "DAYS_OF_MONTH"  => $DAYS_OF_MONTH,
    "DAYS_OF_WEEK"   => (is_array($DAYS_OF_WEEK) ? implode(",", $DAYS_OF_WEEK) : ""),
    "TIMES_OF_DAY"   => $TIMES_OF_DAY,
    "TEMPLATE"       => $TEMPLATE,
    "VISIBLE"        => ($VISIBLE <> "Y" ? "N" : "Y"),
    "FROM_FIELD"     => $FROM_FIELD,
    "LAST_EXECUTED"  => $LAST_EXECUTED
  );

  // сохранение данных
  if($ID > 0)
  {
    $res = $rubric->Update($ID, $arFields);
  }
  else
  {
    $ID = $rubric->Add($arFields);
    $res = ($ID > 0);
  }

  if($res)
  {
    // если сохранение прошло удачно - перенаправим на новую страницу
    // (в целях защиты от повторной отправки формы нажатием кнопки "Обновить" в браузере)
    if ($apply != "")
      // если была нажата кнопка "Применить" - отправляем обратно на форму.
      LocalRedirect("/bitrix/admin/rubric_edit.php?ID=".$ID."&mess=ok⟨=".LANG."&".$tabControl->ActiveTabParam());
    else
      // если была нажата кнопка "Сохранить" - отправляем к списку элементов.
      LocalRedirect("/bitrix/admin/rubric_admin.php?lang=".LANG);
  }
  else
  {
    // если в процессе сохранения возникли ошибки - получаем текст ошибки и меняем вышеопределённые переменные
    if($e = $APPLICATION->GetException())
      $message = new CAdminMessage(GetMessage("rub_save_error"), $e);
    $bVarsFromForm = true;
  }
}
Выборка и подготовка данных для формы

Для начала, определим значения по умолчанию. Все данные, полученные из БД будем сохранять в переменные с префиксом str_

$str_SORT          = 100;
$str_ACTIVE        = "Y";
$str_AUTO          = "N";
$str_DAYS_OF_MONTH = "";
$str_DAYS_OF_WEEK  = "";
$str_TIMES_OF_DAY  = "";
$str_VISIBLE       = "Y";
$str_LAST_EXECUTED = ConvertTimeStamp(false, "FULL");
$str_FROM_FIELD    = COption::GetOptionString("subscribe", "default_from");

Выберем данные:

if($ID>0)
{
  $rubric = CRubric::GetByID($ID);
  if(!$rubric->ExtractFields("str_"))
    $ID=0;
}

Подготовим полученные данные и установим заголовок страницы:

// если данные переданы из формы, инициализируем их
if($bVarsFromForm)
  $DB->InitTableVarsForEdit("b_list_rubric", "", "str_");

$APPLICATION->SetTitle(($ID>0? GetMessage("rub_title_edit").$ID : GetMessage("rub_title_add")));
Задание параметров административного меню

Также можно задать административное меню, которое будет отображаться над таблицей со списком (только если у текущего пользователя есть права на редактирование). Административное формируется в виде массива, элементами которого являются ассоциативные массивы с ключами:

Ключ | Описание
TEXT | Текст пункта меню.
TITLE | Текст всплывающей подсказки пункта меню.
LINK | Ссылка на кнопке.
LINK_PARAM | Дополнительные параметры ссылки (напрямую подставляются в тэг <A>).
ICON | CSS-класс иконки действия.
HTML | Задание пункта меню напрямую HTML-кодом.
SEPARATOR | Разделитель между пунктами меню (true|false).
NEWBAR | Новый блок элементов меню (true|false).
MENU | Создание выпадающего подменю. Значение задается аналогично контекстному меню строки таблицы.

Пример:

$aMenu = array(
  array(
    "TEXT"  => GetMessage("rub_list"),
    "TITLE" => GetMessage("rub_list_title"),
    "LINK"  => "rubric_admin.php?lang=".LANG,
    "ICON"  => "btn_list",
  )
);

if($ID>0)
{
  $aMenu[] = array("SEPARATOR"=>"Y");

  $aMenu[] = array(
    "TEXT"  => GetMessage("rub_add"),
    "TITLE" => GetMessage("rubric_mnu_add"),
    "LINK"  => "rubric_edit.php?lang=".LANG,
    "ICON"  => "btn_new",
  );
  $aMenu[] = array(
    "TEXT"  => GetMessage("rub_delete"),
    "TITLE" => GetMessage("rubric_mnu_del"),
    "LINK"  => "javascript:if(confirm('".GetMessage("rubric_mnu_del_conf")."')) ".
      "window.location='rubric_admin.php?ID=".$ID."&action=delete⟨=".LANG."&".bitrix_sessid_get()."';",
    "ICON"  => "btn_delete",
  );
  $aMenu[] = array("SEPARATOR"=>"Y");
  $aMenu[] = array(
    "TEXT"  => GetMessage("rub_check"),
    "TITLE" => GetMessage("rubric_mnu_check"),
    "LINK"  => "template_test.php?lang=".LANG."&ID=".$ID
  );
}

Результирующая структура передается конструктору класса CAdminContextMenu.

Вывод данных

Как видно на схеме, подготовку страницы и основной вывод необходимо разделить подключением административного файла prolog_admin_after.php:

// не забудем разделить подготовку данных и вывод
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");

Прежде всего, выведем подготовленное административное меню.

// создадим экземпляр класса административного меню
$context = new CAdminContextMenu($aMenu);

// выведем меню
$context->Show();

Если есть сообщения об ошибках или об успешном сохранении - выведем их.

if($_REQUEST["mess"] == "ok" && $ID>0)
  CAdminMessage::ShowMessage(array("MESSAGE"=>GetMessage("rub_saved"), "TYPE"=>"OK"));

if($message)
  echo $message->Show();
elseif($rubric->LAST_ERROR!="")
  CAdminMessage::ShowMessage($rubric->LAST_ERROR);

Далее, выводим собственно форму. Для инициализации механизма закладок и вывода панели закладок следует использовать метод CAdminTabControl::Begin(). Для разделения закладок - CAdminTabControl::BeginNextTab(). Для завершения - CAdminTabControl::End().

<form method="POST" Action="<?echo $APPLICATION->GetCurPage()?>" ENCTYPE="multipart/form-data" name="post_form">
<?// проверка идентификатора сессии ?>
<?echo bitrix_sessid_post();?>
<input type="hidden" name="lang" value="<?=LANG?>">
<?if($ID>0 && !$bCopy):?>
  <input type="hidden" name="ID" value="<?=$ID?>">
<?endif;?>
<?
// отобразим заголовки закладок
$tabControl->Begin();
?>
<?
//********************
// первая закладка - форма редактирования параметров рассылки
//********************
$tabControl->BeginNextTab();
?>
  <tr>
    <td width="40%"><?echo GetMessage("rub_act")?></td>
    <td width="60%"><input type="checkbox" name="ACTIVE" value="Y"<?if($str_ACTIVE == "Y") echo " checked"?> /></td>
  </tr>

  <!--  HTML-код строк таблицы -->

  <tr>
    <td><?echo GetMessage("rub_auto")?></td>
    <td><input type="checkbox" name="AUTO" value="Y"<?if($str_AUTO == "Y") echo " checked"?>
      OnClick="if(this.checked) tabControl.EnableTab('edit2'); else tabControl.DisableTab('edit2');" /></td>
  </tr>
<?
//********************
// вторая закладка - параметры автоматической генерации рассылки
//********************
$tabControl->BeginNextTab();
?>
  <tr class="heading">
    <td colspan="2"><?echo GetMessage("rub_schedule")?></td>
  </tr>
  <tr>
    <td width="40%"><span class="required">*</span><?echo GetMessage("rub_last_executed"). " (".FORMAT_DATETIME."):"?></td>
    <td width="60%"><?echo CalendarDate("LAST_EXECUTED", $str_LAST_EXECUTED, "post_form", "20")?></td>
  </tr>

  <!--  HTML-код строк таблицы -->

  <tr>
    <td><span class="required">*</span><?echo GetMessage("rub_post_fields_from")?></td>
    <td><input type="text" name="FROM_FIELD" value="<?echo $str_FROM_FIELD;?>" size="30" maxlength="255" /></td>
  </tr>
<?
// завершение формы - вывод кнопок сохранения изменений
$tabControl->Buttons(
  array(
    "disabled"=>($POST_RIGHT<"W"),
    "back_url"=>"rubric_admin.php?lang=".LANG,
  )
);
?>
<?
// завершаем интерфейс закладки
$tabControl->End();
?>

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

<?
// дополнительное уведомление об ошибках - вывод иконки около поля, в котором возникла ошибка
$tabControl->ShowWarnings("post_form", $message);
?>

Механизм закладок предоставляет также интерфейс для динамического управления закладками посредством JavaScript. В качестве примера, предоставим блокирование закладки:

<script language="JavaScript">
<!--
  if(document.post_form.AUTO.checked)
    tabControl.EnableTab('edit2');
  else
    tabControl.DisableTab('edit2');
//-->
</script>

Ну и завершим нашу страницу информационным сообщением:

<?echo BeginNote();?>
<span class="required">*</span><?echo GetMessage("REQUIRED_FIELDS")?>
<?echo EndNote();?>

<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_admin.php");?>

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


Пример создания страницы редактирования

Описание создания административной страницы редактирования можно увидеть здесь.

Пример

<?
// подключим все необходимые файлы:
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_before.php"); // первый общий пролог

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/include.php"); // инициализация модуля
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/subscribe/prolog.php"); // пролог модуля

// подключим языковой файл
IncludeModuleLangFile(__FILE__);

// получим права доступа текущего пользователя на модуль
$POST_RIGHT = $APPLICATION->GetGroupRight("subscribe");
// если нет прав - отправим к форме авторизации с сообщением об ошибке
if ($POST_RIGHT == "D")
  $APPLICATION->AuthForm(GetMessage("ACCESS_DENIED"));

// сформируем список закладок
$aTabs = array(
  array("DIV" => "edit1", "TAB" => GetMessage("rub_tab_rubric"), "ICON"=>"main_user_edit", "TITLE"=>GetMessage("rub_tab_rubric_title")),
  array("DIV" => "edit2", "TAB" => GetMessage("rub_tab_generation"), "ICON"=>"main_user_edit", "TITLE"=>GetMessage("rub_tab_generation_title")),
);
$tabControl = new CAdminTabControl("tabControl", $aTabs);

$ID = intval($ID);		// идентификатор редактируемой записи
$message = null;		// сообщение об ошибке
$bVarsFromForm = false; // флаг "Данные получены с формы", обозначающий, что выводимые данные получены с формы, а не из БД.

// ******************************************************************** //
//                ОБРАБОТКА ИЗМЕНЕНИЙ ФОРМЫ                             //
// ******************************************************************** //

if(
    $REQUEST_METHOD == "POST" // проверка метода вызова страницы
    &&
    ($save!="" || $apply!="") // проверка нажатия кнопок "Сохранить" и "Применить"
    &&
    $POST_RIGHT=="W"          // проверка наличия прав на запись для модуля
    &&
    check_bitrix_sessid()     // проверка идентификатора сессии
)
{
  $rubric = new CRubric;

  // обработка данных формы
  $arFields = Array(
    "ACTIVE"  => ($ACTIVE <> "Y"? "N":"Y"),
    "NAME"    => $NAME,
    "SORT"    => $SORT,
    "DESCRIPTION"  => $DESCRIPTION,
    "LID"    => $LID,
    "AUTO"    =>($AUTO <> "Y"? "N":"Y"),
    "DAYS_OF_MONTH"  => $DAYS_OF_MONTH,
    "DAYS_OF_WEEK"  => (is_array($DAYS_OF_WEEK)?implode(",", $DAYS_OF_WEEK):""),
    "TIMES_OF_DAY"  => $TIMES_OF_DAY,
    "TEMPLATE"  => $TEMPLATE,
    "VISIBLE"  => ($VISIBLE <> "Y"? "N":"Y"),
    "FROM_FIELD"  => $FROM_FIELD,
    "LAST_EXECUTED"  => $LAST_EXECUTED
  );

  // сохранение данных
  if($ID > 0)
  {
    $res = $rubric->Update($ID, $arFields);
  }
  else
  {
    $ID = $rubric->Add($arFields);
    $res = ($ID > 0);
  }

  if($res)
  {
    // если сохранение прошло удачно - перенаправим на новую страницу
    // (в целях защиты от повторной отправки формы нажатием кнопки "Обновить" в браузере)
    if ($apply != "")
      // если была нажата кнопка "Применить" - отправляем обратно на форму.
      LocalRedirect("/bitrix/admin/rubric_edit.php?ID=".$ID."&mess=ok&lang=".LANG."&".$tabControl->ActiveTabParam());
    else
      // если была нажата кнопка "Сохранить" - отправляем к списку элементов.
      LocalRedirect("/bitrix/admin/rubric_admin.php?lang=".LANG);
  }
  else
  {
    // если в процессе сохранения возникли ошибки - получаем текст ошибки и меняем вышеопределённые переменные
    if($e = $APPLICATION->GetException())
      $message = new CAdminMessage(GetMessage("rub_save_error"), $e);
    $bVarsFromForm = true;
  }
}

// ******************************************************************** //
//                ВЫБОРКА И ПОДГОТОВКА ДАННЫХ ФОРМЫ                     //
// ******************************************************************** //

// значения по умолчанию
$str_SORT          = 100;
$str_ACTIVE        = "Y";
$str_AUTO          = "N";
$str_DAYS_OF_MONTH = "";
$str_DAYS_OF_WEEK  = "";
$str_TIMES_OF_DAY  = "";
$str_VISIBLE       = "Y";
$str_LAST_EXECUTED = ConvertTimeStamp(false, "FULL");
$str_FROM_FIELD    = COption::GetOptionString("subscribe", "default_from");

// выборка данных
if($ID>0)
{
  $rubric = CRubric::GetByID($ID);
  if(!$rubric->ExtractFields("str_"))
    $ID=0;
}

// дополнительная подготовка данных
if($ID>0 && !$message)
  $DAYS_OF_WEEK = explode(",", $str_DAYS_OF_WEEK);
if(!is_array($DAYS_OF_WEEK))
  $DAYS_OF_WEEK = array();

// если данные переданы из формы, инициализируем их
if($bVarsFromForm)
  $DB->InitTableVarsForEdit("b_list_rubric", "", "str_");

// ******************************************************************** //
//                ВЫВОД ФОРМЫ                                           //
// ******************************************************************** //

// установим заголовок страницы
$APPLICATION->SetTitle(($ID>0? GetMessage("rub_title_edit").$ID : GetMessage("rub_title_add")));

// не забудем разделить подготовку данных и вывод
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");

// конфигурация административного меню
$aMenu = array(
  array(
    "TEXT"=>GetMessage("rub_list"),
    "TITLE"=>GetMessage("rub_list_title"),
    "LINK"=>"rubric_admin.php?lang=".LANG,
    "ICON"=>"btn_list",
  )
);

if($ID>0)
{
  $aMenu[] = array("SEPARATOR"=>"Y");
  $aMenu[] = array(
    "TEXT"=>GetMessage("rub_add"),
    "TITLE"=>GetMessage("rubric_mnu_add"),
    "LINK"=>"rubric_edit.php?lang=".LANG,
    "ICON"=>"btn_new",
  );
  $aMenu[] = array(
    "TEXT"=>GetMessage("rub_delete"),
    "TITLE"=>GetMessage("rubric_mnu_del"),
    "LINK"=>"javascript:if(confirm('".GetMessage("rubric_mnu_del_conf")."'))window.location='rubric_admin.php?ID=".$ID."&action=delete&lang=".LANG."&".bitrix_sessid_get()."';",
    "ICON"=>"btn_delete",
  );
  $aMenu[] = array("SEPARATOR"=>"Y");
  $aMenu[] = array(
    "TEXT"=>GetMessage("rub_check"),
    "TITLE"=>GetMessage("rubric_mnu_check"),
    "LINK"=>"template_test.php?lang=".LANG."&ID=".$ID
  );
}

// создание экземпляра класса административного меню
$context = new CAdminContextMenu($aMenu);

// вывод административного меню
$context->Show();
?>

<?
// если есть сообщения об ошибках или об успешном сохранении - выведем их.
if($_REQUEST["mess"] == "ok" && $ID>0)
  CAdminMessage::ShowMessage(array("MESSAGE"=>GetMessage("rub_saved"), "TYPE"=>"OK"));

if($message)
  echo $message->Show();
elseif($rubric->LAST_ERROR!="")
  CAdminMessage::ShowMessage($rubric->LAST_ERROR);
?>

<?
// далее выводим собственно форму
?>
<form method="POST" Action="<?echo $APPLICATION->GetCurPage()?>" ENCTYPE="multipart/form-data" name="post_form">
<?// проверка идентификатора сессии ?>
<?echo bitrix_sessid_post();?>
<?
// отобразим заголовки закладок
$tabControl->Begin();
?>
<?
//********************
// первая закладка - форма редактирования параметров рассылки
//********************
$tabControl->BeginNextTab();
?>
  <tr>
    <td width="40%"><?echo GetMessage("rub_act")?></td>
    <td width="60%"><input type="checkbox" name="ACTIVE" value="Y"<?if($str_ACTIVE == "Y") echo " checked"?>></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_visible")?></td>
    <td><input type="checkbox" name="VISIBLE" value="Y"<?if($str_VISIBLE == "Y") echo " checked"?>></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_site")?></td>
    <td><?echo CLang::SelectBox("LID", $str_LID);?></td>
  </tr>
  <tr>
    <td><span class="required">*</span><?echo GetMessage("rub_name")?></td>
    <td><input type="text" name="NAME" value="<?echo $str_NAME;?>" size="30" maxlength="100"></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_sort")?></td>
    <td><input type="text" name="SORT" value="<?echo $str_SORT;?>" size="30"></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_desc")?></td>
    <td><textarea class="typearea" name="DESCRIPTION" cols="45" rows="5" wrap="VIRTUAL"><?echo $str_DESCRIPTION; ?></textarea></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_auto")?></td>
    <td><input type="checkbox" name="AUTO" value="Y"<?if($str_AUTO == "Y") echo " checked"?> OnClick="if(this.checked) tabControl.EnableTab('edit2'); else tabControl.DisableTab('edit2');"></td>
  </tr>
<?
//********************
// вторая закладка - параметры автоматической генерации рассылки
//********************
$tabControl->BeginNextTab();
?>
  <tr class="heading">
    <td colspan="2"><?echo GetMessage("rub_schedule")?></td>
  </tr>
  <tr>
    <td width="40%"><span class="required">*</span><?echo GetMessage("rub_last_executed"). " (".FORMAT_DATETIME."):"?></td>
    <td width="60%"><?echo CalendarDate("LAST_EXECUTED", $str_LAST_EXECUTED, "post_form", "20")?></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_dom")?></td>
    <td><input class="typeinput" type="text" name="DAYS_OF_MONTH" value="<?echo $str_DAYS_OF_MONTH;?>" size="30" maxlength="100"></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_dow")?></td>
    <td>
    <table cellspacing=1 cellpadding=0 border=0 class="internal">
    <?  $arDoW = array(
        "1"  => GetMessage("rubric_mon"),
        "2"  => GetMessage("rubric_tue"),
        "3"  => GetMessage("rubric_wed"),
        "4"  => GetMessage("rubric_thu"),
        "5"  => GetMessage("rubric_fri"),
        "6"  => GetMessage("rubric_sat"),
        "7"  => GetMessage("rubric_sun")
      );
    ?>
      <tr class="heading"><?foreach($arDoW as $strVal=>$strDoW):?>
        <td><?=$strDoW?></td>
        <?endforeach;?>
      </tr>
      <tr>
      <?foreach($arDoW as $strVal=>$strDoW):?>
        <td><input type="checkbox" name="DAYS_OF_WEEK[]" value="<?=$strVal?>"<?if(array_search($strVal, $DAYS_OF_WEEK) !== false) echo " checked"?>></td>
      <?endforeach;?>
      </tr>
    </table>
    </td>
  </tr>
  <tr>
    <td><span class="required">*</span><?echo GetMessage("rub_tod")?></td>
    <td><input type="text" name="TIMES_OF_DAY" value="<?echo $str_TIMES_OF_DAY;?>" size="30" maxlength="255"></td>
  </tr>
  <tr class="heading">
    <td colspan="2"><?echo GetMessage("rub_template")?></td>
  </tr>
<?
$arTemplates=CPostingTemplate::GetList();
if(count($arTemplates)>0):
?>
  <tr>
    <td><span class="required">*</span><?echo GetMessage("rub_templates")?></td>
    <td><table>
<?
  $i=0;
  foreach($arTemplates as $strTemplate):
    $arTemplate = CPostingTemplate::GetByID($strTemplate);
?>
    <tr>
      <td valign="top"><input type="radio" id="TEMPLATE<?=$i?>" name="TEMPLATE" value="<?=$arTemplate["PATH"]?>"<?if($str_TEMPLATE==$arTemplate["PATH"]) echo "checked"?>></td>
      <td>
        <label for="TEMPLATE<?=$i?>" title="<?=$arTemplate["DESCRIPTION"]?>"><?=(strlen($arTemplate["NAME"])>0?$arTemplate["NAME"]:GetMessage("rub_no_name"))?></label><br>
        <?if(IsModuleInstalled("fileman")):?>
          <a title="<?=GetMessage("rub_manage")?>" href="/bitrix/admin/fileman_admin.php?path=<?=urlencode("/".$arTemplate["PATH"])?>"><?=$arTemplate["PATH"]?></a>
        <?else:?>
          <?=$arTemplate["PATH"]?>
        <?endif?>
      </td>
    <?$i++?>
    </tr>
  <?endforeach;?>
    </table></td>
  </tr>
<?else:?>
  <tr>
    <td colspan="2"><?=GetMessage("rub_no_templates")?></td>
  </tr>
<?endif?>
  <tr class="heading">
    <td colspan="2"><?echo GetMessage("rub_post_fields")?></td>
  </tr>
  <tr>
    <td><span class="required">*</span><?echo GetMessage("rub_post_fields_from")?></td>
    <td><input type="text" name="FROM_FIELD" value="<?echo $str_FROM_FIELD;?>" size="30" maxlength="255"></td>
  </tr>
<?
// завершение формы - вывод кнопок сохранения изменений
$tabControl->Buttons(
  array(
    "disabled"=>($POST_RIGHT<"W"),
    "back_url"=>"rubric_admin.php?lang=".LANG,

  )
);
?>
<input type="hidden" name="lang" value="<?=LANG?>">
<?if($ID>0 && !$bCopy):?>
  <input type="hidden" name="ID" value="<?=$ID?>">
<?endif;?>
<?
// завершаем интерфейс закладок
$tabControl->End();
?>

<?
// дополнительное уведомление об ошибках - вывод иконки около поля, в котором возникла ошибка
$tabControl->ShowWarnings("post_form", $message);
?>

<?
// дополнительно: динамическая блокировка закладки, если требуется.
?>
<script language="JavaScript">
<!--
  if(document.post_form.AUTO.checked)
    tabControl.EnableTab('edit2');
  else
    tabControl.DisableTab('edit2');
//-->
</script>

<?
// информационная подсказка
echo BeginNote();?
>
<span class="required">*</span><?echo GetMessage("REQUIRED_FIELDS")?>
<?echo EndNote();?>

<?
// завершение страницы
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_admin.php");
?>


Создание собственных закладок форм

Разберем создание собственных закладок для многостраничных форм в административном интерфейсе.

Для подключения собственных закладок нужно

  1. Реализовать обработчики закладки в виде класса или набора функций;
  2. Зарегистрировать событие посредством AddeventHandler или RegisterModuleDependencies.

Класс должен содержать следующие методы:

  • Описательный метод OnInit(), возвращающий массив с наименованиями или callback-массивами остальных методов. Массив должен содержать следующие ключи:
    • TABSET - идентификатор набора закладок;
    • GetTabs - callback-массив вызова метода, описывающего закладки;
    • ShowTab - callback-массив вызова метода, возвращающего HTML-код страницы формы по идентификатору закладки;
    • Action - callback-массив вызова метода, обрабатывающего данные, полученные из формы;
    • Check - callback-массив вызова метода, проверяющего данные, полученные из формы.
  • Все методы, перечисленные в списке, возвращаемом OnInit()
  • Любые дополнительные методы, используемые в вышеперечисленных.

Примерная структура класса, реализующего собственные закладки:

<?
class CCustomOETabs
{
  function OnInit()
  {
    return array(
      "TABSET" => "YYY",
      "GetTabs" => array("CCustomOETabs", "GetTabs"),
      "ShowTab" => array("CCustomOETabs", "ShowTab"),
      "Action" => array("CCustomOETabs", "Action"),
      "Check" => array("CCustomOETabs", "Check"),
    );
  }

  function Action($arArgs)
  {
     // Основные данные сохранены. Делаем тут действия.
     // Возвращаем True в случае успеха и False - в случае ошибки
     // В случае ошибки делаем так же $GLOBALS["APPLICATION"]-> ThrowException("Ошибка!!!", "ERROR");
  }

  function Check($arArgs)
  {
     // Основные данные ещё не сохранялись. Делаем тут разные чеки.
     // Возвращаем True, если можно все схранять, иначе False
     // В случае False делаем так же $GLOBALS["APPLICATION"]-> ThrowException("Ошибка!!!", "ERROR");
  }

  function GetTabs($arArgs)
  {
     // SORT - после какого стандартного таба вставлять. Не установлено - после последнего
    $arTabs = array(
      array("DIV" => "edit1", "TAB" => "Собственная закладка 1", "ICON" => "sale", "TITLE" => "Собственная закладка 1", "SORT" => 1),
    );
    return $arTabs;
  }

  function ShowTab($divName, $arArgs, $bVarsFromForm)
  {
    if ($divName == "edit1")
    {
      ?>
      <tr>
        <td width="40%">Собственное поле 1:</td>
        <td width="60%"><input type="text" name="custom_field_1"></td>
      </tr>
      <?
    }
  }
}

Все методы, кроме ShowTab() получают на вход массив аргументов, задаваемых при помощи конструктора класса CAdminTabEngine или при помощи метода CAdminTabEngine::SetArgs(). Формат масссива, который должен возвращать метод GetTabs описан здесь.


Создание собственных закладок форм

Классы

  • CAdminContextMenu
  • CAdminException
  • CAdminFilter
  • CAdminList
  • CAdminListRow
  • CAdminMessage
  • CAdminResult
  • CAdminSorting
  • CAdminTabControl
  • CAdminTabEngine


Класс CAdminContextMenu

CAdminContextMenu - меню на страницах панели управления.

Методы для работы с фильтром

Метод | Описание
CAdminContextMenu | Конструктор класса.
Show | Вывод меню.

Пример работы с меню

Работа с меню описана в руководстве по созданию административных страниц.


Конструктор CAdminContextMenu

CAdminContextMenu::Конструктор CAdminContextMenu

object
CAdminContextMenu(
    array $arMenu
)

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

Ключ | Описание
TEXT | Текст пункта меню.
TITLE | Текст всплывающей подсказки пункта меню.
LINK | Ссылка на кнопке.
LINK_PARAM | Дополнительные параметры ссылки (напрямую подставляются в тэг <A>).
ICON | CSS-класс иконки действия.
HTML | Задание пункта меню напрямую HTML-кодом.
SEPARATOR | Разделитель между пунктами меню (true|false).
NEWBAR | Новый блок элементов меню (true|false).
MENU | Создание выпадающего подменю. Значение задается аналогично контекстному меню строки таблицы.

Пример

// сформируем меню из одного пункта - добавление рассылки
$aContext = array(
  array(
    "TEXT"=>GetMessage("POST_ADD"),
    "LINK"=>"rubric_edit.php?lang=".LANG,
    "TITLE"=>GetMessage("POST_ADD_TITLE"),
    "ICON"=>"btn_new",
  ),
);

// и прикрепим его к списку
$oMenu = new CAdminContextMenu($aContext);
$oMenu->Show();


Show

CAdminContextMenu::Show

void
CAdminContextMenu::Show(
)

Выводит предварительно сконфгурированное меню.

Пример

// сформируем меню из одного пункта - добавление рассылки
$aContext = array(
  array(
    "TEXT"=>GetMessage("POST_ADD"),
    "LINK"=>"rubric_edit.php?lang=".LANG,
    "TITLE"=>GetMessage("POST_ADD_TITLE"),
    "ICON"=>"btn_new",
  ),
);

// и прикрепим его к списку
$oMenu = new CAdminContextMenu($aContext);
$oMenu->Show();


Класс CAdminException

CAdminException - класс-наследник, расширяющий возможности класса CApplicationException для административного использования.

Изменения связаны с возможностью обработки множественных сообщений об ошибках.

Методы

Метод | Описание
CAdminException | Конструктор класса.
GetMessages | Получение списка сообщений об ошибках.
AddMessage | Добавление сообщения об ошибке в список.


Конструктор CAdminException

CAdminException::Конструктор CAdminException

object
CAdminException(
  array $arMessages[,
  string $id = false]
)

Конструктор класса принимает на вход массив сообщений. Каждое сообщение представляет собой ассоциативный массив вида array("id"=>"Идентификатор_ошибки", "text" => "Текст_ошибки"). Второй параметр вызова конструктора - $id - аналогичен такому же параметру CApplicationException и передается всквозную.


AddMessage

CAdminException::AddMessage

void
CAdminException::AddMessage(
  array $arMessage
)

Добавляет сообщение к списку ошибок, зарегистрированных в экземпляре класса. Сообщение принимается в формате array("id"=>"Идентификатор_ошибки", "text" => "Текст_ошибки").


GetMessages

CAdminException::GetMessages

array
CAdminException::GetMessages(
)

Возвращает массив ошибок, переданных экземпляру класса.


Класс CAdminFilter

CAdminFilter - класс для работы с фильтром списка результатов на странице панели управления.

Методы для работы с фильтром

Метод | Описание
CAdminFilter | Конструктор класса.
Begin | Вывод шапки фильтра.
Buttons | Вывод кнопок фильтра.
End | Завершение вывода фильтра.

Пример работы с фильтром

Предварительная работа с фильтром осуществляется следующим образом:

// проверку значений фильтра для удобства вынесем в отдельную функцию
function CheckFilter()
{
    global $FilterArr, $lAdmin;
    foreach ($FilterArr as $f) global $$f;

    /*	здесь проверяем значения переменных $find_имя и, в случае возникновения ошибки, вызываем $lAdmin->AddFilterError("текст_ошибки"). */

    return count($lAdmin->arFilterErrors) == 0; // если ошибки есть, вернем false;
}

// опишем элементы фильтра
$FilterArr = Array(
    "find_id",
    "find_lid",
    "find_active",
    "find_visible",
    "find_auto",
    );

// инициализируем фильтр
$lAdmin->InitFilter($FilterArr);

// если все значения фильтра корректны, обработаем его
if (CheckFilter())
{
    // создадим массив фильтрации для выборки CRubric::GetList() на основе значений фильтра
    $arFilter = Array(
        "ID"		=> $find_id,
        "LID"		=> $find_lid,
        "ACTIVE"	=> $find_active,
        "VISIBLE"	=> $find_visible,
        "AUTO"		=> $find_auto,
    );
}

// далее, полученный массив передаем в CRubric::GetList()

Для вывода фильтра требуется сперва создать экземпляр класса CAdminFilter, передав ему список полей, а затем сформировать форму фильтра "вручную".

// создадим объект фильтра
$oFilter = new CAdminFilter(
  $sTableID."_filter",
  array(
    "ID",
    GetMessage("rub_f_site"),
    GetMessage("rub_f_active"),
    GetMessage("rub_f_public"),
    GetMessage("rub_f_auto"),
  )
);
?>
<form name="find_form" method="get" action="<?echo $APPLICATION->GetCurPage();?>">
<?$oFilter->Begin();?>
<tr>
  <td><?="ID"?>:</td>
  <td>
    <input type="text" name="find_id" size="47" value="<?echo htmlspecialchars($find_id)?>">
  </td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_site").":"?></td>
  <td><input type="text" name="find_lid" size="47" value="<?echo htmlspecialchars($find_lid)?>"></td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_active")?>:</td>
  <td>
    <?
    $arr = array(
      "reference" => array(
        GetMessage("POST_YES"),
        GetMessage("POST_NO"),
      ),
      "reference_id" => array(
        "Y",
        "N",
      )
    );
    echo SelectBoxFromArray("find_active", $arr, $find_active, GetMessage("POST_ALL"), "");
    ?>
  </td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_public")?>:</td>
  <td><?echo SelectBoxFromArray("find_visible", $arr, $find_visible, GetMessage("POST_ALL"), "");?></td>
</tr>
<tr>
  <td><?=GetMessage("rub_f_auto")?>:</td>
  <td><?echo SelectBoxFromArray("find_auto", $arr, $find_auto, GetMessage("POST_ALL"), "");?></td>
</tr>
<?
$oFilter->Buttons(array("table_id"=>$sTableID,"url"=>$APPLICATION->GetCurPage(),"form"=>"find_form"));
$oFilter->End();
?>
</form>


Конструктор CAdminFilter

CAdminFilter::Конструктор CAdminFilter

object
CAdminFilter(
    string $ID[,
    array $arPopup = false]
)

Конструктор класса фильтра.

Параметры

Параметр | Описание
ID | Идентификатор фильтра, уникальный в пределах страницы.
arPopup | Массив названий полей фильтра.


Begin

CAdminFilter::Begin

void
CAdminFilter::Begin(
)

Выводит заголовок формы фильтра.


Buttons

CAdminFilter::Buttons

void
CAdminFilter::Buttons(
  mixed $arParams = false
)

Кнопки управления формы фильтра.

Параметры

Параметр Описание
arParams Необязательный массив параметров. Возможные ключи массива:
  • url - путь к странице-обработчику фильтра. По умолчанию - текущая страница;
  • table_id - идентификатор таблицы списка;
  • report - используется на страницах с отчетами. По умолчанию - false.


End

CAdminFilter::End

void
CAdminFilter::End(
)

Выводит заголовок формы фильтра.


Класс CAdminList

CAdminList - класс для работы со списком результатов на странице панели управления.

Методы для работы со списком

Метод | Описание
CAdminList | Конструктор класса.
AddHeaders | Установка заголовков таблицы списка.
AddAdminContextMenu | Установка дополнительного административного меню.
IsUpdated | Функция, указывающая, были ли произведены какие-либо изменения строк таблицы в режиме редактирования списка.
EditAction | Функция возвращает true, если было произведено редактирование строк таблицы и требуется сохранение изменений.
GroupAction | Функция возвращает true, если были совершены групповые операции над строками таблицы и требуется сохранение изменений.
ActionRedirect | Метод возвращает JavaScript-вызов, осуществляющий переадресацию пользователя на заданную страницу.
ActionAjaxReload | Метод возвращает JavaScript-вызов, осуществляющий динамическое обновление строк таблицы списка с использованием заданной ссылки.
ActionDoGroup | Метод возвращает JavaScript-вызов, осуществляющий динамическое обновление строк таблицы списка с использованием автоматически сгенерированной ссылки на основе заданных параметров.
ActionPost | Метод возвращает JavaScript-вызов, осуществляющий переадресацию пользователя на заданную страницу методом POST.
CheckListMode | Метод проверяет требуемый тип вывода списка и осуществляет вывод, если требуется вывод списка посредством AJAX или в виде Excel-таблицы.
InitFilter | Инициализация фильтра списка.
AddRow | Добавление новой строки в список.
AddFooter | Вставка резюме списка.
Display | Вывод таблицы со списком.
AddGroupActionTable | Настройка групповых действий над элементами списка.
DisplayList | Обновление списка из скрипта, вызываемого посредством AJAX.
AddUpdateError | Добавление сообщения в список ошибок, возникших при сохранении обновленных результатов.
AddGroupError | Добавление сообщения в список ошибок, возникших в результате групповых действий над элементами.
AddFilterError | Добавление сообщения в список ошибок, возникших в результате обработки данных фильтра.

Примеры

Подробный пример описания создания страницы со списком можно увидеть здесь.


Конструктор CAdminList

CAdminList::Конструктор CAdminList

object
CAdminList(
    string $ID[,
    mixed $oSort = false]
)

Конструктор класса списка.

Параметры

Параметр | Описание
ID | Уникальный на странице идентификатор таблицы списка.
oSort | Экземпляр класса CAdminSorting. Необязательный параметр.


ActionAjaxReload

CAdminList::ActionAjaxReload

string
CAdminList::ActionAjaxReload(
  string $url
)

Метод возвращает строку, которая представляет собой JavaScript-вызов для динамического обновления таблицы списка с использованием заданного URL. Ссылка на скрипт, осуществляющий обновление, задается первым и единственным параметром вызова метода. Скрипт обновления может использовать метод CAdminList::CheckListMode() для проверки типа действия.

Пример

Формирование административного меню списка файлов в модуле "Управление структурой" (fileman)

$defaultEdit = COption::GetOptionString("fileman", "default_edit", "text");

if($FILE_ACCESS > "U")
{
  $arDDMenu = array();

  $isB = false;
  $dbRes = CGroup::GetDropDownList();
  while ($arRes = $dbRes->Fetch())
  {
    if($show_perms_for == $arRes["REFERENCE_ID"])
      $isB = true;

    $arDDMenu[] = array(
      "TEXT" => $arRes["REFERENCE"],
      "ACTION" => $lAdmin->ActionAjaxReload("fileman_admin.php?".$addUrl.
                                           "&site=".UrlEncode($site)."&path=".UrlEncode($path).
                                           "&show_perms_for=".$arRes["REFERENCE_ID"]).';return false;',
      "ICON" =>  ($show_perms_for == $arRes["REFERENCE_ID"] ? "checked" : "" ),
    );
  }

  $arDDMenu[] = array(
    "TEXT" => GetMessage("FILEMAN_ADM_CUR_USER"),
    "ACTION" => $lAdmin->ActionAjaxReload("fileman_admin.php?".$addUrl.
                                                "&site=".UrlEncode($site)."&path=".
                                                UrlEncode($path)."&show_perms_for=0").';return false;',
    "ICON" =>  (!$isB ? "checked" : "" ),
  );

  $aContext = array(
    array(
      "TEXT" => GetMessage("FILEMAN_ADMIN_NEW_FOLDER"),
      "ICON" => "btn_new_folder",
      "LINK" => "fileman_newfolder.php?".$addUrl."&site=".$site."&path=".UrlEncode($path)."",
      "TITLE" => GetMessage("FILEMAN_ADMIN_NEW_FOLDER")
    ),
    array(
      "TEXT" => GetMessage("FILEMAN_ADMIN_NEW_FILE"),
      "ICON" => "btn_new_file",
      "LINK" =>
        ($defaultEdit == 'html'?
          "fileman_html_edit.php?".$addUrl."&site=".$site."&path=".UrlEncode($path)."&new=y"
        :
          (
          $defaultEdit == 'php' && $USER->IsAdmin()?
            "fileman_file_edit.php?".$addUrl."&site=".$site."&full_src=Y&path=".UrlEncode($path)."&new=y"
          :
            "fileman_file_edit.php?".$addUrl."&site=".$site."&path=".UrlEncode($path)."&new=y"
          )
        ),
      "TITLE" => GetMessage("FILEMAN_ADMIN_NEW_FILE")
    ),
    array(
      "TEXT" => GetMessage("FILEMAN_ADMIN_FILE_UPLOAD"),
      "ICON" => "btn_upload",
      "LINK" => "fileman_file_upload.php?".$addUrl."&site=".$site."&path=".UrlEncode($path)."",
      "TITLE" => GetMessage("FILEMAN_ADMIN_FILE_UPLOAD")
    ),
    array(
      "TEXT" => GetMessage("FILEMAN_ADMIN_MENU_ADD"),
      "ICON" => "btn_new_menu",
      "LINK" => "fileman_menu_edit.php?".$addUrl."&site=".$site."&path=".UrlEncode($path)."&new=y",
      "TITLE" => GetMessage("FILEMAN_ADMIN_MENU_ADD")
    ),
    array(
      "NEWBAR" => True
    ),
    array(
      "TEXT" => GetMessage("FILEMAN_ADMIN_FOLDER_PROP"),
      "LINK" => "fileman_folder.php?".$addUrl."&site=".$site."&path=".UrlEncode($path)."",
      "ICON" => "btn_folder_prop",
      "TITLE" => GetMessage("FILEMAN_ADMIN_FOLDER_PROP")
    ),
    array(
      "TEXT" => GetMessage('FILEMAN_SHOW_PRM_FOR'),
      "TITLE" => GetMessage('FILEMAN_SHOW_PRM_FOR'),
      "MENU" => $arDDMenu
    ),
    array(
      "NEWBAR" => True
    ),
  );
}


ActionDoGroup

CAdminList::ActionDoGroup

string
CAdminList::ActionDoGroup(
  string $ID,
  string $action_id[,
  string $add_params='']
)

Метод возвращает строку, которая представляет собой JavaScript-вызов для динамического обновления таблицы списка с текущего URL с заданными параметрами. Скрипт обновления может использовать метод CAdminList::CheckListMode() для проверки типа действия.

Параметры

Параметр | Описание
ID | Идентификатор таблицы списка.
action_id | Идентфикатор требуемого действия.
add_params | Сформированная строка дополнительных параметров GET-запроса.

Пример

  // создаем строку. результат - экземпляр класса CAdminListRow
  $row =& $lAdmin->AddRow($f_ID, $arRes);

  // сформируем контекстное меню
  $arActions = Array();

  // удаление элемента
  if ($POST_RIGHT>="W")
    $arActions[] = array(
      "ICON"=>"delete",
      "TEXT"=>GetMessage("rub_del"),
      "ACTION"=>"if(confirm('".GetMessage('rub_del_conf')."')) ".$lAdmin->ActionDoGroup($f_ID, "delete")
    );
  // применим контекстное меню к строке
  $row->AddActions($arActions);


ActionPost

CAdminList::ActionPost

string
CAdminList::ActionPost(
  string $url
)

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

Пример

  // создаем строку. результат - экземпляр класса CAdminListRow
  $row =& $lAdmin->AddRow($f_ID, $arRes);

  // сформируем контекстное меню
  $arActions = Array();

  if ($Elem["PERMISSION"] > "R")
  {
    $arActions[] = array("SEPARATOR" => true);
    $arActions[] = array(
      "ICON" => "rename",
      "TEXT" => GetMessage("FILEMAN_RENAME_SAVE"),
      "ACTION" => 'setCheckbox(\''.$f_NAME.'\'); if('.$lAdmin->table_id.'.IsActionEnabled(\'edit\')){document.forms[\'form_'.$lAdmin->table_id.'\'].elements[\'action_button\'].value=\'edit\'; '.$lAdmin->ActionPost().'}'
    );
  }

  // применим контекстное меню к строке
  $row->AddActions($arActions);


ActionRedirect

CAdminList::ActionRedirect

string
CAdminList::ActionRedirect(
  string $url
)

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

Пример

while($arRes = $rsData->NavNext(true, "f_")):

  // создаем строку. результат - экземпляр класса CAdminListRow
  $row =& $lAdmin->AddRow($f_ID, $arRes);

  // далее настроим отображение значений при просмотре и редактировании списка

  // параметр NAME будет редактироваться как текст, а отображаться ссылкой
  $row->AddInputField("NAME", array("size"=>20));
  $row->AddViewField("NAME", '<a href="rubric_edit.php?ID='.$f_ID.'&lang='.LANG.'">'.$f_NAME.'</a>');

  // параметр LID будет редактироваться в виде выпадающего списка языков
  $row->AddEditField("LID", CLang::SelectBox("LID", $f_LID));

  // параметр SORT будет редактироваться текстом
  $row->AddInputField("SORT", array("size"=>20));

  // флаги ACTIVE и VISIBLE будут редактироваться чекбоксами
  $row->AddCheckField("ACTIVE");
  $row->AddCheckField("VISIBLE");

  // параметр AUTO будет отображаться в виде "Да" или "Нет", полужирным при редактировании
  $row->AddViewField("AUTO", $f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"));
  $row->AddEditField("AUTO", "<b>".($f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"))."</b>");

  // сформируем контекстное меню
  $arActions = Array();

  // редактирование элемента
  $arActions[] = array(
    "ICON"=>"edit",
    "DEFAULT"=>true,
    "TEXT"=>GetMessage("rub_edit"),
    "ACTION"=>$lAdmin->ActionRedirect("rubric_edit.php?ID=".$f_ID)
  );

  // удаление элемента
  if ($POST_RIGHT>="W")
    $arActions[] = array(
      "ICON"=>"delete",
      "TEXT"=>GetMessage("rub_del"),
      "ACTION"=>"if(confirm('".GetMessage('rub_del_conf')."')) ".$lAdmin->ActionDoGroup($f_ID, "delete")
    );

  // вставим разделитель
  $arActions[] = array("SEPARATOR"=>true);

  // проверка шаблона для автогенерируемых рассылок
  if (strlen($f_TEMPLATE)>0 && $f_AUTO=="Y")
    $arActions[] = array(
      "ICON"=>"",
      "TEXT"=>GetMessage("rub_check"),
      "ACTION"=>$lAdmin->ActionRedirect("template_test.php?ID=".$f_ID)
    );

  // если последний элемент - разделитель, почистим мусор.
  if(is_set($arActions[count($arActions)-1], "SEPARATOR"))
    unset($arActions[count($arActions)-1]);

  // применим контекстное меню к строке
  $row->AddActions($arActions);

endwhile;


AddAdminContextMenu

CAdminList::AddAdminContextMenu

void
CAdminList::AddAdminContextMenu([
  array $aMenu = array(),
  bool $bShowExcel = true,
  bool $bShowSettings = true
])

Формирование административного меню страницы.

Параметры

Параметр | Описание
aMenu | Описательный массив меню. Подробнее см. CAdminContextMenu
bShowExcel | Добавлять ли в меню кнопку экспорта списка в MS Excel. Необязательный параметр. По умолчанию - true. Кнопка будет добавлена в конец последнего блока элементов меню.
bShowExcel | Добавлять ли в меню редактирования настроек списка. Необязательный параметр. По умолчанию - true. Кнопка будет добавлена в конец последнего блока элементов меню.


AddFilterError

CAdminList::AddFilterError

void
CAdminList::AddFilterError(
  string $strError
)

Метод служит для добавления в список ошибок, возникших в процессе обработки групповых действий над строками таблицы.

Параметры:

Параметр | Описание
strError | Текст ошибки.


AddFooter

CAdminList::AddFooter

void
CAdminList::AddFooter(
  array $arFooter
)

Метод добавляет строку резюме к таблице списка. Резюме таблицы формируется в виде массива, элементами которого являются ассоциативные массивы с ключами "title" - название параметра - и "value" - значение параметра. Кроме того, ассоциативный массив может содержать элемент с ключом "counter" и значением true. В этом случае, элемент резюме будет счетчиком отмеченных элементов таблицы и значение будет динамически изменяться.

Пример

// резюме таблицы
$lAdmin->AddFooter(
  array(
    array("title"=>GetMessage("MAIN_ADMIN_LIST_SELECTED"), "value"=>$rsData->SelectedRowsCount()), // кол-во элементов
    array("counter"=>true, "title"=>GetMessage("MAIN_ADMIN_LIST_CHECKED"), "value"=>"0"), // счетчик выбранных элементов
  )
);


AddGroupActionTable

CAdminList::AddGroupActionTable

void
CAdminList::AddGroupActionTable(
  array $arActions[,
  array $arParams = array()]
)

Метод служит для задания списка доступных групповых операций над элементами списка. Список возможных групповых операций задается в виде массива элементов вида "идентификатор_операции"=>"название_операции".

Формат входных параметров

Список действий

Список действий $arActions может задаваться двумя вариантами. Первый - упрощённый - в виде ассоциативного массива, содержащего пары "идентификатор_действия" => "название_пункта_меню". В этом случае пункт меню будет представлять собой ссылку на текущую страницу с дополнительным GET-параметром action=идентфикатор_действия, который должен обрабатываться на этапе сохранения изменений списка.

Во втором варианте - расширенном - каждый элемент массива $arActions представляет собой ассоциативный массив, содержащий следующие ключи:

Ключ | Описание
action | javascript-код, который будет выполнен при выборе пункта меню
type значение, описывающее внешний вид ссылки действия. Может принимать следующие значения:
  • button - действие будет отображаться в виде кнопки;
  • html - ссылка с текстом, определяемым в параметре value.
Если параметр содержит другое значение, или не определён, то действие будет выводиться в виде элемента выпадающего списка действий.
value | значение определяет подпись действия ("название_пункта_меню" упрощённого варианта).

Оба типа задания списка действий можно использовать в одном массиве $arActions.

arParams

Настройка параметров действий представляет собой ассоциативный массив, который может содержать следующие ключи:

  • disable_action_target флаг, определяющий, будет ли появляться чекбокс "применить ко всем элементам";
  • select_onchange - javascript, который будет выполнен при выборе действия из выпадающего списка.

Пример (упрощённый вариант):

$lAdmin->AddGroupActionTable(Array(
  "delete"    => GetMessage("MAIN_ADMIN_LIST_DELETE"),
  "activate"  => GetMessage("MAIN_ADMIN_LIST_ACTIVATE"),
  "deactivate"=> GetMessage("MAIN_ADMIN_LIST_DEACTIVATE"),
));

Пример (расширенный вариант):

// показ формы с кнопками добавления, ...
$lAdmin->AddGroupActionTable(
  array(
    "delete" => GetMessage("MAIN_ADMIN_LIST_DELETE"),
    "access" => array(
      "action" => "setAccess('".str_replace("'", "\'", $site)."', '".str_replace("'", "\'", $path)."')",
      "value" => "access",
      "name" => GetMessage('FILEMAN_ADMIN_ACCESS_CMD')
    ),
    "copy" => GetMessage("FILEMAN_ADM_COPY"),
    "move" => GetMessage("FILEMAN_ADM_MOVE"),
    "copy2" => array(
      "type" => "html",
      "value" => " ".GetMessage("FILEMAN_ADMIN_IN")." "
    ),
    "copy1" => array(
      "type" => "html",
      "value" => $strHTML
    ),
  ),
  array("select_onchange"=>"this.form.copy_to_button.disabled=this.form.copy_to.disabled=!(this[this.selectedIndex].value == 'copy' || this[this.selectedIndex].value == 'move')")
);


AddGroupError

CAdminList::AddGroupError

void
CAdminList::AddGroupError(
  string $strError[,
  mixed $ID = false]
)

Метод служит для добавления в список ошибок, возникших в процессе обработки групповых действий над строками таблицы.

Параметры:

Параметр | Описание
strError | Текст ошибки.
ID | Идентификатор стоки, в которой возникла ошибка.


AddHeaders

CAdminList::AddHeaders

void
CAdminList::AddHeaders(
  array $aHeaders
)

Формирование списка колонок таблицы списка. В качестве параметра указывается массив колонок таблицы. Каждая колонка описывается массивом, содержащим следующие ключи:

Ключ | Описание
id | Идентификатор колонки.
content | Заголовок колонки.
sort | Значение параметра GET-запроса для сортировки.
default | Параметр, показывающий, будет ли колонка по умолчанию отображаться в списке (true|false)

Пример

$lAdmin->AddHeaders(array(
  array(  "id"    =>"ID",
    "content"  =>"ID",
    "sort"     =>"id",
    "default"  =>true,
  ),
  array(  "id"    =>"NAME",
    "content"  =>GetMessage("rub_name"),
    "sort"     =>"name",
    "default"  =>true,
  ),
  array(  "id"    =>"LID",
    "content"  =>GetMessage("rub_site"),
    "sort"     =>"lid",
    "default"  =>true,
  ),
  array(  "id"    =>"SORT",
    "content"  =>GetMessage("rub_sort"),
    "sort"     =>"sort",
    "align"    =>"right",
    "default"  =>true,
  ),
  array(  "id"    =>"ACTIVE",
    "content"  =>GetMessage("rub_act"),
    "sort"     =>"act",
    "default"  =>true,
  ),
  array(  "id"    =>"VISIBLE",
    "content"  =>GetMessage("rub_visible"),
    "sort"     =>"visible",
    "default"  =>true,
  ),
  array(  "id"    =>"AUTO",
    "content"  =>GetMessage("rub_auto"),
    "sort"     =>"auto",
    "default"  =>true,
  ),
  array(  "id"    =>"LAST_EXECUTED",
    "content"  =>GetMessage("rub_last_exec"),
    "sort"     =>"last_executed",
    "default"  =>true,
  ),
));


AddRow

CAdminList::AddRow

object CAdminListRow
CAdminList::&AddRow(
  string $ID[,
  array $arRes = Array(),
  mixed $link = false,
  mixed $title = false]
)

Функция добавляет новую строку к таблице. Строка описывается экземпляром класса CAdminListRow. Метод инициализирует новый экземпляр класса и возвращает ссылку на него.

Параметры

Параметр | Описание
ID | Уникальный идентификатор строки.
arRes | Список значений в виде массива "параметр"=>"значение".
link | Ссылка, принимаемая в качестве действия по умолчанию для строки.
title | Текст всплывающей подсказки строки.

Пример

while($arRes = $rsData->NavNext(true, "f_")):

  // создаем строку. результат - экземпляр класса CAdminListRow
  $row =& $lAdmin->AddRow($f_ID, $arRes);

  // далее настроим отображение значений при просмотре и редактировании списка

  // параметр NAME будет редактироваться как текст, а отображаться ссылкой
  $row->AddInputField("NAME", array("size"=>20));
  $row->AddViewField("NAME", '<a href="rubric_edit.php?ID='.$f_ID.'&lang='.LANG.'">'.$f_NAME.'</a>');

  // параметр LID будет редактироваться в виде выпадающего списка языков
  $row->AddEditField("LID", CLang::SelectBox("LID", $f_LID));

  // параметр SORT будет редактироваться текстом
  $row->AddInputField("SORT", array("size"=>20));

  // флаги ACTIVE и VISIBLE будут редактироваться чекбоксами
  $row->AddCheckField("ACTIVE");
  $row->AddCheckField("VISIBLE");

  // параметр AUTO будет отображаться в виде "Да" или "Нет", полужирным при редактировании
  $row->AddViewField("AUTO", $f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"));
  $row->AddEditField("AUTO", "<b>".($f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"))."</b>");

  // сформируем контекстное меню
  $arActions = Array();

  // редактирование элемента
  $arActions[] = array(
    "ICON"=>"edit",
    "DEFAULT"=>true,
    "TEXT"=>GetMessage("rub_edit"),
    "ACTION"=>$lAdmin->ActionRedirect("rubric_edit.php?ID=".$f_ID)
  );

  // удаление элемента
  if ($POST_RIGHT>="W")
    $arActions[] = array(
      "ICON"=>"delete",
      "TEXT"=>GetMessage("rub_del"),
      "ACTION"=>"if(confirm('".GetMessage('rub_del_conf')."')) ".$lAdmin->ActionDoGroup($f_ID, "delete")
    );

  // вставим разделитель
  $arActions[] = array("SEPARATOR"=>true);

  // проверка шаблона для автогенерируемых рассылок
  if (strlen($f_TEMPLATE)>0 && $f_AUTO=="Y")
    $arActions[] = array(
      "ICON"=>"",
      "TEXT"=>GetMessage("rub_check"),
      "ACTION"=>$lAdmin->ActionRedirect("template_test.php?ID=".$f_ID)
    );

  // если последний элемент - разделитель, почистим мусор.
  if(is_set($arActions[count($arActions)-1], "SEPARATOR"))
    unset($arActions[count($arActions)-1]);

  // применим контекстное меню к строке
  $row->AddActions($arActions);

endwhile;


AddUpdateError

CAdminList::AddUpdateError

void
CAdminList::AddUpdateError(
  string $strError[,
  mixed $ID = false]
)

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

Параметры:

Параметр | Описание
strError | Текст ошибки.
ID | Идентификатор стоки, в которой возникла ошибка.


CheckListMode

CAdminList::CheckListMode

void
CAdminList::CheckListMode(
)

Метод проверяет требуемый тип вывода списка. Если требуется вывод списка посредством AJAX или в виде Excel-таблицы, то выполнение скрипта прерывается и вывод списка осуществляется внутри метода.


Display

CAdminList::Display

void
CAdminList::Display(
)

Метод осуществляет вывод предварительно подготовленного списка.


DisplayList

CAdminList::DisplayList

void
CAdminList::DisplayList(
)

Метод осуществляет вывод предварительно подготовленного списка. В отличие от CAdminList::Display() добавляет к списку все "обрамление" - кнопки, вывод из AJAX и т.д.


EditAction

CAdminList::EditAction

bool
CAdminList::EditAction(
)

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

Пример

// сохранение отредактированных элементов
if($lAdmin->EditAction() && $POST_RIGHT=="W")
{
    // пройдем по списку переданных элементов
    foreach($FIELDS as $ID=>$arFields)
    {
        // если элементы списка не изменялись - не будем совершать никаких действий
        if(!$lAdmin->EditAction($ID))
            continue;

        // сохраним изменения каждого элемента
        $DB->StartTransaction();
        $ID = IntVal($ID);
        $cData = new CRubric;
        if(($rsData = $cData->GetByID($ID)) && ($arData = $rsData->Fetch()))
        {
            foreach($arFields as $key=>$value)
                $arData[$key]=$value;
            if(!$cData->Update($ID, $arData))
            {
                $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".$cData->LAST_ERROR, $ID);
                $DB->Rollback();
            }
        }
        else
        {
            $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
            $DB->Rollback();
        }
        $DB->Commit();
    }
}


GroupAction

CAdminList::GroupAction

bool
CAdminList::GroupAction(
)

Функция возвращает true, если были совершены групповые операции над строками таблицы и требуется сохранение изменений.

Пример

// обработка одиночных и групповых действий
if(($arID = $lAdmin->GroupAction()) && $POST_RIGHT=="W")
{
    // если выбрано "Для всех элементов"
    if($_REQUEST['action_target']=='selected')
    {
        $cData = new CRubric;
        $rsData = $cData->GetList(array($by=>$order), $arFilter);
        while($arRes = $rsData->Fetch())
            $arID[] = $arRes['ID'];
    }

    // пройдем по списку элементов
    foreach($arID as $ID)
    {
        if(strlen($ID)<=0)
            continue;
           $ID = IntVal($ID);

        // для каждого элемента совершим требуемое действие
        switch($_REQUEST['action'])
        {
        // удаление
        case "delete":
            @set_time_limit(0);
            $DB->StartTransaction();
            if(!CRubric::Delete($ID))
            {
                $DB->Rollback();
                $lAdmin->AddGroupError(GetMessage("rub_del_err"), $ID);
            }
            $DB->Commit();
            break;

        // активация/деактивация
        case "activate":
        case "deactivate":
            $cData = new CRubric;
            if(($rsData = $cData->GetByID($ID)) && ($arFields = $rsData->Fetch()))
            {
                $arFields["ACTIVE"]=($_REQUEST['action']=="activate"?"Y":"N");
                if(!$cData->Update($ID, $arFields))
                    $lAdmin->AddGroupError(GetMessage("rub_save_error").$cData->LAST_ERROR, $ID);
            }
            else
                $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
            break;
        }

    }
}


InitFilter

CAdminList::InitFilter

void
CAdminList::InitFilter(
  array $arFilterFields
)

Метод инициализирует фильтр. Пример создания административной страницы с фильтром подробно разобран здесь.


IsUpdated

CAdminList::IsUpdated

bool
CAdminList::IsUpdated(
  string $ID
)

Функция возвращает true, если какие-либо из строк таблицы были отредактированы при операции редактирования значений элементов списка. В качестве параметра указывается идентификатор таблицы.

Пример

// сохранение отредактированных элементов
if($lAdmin->EditAction() && $POST_RIGHT=="W")
{
    // пройдем по списку переданных элементов
    foreach($FIELDS as $ID=>$arFields)
    {
        // если элементы списка не изменялись - не будем совершать никаких действий
        if(!$lAdmin->IsUpdated($ID))
            continue;

        // сохраним изменения каждого элемента
        $DB->StartTransaction();
        $ID = IntVal($ID);
        $cData = new CRubric;
        if(($rsData = $cData->GetByID($ID)) && ($arData = $rsData->Fetch()))
        {
            foreach($arFields as $key=>$value)
                $arData[$key]=$value;
            if(!$cData->Update($ID, $arData))
            {
                $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".$cData->LAST_ERROR, $ID);
                $DB->Rollback();
            }
        }
        else
        {
            $lAdmin->AddGroupError(GetMessage("rub_save_error")." ".GetMessage("rub_no_rubric"), $ID);
            $DB->Rollback();
        }
        $DB->Commit();
    }
}


Класс CAdminListRow

CAdminListRow - класс для работы со строками списка результатов на странице панели управления. Экземпляр класса генерируется в методе CAdminList::AddRow(), который возвращает ссылку на него.

Методы для работы со строками

Методы класса позволяют настроить способ отображения ячеек строки в режимах просмотра и редактирования списка.

Метод | Описание
AddField | значение ячейки будет отображаться в заданном виде при просмотре и при редактировании списка.
AddCheckField | значение ячейки будет редактироваться в виде чекбокса.
AddSelectField | значение ячейки будет редактироваться в виде выпадающего списка.
AddInputField | значение ячейки будет редактироваться в виде текстового поля с заданным набором атрибутов.
AddCalendarField | значение ячейки будет редактироваться в виде поля для ввода даты.
AddViewField | при просмотре списка значение ячейки будет отображаться в заданном виде.
AddEditField | при редактировании списка значение ячейки будет отображаться в заданном виде.
AddActions | формирование контекстного меню строки.

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

Примеры

Подробный пример описания создания страницы со списком можно увидеть здесь.


AddActions

CAdminListRow::AddActions

void
CAdminListRow::AddActions(
  array $arActions
)

Метод позволяет настроить контекстное меню строки списка. Параметры меню задаются массивом (первый и единственный параметр метода), элементы которого представляют собой ассоциативные массивы со следующим набором ключей:

Ключ | Описание
ICON | Имя CSS-класса с иконкой действия.
DISABLED | Флаг "пункт меню заблокирован" (true|false).
DEFAULT | Флаг "пункт меню является действием по умолчанию" (true|false). При двойном клике по строке сработает действие по умолчанию.
TEXT | Название пункта меню.
TITLE | Текст всплывающей подсказки пункта меню.
ACTION | Действие, производимое по выбору пункта меню (Javascript).
SEPARATOR | Вставка разделителя {true|false}. При значении, равном true, остальные ключи пункта меню будут проигнорированы.

Пример:

// сформируем контекстное меню
$arActions = Array();

// редактирование элемента
$arActions[] = array(
"ICON"=>"edit",
"DEFAULT"=>true,
"TEXT"=>GetMessage("rub_edit"),
"ACTION"=>$lAdmin->ActionRedirect("rubric_edit.php?ID=".$f_ID)
);

// удаление элемента
if ($POST_RIGHT>="W")
$arActions[] = array(
  "ICON"=>"delete",
  "TEXT"=>GetMessage("rub_del"),
  "ACTION"=>"if(confirm('".GetMessage('rub_del_conf')."')) ".$lAdmin->ActionDoGroup($f_ID, "delete")
);

// вставим разделитель
$arActions[] = array("SEPARATOR"=>true);

// проверка шаблона для автогенерируемых рассылок
if (strlen($f_TEMPLATE)>0 && $f_AUTO=="Y")
$arActions[] = array(
  "ICON"=>"",
  "TEXT"=>GetMessage("rub_check"),
  "ACTION"=>$lAdmin->ActionRedirect("template_test.php?ID=".$f_ID)
);

// если последний элемент - разделитель, почистим мусор.
if(is_set($arActions[count($arActions)-1], "SEPARATOR"))
unset($arActions[count($arActions)-1]);

// применим контекстное меню к строке
$row->AddActions($arActions);


AddCalendarField

CAdminListRow::AddCalendarField

void
CAdminListRow::AddCalendarField(
  string $ID[,
  array $arAttributes = array()]
)

Метод позволяет настроить отображение поля списка в режиме редактирования в виде поля ввода даты.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.
arAttributes | Массив дополнительных атрибутов тэга INPUT в виде "атрибут" => "значение".

Пример:

$row->AddCalendarField(
    "DATE",
    array(
        "size" => "15"
    )
);


AddCheckField

CAdminListRow::AddCheckField

void
CAdminListRow::AddCheckField(
  string $ID
)

Метод позволяет настроить отображение поля списка в режиме редактирования в виде чекбокса. Чекбокс будет включенным, если значение ячейки равно 'Y'.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.

Пример:

// флаги ACTIVE и VISIBLE будут редактироваться чекбоксами
$row->AddCheckField("ACTIVE");
$row->AddCheckField("VISIBLE");


AddEditField

CAdminListRow::AddEditField

void
CAdminListRow::AddEditField(
  string $ID,
  string $HTML
)

Метод позволяет настроить отображение поля списка в режиме редактирования.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.
HTML | HTML-код, выводимый в ячейку таблицы.

Пример:

// параметр AUTO будет отображаться в виде "Да" или "Нет", полужирным при редактировании
$row->AddViewField("AUTO",
                   $f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"));
$row->AddEditField("AUTO",
                   "<b>".($f_AUTO=="Y"?GetMessage("POST_U_YES"):GetMessage("POST_U_NO"))."</b>");


AddField

CAdminListRow::AddField

void
CAdminListRow::AddField(
  string $ID,
  string $HTML[,
  bool $edit = false]
)

Метод позволяет настроить отображение поля списка в режимах просмотра и редактирования.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.
HTML | HTML-код отображения содержимого ячейки в режиме просмотра списка.
edit | Будет ли значение ячейки редактироваться. Необязательный параметр. По умолчанию - false (не редактируется).

Пример:

$row->AddField(
    "ID",
    '<a href="/bitrix/admin/blog_blog_edit.php?ID='.$f_ID.'&lang='.LANGUAGE_ID.'" title="'.GetMessage("BLB_UPDATE_ALT").'">'
    .$f_ID
    .'</a>'
);


AddInputField

CAdminListRow::AddInputField

void
CAdminListRow::AddInputField(
  string $ID[,
  array $arAttributes = array()]
)

Метод позволяет настроить отображение поля списка в режиме редактирования в виде текстового поля с заданным набором атрибутов.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.
arAttributes | Массив дополнительных атрибутов тэга INPUT в виде "атрибут" => "значение".

Пример:

// параметр NAME будет редактироваться как текст, а отображаться ссылкой
$row->AddInputField("NAME",
                    array("size"=>20));
$row->AddViewField("NAME",
                   '<a href="rubric_edit.php?ID='.$f_ID.
                   '&lang='.LANG.'">'.$f_NAME.'</a>');


AddSelectField

CAdminListRow::AddSelectField

void
CAdminListRow::AddSelectField(
  string $ID,
  array $arValues[,
  array $arAttributes = array()]
)

Метод позволяет настроить отображение поля списка в режиме редактирования в виде выпадающего списка.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.
arValues | Массив значений элементов выпадающего списка в виде "значение" => "наименование"
arAttributes | Массив дополнительных атрибутов тэга SELECT в виде "атрибут" => "значение".

Пример:

$arStatusList = array(
    "Draft" => GetMessage("STATUS_DRAFT"),
    "Published" => GetMessage("STATUS_PUBLISHED"),
);

$row->AddSelectField(
    "STATUS",
    $arStatusList
);


AddViewField

CAdminListRow::AddViewField

void
CAdminListRow::AddViewField(
  string $ID,
  string $HTML
)

Метод позволяет настроить отображение поля списка в режиме просмотра.

Параметры

Параметр | Описание
ID | Идентификатор ячейки.
HTML | HTML-код, выводимый в ячейку таблицы.

Пример:

// параметр NAME будет редактироваться как текст, а отображаться ссылкой
$row->AddInputField("NAME", array("size"=>20));
$row->AddViewField("NAME", '<a href="rubric_edit.php?ID='.$f_ID.'&lang='.LANG.'">'.$f_NAME.'</a>');


Класс CAdminMessage

CAdminMessage - класс для работы с сообщениями на страницах панели управления.

Методы для работы с сообщениями

Методы класса:

Метод | Описание
CAdminMessage | Конструктор класса.
Show | Вывод сообщения.
GetMessages | Получение списка сообщений.

Методы, не трубеющие создания экземпляра класса:

Метод | Описание
ShowNote | Вывод замечания.
ShowMessage | Вывод сообщения об ошибке.


Конструктор CAdminMessage

CAdminMessage::Конструктор CAdminMessage

object
CAdminMessage(
    array $arMessage[,
    mixed $exception = false]
)

Конструктор класса CAdminMessage.

Параметры:

Параметр | Описание
arMessage Массив, содержащий следующие ключи:
  • MESSAGE - текст сообщения,
  • TYPE - тип сообщения ("ERROR" - сообщение об ошибке; "OK" - уведомление),
  • DETAILS - подробное описание,
  • HTML - выводить текст ошибки напрямую, или обрабатывать (true|false)
exception | Экземпляр класса CApplicationException. Если не задано подробное описание ошибки, оно берется из него.

Пример:

if($strError)
{
  $aMsg = array();
  $arrErr = explode("<br />",$strError);
  reset($arrErr);
  while (list(,$err)=each($arrErr)) $aMsg[]['text']=$err;

  $e = new CAdminException($aMsg);
  $GLOBALS["APPLICATION"]->ThrowException($e);
  $message = new CAdminMessage(GetMessage("FORM_ERROR_SAVE"), $e);
  echo $message->Show();
}


GetMessages

CAdminMessage::GetMessages

array
CAdminMessage::GetMessages(
)

Получение списка сообщений. При создании экземпляра класса CAdminMessage в качестве второго параметра должен быть передан экземпляр класса CAdminException.


Show

CAdminMessage::Show

string
CAdminMessage::Show(
)

Вывод подготовленного сообщения.

Пример:

if($ex = $APPLICATION->GetException())
{
  $message = new CAdminMessage(GetMessage("FORM_ERROR_SAVE"), $ex);
  echo $message->Show();
}


ShowMessage

CAdminMessage::ShowMessage

string
CAdminMessage::ShowMessage(
    string $message
)

Вывод сообщения об ошибке.

Пример:

if (strlen(strError) > 0)
{
  echo CAdminMessage::ShowMessage($strError);
}


ShowNote

CAdminMessage::ShowNote

string
CAdminMessage::ShowNote(
  string $message
)

Вывод уведомления.

Пример:

echo CAdminMessage::ShowNote('Не нажимайте кнопки "Назад" и "Обновить" Вашего браузера!');


Класс CAdminResult

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


Класс CAdminSorting

Класс CAdminSorting представляет собой дескриптор сортировки таблицы списка элементов на страницах панели управления.

Методы

Метод | Описание
CAdminSorting | Конструктор класса.

Пример работы с сортировками

Работа сортировок описана в руководстве по созданию административных страниц.


Конструктор CAdminSorting

CAdminSorting::Конструктор CAdminSorting

object
CAdminSorting(
   string $table_id[,
   mixed $by_initial = false,
   mixed $order_initial = false,
   string $by_name = "by",
   string $order_name = "order"]
)

Класс описывает параметры сортировки строки таблицы списка элементов на административной странице по любой из колонок, для которых предусмотрена сортировка. Настройка сортировки по колонкам осуществляется при помощи CAdminList::AddHeaders().

Параметры

Параметр | Описание
table_id | Идентификатор таблицы.
by_inital | Идентификатор колонки, по которой идет сортировка по умолчанию.
order_inital | Направление сортировки по умолчанию ({'asc'|'desc'}).
by_name | Имя GET-переменной, в которой будет содержаться идентификатор колонки, по которой производится сортировка. Не обязательный параметр. По умолчанию - 'by'
order_name | Имя GET-переменной, в которой будет содержаться направление сортировки. Не обязательный параметр. По умолчанию - 'order'

Инициализированный экземпляр класса сортировки передается конструктору класса CAdminList. Дальнейшая подготовка осуществляется автоматически и не требует вмешательства.

Пример

$sTableID = "tbl_rubric"; // ID таблицы
$oSort = new CAdminSorting($sTableID, "ID", "desc"); // объект сортировки
$lAdmin = new CAdminList($sTableID, $oSort); // основной объект списка


Класс CAdminTabControl

CAdminTabControl - класс для работы с многостраничными формами с переключением посредством закладок на странице панели управления.

Методы для работы со закладками:

Метод | Описание
CAdminTabControl | Конструктор класса.
AddTabs | Добавление собственных закладок.
Begin | Вывод закладок и начало первой страницы.
BeginNextTab | Завершение предыдущей закладки, если она есть, и начало новой.
EndTab | Завершение закладки.
Buttons | Добавление кнопок отправки формы.
End | Завершение вывода закладок.
ActiveTabParam | Метод возвращает имя и значение GET-переменной, содержащее имя вкладки, которая будет активной сразу при загрузке страницы.
ShowWarnings | Показ сообщений об ошибках возникших в процессе обработки формы, с выделением полей формы, значения которых ошибочны.

Примеры

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


Конструктор CAdminTabControl

CAdminTabControl::Конструктор CAdminTabControl

object
CAdminTabControl(
   string $NAME,
   array $aTabs[,
   bool $bCanExpand = true]
)

Конструктор класса, реализующего механизм форм, разбитых нас страницы, динамически переключаемые закладками.

Параметры

Параметр | Описание
NAME | Уникальный в рамках страницы идентификатор.
aTabs | Массив, описывающий список закладок. Формат массива см. ниже.
bCanExpand | Флаг, означающий возможность развернуть страницы в одну. Необязательный параметр. По умолчанию - true - можно развернуть.

Конфигурация закладок задается в виде массива, элементами которого являются ассоциативные массивы, которые могут иметь следующие ключи:

Ключ | Описание
DIV | Уникальный идентификатор закладки.
TAB | Текст, помещаемый на закладку.
TITLE | Описание страницы, к которой ведет закладка.
ICON | CSS-класс иконки, выводимой рыдом с описанием страницы.
ONSELECT | JavaScript-сценарий, который будет выполнен при переключении на закладку.

Пример

$aTabs = array(
  array("DIV" => "edit1",
        "TAB" => GetMessage("rub_tab_rubric"),
        "ICON"=>"main_user_edit",
        "TITLE"=>GetMessage("rub_tab_rubric_title")),
  array("DIV" => "edit2",
        "TAB" => GetMessage("rub_tab_generation"),
        "ICON"=>"main_user_edit",
        "TITLE"=>GetMessage("rub_tab_generation_title")),
);
$tabControl = new CAdminTabControl("tabControl", $aTabs);


ActiveTabParam

CAdminTabControl::ActiveTabParam

string
CAdminTabControl::ActiveTabParam(
)

Возвращает имя и значение GET-переменной, содержащей имя вкладки, которая будет активной сразу при загрузке страницы.

Пример

Перенаправление пользователя после обработки данных формы.

if (strlen($strError)<=0)
{
  // если была нажат кнопка "Сохранить", отправим к списку
  if (strlen($save)>0)
    LocalRedirect("form_field_list.php?WEB_FORM_ID=".
                  $WEB_FORM_ID."&additional=".
                  $additional."&lang=".LANGUAGE_ID);
  // если "Применить" - назад на форму с открытой последней вкладкой.
  else
    LocalRedirect("form_field_edit_simple.php?".$tabControl->ActiveTabParam().
                  "&ID=".$ID."&WEB_FORM_ID=".$WEB_FORM_ID."&additional=".
                  $additional."&lang=".LANGUAGE_ID);
}


AddTabs

CAdminTabControl::AddTabs

void
CAdminTabControl::AddTabs(
  CAdminTabEngine &$customTabber
)

Добавляет пользовательские страницы с закладками закладки к форме. В качестве параметра принимается экземпляр класса CAdminTabEngine. Подробнее про создание собственных форм с закладками см. здесь.

Пример

$customTabber = new CAdminTabEngine("OnAdminIBlockElementEdit", array("ID" => $ID));

// ..........................

$tabControl = new CAdminTabControl("tabControl", $aTabs);
$customTabber->SetErrorState($bVarsFromForm);
$tabControl->AddTabs($customTabber);


Begin

CAdminTabControl::Begin

void
CAdminTabControl::Begin(
)

Выводит строку закладок и начинает первую страницу.

Пример

<?
$aTabs = array(
  array("DIV" => "edit1",
        "TAB" => GetMessage("rub_tab_rubric"),
        "ICON"=>"main_user_edit",
        "TITLE"=>GetMessage("rub_tab_rubric_title")),
  array("DIV" => "edit2",
        "TAB" => GetMessage("rub_tab_generation"),
        "ICON"=>"main_user_edit",
        "TITLE"=>GetMessage("rub_tab_generation_title")),
);
$tabControl = new CAdminTabControl("tabControl", $aTabs);
?>
<?
// отобразим заголовки закладок
$tabControl->Begin();
?>


BeginNextTab

CAdminTabControl::BeginNextTab

void
CAdminTabControl::BeginNextTab(
)

Завершает предыдущую закладку, если она есть, и начинает следующую.

Пример

<?
// отобразим заголовки закладок
$tabControl->Begin();
?>
<?
//********************
// первая закладка - форма редактирования параметров рассылки
//********************
$tabControl->BeginNextTab();
?>
  <tr>
    <td width="40%"><?echo GetMessage("rub_act")?></td>
    <td width="60%"><input type="checkbox" name="ACTIVE" value="Y"<?if($str_ACTIVE == "Y") echo " checked"?>></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_visible")?></td>
    <td><input type="checkbox" name="VISIBLE" value="Y"<?if($str_VISIBLE == "Y") echo " checked"?>></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_site")?></td>
    <td><?echo CLang::SelectBox("LID", $str_LID);?></td>
  </tr>
  <tr>
    <td><span class="required">*</span><?echo GetMessage("rub_name")?></td>
    <td><input type="text" name="NAME" value="<?echo $str_NAME;?>" size="30" maxlength="100"></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_sort")?></td>
    <td><input type="text" name="SORT" value="<?echo $str_SORT;?>" size="30"></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_desc")?></td>
    <td><textarea class="typearea" name="DESCRIPTION" cols="45" rows="5" wrap="VIRTUAL"><?echo $str_DESCRIPTION; ?></textarea></td>
  </tr>
  <tr>
    <td><?echo GetMessage("rub_auto")?></td>
    <td><input type="checkbox" name="AUTO" value="Y"<?if($str_AUTO == "Y") echo " checked"?> OnClick="if(this.checked) tabControl.EnableTab('edit2'); else tabControl.DisableTab('edit2');"></td>
  </tr>
<?
//********************
// вторая закладка
//********************
$tabControl->BeginNextTab();
?>


Buttons

CAdminTabControl::Buttons

void
CAdminTabControl::Buttons([
  mixed $arParams = false
])

Выводит стандартные кнопки отправки формы. Если есть открытые закладки - закрывает их.

Параметры

Параметр Описание
arParams Массив дополнительных параметров. Может содержать следующие ключи:
  • disabled - при значении true кнопки отправки формы будут заблокированы.
  • back_url - URL страницы, с которой произошла пересылка на форму. При нажатии кнопки "Отмена" произойдет переход по этому адресу.
Если значение параметра не указано (или указано значение false), то метод закроет все вкладки, не выводя стандартных кнопок отправки. В этом случае их можно создать вручную.

Пример

<?
// завершение формы - вывод кнопок сохранения изменений
$tabControl->Buttons(
  array(
    "disabled" => ($POST_RIGHT < "W"),
    "back_url" => $_REQUEST["back_url"],
  )
);
?>

<?
// завершение формы без вывода кнопок
$tabControl->Buttons();
?>
<input class="mybutton"
       type="submit" name="save"
       value="Нажми меня!!!! ;-)"
       title="Моя кнопка для сохранения" />&nbsp;
<input class="mybutton"
       type="button" name="foo"
       value="И меня тоже нажми!"
       onClick="alert('Hello, world!')" />
<?
$tabControl->End();
?>


End

CAdminTabControl::End

void
CAdminTabControl::End(
)

Завершает вывод формы с закладками. Если есть открытые закладки - закрывает их.

Пример

<?
// завершение формы - вывод кнопок сохранения изменений
$tabControl->Buttons(
  array(
    "disabled"=>($POST_RIGHT<"W"),
    "back_url"=>"rubric_admin.php?lang=".LANG,
  )
);
?>
<?
// завершаем интерфейс закладки
$tabControl->End();
?>


EndTab

CAdminTabControl::EndTab

void
CAdminTabControl::EndTab(
)

Завершает текущую страницу формы. Вызывается автоматически в CAdminTabControl::BeginNextTab, CAdminTabControl::Buttons и CAdminTabControl::End.


ShowWarnings

CAdminTabControl::ShowWarnings

void
CAdminTabControl::ShowWarnings(
    string $FORM,
    CAdminException $messages[,
    mixed $arFields = false]
)

Метод выделяет поля, в которых в процессе обработки формы были выявлены ошибки.

Параметры

Параметр | Описание
FORM | значение атрибута name тэга формы.
messages | экземпляр класса CAdminException, содержащий сообщения об ошибках.
arFields | Массив соответствий вида "id_параметра_с_ошибкой" => "имя_поля_в_форме". Необязательный параметр. По умолчанию ищутся поля с тем же именем, что и id параметра с ошибкой.

Пример

if($e = $APPLICATION->GetException())
  $message = new CAdminMessage(GetMessage("currency_error"), $e);

if($message)
  echo $message->Show();

<form method="post" action="<?$APPLICATION->GetCurPage()?>" name="form1">

<!-- форма -->

</form>

<?$tabControl->ShowWarnings("form1", $message);?>


Класс CAdminTabEngine

CAdminTabEngine - класс для работы собственными закладками форм. Подробнее про создание собственных форм с закладками см. здесь.

Методы для работы собственными закладками:

Метод | Описание
CAdminTabEngine | Конструктор класса.
SetErrorState | Установка значения флага "Данные взяты из формы в результате возникновения ошибки".
SetArgs | Установка дополнительных аргументов для передачи в обработчик собственных закладок.
Check | Вызов обработчиков собственных закладок для проверки данных, полученных из формы.
Action | Вызов обработчиков собственных закладок для совершения действий над данными, полученными из формы.
GetTabs | Получение конфигурации собственных закладок.
ShowTab | Вывод страниц формы, соответствующих собственным закладкам.

Примеры

Подробнее про создание собственных форм с закладками см. здесь.


Конструктор CAdminTabEngine

CAdminTabEngine::Конструктор CAdminTabEngine

object
CAdminTabEngine(
   string $EVENT_NAME[,
   array $aArgs = array()]
)

Конструктор класса, реализующего добавления собственных закладок в многостраничные формы.

Параметры

Параметр | Описание
EVENT_NAME | Имя события, для которого сконфигурированы собственные закладки.
aArgs | Массив дополнительных аргументов, передаваемых обработчикам закладок.

Пример

$customTabber = new CAdminTabEngine("OnAdminSaleOrderEdit", array("ID" => $ID));
$tabControl = new CAdminTabControl("tabControl", $aTabs);
$customTabber->SetErrorState($bVarsFromForm);
$tabControl->AddTabs($customTabber);


Action

CAdminTabEngine::Action

bool
CAdminTabEngine::Action(
)

Метод вызывает обработчики собственных закладок для обработки данных формы. Если в одном из обработчиков возникла ошибка, остальные все равно вызываются.

Пример

if (!$customTabber->Action())
{
  if ($ex = $APPLICATION->GetException())
    $errorMessage .= $ex->GetString();
  else
    $errorMessage .= "Error. ";
}


Check

CAdminTabEngine::Check

bool
CAdminTabEngine::Check(
)

Метод вызывает обработчики собственных закладок для проверки данных формы. Если в одном из обработчиков возникла ошибка, остальные все равно вызываются.

Пример

if (!$customTabber->Check())
{
  if ($ex = $APPLICATION->GetException())
    $errorMessage .= $ex->GetString();
  else
    $errorMessage .= "Error. ";
}


GetTabs

CAdminTabEngine::GetTabs

array
CAdminTabEngine::GetTabs(
)

Метод вызывает обработчики собственных закладок для получения конфигурации закладок. Автоматически вызывается в CAdminTabControl::AddTabs.


SetArgs

CAdminTabEngine::SetArgs

void
CAdminTabEngine::SetArgs([
  array $arArgs = array()
])

Метод служит для установки дополнительных аргументов, которые будут переданы обработчикам собственных закладок. Аналогично заполнению второго параметра конструктора класса CAdminTabEngine.


SetErrorState

CAdminTabEngine::SetErrorState

void
CAdminTabEngine::SetErrorState([
  bool $bVarsFromForm = false
])

Метод служит для установки значения флага "Данные взяты из формы в результате возникновения ошибки". Значение передается обработчикам собственных закладок.

Пример

$customTabber = new CAdminTabEngine("OnAdminSaleOrderEdit", array("ID" => $ID));
$tabControl = new CAdminTabControl("tabControl", $aTabs);
$customTabber->SetErrorState($bVarsFromForm);
$tabControl->AddTabs($customTabber);


ShowTab

CAdminTabEngine::ShowTab

void
CAdminTabEngine::ShowTab(
  string $tabName
)

Метод вызывает обработчики собственных закладок для получения HTML-кода страниц. В качестве параметра принимает идентификатор закладки. Автоматически вызывается в CAdminTabControl::BeginNextTab.


Классы и функции

"Ядро" системы состоит из функций, событий и следующих классов:

Класс | Описание
CMain | Основной класс.
CDatabase | Класс для работы с базой данной.
CDBResult | Класс результата выполнения запроса.
CAgent | Класс для работы с агентами.
CEvent | Класс для отправки почтовых событий.
CEventMessage | Класс для работы с шаблонами почтовых событий.
CEventType | Класс для работы с типами почтовых событий.
CFile | Класс для работы с файлами и изображениями.
CUser | Класс для работы с пользователями.
CGroup | Класс для работы с группами пользователей.
CSite | Класс для работы с сайтами.
CLanguage | Класс для работы с языками.
CMainPage | Класс для использования на индексной странице портала.
CMenu | Обработка меню.
CModule | Управление модулями.
COption | Класс для работы с параметрами модулей.
CPageOption | Класс для работы с параметрами действующими только на странице.
CPageCache | Класс для кеширования HTML.
CPHPCache | Класс для кеширования PHP переменных и HTML.
CUserFieldEnum | Класс для работы с пользовательскими полями типа "список".


Класс CAdminFileDialog

CAdminFileDialog - класс для работы с файловым диалогом в административной части системы

Методы класса

Метод | Описание
ShowScript | Генерирует и добавляет скрипты, необходимые для показа диалога.


ShowScript

CAdminFileDialog::ShowScript

CAdminFileDialog::ShowScript(
 Array arConfig
)

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

Параметры функции

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

Ключ | Описание
event | Строка, содержащая имя Javascript-функции, которая вызывает файловый диалог. Функция должна быть задана в глобальной области видимости.
arResultDest Ассоциативный массив, определяющий способ возврата результата файлового диалога. Возможные следующие варианты задания.
  1. Результат выбора пользователя возвращается в функцию.

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

    Если operation = "O" (латинская буква "О"), функция возвращает 3 параметра в случае выбора пользователем файла:

    • filename - имя выбранного файла;
    • path - путь к выбранному файлу;
    • site - ID сайта.

    В случае, если operation = "S", то дополнительно передаются ещё 2 параметра:

    • title - заголовок сохраняемой страницы;
    • menu - ассоциативный массив, определяющий необходимость сохранения страницы в меню.
  2. Результат выбора пользователя возвращается в заданный элемент заданной формы.

    Чтобы передать результат выбора пользователя в некоторый элемент некоторой формы, следует определить в массиве следующие ключи:

    • FORM_NAME - id формы;
    • FORM_ELEMENT_NAME - имя элемента формы.
  3. Результат выбора пользователя возвращается в элемент с заданным ID.

    В данном случае, следует задать ключ ELEMENT_ID, равный ID элемента. В атрибут value этого элемента будет занесен результат.

arPath Ассоциативный массив, задающий путь. Массив может быть пустым или содержать один из следующих ключей:
  • PATH - заданный путь;
  • SITE - id сайта.
select Определяет, какие объекты может выбирать пользователь в диалоге:
  • "F" - выбор только файлов;
  • "D" - выбор только директорий.
operation Определяет режим работы файлового диалога:
  • "O" - открытие файлов или директорий
  • "S" - сохранение файлов
showUploadTab Определяет, показывать ли вкладку загрузки файлов (имеет силу только, если operation = "O"):
  • true - показывать;
  • false - не показывать.
showAddToMenuTab Определяет, показывать ли вкладку добавления страницы в меню (имеет силу только, если operation = "S"):
  • true - показывать;
  • false - не показывать.
fileFilter Фильтр файлов по расширению, может принимать следующие значения:
  • "" - фильтр отсутствует (выпадающий список отображаться не будет);
  • "image" - предустановленный вариант файлового фильтра ("Все рисунки");
  • "ext1,ext2,ext3" - строка со списком расширений файлов (в данном примере ext1,ext2,ext3), перечисленных через запятую.
allowAllFiles Определяет, позволять ли пользователям выбирать вариант "Все файлы(*.*)" в файловом фильтре (имеет силу только, если параметр fileFilter не равен ""):
  • true - позволять;
  • false - не позволять.
SaveConfig Определяет, будут ли сохраняться пользовательские настройки диалога (вид, сортировка, путь):
  • true - сохранять;
  • false - не сохранять.

Пример вызова диалога открытия файла:

CAdminFileDialog::ShowScript(Array
    (
        "event" => "OpenImage",
        "arResultDest" => Array("FUNCTION_NAME" => "SetImageUrl"),
        "arPath" => Array(),
        "select" => 'F',
        "operation" => 'O',
        "showUploadTab" => true,
        "showAddToMenuTab" => false,
        "fileFilter" => 'image',
        "allowAllFiles" => true,
        "SaveConfig" => true
    )
);

<script>
document.getElementById("open_dialog_button").onclick = OpenImage;
var SetImageUrl = function(filename,path,site)
{
    // Обработка результата
    alert("filename = "+filename+"; /n path = "+path+"; /n site = "+site);
}
</script>


Класс CAgent

CAgent - класс для работы с функциями-агентами.

Методы класса

Метод | Описание
AddAgent | Добавляет функцию-агент.
CheckAgents | Проверяет и запускает функции-агенты.
Delete | Удаляет функцию-агент по ее ID.
RemoveAgent | Удаляет функцию-агент по ее имени.
RemoveModuleAgents | Удаляет все функции-агенты указанного модуля.

См. также

  • Агенты


AddAgent

CAgent::AddAgent

mixed
CAgent::AddAgent(
 string name,
 string module = "",
 string period = "N",
 int interval = 86400,
 string datecheck = "",
 string active = "Y",
 string next_exec = "",
 int sort = 100
)

Функция регистрирует новую функцию-агент.

Параметры функции

Параметр | Описание
name | PHP строка для запуска функции-агента.
module Идентификатор модуля. Необходим для подключения файлов модуля.
Необязательный. По умолчанию пустой.
period

Если значение - "Y", то очередная дата запуска агента (next_exec) будет рассчитываться как:

next_exec = next_exec + interval
Т.е. при очередном запуске, если прошло уже больше времени чем указано в параметре interval, агент сначала будет запускаться ровно столько раз сколько он должен был запуститься (т.е. столько раз сколько он "пропустил"), а затем, когда next_exec достигнет либо превысит текущую дату, он будет в дальнейшем запускаться с периодичностью указанной в параметре interval. Как правило, подобное используется в агентах которые должны гарантированно запуститься определённое количество раз.

Если значение - "N", то очередная дата запуска агента (next_exec) будет рассчитываться как:

next_exec = дата последнего запуска + interval
Т.е. агент после первого запуска будет в дальнейшем запускаться с периодичностью указанной в параметре interval. Параметр необязательный, по умолчанию - "N".
interval Интервал (в секундах), с какой периодичностью запускать агента.
Необязательный. По умолчанию - 86400 (1 сутки).
datecheck Дата первой проверки "не пора ли запустить агент" в формате текущего языка.
Необязательный. По умолчанию - текущее время.
active Активность агента (Y|N).
Необязательный. По умолчанию - "Y" (активен).
next_exec Дата первого запуска агента в формате текущего языка.
Необязательный. По умолчанию - текущее время.
sort Индекс сортировки позволяющий указать порядок запуска данного агента относительно других агентов для которых подошло время запуска.
Необязательный. По умолчанию - 100.

Возвращаемые значения

При успешном выполнении, возвращает ID вновь добавленного агента, иначе - false.

См. также

  • Агенты
  • CAgent::RemoveAgent
  • CAgent::RemoveModuleAgents
  • Структура файлов

Примеры использования

<?
// добавим агент модуля "Статистика"
CAgent::AddAgent(
    "CStatistic::CleanUpStatistics_2();", // имя функции
    "statistic",                          // идентификатор модуля
    "N",                                  // агент не критичен к кол-ву запусков
    86400,                                // интервал запуска - 1 сутки
    "07.04.2005 20:03:26",                // дата первой проверки на запуск
    "Y",                                  // агент активен
    "07.04.2005 20:03:26",                // дата первого запуска
    30);
?>
<?
// добавим агент модуля "Техподдержка"
CAgent::AddAgent(
    "CTicket::AutoClose();",  // имя функции
    "support",                // идентификатор модуля
    "N",                      // агент не критичен к кол-ву запусков
    86400,                    // интервал запуска - 1 сутки
    "",                       // дата первой проверки - текущее
    "Y",                      // агент активен
    "",                       // дата первого запуска - текущее
    30);
?>
<?
// добавим произвольный агент не принадлежащий ни одному модулю
CAgent::AddAgent("My_Agent_Function();");
?>

<?
// файл /bitrix/php_interface/init.php

function My_Agent_Function()
{
   // выполняем какие-либо действия
   return "My_Agent_Function();";
}
?>
<?
// добавим произвольный агент принадлежащий модулю
// с идентификатором my_module

CAgent::AddAgent(
   "CMyModule::Agent007(1)",
   "my_module",
   "Y",
    86400);
?>

<?
// данный агент будет запущен ровно 7 раз с периодичностью раз в сутки,
// после чего будет удален из таблицы агентов.

Class CMyModule
{
   function Agent007($cnt=1)
   {
      echo "Hello!";
      if($cnt>=7)
         return "";
      return "CMyModule::Agent007(".($cnt+1).")";
   }
}
?>


CheckAgents

CAgent::CheckAgents

CAgent::CheckAgents()

Выполняет функцию-агента, время запуска которой наступило. Функция автоматически вызывается вначале каждой страницы и не требует ручного запуска.

Параметры функции

Без параметров.

См. также

  • Агенты


Delete

CAgent::Delete

CAgent::Delete(
 int id
)

Удаляет функцию-агент из таблицы зарегистрированных агентов.

Параметры функции

Параметр | Описание
id | ID функции-агента.

См. также

  • Агенты
  • CAgent::RemoveAgent
  • CAgent::RemoveModuleAgents

Примеры использования

<?
if (CAgent::Delete(34)) echo "Агент #34 успешно удален.";
?>


RemoveAgent

CAgent::RemoveAgent

CAgent::RemoveAgent(
 string name,
 string module=""
)

Удаляет функцию-агента из таблицы зарегистрированных агентов.

Параметры функции

Параметр | Описание
name | Функция-агент.
module | Идентификатор модуля. Необязательный. По умолчанию - главный модуль ("main").

См. также

  • Агенты
  • CAgent::RemoveModuleAgents
  • CAgent::Delete

Примеры использования

<?
CAgent::RemoveAgent("CCatalog::PreGenerateXML(\"yandex\");", "catalog");
if ($bNeedAgent)
{
    CAgent::AddAgent("CCatalog::PreGenerateXML(\"yandex\");", "catalog", "N", 24*60*60, "", "Y");
}
?>


RemoveModuleAgents

CAgent::RemoveModuleAgents

CAgent::RemoveModuleAgents(
 string module
)

Удаляет все функции-агенты указанного модуля из таблицы зарегистрированных агентов.

Параметры функции

Параметр | Описание
module | Идентификатор модуля.

См. также

  • Агенты
  • CAgent::RemoveAgent
  • CAgent::Delete

Примеры использования

<?
CAgent::RemoveModuleAgents("statistic");
?>


Класс CApplicationException

CApplicationException - класс для работы с исключениями.

Методы класса

Метод | Описание
CApplicationException | Инициализирует исключение (конструктор).
GetString | Возвращает текст исключения.

См. также

  • CMain::ThrowException


Конструктор CApplicationException

CApplicationException::Конструктор CApplicationException

CApplicationException(
 string msg,
 mixed id = false
)

Создает объект исключения класса CApplicationException с текстом msg c кодом id.

Параметры конструктора

Параметр | Описание
msg | Текст ошибки.
id | Идентификатор ошибки.

Примечание

Для вызова исключений рекомендуется использовать напрямую метод $APPLICATION->ThrowException. Данный конструктор предназначен прежде всего как шаблон для создания своих классов обработки исключений, наследуемых от CApplicationException.

См. также

  • CMain::ThrowException

Примеры использования

<?
$exception = new CApplicationException("File is not found", BX_E_FILE_NOT_FOUND);
$APPLICATION->ThrowException($exception);
?>


GetString

CApplicationException::GetString

string
CApplicationException::GetString()

Метод возвращает текст исключения

Параметры функции

Без параметров.

См. также

  • CApplicationException
  • CMain::ThrowException

Примеры использования

<?
$DB->StartTransaction();
if(!$langs->Delete($del_id))
{
  $DB->Rollback();
  if($ex = $APPLICATION->GetException())
    $strError = $ex->GetString();
}
else
  $DB->Commit();
?>


Класс CBitrixComponent

Класс CBitrixComponent является оболочкой компонента. Для каждого подключаемого компонента создаётся свой экземпляр класса CBitrixComponent, который живет до конца подключения компонента. Внутри компонента методы этого класса доступны через переменную-псевдоним $this.


AbortResultCache

CBitrixComponent::AbortResultCache

void
AbortResultCache();

Метод поддержки внутреннего кеширования компонента.

Применяется, если в результате выборки данных (в случае отсутствия валидного кеша) выяснилось, что кешировать данные не требуется. Например, если новости с требуемым ID нет, следует прервать кеширование и выдать сообщение, что такой новости нет. Если кеширование не прервать, то злоумышленники смогут увеличить кеш до всего отведенного сайту дискового пространства, вызывая страницу с произвольными (в том числе и не существующими) ID.

Пример

// Проверка и инициализация входных параметров
if ($arParams["ID"] <= 0)
    $arParams["ID"] = 10;

// Если нет валидного кеша (то есть нужно запросить
// данные и сделать валидный кеш)
if ($this->StartResultCache())
{
    // Запрос данных и заполнение $arResult
    $arResult = array(
        "ID" => rand(1, 100)
    );

    for ($i = 0; $i < 5; $i++)
        $arResult["FIELDS"][] = rand(1, 100);

    // Если выполнилось какое-то условие, то кешировать
    // данные не надо
    if ($arParams["ID"] < 10)
        $this->AbortResultCache();

    // Подключить шаблон вывода
    $this->IncludeComponentTemplate();
}

// Установить заголовок страницы с помощью отложенной
// функции
$APPLICATION->SetTitle($arResult["ID"]);

См. также

  • CBitrixComponent::StartResultCache
  • CBitrixComponent::ClearResultCache
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


AddIncludeAreaIcon

CBitrixComponent::AddIncludeAreaIcon

void
AddIncludeAreaIcon(
 array arIcon
);

Добавляет новую кнопку к тем кнопкам компонента, которые отображаются в области компонента в режиме редактирования сайта.

Параметры функции

Параметр Описание
arIcon Массив, описывающий кнопку, в формате:
array(
    'URL'   => "javascript:alert('Это новая кнопка');",
    'SRC'   => $this->GetPath().'/images/znak.gif',
    'TITLE' => "Это новая кнопка"
)

Пример

$this->AddIncludeAreaIcon(
    array(
        'URL'   => "javascript:alert('Это новая кнопка для ".$this->GetName()."');",
        'SRC'   => $this->GetPath().'/images/znak.gif',
        'TITLE' => "Это новая кнопка"
    )
);

См. также

  • CBitrixComponent::AddIncludeAreaIcons


AddIncludeAreaIcons

CBitrixComponent::AddIncludeAreaIcons

void
AddIncludeAreaIcons(
 array arIcons
);

Добавляет массив новых кнопок к тем кнопкам компонента, которые отображаются в области компонента в режиме редактирования сайта. При этом, вызов метода AddIncludeAreaIcons отменяет все предыдущие вызовы методов AddIncludeAreaIcons и AddIncludeAreaIcon.

Параметры функции

Параметр Описание
arIcons Массив, содержащий массивы, которые описывают кнопку. Каждый из массивов, описывающих кнопку, имеет формат:
array(
    'URL'   => "javascript:alert('Это новая кнопка');",
    'SRC'   => $this->GetPath().'/images/znak.gif',
    'TITLE' => "Это новая кнопка"
)

Пример

$this->AddIncludeAreaIcons(
    array(
        array(
            'URL' => "javascript:alert('Это новая кнопка для ".$this->GetName()."');",
            'SRC' => $this->GetPath().'/images/znak.gif',
            'TITLE' => "Это новая кнопка"
        ),
        array(
            'URL' => "javascript:alert('Это ещё одна кнопка для ".$this->GetName()."');",
            'SRC' => $this->GetPath().'/images/znak1.gif',
            'TITLE' => "Это ещё одна кнопка"
        ),
    )
);

См. также

  • CBitrixComponent::AddIncludeAreaIcon
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


ClearResultCache

CBitrixComponent::ClearResultCache

bool
ClearResultCache(
 string additionalCacheID [,
 string cachePath]]
);

Метод поддержки внутреннего кеширования компонента.

Применяется, если при выполнении некоторых условий требуется очистить кеш компонента (например, при изменении данных).

Параметры функции

Параметр | Описание
additionalCacheID | Кеш зависит от текущего сайта (SITE_ID), имени компонента, пути в файлу и входных параметров $arParams. Если кеш должен зависеть от каких-либо дополнительных параметров, то их необходимо передать сюда в виде строки. По умолчанию параметр равен False, то есть кеш зависит только от текущего сайта SITE_ID, имени компонента, пути в файлу и входных параметров $arParams.
cachePath | Путь к файлу кеша относительно папки кэшей. По умолчанию равен "/".SITE_ID.<путь к компоненту относительно bitrix/components>.

См. также

  • CBitrixComponent::StartResultCache
  • CBitrixComponent::AbortResultCache
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


GetName

CBitrixComponent::GetName

string
GetName();

Метод возвращает имя компонента.

Пример

$name = $this->GetName();


GetParent

CBitrixComponent::GetParent

object &
GetParent();

Метод возвращает ссылку на объект родительского комплексного компонента.

Пример

$parent = & $this->GetParent();
$parentName = $parent->GetName();


GetPath

CBitrixComponent::GetPath

string
GetPath();

Метод возвращает путь к папке компонента относительно корня сайта.

Пример

$path = $this->GetPath();


GetRelativePath

CBitrixComponent::GetRelativePath

string
GetRelativePath();

Метод возвращает путь к папке компонента относительно папки /bitrix/components.

Пример

$relativePath = $this->GetRelativePath();


GetTemplate

CBitrixComponent::GetTemplate

object &
GetTemplate();

Метод возвращает ссылку на объект шаблона компонента. Шаблон компонента становится известен только после вызова методов IncludeComponentTemplate или InitComponentTemplate. До вызова указанных методов возвращается ссылка на значение null.

Пример

$template = & $this->GetTemplate();
$tamplateFile = $template->GetFile();


GetTemplateCachedData

CBitrixComponent::GetTemplateCachedData

mixed
GetTemplateCachedData();

Метод GetTemplateCachedData вызывают, если не используется встроенное в компонент кэширование и при этом вызов IncludeComponentTemplate кэшируется. Этот метод возвращает данные, которые необходимо сохранить в кэше, а потом восстановить из кэша и вернуть шаблону методом SetTemplateCachedData.

Пример

// Проверка и инициализация входных параметров
if ($arParams["ID"] <= 0)
   $arParams["ID"] = 10;

$arParams["CACHE_TIME"] = IntVal($arParams["CACHE_TIME"]);
$CACHE_ID = SITE_ID."|".$APPLICATION->GetCurPage()."|";
// кэш зависит только от подготовленных параметров без "~"
foreach ($this->arParams as $k => $v)
    if (strncmp("~", $k, 1))
        $CACHE_ID .= ",".$k."=".$v;
$CACHE_ID .= "|".$USER->GetGroups();

$cache = new CPageCache;
if ($cache->StartDataCache($arParams["CACHE_TIME"],
                           $CACHE_ID,
                           "/".SITE_ID.$this->GetRelativePath()))
{
    // Запрос данных и формирование массива $arResult
    $arResult = array("a" => 1, "b" => 2);

    // Подключение шаблона компонента
    $this->IncludeComponentTemplate();

    $templateCachedData = $this->GetTemplateCachedData();

    $cache->EndDataCache(
        array(
            "arResult" => $arResult,
            "templateCachedData" => $templateCachedData
        )
    );
}
else
{
    extract($cache->GetVars());
    $this->SetTemplateCachedData($templateCachedData);
}

См. также

  • Кэширование в компоненте
  • CBitrixComponent::SetTemplateCachedData


GetTemplateName

CBitrixComponent::GetTemplateName

string
GetTemplateName();

Метод возвращает имя шаблона компонента в том виде, в котором оно было передано при подключении компонента.

Пример

$name = $this->GetTemplateName();


GetTemplatePage

CBitrixComponent::GetTemplatePage

string
GetTemplatePage();

Метод возвращает имя страницы шаблона компонента.

Пример

$name = $this->GetTemplatePage();


IncludeComponentTemplate

CBitrixComponent::IncludeComponentTemplate

void
IncludeComponentTemplate([
 string templatePage]
);

Метод инициализирует и подключает шаблон компонента. Если инициализация шаблона прошла неудачно, он выводит ошибку на экран.

Параметры функции

Параметр | Описание
templatePage | Имя страницы шаблона компонента. Устанавливается для комплексных компонентов. Для обычных компонентов должно быть равно пустой строке или не установлено.

Пример

$this->IncludeComponentTemplate();

См. также

  • CBitrixComponent::InitComponentTemplate
  • CBitrixComponent::ShowComponentTemplate
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


InitComponentTemplate

CBitrixComponent::InitComponentTemplate

bool
InitComponentTemplate([
 string templatePage]
);

Метод инициализирует шаблон компонента. После вызова этого метода можно получить объект шаблона с помощью метода CBitrixComponent::GetTemplate. Шаблон компонента в этом случае подключается методом CBitrixComponent::ShowComponentTemplate.

Если объект шаблона коду компонента не нужен, воспользуйтесь одним методом CBitrixComponent::IncludeComponentTemplate, который сразу и инициализирует и подключает шаблон.

Параметры функции

Параметр | Описание
templatePage | Имя страницы шаблона компонента. Устанавливается для комплексных компонентов. Для обычных компонентов должно быть равно пустой строке или не установлено.

Возвращаемое значение

Возвращает True в случае успешной инициализации, иначе - False.

Пример

if ($this->InitComponentTemplate($templatePage))
{
    $template = & $this->GetTemplate();
    $folderPath = $template->GetFolder();
    if (strlen($folderPath) > 0)
    {
        * * *
    }
    $this->ShowComponentTemplate();
}

См. также

  • CBitrixComponent::ShowComponentTemplate
  • CBitrixComponent::GetTemplate
  • CBitrixComponent::IncludeComponentTemplate
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


SetTemplateCachedData

CBitrixComponent::SetTemplateCachedData

void
SetTemplateCachedData(
 mixed templateCachedData
);

Метод SetTemplateCachedData вызывают, если не используется встроенное в компонент кэширование, и при этом вызов CBitrixComponent::IncludeComponentTemplate кэшируется. Этот метод возвращает шаблону данные, которые необходимо было сохранить в кэше.

Пример

// Проверка и инициализация входных параметров
if ($arParams["ID"] <= 0)
   $arParams["ID"] = 10;

$arParams["CACHE_TIME"] = IntVal($arParams["CACHE_TIME"]);
$CACHE_ID = SITE_ID."|".$APPLICATION->GetCurPage()."|";
// кэш зависит только от подготовленных параметров без "~"
foreach ($this->arParams as $k => $v)
    if (strncmp("~", $k, 1))
        $CACHE_ID .= ",".$k."=".$v;
$CACHE_ID .= "|".$USER->GetGroups();

$cache = new CPageCache;
if ($cache->StartDataCache($arParams["CACHE_TIME"], $CACHE_ID, "/".SITE_ID.$this->GetRelativePath()))
{
    // Запрос данных и формирование массива $arResult
    $arResult = array("a" => 1, "b" => 2);

    // Подключение шаблона компонента
    $this->IncludeComponentTemplate();

    $templateCachedData = $this->SetTemplateCachedData();

    $cache->EndDataCache(
        array(
            "arResult" => $arResult,
            "templateCachedData" => $templateCachedData
        )
    );
}
else
{
    extract($cache->GetVars());
    $this->SetTemplateCachedData($templateCachedData);
}

См. также

  • Кэширование в компоненте
  • CBitrixComponent::GetTemplateCachedData
    •


ShowComponentTemplate

CBitrixComponent::ShowComponentTemplate

void
ShowComponentTemplate();

Метод подключает шаблон компонента. Перед вызовом этого метода шаблон должен быть инициализирован методом CBitrixComponent::InitComponentTemplate.

Если объект шаблона коду компонента не нужен, используйте CBitrixComponent::IncludeComponentTemplate, который сразу и инициализирует и подключает шаблон.

Пример

if ($this->InitComponentTemplate($templatePage))
{
    $template = & $this->GetTemplate();
    $folderPath = $template->GetFolder();
    if (strlen($folderPath) > 0)
    {
        * * *
    }
    $this->ShowComponentTemplate();
}

См. также

  • CBitrixComponent::GetTemplate
    •


StartResultCache

CBitrixComponent::StartResultCache

bool
StartResultCache([
 int cacheTime [,
 string additionalCacheID [,
 string cachePath]]]
);

Метод поддержки внутреннего кеширования компонента.

Если кеш действителен, метод отправляет на экран его содержимое, заполняет $arResult и возвращает False. Если кеш недействителен, метод возвращает True, кеширование завершается и кеш сохраняется при вызове методов CBitrixComponent::IncludeComponentTemplate или CBitrixComponent::ShowComponentTemplate сразу после подключения шаблона компонента.

Параметры функции

Параметр | Описание
cacheTime | Время кеширования в секундах. Если этот параметр равен False, то время кеширования берется из входного параметра $arParams["CACHE_TIME"].
additionalCacheID | Кеш зависит от текущего сайта ( SITE_ID), имени компонента, пути в файлу и входных параметров $arParams. Если кеш должен зависеть от каких-либо дополнительных параметров, то их необходимо передать сюда в виде строки. По умолчанию параметр равен False, т.е. кеш зависит только от текущего сайта SITE_ID, имени компонента, пути в файлу и входных параметров $arParams.
cachePath | Путь к файлу кеша относительно папки кешей. По умолчанию равен "/".SITE_ID.<путь к компоненту относительно bitrix/components>.

Возвращаемое значение

Возвращает True в случае, если кеш недействителен, или False в противном случае.

Пример

// Проверка и инициализация входных параметров
if ($arParams["ID"] <= 0)
    $arParams["ID"] = 10;

// Если нет валидного кеша (то есть нужно запросить
// данные и сделать валидный кеш)
if ($this->StartResultCache())
{
    // Запрос данных и заполнение $arResult
    $arResult = array(
        "ID" => rand(1, 100)
    );

    for ($i = 0; $i < 5; $i++)
        $arResult["FIELDS"][] = rand(1, 100);

    // Если выполнилось какое-то условие, то кешировать
    // данные не надо
    if ($arParams["ID"] < 10)
        $this->AbortResultCache();

    // Подключить шаблон вывода
    $this->IncludeComponentTemplate();
}

// Установить заголовок страницы с помощью отложенной
// функции
$APPLICATION->SetTitle($arResult["ID"]);

// кеш должен зависеть от групп пользователей, которым принадлежит посетитель
if ($this->StartResultCache(false, $USER->GetGroups()))
{
   // Валидного кеша нет. Выбираем данные из
   // базы в $arResult
}

См. также

  • CBitrixComponent::AbortResultCache
  • CBitrixComponent::ClearResultCache
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


Класс CBitrixComponentTemplate

Класс CBitrixComponentTemplate является оболочкой шаблона компонента. Для каждого подключаемого шаблона компонента создаётся свой экземпляр класса CBitrixComponentTemplate, который живет от момента инициализации шаблона в коде компонента до конца подключения компонента.

Для получения доступа к методам этого класса внутри компонента (после инициализации шаблона) нужно получить объект шаблона с помощью метода компонента CBitrixComponent::GetTemplate:

$template = & $this->GetTemplate();
$templateFile = $template->GetFile();


GetFile

CBitrixComponentTemplate::GetFile

string
GetFile();

Метод возвращает путь к файлу шаблона относительно корня сайта.

Пример

// В коде компонента
$template = & $this->GetTemplate();
$templateFile = $template->GetFile();


GetFolder

CBitrixComponentTemplate::GetFolder

string
GetFolder();

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

Пример

// В коде компонента
$template = & $this->GetTemplate();
$templateFolder = $template->GetFolder();


GetName

CBitrixComponentTemplate::GetName

string
GetName();

Метод возвращает имя шаблона компонента.

Пример

// В коде компонента
$template = & $this->GetTemplate();
$templateName = $template->GetName();


GetSiteTemplate

CBitrixComponentTemplate::GetSiteTemplate

string
GetSiteTemplate();

Метод возвращает шаблон сайта, в котором лежит шаблон компонента. Если это системный шаблон компонента (т.е. лежит в папке компонента), то возвращается пустая строка.

Пример

// В коде компонента
$template = & $this->GetTemplate();
$siteTemplate = $template->GetSiteTemplate();


Класс CComponentEngine

Класс CComponentEngine инкапсулирует вспомогательные методы, полезные при разработке компонентов.


InitComponentVariables

CComponentEngine::InitComponentVariables

void
InitComponentVariables(
 string componentPage ,
 array arComponentVariables ,
 array arVariableAliases ,
 array & arVariables
);

Метод служит для поддержки псевдонимов переменных в комплексных компонентах (как в ЧПУ режиме, так и в обычном). Метод восстанавливает истинные переменные из $_REQUEST на основании их псевдонимов.

Параметры функции

Параметр | Описание
componentPage | Для ЧПУ режима: код шаблона пути, который был получен методом CComponentEngine::ParseComponentPath. Если компонент работает не в ЧПУ режиме, этот параметр должен быть равен False.
arComponentVariables | Массив имен переменных, которые компонент может получать из запроса. Этот параметр имеет вид array("имя переменной 1", "имя переменной 2", ...).
arVariableAliases Массив псевдонимов переменных.

Для режима ЧПУ имеет формат:
array(
    "код шаблона пути 1" => array(
        "название переменной 11" => "псевдоним переменной 11",
        "название переменной 12" => "псевдоним переменной 12",
        * * *
    ),
    "код шаблона пути 2" => array(
        "название переменной 21" => "псевдоним переменной 21",
        "название переменной 22" => "псевдоним переменной 22",
        * * *
    ),
    * * *
)
Для не ЧПУ режима:
array(
    "название переменной" => "псевдоним переменной",
    * * *
)
arVariables | Переменная, в которой возвращаются восстановленные переменные.

Пример

// Для ЧПУ режима

// В этой переменной будем накапливать значения истинных переменных
$arVariables = array();

// Соберем массив шаблонов путей из массива шаблонов путей
// "по-умолчанию" $arDefaultUrlTemplates404
// и массива, переданого во входных параметрах $arParams["SEF_URL_TEMPLATES"]
$arUrlTemplates =
    CComponentEngine::MakeComponentUrlTemplates($arDefaultUrlTemplates404,
                                                $arParams["SEF_URL_TEMPLATES"]);

// Соберем массив псевдонимов переменных из массива псевдонимов
// "по-умолчанию" $arDefaultVariableAliases404
// и массива, переданого во входных параметрах $arParams["VARIABLE_ALIASES"]
$arVariableAliases =
    CComponentEngine::MakeComponentVariableAliases($arDefaultVariableAliases404,
                                                   $arParams["VARIABLE_ALIASES"]);

// Определим код шаблона, которому соответствует текущая запрошения страница
$componentPage = CComponentEngine::ParseComponentPath(
    $arParams["SEF_FOLDER"],
    $arUrlTemplates,
    $arVariables
);

// Если запрошеная страница не соответствует ни одному шаблону,
// то установим явно что показывать
if (StrLen($componentPage) <= 0)
    $componentPage = "list";

// Теперь у нас установлен код шаблона пути и переменные,
// которые пришли в виде пути к запрошеной
// странице, записаны в $arVariables

// Восстановим переменные, которые пришли в параметрах запроса
// и допишем их в $arVariables
CComponentEngine::InitComponentVariables($componentPage,
                                         $arComponentVariables,
                                         $arVariableAliases,
                                         $arVariables);

// Теперь на основании кода шаблона пути $componentPage
// и истинных переменных $arVariables
// можно определить, какую страницу шаблона компонента нужно показать

if ($componentPage == "element")
    $componentPage = "element";
elseif ($componentPage == "section1" || $componentPage == "section2")
    $componentPage = "section";
else
    $componentPage = "list";

$this->IncludeComponentTemplate(
    array(
        "FOLDER" => $arParams["SEF_FOLDER"],
        "URL_TEMPLATES" => $arUrlTemplates,
        "VARIABLES" => $arVariables,
        "ALIASES" => $arVariableAliases
    ),
    $componentPage
);

// Для не ЧПУ режима

// В этой переменной будем накапливать значения истинных переменных
$arVariables = array();

// Соберем массив псевдонимов переменных из массива псевдонимов
// "по-умолчанию" $arDefaultVariableAliases
// и массива, переданого во входных параметрах $arParams["VARIABLE_ALIASES"]
$arVariableAliases =
    CComponentEngine::MakeComponentVariableAliases($arDefaultVariableAliases,
                                                   $arParams["VARIABLE_ALIASES"]);

// Восстановим переменные, которые пришли в параметрах запроса
// и допишем их в $arVariables
CComponentEngine::InitComponentVariables(False, $arComponentVariables,
                                         $arVariableAliases, $arVariables);

// Теперь на основании истинных переменных $arVariables
// можно определить, какую страницу шаблона компонента нужно показать

$componentPage = "";
if (IntVal($arVariables["ELEMENT_ID"]) > 0)
    $componentPage = "element";
elseif (IntVal($arVariables["IBLOCK_ID"]) > 0 ||
        IntVal($arVariables["SECTION"]) > 0)
    $componentPage = "section";
else
    $componentPage = "list";

$this->IncludeComponentTemplate(
    array(
        "VARIABLES" => $arVariables,
        "ALIASES" => $arVariableAliases
    ),
    $componentPage
);

См. также

  • Структура комплексного компонента
  • Псевдонимы входящих переменных
  • CComponentEngine::MakeComponentVariableAliases
  • CComponentEngine::MakeComponentUrlTemplates
    •


MakeComponentUrlTemplates

CComponentEngine::MakeComponentUrlTemplates

array
MakeComponentUrlTemplates(
 array arDefaultUrlTemplates,
 array arCustomUrlTemplates
);

Метод служит для поддержки ЧПУ режима в комплексных компонентах. Метод принимает на входе шаблоны путей по умолчанию и шаблоны путей, переданные во входных параметрах компонента и заменяет те шаблоны путей по умолчанию, которые были переопределены во входных параметрах компонента.

Параметры функции

Параметр | Описание
arDefaultUrlTemplates | Массив шаблонов путей по умолчанию.
arCustomUrlTemplates | Массив шаблонов путей, переданных во входных параметрах компонента.

Возвращаемое значение

Массив шаблонов путей.

Пример

// если массив шаблонов путей по умолчанию имеет вид
$arDefaultUrlTemplates = array(
    "list" => "index.php",
    "element" => "#IBLOCK_ID#/#ELEMENT_ID#.php?SID=#SECTION_ID#"
);

// а во входных параметрах был передан массив
$arParams["SEF_URL_TEMPLATES"] = array(
    "element" => "#IBLOCK_ID#/#SECTION_ID#/#ELEMENT_ID#.php"
);

// тогда, после вызова метода:
$arUrlTemplates =
    CComponentEngine::MakeComponentUrlTemplates($arDefaultUrlTemplates,
                                                $arParams["SEF_URL_TEMPLATES"]);

// массив $arUrlTemplates будет иметь вид
$arUrlTemplates = array(
    "list" => "index.php",
    "element" => "#IBLOCK_ID#/#SECTION_ID#/#ELEMENT_ID#.php"
)

См. также

  • Структура комплексного компонента
  • CComponentEngine::ParseComponentPath
    •


MakeComponentVariableAliases

CComponentEngine::MakeComponentVariableAliases

array
MakeComponentVariableAliases(
 array arDefaultVariableAliases ,
 array arCustomVariableAliases
);

Метод принимает псевдонимы переменных по умолчанию и псевдонимы переменных, переданные во входных параметрах компонента и заменяет те псевдонимы переменных по умолчанию, которые были переопределены во входных параметрах компонента.

Параметры функции

Параметр | Описание
arDefaultVariableAliases | Массив псевдонимов переменных по умолчанию.
arCustomUrlTemplates | Массив псевдонимов переменных, переданных во входных параметрах компонента.

Возвращаемое значение

Массив псевдонимов переменных.

Пример

// если псевдонимов переменных по умолчанию имеет вид
$arDefaultVariableAliases404 = array();

// а во входных параметрах был передан массив
$arParams["VARIABLE_ALIASES"] = array(
    "element" => array(
        "IBLOCK_ID" => "BID",
        "SECTION_ID" => "SID",
    )
);

// тогда, после вызова метода
$arVariableAliases =
    CComponentEngine::MakeComponentVariableAliases($arDefaultVariableAliases404,
                                                   $arParams["VARIABLE_ALIASES"]);

// массив $arVariableAliases будет иметь вид
$arVariableAliases = array(
    "element" => array(
        "IBLOCK_ID" => "BID",
        "SECTION_ID" => "SID",
    )
)

См. также

  • Структура комплексного компонента
  • Псевдонимы входящих переменных
  • CComponentEngine::InitComponentVariables
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


MakePathFromTemplate

CComponentEngine::MakePathFromTemplate

string
MakePathFromTemplate(
 string template ,
 array arParams
);

Метод заменяет в шаблоне template подстроки #SITE_DIR#, #SITE#, #SERVER_NAME# на значения системных констант SITE_DIR, SITE_ID, SITE_SERVER_NAME, соответственно.

Кроме того, метод заменяет все подстроки вида "#ключ массива arParams#" на соответствующие значения в соответствии с правилами массива arParams.

Параметры функции

Параметр | Описание
template | Шаблон пути, который может содержать подстроки вида "#.....#".
arParams Массив замен. Имеет формат:
array(
    "ключ1" => "значение 1",
    "ключ2" => "значение 2",
    * * *
)
Подстрока "#ключ1#" в шаблоне заменяется на "значение 1", "#ключ2#" - на "значение 2" и т.д.

Возвращаемое значение

Итоговая строка, получившаяся после замен из шаблона.

Пример

// Пусть во входных параметрах компонента - шаблон пути
$arParams["SECTION_PAGE_TEMPLATE2"] =
    "/#IBLOCK_ID#/#SECTION_ID#.php?s=#SITE#";

// Пусть в компоненте вычислены значения:
$IBLOCK_ID = 3;
$SECTION_ID = 982;

// Сформируем путь на основании этого шаблона и
// вычисленных в компоненте значений
$pagePath = CComponentEngine::MakePathFromTemplate(
    $arParams["SECTION_PAGE_TEMPLATE2"],
    array(
        "IBLOCK_ID" => $IBLOCK_ID,
        "SECTION_ID" => $SECTION_ID
    )
);

// В переменной $pagePath будет содержатся строка:
$pagePath = "/3/982.php?s=ru";


ParseComponentPath

CComponentEngine::ParseComponentPath

bool
ParseComponentPath(
 string folder404 ,
 array arUrlTemplates ,
 array & arVariables [,
 string requestURL]
);

Метод служит для поддержки ЧПУ режима в комплексных компонентах.

Метод выясняет код шаблона пути комплексного компонента на основании папки, в которой работает компонент, массива шаблонов путей и текущей запрошенной страницы. Кроме того, этот метод восстанавливает те переменные, которые были заданы с помощью пути.

Параметры функции

Параметр | Описание
folder404 | Путь, в котором работает комплексный компонент в режиме ЧПУ. Этот путь передается во входном параметре $arParams["SEF_FOLDER"].
arUrlTemplates | Массив шаблонов путей комплексного компонента для режима ЧПУ. Этот массив задается в коде комплексного компонента и может полностью или частично переопределиться с помощью входного параметра $arParams["SEF_URL_TEMPLATES"].
arVariables | Переменная, в которой возвращаются восстановленные из запрощенного пути переменные (на основании найденного шаблона пути).
requestURL | Запрошенный путь. По умолчанию равен $APPLICATION->GetCurPage().

Возвращаемое значение

Если шаблон был найден, то возвращается его код, иначе возвращается пустая строка.

Пример

// если массив шаблонов путей имеет вид
$arUrlTemplates = array(
    "list" => "index.php",
    "element" => "#IBLOCK_ID#/#ELEMENT_ID#.php?SID=#SECTION_ID#"
);
// входной параметр SEF_FOLDER равен /company/news/
// запрошенный адрес равен /company/news/15/7653.php?SID=28

// то после вызова метода
$arVariables = array();
$page =
    CComponentEngine::ParseComponentPath($arParams["SEF_FOLDER"],
                                         $arUrlTemplates, $arVariables);

// в переменной $page будет строка "element"
// (код соответствующего шаблона)
// а массив $arVariables будет иметь вид
$arVariables = array(
    "IBLOCK_ID" => 15,
    "ELEMENT_ID" => 7653
)

См. также

  • Структура комплексного компонента
  • Псевдонимы входящих переменных
  • CComponentEngine::MakeComponentUrlTemplates
    •


Класс CDatabase

CDatabase - класс для работы с базой данной.

При запуске каждой страницы автоматически создаётся глобальный объект $DB класса CDatabase. Именно при помощи этого объекта и следует проводить все действия с базой данных.

Методы класса

Метод | Описание
ForSql | Преобразует строки для вставки в SQL запрос.
Query | Выполняет запрос.
QueryBind | Выполняет SQL-запросы типа "UPDATE", "INSERT", в которых есть необходимость связывания переменных (как правило для полей типа BLOB, CLOB, LONG и т.п.).
QueryBindSelect | Выполняет SQL-запрос типа "SELECT", в котором есть необходимость связывания переменных.
Update | Универсальный update в базу данных (без подготовки значений полей).
NextID | Возвращает очередное значения сиквенса.
Insert | Универсальный insert в базу данных (без подготовки значений полей).
LastID | Получает ID последней вставленной записи.
PrepareFields | Инициализирует глобальные переменные для вставки в SQL запрос.
PrepareInsert | Универсальный insert в базу данных (c подготовкой значений полей).
PrepareUpdate | Универсальный update в базу данных (c подготовкой значений полей).
InitTableVarsForEdit | Инициализирует глобальные переменные для показа.
ParseSqlBatch | Разбирает пакет запросов на массив.
RunSqlBatch | Выполняет файл с пакетом запросов.
StartTransaction | Открывает транзакцию.
Commit | Записывает транзакцию.
Rollback | Откатывает транзакцию.
Connect | Соединяет с базой данных.
Disconnect | Закрывает соединение с базой данных.

Функции для работы с датой и временем

Метод | Описание
CurrentDateFunction | Возвращает функцию текущей даты.
CurrentTimeFunction | Возвращает функцию текущей даты-время.
CharToDateFunction | Строка для вставки значения даты в запрос к базе данных.
DateToCharFunction | Строка для получения значения даты в запросе к базе данных.
DateFormatToPHP | Конвертирует формат даты заданный для языка (сайта) в формат принятый в PHP (в функции date).
FormatDate | Форматирует дату из одного формата в другой.
CompareDates | Сравнивает две даты между собой.
IsDate | Проверяет дату на правильность.

См. также

  • Работа с датой и временем
  • Функции для работы с датой и временем


CharToDateFunction

CDatabase::CharToDateFunction

string
CDatabase::CharToDateFunction(
 string value,
 string type = "FULL",
 string site = false
 )

Возвращает для MySQL значение сконвертированное в формат YYYY-MM-DD [HH:MI:SS], для Oracle - функция вернет строку TO_DATE с нужными параметрами.
Форматы даты устанавливается в настройках языка, либо настройках сайта.

Параметры функции

Параметр | Описание
value | Если функция вызывается в публичной части сайта, то это - значение даты для формата текущего сайта. Если функция вызывается в административной части, то это - значение даты для формата текущего языка.
type | Тип формата даты: "FULL" - для даты со временем, "SHORT" - для даты (без времени) Необязательный. По умолчанию "FULL".
site | Код сайта для публичной части, либо код языка для административной части. Необязательный. По умолчанию текущий.

См. также

  • CDatabase::DateToCharFunction
  • Функции для работы с датой и временем

Примеры использования

<?
$arr = getdate();
$ndate = mktime(9,0,0,$arr["mon"],$arr["mday"],$arr["year"]);
$next_exec = $DB->CharToDateFunction(GetTime($ndate,"FULL"));
CAgent::AddAgent("SendDailyStatistics();","statistic","Y",86400,"","Y",$next_exec, 25);
?>
<?
$strSql = "
    SELECT
        ID
    FROM
        my_table
    WHERE
        DATE_CREATE <= ".$DB->CharToDateFunction("10.01.2003 23:59:59")."
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>


Commit

CDatabase::Commit

CDatabase::Commit()

Завершает открытую транзакцию.

Работает для Oracle, MSSQL, MySQL (для типа таблиц InnoDB).

Параметры функции

Без параметров.

См. также

  • CDatabase::Rollback
  • CDatabase::StartTransaction

Примеры использования

<?
if (strlen($save)>0)
{
    if (CheckFields())
    {
        $DB->PrepareFields("b_form");
        $arFields = array(
            "TIMESTAMP_X"             => $DB->GetNowFunction(),
            "NAME"                    => "'".trim($str_NAME)."'",
            "VARNAME"                 => "'".trim($str_VARNAME)."'",
            "C_SORT"                  => "'".intval($str_C_SORT)."'",
            "FIRST_SITE_ID"           => "'".$DB->ForSql($FIRST_SITE_ID,2)."'",
            "BUTTON"                  => "'".$str_BUTTON."'",
            "DESCRIPTION"             => "'".$str_DESCRIPTION."'",
            "DESCRIPTION_TYPE"        => "'".$str_DESCRIPTION_TYPE."'",
            "SHOW_TEMPLATE"           => "'".trim($str_SHOW_TEMPLATE)."'",
            "MAIL_EVENT_TYPE"         => "'".$DB->ForSql("FORM_FILLING_".$str_VARNAME,50)."'",
            "SHOW_RESULT_TEMPLATE"    => "'".trim($str_SHOW_RESULT_TEMPLATE)."'",
            "PRINT_RESULT_TEMPLATE"   => "'".trim($str_PRINT_RESULT_TEMPLATE)."'",
            "EDIT_RESULT_TEMPLATE"    => "'".trim($str_EDIT_RESULT_TEMPLATE)."'",
            "FILTER_RESULT_TEMPLATE"  => "'".trim($str_FILTER_RESULT_TEMPLATE)."'",
            "TABLE_RESULT_TEMPLATE"   => "'".trim($str_TABLE_RESULT_TEMPLATE)."'",
            "STAT_EVENT1"             => "'".trim($str_STAT_EVENT1)."'",
            "STAT_EVENT2"             => "'".trim($str_STAT_EVENT2)."'",
            "STAT_EVENT3"             => "'".trim($str_STAT_EVENT3)."'"
            );
        $DB->StartTransaction();
        if ($ID>0)
        {
            $DB->Update("b_form", $arFields, "WHERE ID='".$ID."'", $err_mess.__LINE__);
        }
        else
        {
            $ID = $DB->Insert("b_form", $arFields, $err_mess.__LINE__);
            $new="Y";
        }
        $ID = intval($ID);
        if (strlen($strError)<=0)
        {
            <b>$DB->Commit</b>();
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            elseif ($new=="Y") LocalRedirect("form_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
        }
        else $DB->Rollback();
    }
}?>


CompareDates

CDatabase::CompareDates

int
CDatabase::CompareDates(
 string date1,
 string date2,
)

Сравнивает между собой две даты. Возвращаемые значения:

Условие | Возвращаемое значение
date1 > date2 | 1
date1 < date2 | -1
date1 = date2 | 0

Параметры функции

Параметр | Описание
date1 | Первая дата для сравнения.
date2 | Вторая дата для сравнения.

См. также

  • Функции для работы с датой и временем
  • CheckFilterDates

Примеры использования

<?
// зададим дату 1
$date1 = "01.01.2005";

// зададим дату 2
$date2 = "01.01.2006";

$result = $DB->CompareDates($date2, $date1);

if ($result==1) echo $date1." > ".$date2;
elseif ($result==-1) echo $date1." < ".$date2;
elseif ($result==0) echo $date1." = ".$date2;
?>


Connect

CDatabase::Connect

bool
CDatabase::Connect(
 string host,
 string db,
 string login,
 string password
)

Открывает соединение с базой данных. Функция возвращает "true" при успешном открытии соединения или "false" при ошибке.

Параметры функции

Параметр | Описание
host | Сервер (хост) базы данных.
db | Имя базы данных.
login | Логин.
password | Пароль.

См. также

  • CDatabase::Disconnect

Примеры использования

<?
if(!($DB->Connect($DBHost, $DBName, $DBLogin, $DBPassword)))
{
    if(file_exists($_SERVER["DOCUMENT_ROOT"].BX_ROOT."/php_interface/dbconn_error.php"))
    {
        include($_SERVER["DOCUMENT_ROOT"].BX_ROOT."/php_interface/dbconn_error.php");
    }
    else
    {
        include($_SERVER["DOCUMENT_ROOT"].BX_ROOT."/modules/main/include/dbconn_error.php");
    }
    die();
}
?>


CurrentDateFunction

CDatabase::CurrentDateFunction

string
CDatabase::CurrentDateFunction()

Функция возвращает SQL функцию, которая в свою очередь возвращающую текущую дату. А именно: "CURRENT_DATE" для MySQL и "TRUNC(SYSDATE)" для Oracle.

Параметры функции

Без параметров.

См. также

  • CDatabase::CurrentTimeFunction
  • Функции для работы с датой и временем

Примеры использования

<?
$strSql = "UPDATE my_table SET DATE_CHANGE=".$DB->CurrentDateFunction()." WHERE ID=45";
$Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
?>
<?
$strSql = "
    SELECT
        ID
    FROM
        my_table
    WHERE
        DATE_CREATE <= ".$DB->CurrentDateFunction()."
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>


CurrentTimeFunction

CDatabase::CurrentTimeFunction

string
CDatabase::CurrentTimeFunction()

Функция возвращает строку "SYSDATE" для Oracle версии и "now()" для MySQL.

Параметры функции

Без параметров.

См. также

  • CDatabase::CurrentDateFunction
  • Функции для работы с датой и временем

Примеры использования

<?
$DB->Update("my_table", Array("TIME_CHANGE" => $DB->CurrentTimeFunction()),
"WHERE ID=45", $err_mess.__LINE__);
?>
<?
$strSql = "
    UPDATE my_table SET
        TIME_CHANGE=".$DB->CurrentTimeFunction()."
    WHERE ID=45
    ";
$Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
?>
<?
$strSql = "
    SELECT
        ID
    FROM
        my_table
    WHERE
        TIME_CHANGE <= ".$DB->CurrentTimeFunction()."
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>


DateFormatToPHP

CDatabase::DateFormatToPHP

string
CDatabase::DateFormatToPHP(
 string date_format
)

Функция конвертирует любой формат времени допустимый в настройках сайта в формат принятый в PHP.

Правила конвертации:

Исходные символы | После конвертации | Описание
YYYY | Y | Год (0001 - 9999)
MM | m | Месяц (01 - 12)
DD | d | День (01 - 31)
HH | H | Часы (00 - 24)
MI | i | Минуты (00 - 59)
SS | s | Секунды (00 - 59)

Параметры функции

Параметр | Описание
date_format | Формат для конвертации.

См. также

  • CDatabase::FormatDate
  • CSite::GetDateFormat
  • Функции для работы с датой и временем

Примеры использования

<?
// исходный формат
$format = "DD.MM.YYYY HH:MI:SS";

// переведем в PHP формат
$php_format = $DB->DateFormatToPHP($format); // d.m.Y H:i:s
?>
<?
// вывод текущей даты в формате текущего сайта

// получим формат сайта
$site_format = CSite::GetDateFormat("SHORT");

// переведем формат сайта в формат PHP
$php_format = $DB->DateFormatToPHP($site_format);

// выведем текущую дату в формате текущего сайта
echo date($php_format, time());
?>
<?
// вывод вчерашне даты в формате текущего сайта

// получим формат сайта
$site_format = CSite::GetDateFormat("SHORT");

// переведем формат сайта в формат PHP
$php_format = $DB->DateFormatToPHP($site_format);

// выведем вчерашнюю дату в формате текущего сайта
echo date($php_format, time()-86400);
?>


DateToCharFunction

CDatabase::DateToCharFunction

string
CDatabase::DateToCharFunction(
 string value,
 string type = "FULL",
 string site = false
 )

Возвращает для MySQL строку DATE_FORMAT, для Oracle - TO_CHAR с нужными параметрами.
Форматы даты устанавливается в настройках языка или сайта.

Параметры функции

Параметр | Описание
value | Значение даты для формата текущего сайта.
type | Тип формата даты: "FULL" - для даты со временем, "SHORT" - для даты (без времени) Необязательный. По умолчанию "FULL".
site | Код сайта для публичной части, либо код языка для административной части. Необязательный. По умолчанию текущий.

См. также

  • CDatabase::CharToDateFunction
  • Функции для работы с датой и временем

Примеры использования

<?
$strSql = "
    SELECT
        ID,
        ".$DB->DateToCharFunction("DATE_CREATE")."    DATE_CREATE
    FROM
        my_table
    ";
$rs = $DB->Query($strSql, false, $err_mess.__LINE__);
?>


Disconnect

CDatabase::Disconnect

CDatabase::Disconnect()

Закрывает соединение с базой данных.

Параметры функции

Без параметров.

См. также

  • CDatabase::Connect

Примеры использования

<?
$DB->Disconnect();
?>


FormatDate

CDatabase::FormatDate

string
CDatabase::FormatDate(
 string date,
 string from_format = "DD.MM.YYYY HH:MI:SS",
 string to_format = "DD.MM.YYYY HH:MI:SS"
)

Преобразует дату из одного заданного формата в другой заданный формат. В формате допустимы следующие обозначения:

Обозначение | Описание
YYYY | Год (0001 - 9999)
MM | Месяц (01 - 12)
DD | День (01 - 31)
HH | Часы (00 - 24)
MI | Минуты (00 - 59)
SS | Секунды (00 - 59)

Параметры функции

Параметр | Описание
date | Дата для конвертации.
from_format | Текущий формат даты. Необязательный. По умолчанию - "DD.MM.YYYY HH:MI:SS".
to_format | В какой формат необходимо преобразовать. Необязательный. По умолчанию - "DD.MM.YYYY HH:MI:SS".

См. также

  • CDatabase::DateFormatToPHP
  • CSite::GetDateFormat
  • ConvertDateTime
  • Функции для работы с датой и временем

Примеры использования

<?
// зададим дату
$date = "31.12.2007";

// укажем формат этой даты
$format = "DD.MM.YYYY";

// получим формат текущего сайта
$new_format = CSite::GetDateFormat("SHORT"); // YYYY-MM-DD

// переведем дату из одного формата в другой
$new_date = $DB->FormatDate($date, $format, $new_format);

// в результате получим дату в новом формате
echo $new_date; // 2007-12-31
?>
<?
// конвертация даты из формата одного сайта в формат другого

// получим формат сайта ru
$format_ru = CSite::GetDateFormat("SHORT", "ru"); // DD.MM.YYYY

// получим формат сайта en
$format_en = CSite::GetDateFormat("SHORT", "en"); // YYYY-MM-DD

// переведем дату из формата сайта ru в формат сайта en
$new_date = $DB->FormatDate($date, $format_ru, $format_en);

// в результате получим дату в новом формате
echo $date; // 2007-12-31
?>


ForSql

CDatabase::ForSql

string
CDatabase::ForSql(
 string value,
 int max_length=0
)

Подготавливает строку (заменяет кавычки и прочее) для вставки в SQL запрос. Если задан параметр max_length, то также обрезает строку до длины max_length.

Параметры функции

Параметр | Описание
value | Исходная строка.
max_length | Максимальная длина. Необязательный. По умолчанию - "0" (строка не обрезается).

См. также

  • CDatabase::Query
  • CDatabase::Update
  • CDatabase::Insert

Примеры использования

<?
$strSql = "
    SELECT
        ID
    FROM
        b_stat_phrase_list
    WHERE
        PHRASE='".$DB->ForSql($search_phrase)."'
    and SESSION_ID='".$_SESSION["SESS_SESSION_ID"]."'
    ";
$w = $DB->Query($strSql, false, $err_mess.__LINE__);
?>


InitTableVarsForEdit

CDatabase::InitTableVarsForEdit

CDatabase::InitTableVarsForEdit(
 string table,
 string prefix_from = "str_",
 string prefix_to = "str_",
 string postfix_from = "",
 bool init_anyway = false
 )

Создает глобальные переменные с именами ${prefix_to.имя_поля} и присваивает им значения переменных с именами ${prefix_from.имя_поля.postfix_from} переводя при этом в HTML-безопасный вид. Под "имя_поля" подразумеваются имена полей таблицы table.

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

Параметры функции

Параметр | Описание
table | Название таблицы.
prefix_from | Префикс для переменных ИЗ которых будет производиться преобразование. Необязательный. По умолчанию "str_".
prefix_to | Префикс для переменных В которые будет производиться преобразование. Необязательный. По умолчанию "str_".
postfix_from | Суффикс (постфикс) для переменных ИЗ которых будет производиться преобразование. Необязательный. По умолчанию "".
init_anyway | Значение "true" - инициализировать переменные всегда, т.е. не зависимо были ли они изначально. Необязательный. По умолчанию - "false".

См. также

  • CDatabase::PrepareFields

Примеры использования

<?
$stoplist = CStoplist::GetByID($ID);
if (!($stoplist && $stoplist->ExtractFields()))
{
    $ID=0;
    $str_ACTIVE="Y";
    $str_MASK_1="255";
    $str_MASK_2="255";
    $str_MASK_3="255";
    $str_MASK_4="255";
    $str_IP_1 = $net1;
    $str_IP_2 = $net2;
    $str_IP_3 = $net3;
    $str_IP_4 = $net4;
    $str_USER_AGENT = $user_agent;
    $str_DATE_START=GetTime(time(),"FULL");
    $str_MESSAGE = GetMessage("STAT_DEFAULT_MESSAGE");
    $str_MESSAGE_LID = LANGUAGE_ID;
    $str_SAVE_STATISTIC = "Y";
}
if (strlen($strError)>0) $DB->InitTableVarsForEdit("b_stop_list", "", "str_");
?>


Insert

CDatabase::Insert

mixed
CDatabase::Insert(
 string table,
 array fields,
 string error_position = "",
 bool debug = false,
 int exist_id = "",
 bool ignore_errors = false
)

Функция вставляет запись в таблицу table с значениями полей fields. Необходимые условия использования данной функции:

  • Необходимо наличие поля "ID" в таблице, представляющее из себя Primary Key для данной таблицы.
  • Для MySQL поле "ID" должно быть auto increment (если при вызове функции явно не задается параметр exist_id).
  • Для Oracle обязательно наличие sequence (последовательности) с именем вида "SQ_.table".
Возвращает ID вставленной записи или false в случае ошибки.

Примечание: все значения полей должны быть подготовлены для SQL запроса, например, при помощи функции CDatabase::ForSql.

Параметры функции

Параметр | Описание
table | Название таблицы.
fields | Массив вида значений полей "поле"=>"значение",...
error_position | Строка идентифицирующая позицию в коде, откуда была вызвана данная функция CDatabase::Insert. Если в SQL запросе будет ошибка и если в файле /bitrix/php_interface/dbconn.php установлена переменная $DBDebug=true;, то на экране будет выведена данная информация и сам SQL запрос.
debug | Если значение - "true", то на экран будет выведен текст SQL запроса.
exist_id | Если данный параметр задан в виде положительного числа, то при вставке записи в таблицу, будет добавлено поле с именем "ID" и значением exist_id. Если данный параметр явно не задан, то для Oracle таблицы будет добавлено поле "ID", со значением SQ_table.nextval().
ignore_errors | если значение "true", то в случае ошибки возникшей в результате выполнения SQL запроса, она будет проигнорирована и работа скрипта продолжена.

См. также

  • CDatabase::Query
  • CDatabase::ForSql
  • CDatabase::Update
  • CDatabase::PrepareInsert
  • CDatabase::PrepareUpdate

Примеры использования

<?
if (strlen($save)>0)
{
    if (CheckFields())
    {
        $DB->PrepareFields("b_form");
        $arFields = array(
            "TIMESTAMP_X"             => $DB->GetNowFunction(),
            "NAME"                    => "'".trim($str_NAME)."'",
            "VARNAME"                 => "'".trim($str_VARNAME)."'",
            "C_SORT"                  => "'".intval($str_C_SORT)."'",
            "FIRST_SITE_ID"           => "'".$DB->ForSql($FIRST_SITE_ID,2)."'",
            "BUTTON"                  => "'".$str_BUTTON."'",
            "DESCRIPTION"             => "'".$str_DESCRIPTION."'",
            "DESCRIPTION_TYPE"        => "'".$str_DESCRIPTION_TYPE."'",
            "SHOW_TEMPLATE"           => "'".trim($str_SHOW_TEMPLATE)."'",
            "MAIL_EVENT_TYPE"         => "'".$DB->ForSql("FORM_FILLING_".$str_VARNAME,50)."'",
            "SHOW_RESULT_TEMPLATE"    => "'".trim($str_SHOW_RESULT_TEMPLATE)."'",
            "PRINT_RESULT_TEMPLATE"   => "'".trim($str_PRINT_RESULT_TEMPLATE)."'",
            "EDIT_RESULT_TEMPLATE"    => "'".trim($str_EDIT_RESULT_TEMPLATE)."'",
            "FILTER_RESULT_TEMPLATE"  => "'".trim($str_FILTER_RESULT_TEMPLATE)."'",
            "TABLE_RESULT_TEMPLATE"   => "'".trim($str_TABLE_RESULT_TEMPLATE)."'",
            "STAT_EVENT1"             => "'".trim($str_STAT_EVENT1)."'",
            "STAT_EVENT2"             => "'".trim($str_STAT_EVENT2)."'",
            "STAT_EVENT3"             => "'".trim($str_STAT_EVENT3)."'"
            );
        $DB->StartTransaction();
        if ($ID>0)
        {
            $DB->Update("b_form", $arFields, "WHERE ID='".$ID."'", $err_mess.__LINE__);
        }
        else
        {
            $ID = $DB->Insert("b_form", $arFields, $err_mess.__LINE__);
            $new="Y";
        }
        $ID = intval($ID);
        if (strlen($strError)<=0)
        {
            $DB->Commit();
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            elseif ($new=="Y") LocalRedirect("form_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
        }
        else $DB->Rollback();
    }
}
?>


IsDate

CDatabase::IsDate

bool
CDatabase::IsDate(
 string date,
 string format=false,
 string site=false,
 string type="SHORT"
 )

Проверяет дату на корректность и возвращает "true" если дата корректна, в противном случае - "false".

Параметры функции

Параметр | Описание
date | Строка с проверяемой датой.
format | Формат даты. Необязательный. По умолчанию - "false" - определять формат по текущему сайту, либо языку (если административная часть).
site | Код сайта для публичной части, либо код языка для административной части (для определения формата, если format равен false). Необязательный. По умолчанию - текущий сайт, либо текущий язык (если административная часть).
type | Тип формата даты: "FULL" - для даты со временем, "SHORT" - для даты (без времени) Необязательный. По умолчанию "SHORT".

См. также

  • Функции для работы с датой и временем
  • CheckFilterDates

Примеры использования

<?
if (!$DB->IsDate("12.10.2005 22:34:15", "DD.MM.YYYY HH:MI:SS"))
  echo "Ошибка. Неверный формат даты.";
?>


LastID

CDatabase::LastID

int
CDatabase::LastID()

Функция возвращает ID последней вставленной записи.

Только для MySQL версии!

Параметры функции

Без параметров.

См. также

  • CDatabase::Query

Примеры использования

<?
function AddResultAnswer($arFields)
{
    $err_mess = (CForm::err_mess())."<br>Function: AddResultAnswer<br>Line: ";
    global $DB;
    $arInsert = $DB->PrepareInsert("b_form_result_answer", $arFields, "form");
    $strSql = "INSERT INTO b_form_result_answer (".$arInsert[0].") VALUES (".$arInsert[1].")";
    $DB->Query($strSql, false, $err_mess.__LINE__);
    return intval($DB->LastID());
}
?>


NextID

CDatabase::NextID

int
CDatabase::NextID(
 string sequence_name
)

Только для Oracle версии!

Функция возвращает следующее значение из sequence sequence_name.

Параметры функции

Параметр | Описание
sequence_name | Имя sequence.

См. также

  • CDatabase::Query

Примеры использования

<?
function AddResultAnswer($arFields)
{
    $err_mess = (CForm::err_mess())."<br>Function: AddResultAnswer<br>Line: ";
    global $DB;
    $arBinds = array();
    $arInsert = $DB->PrepareInsert("b_form_result_answer", $arFields, "form");
    $AID = $DB->NextID("sq_b_form_result_answer");
    $strSql="INSERT INTO b_form_result_answer (ID,".$arInsert[0].") VALUES ($AID,".$arInsert[1].")";
    if (is_set($arFields, "USER_TEXT"))
        $arBinds["USER_TEXT"] = $arFields["USER_TEXT"];
    if (is_set($arFields, "ANSWER_TEXT_SEARCH"))
        $arBinds["ANSWER_TEXT_SEARCH"] = $arFields["ANSWER_TEXT_SEARCH"];
    if (is_set($arFields, "ANSWER_VALUE_SEARCH"))
        $arBinds["ANSWER_VALUE_SEARCH"] = $arFields["ANSWER_VALUE_SEARCH"];
    if (is_set($arFields, "USER_TEXT_SEARCH"))
        $arBinds["USER_TEXT_SEARCH"] = $arFields["USER_TEXT_SEARCH"];
    $DB->QueryBind($strSql, $arBinds);
    return $AID;
}
?>


ParseSqlBatch

CDatabase::ParseSqlBatch

array
CDatabase::ParseSqlBatch(
 string sql
)

Функция разбирает строку из пакета запросов на массив запросов и возвращает этот массив.

Параметры функции

Параметр | Описание
sql | Строка с пакетом запросов, разделенных символом ";" для MySQL версии и символом "/" для Oracle версии.

См. также

  • CDatabase::RunSqlBatch
  • CDatabase::Query

Примеры использования

<?
function RunSqlBatch($filepath)
{
    $arErr = Array();
    // откроем файл с запросами
    $f = @fopen($filepath, "rb");
    if($f)
    {
        $contents = fread($f, filesize($filepath));
        fclose($f);

        // разобьем на отдельные запросы
        $arSql = $this->ParseSqlBatch($contents);
        for($i=0; $i<count($arSql); $i++)
        {
            $strSql = str_replace("\r\n", "\n", $arSql[$i]);
            if(!$this->Query($strSql, true))
                $arErr[] = $this->db_Error;
        }
    }
    if(count($arErr)>0)
        return $arErr;

    return false;
}
?>


PrepareFields

CDatabase::PrepareFields

CDatabase::PrepareFields(
 string table,
 string prefix = "str_",
 string postfix = ""
)

Функция подготавливает глобальные переменные, соответствующие именам полей таблицы table для записи в БД.

Создает глобальные переменные ${prefix.имя_поля.postfix} и устанавливает их значениями глобальных переменных, соответствующих именам полей из таблицы table, предварительно преобразовав их в зависимости от типа поля.

Например, для поля типа int будет выполнено:

${prefix.имя_поля.postfix} = intval(${имя_поля});
Для поля типа varchar:

${prefix.имя_поля.postfix} = CDatabase::ForSql(${имя_поля}, размер_поля);

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

Параметры функции

Параметр | Описание
table | Имя таблицы.
prefix | Префикс переменных. Необязательный. По умолчанию "str_".
postfix | Постфикс переменных. Необязательный. По умолчанию пустая строка.

См. также

  • CDatabase::InitTableVarsForEdit

Примеры использования

<?
if (strlen($save)>0)
{
    if (CheckFields())
    {
        $DB->PrepareFields("b_form");
        $arFields = array(
            "TIMESTAMP_X"             => $DB->GetNowFunction(),
            "NAME"                    => "'".trim($str_NAME)."'",
            "VARNAME"                 => "'".trim($str_VARNAME)."'",
            "C_SORT"                  => "'".intval($str_C_SORT)."'",
            "FIRST_SITE_ID"           => "'".$DB->ForSql($FIRST_SITE_ID,2)."'",
            "BUTTON"                  => "'".$str_BUTTON."'",
            "DESCRIPTION"             => "'".$str_DESCRIPTION."'",
            "DESCRIPTION_TYPE"        => "'".$str_DESCRIPTION_TYPE."'",
            "SHOW_TEMPLATE"           => "'".trim($str_SHOW_TEMPLATE)."'",
            "MAIL_EVENT_TYPE"         => "'".$DB->ForSql("FORM_FILLING_".$str_VARNAME,50)."'",
            "SHOW_RESULT_TEMPLATE"    => "'".trim($str_SHOW_RESULT_TEMPLATE)."'",
            "PRINT_RESULT_TEMPLATE"   => "'".trim($str_PRINT_RESULT_TEMPLATE)."'",
            "EDIT_RESULT_TEMPLATE"    => "'".trim($str_EDIT_RESULT_TEMPLATE)."'",
            "FILTER_RESULT_TEMPLATE"  => "'".trim($str_FILTER_RESULT_TEMPLATE)."'",
            "TABLE_RESULT_TEMPLATE"   => "'".trim($str_TABLE_RESULT_TEMPLATE)."'",
            "STAT_EVENT1"             => "'".trim($str_STAT_EVENT1)."'",
            "STAT_EVENT2"             => "'".trim($str_STAT_EVENT2)."'",
            "STAT_EVENT3"             => "'".trim($str_STAT_EVENT3)."'"
            );
        if ($ID>0)
        {
            $DB->Update("b_form", $arFields, "WHERE ID='".$ID."'", $err_mess.__LINE__);
        }
        else
        {
            $ID = $DB->Insert("b_form", $arFields, $err_mess.__LINE__);
            $new="Y";
        }
        $ID = intval($ID);
        if (strlen($strError)<=0)
        {
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            elseif ($new=="Y") LocalRedirect("form_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
        }
    }
}
?>


PrepareInsert

CDatabase::PrepareInsert

array
CDatabase::PrepareInsert(
 string table,
 array fields,
 string dir = "",
 string site = false
)

Функция подготавливает массив из двух строк для SQL запроса вставки записи в базу данных. Возвращает массив из двух элементов, где элемент с ключом 0 строка список полей вида "имя поля1, имя поля2[, ...]", а элемент с ключом 1 строка значений вида "значение1, значение2[, ...]". При этом функция сама преобразует все значение в SQL вид в зависимости от типа поля и обрабатывает загрузку файлов, возвращая ID из таблицы файлов.

Параметры функции

Параметр | Описание
table | Имя таблицы для вставки записи.
fields Массив значений полей в формате "имя поля1"=>"значение1", "имя поля2"=>"значение2" [, ...].
Если необходимо вставить значение NULL, то значение должно быть равно false. При вставке файла, привязанного к записи, "значение" должно быть представлено в виде массива
Array(
"name" => "название файла",
"size" => "размер",
"tmp_name" => "временный путь на сервере",
"type" => "тип загружаемого файла",
"del" => "флажок - удалить ли существующий файл (Y|N)",
"MODULE_ID" => "название модуля");

Массив такого вида может быть получен, например, объединением массивов $HTTP_POST_FILES[имя поля] и Array("del" => ${"имя поля"."_del"}, "MODULE_ID" = "название модуля");
dir Имя папки (будет находится внутри папки upload) для хранения файлов. Используется для вставки файлов, привязанных к записи.
Необязательный. По умолчанию пустая строка.
site Код сайта для публичной части, либо код языка для административной части. Используется для определения формата даты, для вставки полей типа date или datetime.
Необязательный. По умолчанию текущий.

См. также

  • CDatabase::PrepareUpdate

Примеры использования

<?
function AddResultAnswer($arFields)
{
    $err_mess = (CForm::err_mess())."<br>Function: AddResultAnswer<br>Line: ";
    global $DB;
    $arInsert = $DB->PrepareInsert("b_form_result_answer", $arFields, "form");
    $strSql = "INSERT INTO b_form_result_answer (".$arInsert[0].") VALUES (".$arInsert[1].")";
    $DB->Query($strSql, false, $err_mess.__LINE__);
    return intval($DB->LastID());
}
?>


PrepareUpdate

CDatabase::PrepareUpdate

array
CDatabase::PrepareUpdate(
 string table,
 array fields,
 string dir="",
 string site=false
)

Функция подготавливает строку для SQL запроса изменения записи в базе данных. Возвращает строку вида "имя поля1 = значение1", имя поля2 = значение2[, ...]". При этом функция сама преобразует все значение в SQL вид в зависимости от типа поля и обрабатывает загрузку файлов, возвращая ID из таблицы файлов.

Параметры функции

Параметр | Описание
table | Имя таблицы.
fields Массив значений полей в формате "имя поля1"=>"значение1", "имя поля2"=>"значение2" [, ...].
Если необходимо изменить значение на NULL, то значение в массиве должно быть равно false. При вставке файла, привязанного к записи, "значение" должно быть представленно в виде массива
Array(
"name" => "название файла",
"size" => "размер",
"tmp_name" => "временный путь на сервере",
"type" => "тип загружаемого файла",
"del" => "флажок - удалить ли существующий файл (Y|N)",
"MODULE_ID" => "название модуля");

Массив такого вида может быть получен, например, объединением массивов $HTTP_POST_FILES[имя поля] и Array("del" => ${"имя поля"."_del"}, "MODULE_ID" = "название модуля");
Если какого-либо поля нет в массиве, то его значение в таблице останется прежним.
dir Имя папки (будет находится внутри папки upload) для хранения файлов. Используется для вставки файлов, привязанных к записи.
Необязательный. По умолчанию пустая строка.
site Код сайта для публичной части, либо код языка для административной части. Используется для определения формата даты, для вставки полей типа date или datetime.
Необязательный. По умолчанию текущий.

См. также

  • CDatabase::PrepareInsert

Примеры использования

<?
function UpdateResultField($arFields, $RESULT_ID, $FIELD_ID)
{
    $err_mess = (CForm::err_mess())."<br>Function: UpdateResultField<br>Line: ";
    global $DB;
    $RESULT_ID = intval($RESULT_ID);
    $FIELD_ID = intval($FIELD_ID);
    $strUpdate = $DB->PrepareUpdate("b_form_result_answer", $arFields, "form");
    $strSql = "UPDATE b_form_result_answer SET ".$strUpdate." WHERE RESULT_ID=".$RESULT_ID." and FIELD_ID=".$FIELD_ID;
    $DB->Query($strSql, false, $err_mess.__LINE__);
}
?>


Query

CDatabase::Query

mixed
CDatabase::Query(
 string sql,
 bool ignore_errors=false,
 string error_position=""
)

Функция выполняет запрос к базе данных и если не произошло ошибки возвращает результат. В случае успешного выполнения функция возвращает объект класса CDBResult.
Если произошла ошибка и параметр ignore_errors равен "true", то функция вернет "false".
Если произошла ошибка и параметр ignore_errors равен "false", то функция прерывает выполнение страницы, выполняя перед этим следующие действия:

  1. Вызов функции AddMessage2Log.
  2. Если текущий пользователь является администратором сайта, либо в файле /bitrix/php_interface/dbconn.php была инициализирована переменная $DBDebug=true;, то на экран будет выведен полный текст ошибки, в противном случае будет вызвана функция SendError.
  3. Будет подключен файл /bitrix/php_interface/dbquery_error.php, если он не существует, то будет подключен файл /bitrix/modules/main/include/dbquery_error.php

Примечания для Oracle версии:
1. При возникновении ошибки, если была открыта транзакция, то выполняется CDataBase::Rollback.
2. Для вставки текстовых полей типа BLOB, CLOB, LONG и т.п. (длинною больше 4000 символов), воспользуйтесь функцией CDatabase::QueryBind.
3. Если при выполнении SQL-запроса типа "SELECT" требуется связывание переменных, то воспользуйтесь функцией CDatabase::QueryBindSelect.

Параметры функции

Параметр | Описание
sql | SQL запрос.
ignore_errors | Игнорировать ошибки. Если true, то в случае ошибки функция возвращает "false". Если параметр ignore_errors равен "false", то в случае ошибки функция прекращает выполнение всей страницы. Необязательный. По умолчанию - "false".
error_position | Строка идентифицирующая позицию в коде, откуда была вызвана данная функция CDatabase::Query. Если в SQL запросе будет ошибка и если в файле /bitrix/php_interface/dbconn.php установлена переменная $DBDebug=true;, то на экране будет выведена данная информация и сам SQL запрос.

См. также

  • CDatabase::QueryBind
  • CDatabase::QueryBindSelect
  • CDatabase::ForSql
  • AddMessage2Log

Примеры использования

<?
function GetByID($ID, $GET_BY_SID="N")
{
    $err_mess = (CForm::err_mess())."<br>Function: GetByID<br>Line: ";
    global $DB;
    $where = ($GET_BY_SID=="N") ? " F.ID = '".intval($ID)."' " : " F.VARNAME='".$DB->ForSql($ID,50)."' ";
    $strSql = "
        SELECT
            F.*,
            F.FIRST_SITE_ID,
            F.FIRST_SITE_ID									LID,
            F.VARNAME,
            F.VARNAME										SID,
            ".$DB->DateToCharFunction("F.TIMESTAMP_X")."	TIMESTAMP_X,
            count(distinct D1.ID)							C_FIELDS,
            count(distinct D2.ID)							QUESTIONS,
            count(distinct S.ID)							STATUSES
        FROM b_form F
        LEFT JOIN b_form_status S ON (S.FORM_ID = F.ID)
        LEFT JOIN b_form_field D1 ON (D1.FORM_ID = F.ID and D1.ADDITIONAL='Y')
        LEFT JOIN b_form_field D2 ON (D2.FORM_ID = F.ID and D2.ADDITIONAL<>'Y')
        WHERE
            $where
        GROUP BY
            F.ID
        ";
    $res = $DB->Query($strSql, false, $err_mess.__LINE__);
    return $res;
}
?>


QueryBind

CDatabase::QueryBind

mixed
CDatabase::QueryBind(
 string sql,
 array binds,
 bool ignore_errors=false,
 string error_position=""
)

Выполняет SQL-запросы типа "UPDATE", "INSERT", в которых есть необходимость связывания переменных (как правило для полей типа BLOB, CLOB, LONG и т.п.).

В случае успешного выполнения функция возвращает объект класса CDBResult.
Если произошла ошибка и параметр ignore_errors равен "true", то функция вернет "false".
Если произошла ошибка и параметр ignore_errors равен "false", то функция прерывает выполнение страницы, выполняя перед этим следующие действия:

  1. Вызов функции AddMessage2Log.
  2. Если текущий пользователь является администратором сайта, либо в файле /bitrix/php_interface/dbconn.php была инициализирована переменная $DBDebug=true;, то на экран будет выведен полный текст ошибки, в противном случае будет вызвана функция SendError.
  3. Будет подключен файл /bitrix/php_interface/dbquery_error.php, если он не существует, то будет подключен файл /bitrix/modules/main/include/dbquery_error.php

Только для Oracle версии!

Параметры функции

Параметр | Описание
sql | SQL запрос.
binds | Массив полей типа BLOB, CLOB, LONG и т.п. в формате array("имя поля" => "значение" [, ...]).
ignore_errors | Игнорировать ошибки. Если true, то в случае ошибки функция возвращает "false". Если параметр ignore_errors равен "false", то в случае ошибки функция прекращает выполнение всей страницы. Необязательный. По умолчанию - "false".
error_position | Строка идентифицирующая позицию в коде, откуда была вызвана данная функция CDatabase::QueryBind. Если в SQL запросе будет ошибка и если в файле /bitrix/php_interface/dbconn.php установлена переменная $DBDebug=true;, то на экране будет выведена данная информация и сам SQL запрос.

См. также

  • CDatabase::Query
  • CDatabase::QueryBindSelect
  • CDatabase::ForSql
  • AddMessage2Log

Пример использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
$APPLICATION->SetTitle("TEST CLOB");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_before.php");

// обновление поля

$MY_FIELD_VALUE = "123";

// обновим поле MY_FIELD типа CLOB
$strError = "";
$arFields["NEWS_TEXT_FCK"] = $MY_FIELD_VALUE;
$strUpdate = $DB->PrepareUpdate("aa_abc", $arFields);
if($strUpdate != "")
{
$strSql = "UPDATE aa_abc SET ".$strUpdate." WHERE ID=15";
// в переменной $MY_FIELD_VALUE содержится текст длиной более 4000 символов
$arBinds = array("NEWS_TEXT_FCK" => $MY_FIELD_VALUE);

// выполним запрос со связыванием :MY_FIELD с реальным значением
if(!$DB->QueryBind($strSql, $arBinds))
$strError = "Query Error!";
}
if($strError=="")
echo "all Ok!";

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


QueryBindSelect

CDatabase::QueryBindSelect

mixed
CDatabase::QueryBindSelect(
 string sql,
 array binds,
 bool ignore_errors=false,
 string error_position=""
)

Выполняет SQL-запрос типа "SELECT", в котором есть необходимость связывание переменных.

В случае успешного выполнения функция возвращает объект класса CDBResult.
Если произошла ошибка и параметр ignore_errors равен "true", то функция вернет "false".
Если произошла ошибка и параметр ignore_errors равен "false", то функция прерывает выполнение страницы, выполняя перед этим следующие действия:

  1. Вызов функции AddMessage2Log.
  2. Если текущий пользователь является администратором сайта, либо в файле /bitrix/php_interface/dbconn.php была инициализирована переменная $DBDebug=true;, то на экран будет выведен полный текст ошибки, в противном случае будет вызвана функция SendError.
  3. Будет подключен файл /bitrix/php_interface/dbquery_error.php, если он не существует, то будет подключен файл /bitrix/modules/main/include/dbquery_error.php

Только для Oracle версии!

Параметры функции

Параметр | Описание
sql | SQL запрос.
binds | Массив полей типа BLOB, CLOB, LONG и т.п. в формате array("имя поля" => "значение" [, ...])
ignore_errors | Игнорировать ошибки. Если true, то в случае ошибки функция возвращает "false". Если параметр ignore_errors равен "false", то в случае ошибки функция прекращает выполнение всей страницы. Необязательный. По умолчанию - "false".
error_position | Строка идентифицирующая позицию в коде, откуда была вызвана данная функция CDatabase::QueryBindSelect. Если в SQL запросе будет ошибка и если в файле /bitrix/php_interface/dbconn.php установлена переменная $DBDebug=true;, то на экране будет выведена данная информация и сам SQL запрос.

См. также

  • CDatabase::Query
  • CDatabase::QueryBind
  • CDatabase::ForSql
  • AddMessage2Log

Примеры использования

<?
$strSql = "
    SELECT
        *
    FROM
        my_table
    WHERE
        :url like '/ru/index.php%'
    ";
$arrBind = array("url" => $APPLICATION->GetCurUri());
$rs = $DB->QueryBindSelect($strSql, $arrBind, false, "F: ".__FILE__." L: ".__LINE__);
?>


Rollback

CDatabase::Rollback

CDatabase::Rollback()

Откатывает назад изменения произведенные открытой и незавершенной транзакцией.

Работает для Oracle, MSSQL, MySQL (для типа таблиц InnoDB).

Параметры функции

Без параметров.

См. также

  • CDatabase::Commit
  • CDatabase::StartTransaction

Примеры использования

<?
if (strlen($save)>0)
{
    if (CheckFields())
    {
        $DB->PrepareFields("b_form");
        $arFields = array(
            "TIMESTAMP_X"             => $DB->GetNowFunction(),
            "NAME"                    => "'".trim($str_NAME)."'",
            "VARNAME"                 => "'".trim($str_VARNAME)."'",
            "C_SORT"                  => "'".intval($str_C_SORT)."'",
            "FIRST_SITE_ID"           => "'".$DB->ForSql($FIRST_SITE_ID,2)."'",
            "BUTTON"                  => "'".$str_BUTTON."'",
            "DESCRIPTION"             => "'".$str_DESCRIPTION."'",
            "DESCRIPTION_TYPE"        => "'".$str_DESCRIPTION_TYPE."'",
            "SHOW_TEMPLATE"           => "'".trim($str_SHOW_TEMPLATE)."'",
            "MAIL_EVENT_TYPE"         => "'".$DB->ForSql("FORM_FILLING_".$str_VARNAME,50)."'",
            "SHOW_RESULT_TEMPLATE"    => "'".trim($str_SHOW_RESULT_TEMPLATE)."'",
            "PRINT_RESULT_TEMPLATE"   => "'".trim($str_PRINT_RESULT_TEMPLATE)."'",
            "EDIT_RESULT_TEMPLATE"    => "'".trim($str_EDIT_RESULT_TEMPLATE)."'",
            "FILTER_RESULT_TEMPLATE"  => "'".trim($str_FILTER_RESULT_TEMPLATE)."'",
            "TABLE_RESULT_TEMPLATE"   => "'".trim($str_TABLE_RESULT_TEMPLATE)."'",
            "STAT_EVENT1"             => "'".trim($str_STAT_EVENT1)."'",
            "STAT_EVENT2"             => "'".trim($str_STAT_EVENT2)."'",
            "STAT_EVENT3"             => "'".trim($str_STAT_EVENT3)."'"
            );
        $DB->StartTransaction();
        if ($ID>0)
        {
            $DB->Update("b_form", $arFields, "WHERE ID='".$ID."'", $err_mess.__LINE__);
        }
        else
        {
            $ID = $DB->Insert("b_form", $arFields, $err_mess.__LINE__);
            $new="Y";
        }
        $ID = intval($ID);
        if (strlen($strError)<=0)
        {
            $DB->Commit();
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            elseif ($new=="Y") LocalRedirect("form_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
        }
        else $DB->Rollback();
    }
}
?>


RunSqlBatch

CDatabase::RunSqlBatch

mixed
CDatabase::RunSqlBatch(
 string path
)

Функция выполняет пакет запросов из файла path. Возвращает "false", если все запросы выполнились, или массив ошибок для запросов которые привели к ошибке.

Параметры функции

Параметр | Описание
path | Файл с пакетом запросов. Для MySQL версии запросы разделяются символом ";", для Oracle версии разделитель "/".

См. также

  • CDatabase::ParseSqlBatch
  • CDatabase::Query

Пример вызова функции

<?
$arrErrors = $DB->RunSqlBatch($_SERVER["DOCUMENT_ROOT"].
"/bitrix/modules/form/install/db/".strtolower($DB->type)."/install.sql");
?>

Пример файла c запросами для MySQL

create table if not exists b_stat_adv_searcher (
   ID int(11) not null auto_increment,
   ADV_ID int(11) not null,
   SEARCHER_ID int(11) not null,
   primary key (ID));
insert  into b_stat_adv (ID, REFERER1, REFERER2) values (1, 'aport', '') ;
insert  into b_stat_adv_searcher (ID, ADV_ID, SEARCHER_ID) values (1, 2, 4) ;

Пример файла c запросами для Oracle

CREATE TABLE B_STAT_ADDITIONAL
(
    ID         NUMBER(18)    NOT NULL,
    C_TYPE     VARCHAR2(255) NOT NULL,
    NAME       NUMBER(18)    NULL,
    SESSIONS   NUMBER(18)    DEFAULT 0 NOT NULL,
    HITS       NUMBER(18)    DEFAULT 0 NOT NULL,
    NEW_GUESTS NUMBER(18)    DEFAULT 0 NOT NULL,
    C_EVENTS   NUMBER(18)    DEFAULT 0 NOT NULL,
    PRIMARY KEY (ID)
)
/
CREATE SEQUENCE SQ_B_STAT_ADDITIONAL
    START WITH 44
    INCREMENT BY 1
    NOMINVALUE
    NOMAXVALUE
    NOCYCLE
    NOCACHE
    NOORDER
/
INSERT INTO B_STAT_ADV (ID, REFERER1, REFERER2) VALUES (1, 'aport', '')
/
DROP SEQUENCE SQ_B_STAT_ADV
/
CREATE SEQUENCE SQ_B_STAT_ADV
    START WITH 8
    INCREMENT BY 1
    NOMINVALUE
    NOMAXVALUE
    NOCYCLE
    NOCACHE
    NOORDER
/
INSERT INTO B_STAT_ADV_SEARCHER (ID, ADV_ID, SEARCHER_ID) VALUES (1, 2, 4)
/


StartTransaction

CDatabase::StartTransaction

CDatabase::StartTransaction()

Открывает транзакцию. Для закрытия используйте Commit или Rollback.

Работает для Oracle, MSSQL, MySQL (для типа таблиц InnoDB).

Параметры функции

Без параметров.

См. также

  • CDatabase::Commit
  • CDatabase::Rollback

Примеры использования

<?
if (strlen($save)>0)
{
    if (CheckFields())
    {
        $DB->PrepareFields("b_form");
        $arFields = array(
            "TIMESTAMP_X"             => $DB->GetNowFunction(),
            "NAME"                    => "'".trim($str_NAME)."'",
            "VARNAME"                 => "'".trim($str_VARNAME)."'",
            "C_SORT"                  => "'".intval($str_C_SORT)."'",
            "FIRST_SITE_ID"           => "'".$DB->ForSql($FIRST_SITE_ID,2)."'",
            "BUTTON"                  => "'".$str_BUTTON."'",
            "DESCRIPTION"             => "'".$str_DESCRIPTION."'",
            "DESCRIPTION_TYPE"        => "'".$str_DESCRIPTION_TYPE."'",
            "SHOW_TEMPLATE"           => "'".trim($str_SHOW_TEMPLATE)."'",
            "MAIL_EVENT_TYPE"         => "'".$DB->ForSql("FORM_FILLING_".$str_VARNAME,50)."'",
            "SHOW_RESULT_TEMPLATE"    => "'".trim($str_SHOW_RESULT_TEMPLATE)."'",
            "PRINT_RESULT_TEMPLATE"   => "'".trim($str_PRINT_RESULT_TEMPLATE)."'",
            "EDIT_RESULT_TEMPLATE"    => "'".trim($str_EDIT_RESULT_TEMPLATE)."'",
            "FILTER_RESULT_TEMPLATE"  => "'".trim($str_FILTER_RESULT_TEMPLATE)."'",
            "TABLE_RESULT_TEMPLATE"   => "'".trim($str_TABLE_RESULT_TEMPLATE)."'",
            "STAT_EVENT1"             => "'".trim($str_STAT_EVENT1)."'",
            "STAT_EVENT2"             => "'".trim($str_STAT_EVENT2)."'",
            "STAT_EVENT3"             => "'".trim($str_STAT_EVENT3)."'"
            );
        $DB->StartTransaction();
        if ($ID>0)
        {
            $DB->Update("b_form", $arFields, "WHERE ID='".$ID."'", $err_mess.__LINE__);
        }
        else
        {
            $ID = $DB->Insert("b_form", $arFields, $err_mess.__LINE__);
            $new="Y";
        }
        $ID = intval($ID);
        if (strlen($strError)<=0)
        {
            $DB->Commit();
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            elseif ($new=="Y") LocalRedirect("form_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
        }
        else $DB->Rollback();
    }
}
?>


Update

CDatabase::Update

int
CDatabase::Update(
 string table,
 array fields,
 string where = "",
 string error_position = "",
 bool debug = false,
 bool ignore_errors = false
 )

Функция изменяет записи в таблицы table значениями полей fields. Возвращает количество измененных записей.

Примечание: все значения полей должны быть подготовлены для SQL запроса, например, при помощи функции CDatabase::ForSql.

Параметры функции

Параметр | Описание
table | Название таблицы.
fields | Массив вида значений полей "поле"=>"значение",...
where | Ограничение для WHERE в формате SQL Необязательный. По умолчанию все записи в таблице будут изменены.
error_position | Строка идентифицирующая позицию в коде, откуда была вызвана данная функция CDatabase::Update. Если в SQL запросе будет ошибка и если в файле /bitrix/php_interface/dbconn.php установлена переменная $DBDebug=true;, то на экране будет выведена данная информация и сам SQL запрос.
debug | Если значение - "true", то на экран будет выведен текст SQL запроса.
ignore_errors | если значение "true", то в случае ошибки возникшей в результате выполнения SQL запроса, она будет проигнорирована и работа скрипта продолжена.

См. также

  • CDatabase::Query
  • CDatabase::ForSql
  • CDatabase::Insert
  • CDatabase::PrepareInsert
  • CDatabase::PrepareUpdate

Примеры использования

<?
if (strlen($save)>0)
{
    if (CheckFields())
    {
        $DB->PrepareFields("b_form");
        $arFields = array(
            "TIMESTAMP_X"             => $DB->GetNowFunction(),
            "NAME"                    => "'".trim($str_NAME)."'",
            "VARNAME"                 => "'".trim($str_VARNAME)."'",
            "C_SORT"                  => "'".intval($str_C_SORT)."'",
            "FIRST_SITE_ID"           => "'".$DB->ForSql($FIRST_SITE_ID,2)."'",
            "BUTTON"                  => "'".$str_BUTTON."'",
            "DESCRIPTION"             => "'".$str_DESCRIPTION."'",
            "DESCRIPTION_TYPE"        => "'".$str_DESCRIPTION_TYPE."'",
            "SHOW_TEMPLATE"           => "'".trim($str_SHOW_TEMPLATE)."'",
            "MAIL_EVENT_TYPE"         => "'".$DB->ForSql("FORM_FILLING_".$str_VARNAME,50)."'",
            "SHOW_RESULT_TEMPLATE"    => "'".trim($str_SHOW_RESULT_TEMPLATE)."'",
            "PRINT_RESULT_TEMPLATE"   => "'".trim($str_PRINT_RESULT_TEMPLATE)."'",
            "EDIT_RESULT_TEMPLATE"    => "'".trim($str_EDIT_RESULT_TEMPLATE)."'",
            "FILTER_RESULT_TEMPLATE"  => "'".trim($str_FILTER_RESULT_TEMPLATE)."'",
            "TABLE_RESULT_TEMPLATE"   => "'".trim($str_TABLE_RESULT_TEMPLATE)."'",
            "STAT_EVENT1"             => "'".trim($str_STAT_EVENT1)."'",
            "STAT_EVENT2"             => "'".trim($str_STAT_EVENT2)."'",
            "STAT_EVENT3"             => "'".trim($str_STAT_EVENT3)."'"
            );
        $DB->StartTransaction();
        if ($ID>0)
        {
            $DB->Update("b_form", $arFields, "WHERE ID='".$ID."'", $err_mess.__LINE__);
        }
        else
        {
            $ID = $DB->Insert("b_form", $arFields, $err_mess.__LINE__);
            $new="Y";
        }
        $ID = intval($ID);
        if (strlen($strError)<=0)
        {
            $DB->Commit();
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            elseif ($new=="Y") LocalRedirect("form_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
        }
        else $DB->Rollback();
    }
}
?>


Класс CDBResult

CDBResult - класс результата выполнения запроса.

Содержит в себе методы для постраничной навигации и работы с результатом запроса. Автоматически создаётся как результат работы метода CDatabase::Query.

Свойства класса

Свойство | Описание
result | Дескриптор результата.
arResult | Результат в виде массива (доступен только после CDBResult::NavStart). Данное свойство содержит неформатированные данные, например, дата для свойства типа "дата/время" элемента инфоблока. Для работы с объектом рекомендуется использовать CDBresult::Fetch, CDBresult::GetNext.
NavRecordCount | Количество записей (доступен только после CDBResult::NavStart).
NavPageCount | Количество страниц (доступен только после CDBResult::NavStart).
NavPageNomer | Номер текущей страницы постраничной навигации (доступен только после NavStart).
NavPageSize | Размер страницы (доступен только после CDBResult::NavStart).
bFirstPrintNav | Равен "true" если функция CDBResult::NavPrint была вызвана один раз (доступен только после CDBResult::NavStart).
bShowAll | Разрешено ли показывать ссылку "Все" в постраничной навигации ("true"|"false") (доступен только после CDBResult::NavStart).
NavShowAll | Равен "true", если в данный момент показываются все записи выборки, а не постранично (т.е. была нажата ссылка "Все") (доступен только после CDBResult::NavStart).
NavNum | Порядковый номер постраничной навигации использованной на данной странице (доступен только после CDBResult::NavStart).
nStartPage | Равен "true", если в данный момент открыта первая страница в постраничной навигации (доступен только после CDBResult::NavStart).
nEndPage | Равен "true", если в данный момент открыта последняя страница в постраничной навигации (доступен только после CDBResult::NavStart).

Методы класса

Метод | Описание
Fetch | Делает выборку значений полей в массив.
NavNext | Возвращает массив значений полей.
NavPrint | Выводит ссылки для постраничной навигации.
NavStart | Разбивает результат выборки на страницы.
NavStringForCache | Возвращает уникальную строку идентифицирующую состояние постраничной навигации (номер текущей страницы, нажата ли ссылка "Все").
IsNavPrint | Определяет, все ли записи умещаются в одну страницу при постраничной навигации.
GetNext | Возвращает массив значений полей приведенный в HTML-безопасный вид.
ExtractFields | Создает глобальные переменные с именами соответствующими именам полей.
FieldName | Возвращает название поля по его номеру.
FieldsCount | Возвращает количество полей результата выборки.
SelectedRowsCount | Возвращает количество записей, которые вернул SELECT.
AffectedRowsCount | Возвращает количество записей, измененных операцией INSERT, UPDATE или DELETE.
InitFromArray | Инициализирует объект класса CDBResult значениями из массива.


AffectedRowsCount

CDBResult::AffectedRowsCount

int
CDBResult::AffectedRowsCount()

Функция возвращает количество записей, измененных SQL-командами "INSERT", "UPDATE" или "DELETE".

Параметры функции

Без параметров.

См. также

  • CDBResult::SelectedRowsCount

Примеры использования

<?
$strSql = "
    INSERT INTO b_stat_day(
        ID,
        DATE_STAT,
        TOTAL_HOSTS)
    SELECT
        SQ_B_STAT_DAY.NEXTVAL,
        trunc(SYSDATE),
        nvl(PREV.MAX_TOTAL_HOSTS,0)
    FROM
        (SELECT	max(TOTAL_HOSTS) AS MAX_TOTAL_HOSTS	FROM b_stat_day) PREV
    WHERE
        not exists(SELECT 'x' FROM b_stat_day D WHERE TRUNC(D.DATE_STAT) = TRUNC(SYSDATE))
    ";
$q = $DB->Query($strSql, true, $err_mess.__LINE__);
if ($q && intval($q->AffectedRowsCount())>0)
{
    $arFields = Array("LAST"=>"'N'");
    $DB->Update("b_stat_adv_day",$arFields,"WHERE LAST='Y'", $err_mess.__LINE__);
    $DB->Update("b_stat_adv_event_day",$arFields,"WHERE LAST='Y'", $err_mess.__LINE__);
    $DB->Update("b_stat_searcher_day",$arFields,"WHERE LAST='Y'", $err_mess.__LINE__);
    $DB->Update("b_stat_event_day",$arFields,"WHERE LAST='Y'", $err_mess.__LINE__);
    $DB->Update("b_stat_country_day",$arFields,"WHERE LAST='Y'", $err_mess.__LINE__);
    $DB->Update("b_stat_guest",$arFields,"WHERE LAST='Y'",$err_mess.__LINE__);
    $DB->Update("b_stat_session",$arFields,"WHERE LAST='Y'",$err_mess.__LINE__);
}
?>


ExtractFields

CDBResult::ExtractFields

mixed
CDBResult::ExtractFields(
 string prefix="str_",
 bool encode=true
 )

Объявляет глобальные переменные с именами вида ${prefix."имя поля"} и значениями соответствующими именам полей, приведенных в HTML-безопасный вид.
Возвращает массив вида Array("поле"=>"значение" [, ...]) и передвигает курсор на следующую запись. Если достигнута последняя запись (или в результате нет ни одной записи), то функция вернет "false".

Параметры функции

Параметр | Описание
prefix | Префикс глобальных переменных. Необязательный. По умолчанию "str_".
encode | Приводить глобальные переменные в HTML-безопасный вид. Необязательный. По умолчанию - "true".

См. также

  • CDBResult::Fetch
  • CDBResult::GetNext
  • CDBResult::NavNext

Примеры использования

<select>
<?
$rs = CGroup::GetList($order="ID", $by="ASC");
while ($rs->ExtractFields("g_")) :
   ?><option value="<?=$g_ID?>"
   <?if (IntVal($g_ID)==IntVal($show_perms_for)) echo " selected";?>
   ><?=$g_NAME?></option><?
endwhile;
?>
</select>


Fetch

CDBResult::Fetch

mixed
CDBResult::Fetch()

Делает выборку значений полей в массив. Возвращает массив вида Array("поле"=>"значение" [, ...]) и передвигает курсор на следующую запись. Если достигнута последняя запись (или в результате нет ни одной записи) - функция вернет "false".

Параметры функции

Без параметров.

См. также

  • CDBResult::GetNext
  • CDBResult::ExtractFields
  • CDBResult::NavNext

Примеры использования

<?
$rsUser = CUser::GetByID($USER_ID);
$arUser = $rsUser->Fetch();
?>


FieldName

CDBResult::FieldName

mixed
CDBResult::FieldName(
 int column
 )

Функция возвращает название поля по его номеру.

Параметры функции

Параметр | Описание
column | Номер поля.

См. также

  • CDBResult::FieldsCount

Примеры использования

<?
$rs = $DB->Query($query,true);
$intNumFields = $rs->FieldsCount();
$i = 0;
while ($i < $intNumFields)
{
    $arFieldName[] = $rs->FieldName($i);
    $i++;
}
?>


FieldsCount

CDBResult::FieldsCount

int
CDBResult::FieldsCount()

Функция возвращает количество полей результата выборки.

Параметры функции

Без параметров.

См. также

  • CDBResult::FieldName

Примеры использования

<?
$rs = $DB->Query($query,true);
$intNumFields = $rs->FieldsCount();
$i = 0;
while ($i < $intNumFields)
{
    $arFieldName[] = $rs->FieldName($i);
    $i++;
}
?>


GetNext

CDBResult::GetNext

mixed
CDBResult::GetNext(
 bool text_html=true,
 bool original=true
 )

Возвращает массив значений полей приведенный в HTML-безопасный вид. Если достигнут конец результата выборки функция вернет false.

Параметры функции

Параметр | Описание
text_html | Если значение данного параметра - "true", то функция будет автоматически обрабатывать поля с выбором формата text/html. Необязательный. По умолчанию - "true".
original | Если значение данного параметра - "true", то помимо преобразованных в HTML-безопасный вид полей, в результирующий массив будут включены также оригинальные (исходные) значения этих полей (ключи массива с оригинальными значениями этих полей будут иметь суффикс "~"). Необязательный. По умолчанию - "true".

См. также

  • CDBResult::Fetch
  • CDBResult::ExtractFields
  • CDBResult::NavNext

Примеры использования

<select>
<?
$rs = CGroup::GetList($order="ID", $by="ASC");
while ($arGroup=$rs->GetNext()) :
   ?><option value="<?=$arGroup["ID"]?>"
   <?if (IntVal($arGroup["ID"])==IntVal($show_perms_for)) echo " selected";?>
   ><?=$arGroup["NAME"]?></option><?
endwhile;
?>
</select>


InitFromArray

CDBResult::InitFromArray

CDBResult::InitFromArray(
 array values
 )

Функция инициализирует объект класса CDBResult значениями из массива.

Параметры функции

Параметр | Описание
values | Ассоциативный массив со значениями для объекта класса CDBResult.

Примеры использования

<?
$arr = array();
$arr[] = array("ID" => 1, "NAME" => "Заголовок 1");
$arr[] = array("ID" => 2, "NAME" => "Заголовок 2");
$arr[] = array("ID" => 3, "NAME" => "Заголовок 3");
$arr[] = array("ID" => 4, "NAME" => "Заголовок 4");

$rs = new CDBResult;
$rs->InitFromArray($arr);

$rs->NavStart(50);
if($rs->IsNavPrint())
{
     echo "<p>"; $rs->NavPrint("Элементы"); echo "</p>";
}
?>
<?
// получим список файлов и каталогов
CFileMan::GetDirList(Array($site_id, $path), $arDirs, $arFiles, $arFilter, Array($by=>$order), "DF");

// объединим файлы и каталоги в один массив
$arDirContent = array_merge($arDirs, $arFiles);

// создадим объект класса CDBResult
$rsDirContent = new CDBResult;

// инициализируем этот объект исходным массивом
$rsDirContent->InitFromArray($arDirContent);

// теперь на данном объекте
// мы можем использовать все методы класса CDBResult
// например, "Постраничная навигация":
$rsDirContent->NavStart(50);
if($rsDirContent->IsNavPrint()) echo "<p>"; $rs->NavPrint("Файлы"); echo "</p>";
while ($arElement = $rsDirContent->Fetch()):
    // если это каталог то
    if ($arElement["TYPE"]=="D"):
        // выводим название каталога
        echo $arElement["NAME"];
    else: // иначе если это файл то
        // если это служебный файл то переходим к следующему элементу
        if ($arElement["NAME"]==".section.php") continue;
        // иначе выводим его название
        echo $arElement["NAME"];
    endif;
endwhile;
?>


IsNavPrint

CDBResult::IsNavPrint

bool
CDBResult::IsNavPrint()

Функция возвращает "false", если все записи умещаются в одну страницу. В противном случае "true".

Перед использованием данной функции необходимо вызвать CDBResult::NavStart.

Параметры функции

Без параметров.

См. также

  • CDBResult::NavPrint
  • CDBResult::NavStart
  • CDBResult::NavNext

Примеры использования

<?
$arDirContent = array_merge($arDirs, $arFiles);
$rsDirContent = new CDBResult;
$rsDirContent->InitFromArray($arDirContent);
$rsDirContent->NavStart(50);
if($rsDirContent->IsNavPrint())
{
    echo "<p>";
    $rsDirContent->NavPrint("Файлы");
    echo "</p>";
}
?>


NavNext

CDBResult::NavNext

mixed
CDBResult::NavNext(
 bool init_globals = true,
 string prefix = "str_",
 bool safe_for_html = true
 )

Возвращает массив значений полей. Если установлен флаг init_globals, то объявляет глобальные переменные с именами prefix.имя_поля. Если достигнут конец результата выборки, то функция вернет "false".

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

Параметры функции

Параметр | Описание
init_globals | Если "true", то функция будет объявлять глобальные переменные соответствующие именам полей выборки. Необязательный. По умолчанию - "true".
prefix | Префикс глобальных переменных (только если init_globals установлен). Необязательный. По умолчанию - "str_".
safe_for_html | Приводить глобальные переменные в HTML-безопасный вид (только если init_globals установлен). Необязательный. По умолчанию - "true".

См. также

  • CDBResult::NavStart
  • CDBResult::Fetch
  • CDBResult::GetNext
  • CDBResult::ExtractFields

Примеры использования

<?
$rsBanners = CAdvBanner::GetList($by, $order, $arFilter, $is_filtered);
$rsBanners->NavStart(20);
echo $rsBanners->NavPrint("Баннеры");
while($rsBanners->NavNext(true, "f_")):
    echo "[".$f_ID."] ".$f_NAME."<br>";
endwhile;
echo $rsBanners->NavPrint("Баннеры");
?>


NavPrint

CDBResult::NavPrint

CDBResult::NavPrint(
 string title,
 bool show_always=false,
 string text_css_class="text",
 string template_path=false
)

Функция выводит ссылки для постраничной навигации. Перед использованием данной функции необходимо вызвать метод NavStart.

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

CPageOption::SetOptionString("main", "nav_page_in_session", "N");

Параметры функции

Параметр | Описание
title | Названия выводимых элементов.
show_always | Если "false", то функция не будет выводить навигационные ссылки если все записи умещаются на одну страницу. Если "true", то ссылки для постраничной навигации будут выводиться всегда. Необязательный. По умолчанию - "false".
text_css_class | CSS класс шрифта для вывода навигационных ссылок. Необязательный. По умолчанию "text".
template_path | Путь к шаблону показа навигационных ссылок. Если "false", то используется шаблон по умолчанию.

См. также

  • CDBResult::NavStart
  • CDBResult::NavNext
  • CDBResult::IsNavPrint
  • Класс CPageOption

Примеры использования

<?
$rsEvents = CAdv::GetEventList($f_ID,($by="s_def"),($order="desc"), $arF, $is_filtered);
$rsEvents->NavPrint("События", false, "tablebodytext",
"/bitrix/modules/statistic/admin/adv_navprint.php");
?>

Примеры шаблонов для навигационных ссылок

<?
echo('<font class="'.$StyleText.'">('.$title.' ');
echo(($this->NavPageNomer-1)*$this->NavPageSize+1);
echo(' - ');
if($this->NavPageNomer != $this->NavPageCount)
  echo($this->NavPageNomer * $this->NavPageSize);
else
  echo($this->NavRecordCount);
echo(' '.GetMessage("nav_of").' ');
echo($this->NavRecordCount);
echo(")\n \n</font>");

echo('<font class="'.$StyleText.'">');

if($this->NavPageNomer > 1)
  echo('<a class="tablebodylink" href="'.$sUrlPath.'?PAGEN_'.$this->NavNum.'=1'.
  $strNavQueryString.'#nav_start'.$add_anchor.'">'.
  $sBegin.'</a> | <a class="tablebodylink" href="'.$sUrlPath.'?PAGEN_'.
  $this->NavNum.'='.($this->NavPageNomer-1).$strNavQueryString.'#nav_start'.
  $add_anchor.'">'.$sPrev.'</a>');
else
  echo($sBegin.' | '.$sPrev);

echo(' | ');

$NavRecordGroup = $nStartPage;
while($NavRecordGroup <= $nEndPage)
{
  if($NavRecordGroup == $this->NavPageNomer)
    echo('<b>'.$NavRecordGroup.'</b> ');
  else
    echo('<a class="tablebodylink" href="'.$sUrlPath.'?PAGEN_'.$this->NavNum.'='.
    $NavRecordGroup.$strNavQueryString.'#nav_start'.$add_anchor.'">'.
    $NavRecordGroup.'</a> ');

  $NavRecordGroup++;
}

echo('| ');
if($this->NavPageNomer < $this->NavPageCount)
  echo ('<a class="tablebodylink" href="'.$sUrlPath.'?PAGEN_'.$this->NavNum.'='.
  ($this->NavPageNomer+1).$strNavQueryString.'#nav_start'.$add_anchor.'">'.
  $sNext.'</a> | <a class="tablebodylink" href="'.$sUrlPath.'?PAGEN_'.
  $this->NavNum.'='.$this->NavPageCount.$strNavQueryString.
  '#nav_start'.$add_anchor.'">'.$sEnd.'</a> ');
else
  echo ($sNext.' | '.$sEnd.' ');

if($this->bShowAll)
  echo ($this->NavShowAll? '| <a class="tablebodylink"
  href="'.$sUrlPath.'?SHOWALL_'.$this->NavNum.'=0'.$strNavQueryString.
  '#nav_start'.$add_anchor.'">'.$sPaged.
  '</a> ' : '| <a class="tablebodylink" href="'.$sUrlPath.'?SHOWALL_'.
  $this->NavNum.'=1'.$strNavQueryString.
  '#nav_start'.$add_anchor.'">'.$sAll.'</a> ');

echo('</font>');
?>


NavStart

CDBResult::NavStart

CDBResult::NavStart(
 int page_size=10,
 bool show_all=true,
 int page_number=false
)

Функция разбивает результат выборки на страницы.

Для встраивания системы автоматической постраничной навигации необходимо сначала вызвать данную функцию CDBResult::NavStart. После ее вызова, методы

  • CDBResult::Fetch
  • CDBResult::GetNext
  • CDBResult::ExtractFields
  • CDBResult::NavNext
будут ограничены только текущей страницей (а не всей выборкой). Для вывода ссылок постраничной навигации необходимо воспользоваться функций CDBResult::NavPrint.

Параметры функции

Параметр | Описание
page_size | Размер страницы (от 1 и более). Необязательный. По умолчанию 10.
show_all | Разрешить показывать все записи (и выводить ссылку "Все" в навигации). Необязательный. По умолчанию - "true".
page_number | Принудительно всегда открывать страницу с этим номером (не зависящую от параметров в URL). Необязательный. По умолчанию - "false" (показывать автоматически).

См. также

  • CDBResult::NavNext
  • CDBResult::NavPrint
  • CDBResult::IsNavPrint
  • CDBResult::Fetch
  • CDBResult::GetNext
  • CDBResult::ExtractFields

Примеры использования

<?
$rsBanners = CAdvBanner::GetList($by, $order, $arFilter, $is_filtered);
$rsBanners->NavStart(20);
echo $rsBanners->NavPrint("Баннеры");
while($rsBanners->NavNext(true, "f_")):
    echo "[".$f_ID."] ".$f_NAME."<br>";
endwhile;
echo $rsBanners->NavPrint("Баннеры");
?>


NavStringForCache

CDBResult::NavStringForCache

string
CDBResult::NavStringForCache(
 int page_size=10,
 bool show_all=true,
 int page_number=false
)

Возвращает уникальную строку идентифицирующую текущее состояние постраничной навигации (номер текущей страницы, нажата ли ссылка "Все"). Результат данной функции применяется как правило для составления идентификатора кэша, который в свою очередь используется в функциях классов CPageCache и CPHPCache.

Параметры функции

Параметр | Описание
page_size | Размер страницы постраничной навигации (от 1 и более). Необязательный. По умолчанию 10.
show_all | Разрешить ли показывать все записи (и выводить ссылку "Все" в навигации). Необязательный. По умолчанию - "true".
page_number | Принудительно ли открывать страницу с этим номером (в независимости от параметров в URL). Необязательный. По умолчанию - "false" (открывать страницу в зависимости от параметров в URL).

См. также

  • Класс CPageCache
  • Класс CPHPCache

Примеры использования

<?
// создаем объект
$obCache = new CPageCache;

// время кэширования - 30 минут
$life_time = 30*60;

// получим строку идентифицирующую состояние постраничной навигации
$nav = CDBResult::NavStringForCache($PAGE_ELEMENT_COUNT);

// формируем идентификатор кэша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $nav.$ELEMENT_ID.$IBLOCK_TYPE.$USER->GetUserGroupString();

// инициализируем буферизирование вывода
if($obCache->StartDataCache($life_time, $cache_id, "/")):

    // получаем список элементов
    if ($rsElements = GetIBlockElementList($IBLOCK_ID, $SECTION_ID)):

        // инициализируем постраничную навигацию
        $rsElements->NavStart($PAGE_ELEMENT_COUNT);

        // выведем постраничную навигацию
        echo $rsElements->NavPrint($ELEMENT_NAME);

        // пройдемся по элементам
        while ($obElement = $rsElements->GetNextElement()):

            $arElement = $obElement->GetFields();
            $arProperty = $obElement->GetProperties();

            echo "<pre>"; print_r($arElement); echo "</pre>";
            echo "<pre>"; print_r($arProperty); echo "</pre>";

        endwhile;
    endif;

    // записываем буферизированный результат на диск в файл кэша
    $obCache->EndDataCache();
endif;
?>


SelectedRowsCount

CDBResult::SelectedRowsCount

int
CDBResult::SelectedRowsCount()

Функция возвращает количество выбранных записей (выборка записей осуществляется с помощью SQL-команды "SELECT ...").

Для Oracle версии данная функция будет корректно работать только после вызова CDBResult::NavStart, либо если достигнут конец (последняя запись) выборки.

Параметры функции

Без параметров.

См. также

  • CDBResult::AffectedRowsCount

Примеры использования

<?
$rsBanners = CAdvBanner::GetList($by, $order, $arFilter, $is_filtered);
$rsBanners->NavStart(20);
if (intval($rsBanners->SelectedRowsCount())>0):
    echo $rsBanners->NavPrint("Баннеры");
    while($rsBanners->NavNext(true, "f_")):
         echo "[".$f_ID."] ".$f_NAME."<br>";
    endwhile;
    echo $rsBanners->NavPrint("Баннеры");
endif;
?>


Класс CDiskQuota

CDiskQuota - класс для работы с дисковыми квотами.

Метод | Описание
checkDiskQuota | Проверяет свободное место на диске для заданных данных.
reCount | Производит пересчет счетчика.
updateDiskQuota | Изменяет значение счетчика.


checkDiskQuota

CDiskQuota::checkDiskQuota

boolean
CDiskQuota::checkdiskquota(
 mixed size
);

Проверяет свободное место на диске для данных размером size.

Параметры функции

Параметр | Описание
size | Может быть массивом с полями "FILE_SIZE" или "SIZE", где size["SIZE"] - размер в байтах, числом, строкой.

Возвращаемое значение

Если есть свободное место на диске для данных размером size - true, иначе - false.


reCount

CDiskQuota::reCount

CDiskQuota::reCount(
 string ID [,
 boolean recount]
);

Производит пересчёт счётчика ID.

Параметры функции

Параметр | Описание
ID | Идентификатор счётчика.
recount | Если значение - true, то будет запущен механизм пересчёта сначала, а не с последнего шага.

Возвращаемое значение

При завершённом пересчёте вернётся массив, содержащий информацию о стадии пересчёта, последний файл в шаге, суммарный размер файлов за шаг, временная метка финала последнего шага.


updateDiskQuota

CDiskQuota::updateDiskQuota

CDiskQuota::updateDiskQuota(
 string ID,
 int size,
 string action
);

Изменяет счетчик ID на величину size в зависимости от указанного action.

Параметры функции

Параметр | Описание
ID | Идентификатор счетчика.
size | Размер в байтах.
action | Направление счета.

Возвращаемое значение

При успешном выполнении, возвращает true, иначе - false.


Класс CEvent

CEvent - класс для работы с почтовыми событиями.

Методы класса

Метод | Описание
CheckEvents | Проверяет и отсылает неотправленные события.
Send | Добавляет событие в почтовую систему (регистрирует для отправки).

См. также

  • Почтовая система


CheckEvents

CEvent::CheckEvents

CEvent::CheckEvents()

Собирает неотправленные почтовые события и отправляет их в виде E-Mail сообщений. Функция автоматически вызывается при загрузке каждой страницы и не требует ручного вызова.

Параметры функции

Без параметров.

См. также

  • Почтовая система


Send

CEvent::Send

int
CEvent::Send(
 string event_type,
 mixed site,
 array fields,
 string duplicate="Y",
 int template_id=""
)

Функция создает почтовое событие которое будет в дальнейшем отправлено в качестве E-Mail сообщения. Возвращает идентификатор созданного события.

Параметры функции

Параметр | Описание
event_type | Идентификатор типа почтового события.
site | Идентификатор сайта, либо массив идентификаторов сайта.
fields | Массив полей типа почтового события идентификатор которого задается в параметре event_type. Массив имеет следующий формат: array("поле"=>"значение" [, ...]).
duplicate | Отправить ли копию письма на адрес указанный в настройках главного модуля в поле "E-Mail адрес или список адресов через запятую на который будут дублироваться все исходящие сообщения". Необязательный. По умолчанию "Y".
template_id | Идентификатор почтового шаблона по которому будет отправлено письмо. Если данный параметр не задан, либо равен "", то письма будут отправлены по всем шаблонам привязанным к типу почтового события, идентификатор которого задается в параметре event_type, а также привязанных к сайту(ам) идентификатор которого указан в параметре site. Необязательный. По умолчанию - "".

См. также

  • Почтовая система

Примеры использования

<?
$arEventFields = array(
    "ID"                  => $CONTRACT_ID,
    "MESSAGE"             => $mess,
    "EMAIL_TO"            => implode(",", $EMAIL_TO),
    "ADMIN_EMAIL"         => implode(",", $ADMIN_EMAIL),
    "ADD_EMAIL"           => implode(",", $ADD_EMAIL),
    "STAT_EMAIL"          => implode(",", $VIEW_EMAIL),
    "EDIT_EMAIL"          => implode(",", $EDIT_EMAIL),
    "OWNER_EMAIL"         => implode(",", $OWNER_EMAIL),
    "BCC"                 => implode(",", $BCC),
    "INDICATOR"           => GetMessage("AD_".strtoupper($arContract["LAMP"]."_CONTRACT_STATUS")),
    "ACTIVE"              => $arContract["ACTIVE"],
    "NAME"                => $arContract["NAME"],
    "DESCRIPTION"         => $description,
    "MAX_SHOW_COUNT"      => $arContract["MAX_SHOW_COUNT"],
    "SHOW_COUNT"          => $arContract["SHOW_COUNT"],
    "MAX_CLICK_COUNT"     => $arContract["MAX_CLICK_COUNT"],
    "CLICK_COUNT"         => $arContract["CLICK_COUNT"],
    "BANNERS"             => $arContract["BANNER_COUNT"],
    "DATE_SHOW_FROM"      => $arContract["DATE_SHOW_FROM"],
    "DATE_SHOW_TO"        => $arContract["DATE_SHOW_TO"],
    "DATE_CREATE"         => $arContract["DATE_CREATE"],
    "CREATED_BY"          => $CREATED_BY,
    "DATE_MODIFY"         => $arContract["DATE_MODIFY"],
    "MODIFIED_BY"         => $MODIFIED_BY
    );
$arrSITE =  CAdvContract::GetSiteArray($CONTRACT_ID);
CEvent::Send("ADV_CONTRACT_INFO", $arrSITE, $arEventFields);
?>


Класс CEventMessage

CEventMessage - класс предназначеный для работы с почтовыми шаблонами.

Поля

Поле | Тип | Описание
ID | Int | ID почтового шаблона.
EVENT_NAME | Varchar(50) | ID почтового события.
LID | Char(2) | ID языка.
TIMESTAMP_X | Datetime | Последнее изменение шаблона.
ACTIVE | Char | Активен (Y|N)
EMAIL_FROM | Varchar(255) | Отправитель.
EMAIL_TO | Varchar(255) | Получатель.
SUBJECT | Varchar(255) | Тема.
MESSAGE | Text | Тело сообщения.
BODY_TYPE | Char(4) | Тип сообщения (text|html)
BCC | Varchar(255) | Скрытая копия.

Методы класса

Метод | Описание
GetList | Получает список шаблонов по фильтру.
GetByID | Получает данные о шаблоне по его ID
Add | Добавляет новый шаблон.
Update | Изменяет существующий почтовый шаблон.
Delete | Удаляет шаблон.

См. также

  • Почтовая система


Add

CEventMessage::Add

mixed
CEventMessage::Add(
 array fields
)

Функция добавляет новый почтовый шаблон. Возвращает ID вставленного шаблона. При возникновении ошибки, функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр Описание
fields Массив значений полей вида array("поле"=>"значение" [, ...]). В качестве "полей" допустимо использовать:
  • ACTIVE - флаг активности почтового шаблона: "Y" - активен; "N" - не активен;
  • EVENT_NAME - идентификатор типа почтового события
  • LID - идентификатор сайта
  • EMAIL_FROM - поле "From" ("Откуда")
  • EMAIL_TO - поле "To" ("Куда")
  • BCC - поле "BCC" ("Скрытая копия")
  • SUBJECT - заголовок сообщения
  • BODY_TYPE - тип тела почтового сообщения: "text" - текст; "html" - HTML
  • MESSAGE - тело почтового сообщения

См. также

  • Поля шаблона почтового сообщения
  • CEventMessage::Update

Примеры использования

<?
$arr["ACTIVE"] = "Y";
$arr["EVENT_NAME"] = "ADV_CONTRACT_INFO";
$arr["LID"] = array("ru","en");
$arr["EMAIL_FROM"] = "#DEFAULT_EMAIL_FROM#";
$arr["EMAIL_TO"] = "#EMAIL_TO#";
$arr["BCC"] = "#BCC#";
$arr["SUBJECT"] = "Тема сообщения";
$arr["BODY_TYPE"] = "text";
$arr["MESSAGE"] = "
Текст сообщения
";

$emess = new CEventMessage;
$emess->Add($arr);
?>


Delete

CEventMessage::Delete

mixed
CEventMessage::Delete(
 int id
)

Удаляет почтовый шаблон. Если шаблон удален успешно, то возвращается объект CDBResult, в противном случае - "false".

Параметры функции

Параметр | Описание
id | ID шаблона.

См. также

  • Класс CDBResult
  • Событие "OnEventMessageDelete"
  • Событие "OnBeforeEventMessageDelete"

Примеры использования

<?
if(intval($del_id)>0 && $MAIN_RIGHT=="W")
{
    $emessage = new CEventMessage;
    $DB->StartTransaction();
    if(!$emessage->Delete(intval($del_id)))
    {
        $DB->Rollback();
        $strError.=GetMessage("DELETE_ERROR");
    }
    else $DB->Commit();
}
?>


GetByID

CEventMessage::GetByID

CDBResult
CEventMessage::GetByID(
 int id
)

Возвращает почтовый шаблон по его коду id в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
id | ID шаблона.

См. также

  • Поля шаблона почтового сообщения
  • CEventMessage::GetList
  • Класс CDBResult

Примеры использования

<?
$rsEM = CEventMessage::GetByID($ID);
$arEM = $rsEM->Fetch();
echo "<pre>"; print_r($arEM); echo "</pre>";
?>


GetList

CEventMessage::GetList

CDBResult
CEventMessage::GetList(
 string &by="id",
 string &order="desc",
 array filter
)

Возвращает список почтовых шаблонов в виде объекта класса CDBResult.

Параметры функции

Параметр Описание
by Ссылка на переменную с полем для сортировки, может принимать значения:
  • site_id - идентификатор сайта;
  • subject - тема;
  • timestamp_x - дата изменения;
  • event_name - тип события;
  • id - ID шаблона;
  • active - активность;
оrder Ссылка на переменную с порядком сортировки, может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
filter Массив вида array("фильтруемое поле"=>"значение" [, ...]), может принимать значения:
  • ID - ID шаблона;
  • TYPE - код и заголовок типа события (допустима сложная логика);
  • TYPE_ID - код типа события (допустима сложная логика);
  • TIMESTAMP_1 - левая часть интервала ("c") для поиска по дате изменения;
  • TIMESTAMP_2 - правая часть интервала ("по") для поиска по дате изменения;
  • SITE_ID - идентификатор сайта (допустимо задание массива для поиска по логике "или", либо допустимо использование сложной логики);
  • ACTIVE - флаг активности (Y|N);
  • FROM - поле "От кого" (допустима сложная логика);
  • TO - поле "Кому" (допустима сложная логика);
  • BCC - поле "Скрытая копия" (допустима сложная логика);
  • SUBJECT - по теме сообщения (допустима сложная логика);
  • BODY_TYPE - по типу тела сообщения (text|html);
  • BODY - по телу сообщения (допустима сложная логика);

См. также

  • Поля шаблона почтового сообщения
  • CEventMessage::GetByID
  • Класс CDBResult

Примеры использования

<?
$arFilter = Array(
    "ID"            => "12 | 134",
    "TYPE"          => "контракт & рекл",
    "TYPE_ID"       => "ADV_BANNER | ADV_CONTRACT",
    "TIMESTAMP_1"   => "12.11.2001",
    "TIMESTAMP_2"   => "12.11.2005",
    "SITE_ID"       => "ru | en",
    "ACTIVE"        => "Y",
    "FROM"          => "bitrixsoft.ru",
    "TO"            => "#TO#",
    "BCC"           => "admin",
    "SUBJECT"       => "конктракт",
    "BODY_TYPE"     => "text",
    "BODY"          => "auto"
    );
$rsMess = CEventMessage::GetList($by="site_id", $order="desc", $arFilter);
$is_filtered = $rsMess->is_filtered;
?>


Update

CEventMessage::Update

bool
CEventMessage::Update(
 int id,
 array fields
)

Изменяет почтовый шаблон с кодом id. Возвращает "true", если изменение прошло успешно, при возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
id | ID изменяемой записи.
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля шаблона почтового сообщения
  • CEventMessage::Add

Примеры использования

<?
if($REQUEST_METHOD=="POST" && (strlen($save)>0 || strlen($apply)>0)&& $MAIN_RIGHT=="W")
{
    $em = new CEventMessage;
    $arFields = Array(
        "ACTIVE"        => $ACTIVE,
        "EVENT_NAME"    => $EVENT_NAME,
        "LID"           => $LID,
        "EMAIL_FROM"    => $EMAIL_FROM,
        "EMAIL_TO"      => $EMAIL_TO,
        "BCC"           => $BCC,
        "SUBJECT"       => $SUBJECT,
        "MESSAGE"       => $MESSAGE,
        "BODY_TYPE"     => $BODY_TYPE
        );
    if($ID>0)
    {
        $res = $em->Update($ID, $arFields);
    }
    else
    {
        $ID = $em->Add($arFields);
        $res = ($ID>0);
    }
    if(!$res)
    {
        $strError .= $em->LAST_ERROR."<br>";
        $bVarsFromForm = true;
    }
    else
    {
        if (strlen($save)>0)
            LocalRedirect(BX_ROOT."/admin/message_admin.php?lang=".LANGUAGE_ID);
        else
            LocalRedirect(BX_ROOT."/admin/message_edit.php?lang=".LANGUAGE_ID."&ID=".$ID);
    }
}
?>


Класс CEventType

CEventType - класс для работы с типами почтовых событий.

Поля

Поле | Тип | Описание
ID | Int | ID типа почтового события.
EVENT_NAME | Varchar(50) | ID почтового события.
LID | Char(2) | ID языка.
SORT | Int | Порядок сортировки.
NAME | Varchar(100) | Название.
DESCRIPTION | Text | Описание, содержит текст с макросами типа #поле# - описание.

Методы класса

Метод | Описание
GetList | Получает список типов по фильтру.
GetByID | Получает данные о типе по его ID
Add | Добавляет новый тип.
Delete | Удаляет тип.

См. также

  • Почтовая система


Add

CEventType::Add

mixed
CEventType::Add(
 array fields
)

Добавляет тип почтового события. Возвращает ID вставленного типа. При возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр Описание
fields Массив значений полей вида array("поле"=>"значение" [, ...]). В качестве "полей" допустимо использовать:
  • SITE_ID - идентификатор сайта
  • EVENT_NAME - идентификатор типа почтового события
  • NAME - заголовок типа почтового события
  • DESCRIPTION - описание задающее поля типа почтового события

См. также

  • Поля типа почтового события

Примеры использования

<?
function UET($EVENT_NAME, $NAME, $SITE_ID, $DESCRIPTION)
{
    $et = new CEventType;
    $et->Add(array(
        "SITE_ID"       => $SITE_ID,
        "EVENT_NAME"    => $EVENT_NAME,
        "NAME"          => $NAME,
        "DESCRIPTION"   => $DESCRIPTION
        ));
}

UET(
"ADV_BANNER_STATUS_CHANGE","Изменился статус баннера","ru",
"
#EMAIL_TO# - EMail получателя сообщения (#OWNER_EMAIL#)
#ADMIN_EMAIL# - EMail пользователей имеющих роль \"менеджер баннеров\" и \"администратор\"
#ADD_EMAIL# - EMail пользователей имеющих право управления баннерами контракта
#STAT_EMAIL# - EMail пользователей имеющих право просмотра баннеров конракта
#EDIT_EMAIL# - EMail пользователей имеющих право модификации некоторых полей контракта
#OWNER_EMAIL# - EMail пользователей имеющих какое либо право на контракт
#BCC# - скрытая копия (#ADMIN_EMAIL#)
#ID# - ID баннера
#CONTRACT_ID# - ID контракта
#CONTRACT_NAME# - заголовок контракта
#TYPE_SID# - ID типа
#TYPE_NAME# - заголовок типа
#STATUS# - статус
#STATUS_COMMENTS# - комментарий к статусу
#NAME# - заголовок баннера
#GROUP_SID# - группа баннера
#INDICATOR# - показывается ли баннер на сайте ?
#ACTIVE# - флаг активности баннера [Y | N]
#MAX_SHOW_COUNT# - максимальное количество показов баннера
#SHOW_COUNT# - сколько раз баннер был показан на сайте
#MAX_CLICK_COUNT# - максимальное количество кликов на баннер
#CLICK_COUNT# - сколько раз кликнули на баннер
#DATE_LAST_SHOW# - дата последнего показа баннера
#DATE_LAST_CLICK# - дата последнего клика на баннер
#DATE_SHOW_FROM# - дата начала показа баннера
#DATE_SHOW_TO# - дата окончания показа баннера
#IMAGE_LINK# - ссылка на изображение баннера
#IMAGE_ALT# - текст всплывающей подсказки на изображении
#URL# - URL на изображении
#URL_TARGET# - где развернуть URL изображения
#CODE# - код баннера
#CODE_TYPE# - тип кода баннера (text | html)
#COMMENTS# - комментарий к баннеру
#DATE_CREATE# - дата создания баннера
#CREATED_BY# - кем был создан баннер
#DATE_MODIFY# - дата изменения баннера
#MODIFIED_BY# - кем изменен баннер
"
);
?>


Delete

CEventType::Delete

CDBResult
CEventType::Delete(
 string type_id
)

Удаляет тип почтового события. Возвращается объект класса CDBResult.

Параметры функции

Параметр | Описание
type_id | Тип почтового события.

См. также

  • Класс CDBResult

Примеры использования

<?
$et = new CEventType;
$et->Delete("ADV_BANNER_STATUS_CHANGE");
?>


GetByID

CEventType::GetByID

CDBResult
CEventType::GetByID(
 string type_id,
 string site_id
)

Возвращает тип почтового события в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
type_id | Идентификатор типа почтового события.
site_id | Идентификатор сайта.

См. также

  • Поля типа события
  • CEventType::GetList
  • Класс CDBResult

Примеры использования

<?
$rsET = CEventType::GetByID("ADV_BANNER_STATUS_CHANGE", "ru");
$arET = $rsET->Fetch();
?>


GetList

CEventType::GetList

CDBResult
CEventType::GetList(
 array filter
)

Возвращает список типов почтовых событий по фильтру filter в виде объекта класса CDBResult.

Параметры функции

Параметр Описание
filter Массив фильтрации вида array("фильтруемое поле"=>"значение" [, ...]). "Фильтруемое поле" может принимать значения:
  • TYPE_ID - идентификатор типа события;
  • LID - идентификатор языка;

См. также

  • Поля типа события
  • CEventType::GetByID
  • Класс CDBResult

Примеры использования

<?
$arFilter = array(
    "TYPE_ID" => "ADV_BANNER_STATUS_CHANGE",
    "LID"     => "ru"
    );
$rsET = CEventType::GetList($arFilter);
while ($arET = $rsET->Fetch())
{
    echo "<pre>"; print_r($arET); echo "</pre>";
}
?>


Класс CFile

Класс для работы с файлами и изображениями.

Поля

Поле | Тип | Описание
ID | int | ID файла.
TIMESTAMP_X | timestamp | Дата изменения записи.
MODULE_ID | varchar(50) | Идентификатор модуля которому принадлежит файл.
HEIGHT | int | Высота изображения (если файл - графический).
WIDTH | int | Ширина изображения (если файл - графический).
FILE_SIZE | int | Размер файла (байт).
CONTENT_TYPE | varchar(255) | MIME тип файла.
SUBDIR varchar(255) Подкаталог в котором находится файл на диске. Основной каталог для хранения файлов задается в параметре "Папка по умолчанию для загрузки файлов" в настройках главного модуля, значение данного параметра программно можно получить с помощью вызова функции:
COption::GetOptionString("main", "upload_dir", "upload");
FILE_NAME | varchar(255) | Имя файла на диске сервера.
ORIGINAL_NAME | varchar(255) | Оригинальное имя файла в момент загрузки его на сервер.
DESCRIPTION | varchar(255) | Описание файла.

Методы класса

Метод | Описание
GetByID | Возвращает информацию по одному зарегистрированному файлу.
GetPath | Функция возвращает путь от корня сайта к зарегистрированному файлу.
ShowImage | Возвращает HTML для показа изображения.
Show2Images | Возвращает HTML для показа изображения при клике на которое в отдельном окне отображается другое изображение.
CheckFile | Проверяет размер, расширение и mime тип файла. В случае ошибки функция вернет строку с текстом ошибки.
CheckImageFile | Проверяет что файл является картинкой и проверяет ее параметры. В случае ошибки функция вернет строку с текстом ошибки.
IsImage | Функция проверяет расширение и заданный MIME тип файла. Если расширение и MIME тип файла соответствуют изображению, то возвращает "true", иначе "false".
MakeFileArray | Функция формирует массив описывающий файл. Структура массива аналогична структуре массива $_FILES[имя] (или $HTTP_POST_FILES[имя]). Данный массив может быть использован в функциях CFile::SaveFile, CFile::CheckFile, CFile::CheckImageFile.
InputFile | Возвращает HTML код предназначенный для загрузки нового, либо замены существующего файла.
SaveFile | Сохраняет файл и регистрирует его в таблице файлов.
UpdateDesc | Обновляет описание к зарегистрированному файлу.
CopyFile | Копирует зарегистрированный файл.
Delete | Удаляет файл из таблицы зарегистрированных файлов и с диска.


CheckFile

CFile::CheckFile

string
CFile::CheckFile(
 array file,
 int max_size = 0,
 string mime_types = false,
 string extensions = false
)

Функция проверяет размер, расширение и mime тип файла. В случае ошибки функция вернет строку с текстом ошибки.

Параметры функции

Параметр Описание
file Массив с данными файла формата:

Array(
    "name" => "название файла",
    "size" => "размер",
    "tmp_name" => "временный путь к файлу на сервере",
    "type" => "тип загружаемого файла",
    "del" => "флаг - удалить ли существующий файл из базы данных (Y|N)",
    "MODULE_ID" => "название модуля")
Массив такого вида может быть получен, например, объединением массивов $_FILES[имя поля] и Array("del" => ${"имя поля"."_del"}, "MODULE_ID" = "название модуля").
max_size Максимальный размер файла (байт).
Необязательный. По умолчанию - "0" - без ограничений.
mime_types Разрешенный mime тип файла (например, "image/"). Проверка осуществляется по данным полученным от посетителя, поэтому для более безопасной проверки используйте extensions.
Необязательный. По умолчанию - "false" - без ограничений.
extensions Перечисленные через запятую разрешенные расширения файла.
Необязательный. По умолчанию - "false" - без ограничений.

См. также

  • CFile::CheckImageFile
  • CFile::IsImage

Примеры использования

<?
$arrFile = array_merge(
    $_FILES["ATTACHED_IMAGE"],
    array("del" => ${"ATTACHED_IMAGE_del"}, "MODULE_ID" => "forum"));

$res = CFile::CheckFile($arrFile, 200, "image/", CFile::GetImageExtensions());
if (strlen($res)>0) $strError .= $res."<br>";
?>


CheckImageFile

CFile::CheckImageFile

string
CFile::CheckImageFile(
 array file,
 int max_size = 0,
 int max_width = 0,
 int max_height = 0
 array possible_typies = array()
)

Функция проверяет что файл является картинкой и проверяет ее параметры. В случае ошибки функция вернет строку с текстом ошибки.

Параметры функции

Параметр Описание
file Массив с данными файла формата:
Array(
    "name" => "название файла",
    "size" => "размер",
    "tmp_name" => "временный путь
                   к файлу на сервере",
    "type" => "тип загружаемого файла",
    "del" => "флаг: удалить ли
              существующий файл
              из базы данных (Y|N)",
    "MODULE_ID" => "название модуля")
Массив такого вида может быть получен, например, объединением массивов $_FILES[имя поля] и Array("del" => ${"имя поля"."_del"}, "MODULE_ID" = "название модуля").
max_size Максимальный размер файла (байт).
Необязательный. По умолчанию - "0" - без ограничений.
max_width Максимальная ширина картинки (пикселей).
Необязательный. По умолчанию - "0" - без ограничений.
max_height Максимальная высота картинки (пикселей).
Необязательный. По умолчанию - "0" - без ограничений.
possible_typies Массив символьных идентификаторов типов файлов; допустимые следующие идентификаторы:
  • IMAGE - изображение;
  • FLASH - flash файл.
Параметр необязательный. По умолчанию - пустой массив (допустимы только файлы типа IMAGE).

См. также

  • CFile::CheckFile
  • CFile::IsImage

Примеры использования

<?
$arrFile = array_merge(
    $_FILES["ATTACHED_IMAGE"],
    array("del" => ${"ATTACHED_IMAGE_del"}, "MODULE_ID" => "forum"));

$res = CFile::CheckImageFile($arrFile, 200, 50, 50);
if (strlen($res)>0) $strError .= $res."<br>";
?>


CopyFile

CFile::CopyFile

int
CFile::CopyFile(
 int file_id
)

Функция копирует зарегистрированный файл и возвращает ID нового файла копии.

Параметры функции

Параметр | Описание
file_id | Цифровой идентификатор файла предназначенного для копирования.

См. также

  • CopyDirFiles

Примеры использования

<?
if ($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, $IBLOCK_ID, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER, "ID" => "ASC"), false, $arrFilter)):
    $rsElements->NavStart($PAGE_ELEMENT_COUNT);
    while ($obElement = $rsElements->GetNextElement()):
        $arElement = $obElement->GetFields();
        $arrNewImages[$arElement["ID"]][] = CFile::CopyFile($arElement["PREVIEW_PICTURE"]);
    endwhile;
endif;
?>


Delete

CFile::Delete

CFile::Delete(
 int id
)

Функция удаляет файл из таблицы зарегистрированных файлов (b_file) и с диска.

Параметры функции

Параметр | Описание
id | Цифровой идентификатор файла.

См. также

  • DeleteDirFiles
  • DeleteDirFilesEx

Примеры использования

<?
// удаляем изображение формы
$arFilter = array("ID" => 1, "ID_EXACT_MATCH" => "Y");
$rsForm = CForm::GetList($by, $order, $arFilter, $is_filtered);
if ($arForm = $rsForm->Fetch())
{
    if (intval($arForm["IMAGE_ID"])>0) CFile::Delete($arForm["IMAGE_ID"]);
}
?>


GetByID

CFile::GetByID

CDBResult
CFile::GetByID(
 int file_id
)

Функция возвращает информацию по одному зарегистрированному файлу в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
file_id | Цифровой идентификатор файла.

См. также

  • Поля файла
  • CFile::GetPath
  • CFile::InputFile
  • CFile::SaveFile
  • CFile::CopyFile
  • CFile::Delete

Примеры использования

<?
if ($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, $IBLOCK_ID, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER, "ID" => "ASC"), false, $arrFilter)):
    $rsElements->NavStart($PAGE_ELEMENT_COUNT);
    while ($obElement = $rsElements->GetNextElement()):
        $arElement = $obElement->GetFields();
        $rsFile = CFile::GetByID($arElement["PREVIEW_PICTURE"]);
        $arFile = $rsFile->Fetch();
        $arrImages[$arElement["ID"]][] = $arFile;
    endwhile;
endif;
?>


GetPath

CFile::GetPath

string
CFile::GetPath(
 int file_id
)

Функция возвращает путь от корня к зарегистрированному файлу.

Параметры функции

Параметр | Описание
file_id | ID файла.

См. также

  • CFile::GetByID

Примеры использования

<?
if ($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, $IBLOCK_ID, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER, "ID" => "ASC"), false, $arrFilter)):
  $rsElements->NavStart($PAGE_ELEMENT_COUNT);
  while ($obElement = $rsElements->GetNextElement()):
    $arElement = $obElement->GetFields();
    $arImagesPath[$arElement["PREVIEW_PICTURE"]] = CFile::GetPath($arElement["PREVIEW_PICTURE"]);
  endwhile;
endif;
?>


InputFile

CFile::InputFile

string
CFile::InputFile(
 string input_file_name,
 int input_file_width,
 int file_id,
 string file_path = false,
 int file_max_size = 0,
 string file_type = "IMAGE",
 string add_to_input_file = "class=typefile",
 int input_description_width = 0,
 string add_to_input_description = "class=typeinput",
 string add_to_checkbox_delete = "",
 bool show_file_info = true,
)

Функция возвращает HTML код предназначенный для загрузки нового, либо замены существующего файла.

Параметры функции

Параметр | Описание
input_file_name | Название поля для ввода файла: <input type="file" name="input_file_name" ... >
input_file_width | Ширина поля для ввода файла: <input type="file" size="input_file_width" ... >
file_id | Цифровой идентификатор существующего файла.
file_path | Путь к папке от корня сайта в которой хранятся файлы. Например: "/upload/iblock/". Необязательный. По умолочанию false - путь берется из настроек системы.
file_max_size | Максимальный размер файла (байт): <input type="hidden" name="MAX_FILE_SIZE" value="file_max_size"> Необязательный. По умолчанию "0" - без ограничений.
file_type | Тип файла, если "IMAGE", то в информацию по файлу будет добавлена ширина и высота изображения. Необязательный. По умолчанию "IMAGE".
add_to_input_file | Произвольный HTML который будет добавлен в поле для ввода файла: <input type="file" add_to_input_file ... > Необязательный. По умолчанию "class=typefile" - стандартный класс для полей ввода файлов в административной части.
input_description_width | Ширина поля ввода для комментария к файлу: <input type="text" size="input_description_width" ... > Необязательный. По умолчанию "0" - поле ввода для комментария к файлу не показывать.
add_to_input_description | Произвольный HTML который будет добавлен в поле ввода для комментария к файлу: <input type="text" add_to_input_description ... > Необязательный. По умолчанию "class=typeinput" - стандартный класс для однострочных элементов ввода в административной части.
add_to_checkbox_delete | Произвольный HTML который будет добавлен в поле типа "checkbox" для удаления файла: <input type="checkbox" name="input_file_name_del" value="Y" add_to_checkbox_delete ... > Необязательный.
show_file_info | Флаг позволяющий включить, либо отключить показ информации по файлу (размер, ширину, высоту). Необязательный. По умолчанию - "true" - информацию по файлу показать.

См. также

  • CFile::SaveFile

Примеры использования

<tr valign="top">
    <td align="right"><font class="tablefieldtext"><?=GetMessage("VOTE_IMAGE")?></font></td>
    <td><font class="tablebodytext"><?
    echo CFile::InputFile("IMAGE_ID", 20, $str_IMAGE_ID);
    if (strlen($str_IMAGE_ID)>0):
        ?><br><?echo CFile::ShowImage($str_IMAGE_ID, 200, 200, "border=0", "", true);
    endif;
    ?></font>
    </td>
</tr>


IsImage

CFile::IsImage

string
CFile::IsImage(
 string file_name,
 mixed mime_type = false
)

Функция проверяет расширение и заданный MIME тип файла. Если расширение и MIME тип файла соответствуют изображению, то возвращает "true", иначе "false".

Параметры функции

Параметр | Описание
file_name | Краткое имя файла (без пути).
mime_type | MIME тип файла (например, "image/"). Необязательный. По умолчанию - "false" - проверку на MIME тип не делать.

См. также

  • CFile::CheckImageFile
  • CFile::CheckFile

Примеры использования

<?
if ($rsFiles = CTicket::GetFileList($v1="s_id", $v2="asc", array("HASH"=>$hash))) :
  if ($arFile = $rsFiles->Fetch()) :
    $filename = $_SERVER["DOCUMENT_ROOT"]."/".COption::GetOptionString("main", "upload_dir", "upload")."/".$arFile["SUBDIR"]."/".$arFile["FILE_NAME"];
    if ($f = fopen($filename, "rb"))
    {
      $is_image = CFile::IsImage($arFile["FILE_NAME"], $arFile["CONTENT_TYPE"]);
      // если изображение то
      if ($is_image)
      {
        // отдадим как изображение
        header("Content-type: ".$arFile["CONTENT_TYPE"]);
        header("Cache-Control: no-cache, must-revalidate, post-check=0, pre-check=0");
        header("Expires: 0");
        header("Pragma: public");
        while ($buffer = fread($f, 4096)) echo $buffer;
      }
      else // иначе
      {
        // отдадим как текст
        header("Content-type: text/html; charset=".LANG_CHARSET);
        header("Cache-Control: no-cache, must-revalidate, post-check=0, pre-check=0");
        header("Expires: 0");
        header("Pragma: public");
        echo "<pre>";
        while ($buffer = fread($f, 4096)) echo htmlspecialchars($buffer);
        echo "</pre>";
      }
      fclose ($f);
      die();
    }
  endif;
endif;
?>


MakeFileArray

CFile::MakeFileArray

array
CFile::MakeFileArray(
 mixed file,
 mixed mime_type = false
)

Функция формирует массив описывающий файл. Структура массива аналогична структуре массива $_FILES[имя] (или $HTTP_POST_FILES[имя]). Данный массив может быть использован в функциях SaveFile, CheckFile, CheckImageFile. Структура возвращаемого массива:

Array(
    "name" => "название файла",
    "size" => "размер",
    "tmp_name" => "временный путь на сервере",
    "type" => "тип загружаемого файла")

Параметры функции

Параметр Описание
file одно из значений:
  • ID файла
  • абсолютный путь к файлу
  • URL к файлу лежащем на другом сайте.
mime_type MIME тип файла (например, "image/gif").
Необязательный. По умолчанию - "false" - MIME тип файла будет определён автоматически.

См. также

  • CFile::SaveFile
  • CFile::CheckFile
  • CFile::CheckImageFile

Примеры использования

<?
$arFile = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/screen.gif");
$arFile["MODULE_ID"] = "support";
$arFields = array(
  "CREATED_MODULE_NAME"   => "mail",
  "MODIFIED_MODULE_NAME"  => "mail",
  "OWNER_SID"             => "user@mail.ru",
  "SOURCE_SID"            => "email",
  "MESSAGE_AUTHOR_SID"    => "user@mail.ru",
  "MESSAGE_SOURCE_SID"    => "email",
  "TITLE"                 => "title",
  "MESSAGE"               => "message"
  "FILES"                 => array($arFile)
  );
//$TICKET_ID = 866;
$NEW_TICKET_ID = CTicket::Set($arFields, $MESSAGE_ID, $TICKET_ID, "N");
?>


SaveFile

CFile::SaveFile

mixed
CFile::SaveFile(
 array file,
 string save_path
)

Функция сохраняет файл и регистрирует его в таблице файлов (b_file).

Параметры функции

Параметр | Описание
file Массив с данными файла формата:

Array(
    "name" => "название файла",
    "size" => "размер",
    "tmp_name" => "временный путь на сервере",
    "type" => "тип загружаемого файла",
    "old_file" => "ID старого файла",
    "del" => "флажок - удалить ли существующий файл (Y|N)",
    "MODULE_ID" => "название модуля");
Массив такого вида может быть получен, например, объединением массивов $_FILES[имя поля] и Array("del" => ${"имя поля"."_del"}, "MODULE_ID" = "название модуля");
save_path | Путь к папке в которой хранятся файлы (относительно папки /upload).

См. также

  • RewriteFile
  • CFile::InputFile

Примеры использования

<?
if (strlen($save)>0 && $REQUEST_METHOD=="POST")
{
    $arIMAGE = $_FILES["IMAGE_ID"];
    $z = $DB->Query("SELECT IMAGE_ID FROM b_vote WHERE ID='$ID'", false, $err_mess.__LINE__);
    $zr = $z->Fetch();
    $arIMAGE["old_file"] = $zr["IMAGE_ID"];
    $arIMAGE["del"] = ${"IMAGE_ID_del"};
    $arIMAGE["MODULE_ID"] = "vote";
    if (strlen($arIMAGE["name"])>0 || strlen($arIMAGE["del"])>0)
    {
        $fid = CFile::SaveFile($arIMAGE, "vote");
        if (intval($fid)>0) $arFields["IMAGE_ID"] = intval($fid);
        else $arFields["IMAGE_ID"] = "null";
        $DB->Update("b_vote",$arFields,"WHERE ID='".$ID."'",$err_mess.__LINE__);
    }
}
?>


Show2Images

CFile::Show2Images

string
CFile::Show2Images(
 mixed image1,
 mixed image2,
 int max_width = 0,
 int max_height = 0,
 string image_params = "border=0",
 string popup_alt = false,
 int image_width = 0,
 int image_height = 0
)

Функция возвращает HTML для показа изображения при клике на которое в отдельном popup-окне отображается другое изображение.

Параметры функции

Параметр | Описание
image1 | ID файла или путь к файлу на текущем сайте либо URL к файлу лежащем на другом сайте. Если задается путь к файлу на текущем сайте, то его необходимо задавать относительно корня. В данном параметре задается изображение для первоначального показа.
image2 | ID файла или путь к файлу на текущем сайте либо URL к файлу лежащем на другом сайте. Если задается путь к файлу на текущем сайте, то его необходимо задавать относительно корня. В данном параметре задается изображение для показа в popup-окне.
max_width | Максимальная ширина первоначального изображения. Если ширина картинки больше max_width, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
max_height | Максимальная высота первоначального изображения. Если высота картинки больше max_height, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
image_params | Произвольный HTML добавляемый в тэг IMG первоначального изображения: <img image_params ...> Необязательный. По умолчанию "border=0".
popup_alt | Текст всплывающей подсказки на изображении. Необязательный. По умолчанию выводится фраза "Нажмите чтобы увеличить" на языке страницы.
image_width | Ширина изображения (в пикселах) (только если в параметре image задан URL начинающийся с "http://") Необязательный. По умолчанию "0".
image_height | Высота изображения (в пикселах) (только если в параметре image задан URL начинающийся с "http://") Необязательный. По умолчанию "0".

См. также

  • CFile::ShowImage

Примеры использования

<?
if ($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, $IBLOCK_ID, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER, "ID" => "ASC"), false, $arrFilter)):
    $rsElements->NavStart($PAGE_ELEMENT_COUNT);
    while ($obElement = $rsElements->GetNextElement()):
        $arElement = $obElement->GetFields();
        $image1 = intval($arElement["PREVIEW_PICTURE"])<=0 ? $arElement["DETAIL_PICTURE"] : $arElement["PREVIEW_PICTURE"];
        $image2 = intval($arElement["DETAIL_PICTURE"])<=0 ? $arElement["PREVIEW_PICTURE"] : $arElement["DETAIL_PICTURE"];
        echo CFile::Show2Images($image1, $image2, 150, 150, "hspace='0' vspace='0' border='0' title='".$arElement["NAME"]."'", true);
    endwhile;
endif;
?>


ShowImage

CFile::ShowImage

string
CFile::ShowImage(
 mixed image,
 int max_width = 0,
 int max_height = 0,
 string image_params = "border=0",
 string url = "",
 bool popup = false,
 string popup_alt = false,
 int image_width = 0,
 int image_height = 0
)

Функция возвращает HTML для показа изображения.

Параметры функции

Параметр | Описание
image | ID файла или путь к файлу на текущем сайте либо URL к файлу лежащем на другом сайте. Если задается путь к файлу на текущем сайте, то его необходимо задавать относительно корня.
max_width | Максимальная ширина изображения. Если ширина картинки больше max_width, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
max_height | Максимальная высота изображения. Если высота картинки больше max_height, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
image_params | Произвольный HTML добавляемый в тэг IMG: <img image_params ...> Необязательный. По умолчанию "border=0".
url | Ссылка для перехода при нажатии на картинку. Необязательный. По умолчанию "" - не выводить ссылку.
popup | Открывать ли при клике на изображении дополнительное popup окно с увеличенным изображением. Необязательный. По умолчанию - "false".
popup_alt | Текст всплывающей подсказки на изображении (только если popup = true) Необязательный. По умолчанию выводится фраза "Нажмите чтобы увеличить" на языке страницы.
image_width | Ширина изображения (в пикселах) (только если в параметре image задан URL начинающийся с "http://") Необязательный. По умолчанию "0".
image_height | Высота изображения (в пикселах) (только если в параметре image задан URL начинающийся с "http://") Необязательный. По умолчанию "0".

См. также

  • CFile::Show2Images

Примеры использования

<tr valign="top">
    <td align="right"><font class="tablefieldtext"><?echo
    GetMessage("VOTE_IMAGE")?></font></td>
    <td><font class="tablebodytext"><?
    echo CFile::InputFile("IMAGE_ID", 20, $str_IMAGE_ID);
    if (strlen($str_IMAGE_ID)>0):
        ?><br><?
        echo CFile::ShowImage($str_IMAGE_ID, 200, 200, "border=0", "", true);
    endif;
    ?></font>
    </td>
</tr>


UpdateDesc

CFile::UpdateDesc

CDBResult
CFile::UpdateDesc(
 int file_id,
 string description
)

Функция обновляет описание к зарегистрированному файлу. Возвращает объект класса CDBResult.

Параметры функции

Параметр | Описание
file_id | Цифровой идентификатор файла.
description | Новое описание к файлу.

См. также

  • RewriteFile
  • CMain::SaveFileContent
  • CFile::GetByID

Примеры использования

<?
if ($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, $IBLOCK_ID, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER, "ID" => "ASC"), false, $arrFilter)):
    $rsElements->NavStart($PAGE_ELEMENT_COUNT);
    while ($obElement = $rsElements->GetNextElement()):
        $arElement = $obElement->GetFields();
        CFile::UpdateDesc($arElement["PREVIEW_PICTURE"], "Element # ".$arElement["ID"]);
    endwhile;
endif;
?>


Класс CGroup

CGroup - класс для работы с группами пользователей.

Поля

Поле | Тип | Описание
ID | Int | ID группы.
TIMESTAMP_X | datetime | Последнее изменение.
ACTIVE | char | Активна (Y|N).
NAME | varchar (50) | Наименование группы.
DESCRIPTION | varchar (255) | Описание.

Методы класса

Метод | Описание
GetList | Получает список групп по фильтру.
GetByID | Получает данные о группе по ее ID.
GetGroupUser | Список всех пользователей группы.
Add | Добавляет новую группу пользователей.
Update | Изменяет существующую группу.
Delete | Удаляет группу.


Add

CGroup::Add

mixed
CGroup::Add(
 array fields
)

Функция добавляет новую группу. Возвращает ID вставленной группы. При возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля CGroup
  • CGroup::Delete
  • CGroup::Update

Примеры использования

<?
$group = new CGroup;
$arFields = Array(
  "ACTIVE"       => "Y",
  "C_SORT"       => 100,
  "NAME"         => "Имя группы",
  "DESCRIPTION"  => "Описание группы",
  "USER_ID"      => array(128, 134)
  );
$NEW_GROUP_ID = $group->Add($arFields);
if (strlen($group->LAST_ERROR)>0) ShowError($group->LAST_ERROR);
?>


Delete

CGroup::Delete

mixed
CGroup::Delete(
 int id
)

Функция удаляет группу. При успешном удалении возвращается объект класса CDBResult, в противном случае - "false".

Параметры функции

Параметр | Описание
id | ID группы.

См. также

  • CGroup::Add
  • CGroup::Update
  • Событие "OnBeforeGroupDelete"
  • Событие "OnGroupDelete"

Примеры использования

<?
if(IntVal($del_id)>2)
{
  $del_id = IntVal($del_id);
  $group = new CGroup;
  $DB->StartTransaction();
  if(!$group->Delete($del_id))
  {
    $DB->Rollback();
    $strError.=GetMessage("DELETE_ERROR");
  }
  $DB->Commit();
}
?>


GetByID

CGroup::GetByID

CDBResult
CGroup::GetByID(
 int id,
 string get_users_amount = "N"
)

Возвращает группу пользователей по ее коду ID в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
id | ID группы.
get_users_amount | "Y" - в выборке будет присутствовать поле ("USERS") с количеством пользователей в группе; "N" - в выборке не будет поля с количеством пользователей в группе (по умолчанию);

См. также

  • Поля CGroup
  • CGroup::GetList

Примеры использования

<?
$rsGroup = CGroup::GetByID(2, "Y");
$arGroup = $rsGroup->Fetch();
echo "<pre>"; print_r($arGroup); echo "</pre>";
?>


GetGroupUser

CGroup::GetGroupUser

array
CGroup::GetGroupUser(
 int group_id
)

Возвращает массив ID всех пользователей группы по ее коду group_id.

Параметры функции

Параметр | Описание
group_id | ID группы.

См. также

  • Поля CGroup
  • Поля CUser

Примеры использования

<?
$arUsers = CGroup::GetGroupUser(1);
echo "<pre>"; print_r($arUsers); echo "</pre>";
?>


GetList

CGroup::GetList

CDBResult
CGroup::GetList(
 string &by = "c_sort",
 string &order = "asc",
 array filter,
 string get_users_amount = "N"
)

Возвращает список групп в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
by Ссылка на переменную с полем для сортировки, может принимать следующие значения:
  • id - ID группы
  • timestamp_x - дата изменения
  • name - название
  • active - активность
  • c_sort - порядок сортировки
  • description - описание
  • users - кол-во пользователей входящих в группу
оrder Ссылка на переменную с порядком сортировки, может принимать следующие значения:
  • asc - по возрастанию
  • desc - по убыванию
filter Массив для фильтрации пользователей. В массиве допустимы следующие индексы:
  • ID - ID группы (допускается сложная логика)
  • TIMESTAMP_1 - дата изменения настроек группы "с"
  • TIMESTAMP_2 - дата изменения настроек группы "по"
  • ACTIVE - фильтр по активности (Y|N)
  • ADMIN - фильтр по типу группы ("Y" - администраторы | "N" - не администраторы)
  • NAME - по названию (допускается сложная логика)
  • DESCRIPTION - по описанию (допускается сложная логика)
  • USERS_1 - кол-во пользователей "с"
  • USERS_2 - кол-во пользователей "по"
get_users_amount | "Y" - в выборке будет присутствовать поле ("USERS") с количеством пользователей в каждой группе; "N" - в выборке не будет поля с количеством пользователей в каждой группе (по умолчанию);

См. также

  • Поля CGroup
  • CGroup::GetByID

Примеры использования

<?
$filter = Array
(
    "ID"             => "1 | 2",
    "TIMESTAMP_1"    => "04.02.2004", // в формате текущего сайта
    "TIMESTAMP_2"    => "04.02.2005",
    "ACTIVE"         => "Y",
    "NAME                 => "Техподдержка",
    "DESCRITION"     => "специальная | поддержка",
    "USERS_1"        => "2", // от 2 пользователей
    "USERS_2"        => "10" // до 10 пользователей
);
$rsGroups = CGroup::GetList(($by="c_sort"), ($order="desc"), $filter); // выбираем группы
$is_filtered = $rsGroups->is_filtered; // отфильтрована ли выборка ?
$rsGroups->NavStart(50); // разбиваем постранично по 50 записей
echo $rsGroups->NavPrint(GetMessage("PAGES")); // печатаем постраничную навигацию
while($rsGroups->NavNext(true, "f_")) :
    echo "[".$f_ID."] ".$f_NAME." ".$f_DESCRIPTION."<br>";
endwhile;
?>


Update

CGroup::Update

bool
CGroup::Update(
 int id,
 array fields
)

Функция изменяет группу с кодом id. Возвращает "true" если изменение прошло успешно, при возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
id | ID изменяемой записи.
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля CGroup
  • CGroup::Add
  • CGroup::Delete

Примеры использования

<?
$group = new CGroup;
$arFields = Array(
  "ACTIVE"       => "Y",
  "C_SORT"       => 100,
  "NAME"         => "Имя группы",
  "DESCRIPTION"  => "Описание группы",
  "USER_ID"      => array(128, 134)
  );
$group->Update($GROUP_ID, $arFields);
if (strlen($group->LAST_ERROR)>0) ShowError($group->LAST_ERROR);
?>


Класс CLanguage

CLanguage - класс для работы с языками системы.

Поля

Поле | Тип | Описание
LID | char(2) | Двухсимвольный ID языка.
SORT | int | Порядок сортировки.
DEF | char | Язык по умолчанию (Y|N).
ACTIVE | char | Активность (Y|N).
NAME | varchar (50) | Название.
FORMAT_DATE | varchar (50) | Формат даты для административной части.
FORMAT_DATETIME | varchar (50) | Формат даты-время для административной части.
CHARSET | varchar (255) | Кодировка для показа страниц данного языка в административной части.

Методы класса

Метод | Описание
GetList | Получает список языков.
GetByID | Получает данные об одном языке.
SelectBox | Создает выпадающий список с языками.
Add | Добавляет новый язык.
Update | Изменяет существующий язык.
Delete | Удаляет язык.

См. также

  • Языки


Add

CLanguage::Add

mixed
CLanguage::Add(
 array fields
)

Функция добавляет новый язык. Возвращает ID вставленного языка. При возникновении ошибки функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля CLanguage
  • CLanguage::Update
  • CLanguage::Delete

Примеры использования

<?
$arFields = Array(
  "LID"              => "en",
  "ACTIVE"           => "Y",
  "SORT"             => 100,
  "DEF"              => "N",
  "NAME"             => "English",
  "FORMAT_DATE"      => "MM/DD/YYYY",
  "FORMAT_DATETIME"  => "MM/DD/YYYY HH:MI:SS",
  "CHARSET"          => "iso-8859-1"
  );
$obLang = new CLanguage;
$obLang->Add($arFields);
if (strlen($obLang->LAST_ERROR)>0) $strError .= $obLang->LAST_ERROR;
?>


Delete

CLanguage::Delete

CDBResult
CLanguage::Delete(
 string id
)

Функция удаляет язык. Возвращается объект CDBResult.

Параметры функции

Параметр | Описание
id | Двухсимвольный ID языка.

См. также

  • CLanguage::Add
  • CLanguage::Update
  • Событие "OnBeforeLanguageDelete"
  • Событие "OnLanguageDelete"

Примеры использования

<?
if (CLanguage::Delete("en"))
  echo "Язык успешно удален.";
?>


GetByID

CLanguage::GetByID

CDBResult
CLanguage::GetByID(
 string id
)

Возвращает язык по его коду id в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
id | Двухсимвольный ID языка.

См. также

  • Поля CLanguage
  • CLanguage::GetList
  • CLanguage::SelectBox

Примеры использования

<?
$rsLang = CLanguage::GetByID("en");
$arLang = $rsLang->Fetch();
echo "<pre>"; print_r($arLang); echo "</pre>";
?>


GetList

CLanguage::GetList

CDBResult
CLanguage::GetList(
 string &by = "sort",
 string &order = "asc",
 array filter = array()
)

Возвращает список языков в виде объекта класса CDBResult.

Параметры функции

Параметр Описание
by По какому полю сортируем. Допустимы следующие значения:
  • lid - по ID языка
  • active - по флагу активности
  • name - по названию
  • def - по флагу "Язык по умолчанию"
оrder Порядок сортировки. Допустимы следующие значения:
  • asc - по возрастанию
  • desc - по убыванию
filter Массив вида array("фильтруемое поле"=>"значение" [, ...]). "Фильтруемое поле" может принимать следующие значения:
  • LID - двухсимвольный ID языка
  • NAME - название языка
  • ACTIVE - флаг активности (Y|N)

См. также

  • Поля CLanguage
  • CLanguage::GetByID

Примеры использования

<?
$rsLang = CLanguage::GetList($by="sort", $order="desc", Array("NAME" => "russian"));
while ($arLang = $rsLang->Fetch())
{
  echo "<pre>"; print_r($arLang); echo "</pre>";
}
?>


SelectBox

CLanguage::SelectBox

string
CLanguage::SelectBox(
 string name,
 string value,
 string default_value = "",
 string js_function = "",
 string add_to_select = "class=typeselect"
)

Возвращает HTML, представляющий из себя выпадающий список языков (тэг "select").

Параметры функции

Параметр | Описание
name | Имя выпадающего списка: <select name="name" ...>
value | Текущее значение (для инициализации выбранного значения).
default_value | Если задан, то будет выводиться первым пунктом списка (например, фраза "выберите язык"). Не обязательный. По умолчанию "".
js_function | Имя JS функции которая будет вызываться при выборе в выпадающем списке какого либо значения: <select OnChange="js_function" ...> Не обязательный. По умолчанию "".
add_to_select | Произвольный HTML который будет добавлен в тэг "select": <select add_to_select ...> Не обязательный. По умолчанию задан стандартный CSS класс для выпадающих списков административной части.

Примеры использования

<table>
  <tr>
    <td>Язык:</td>
    <td><?=CLanguage::SelectBox("LANGUAGE", LANGUAGE_ID)?></td>
  </tr>
</table>


Update

CLanguage::Update

bool
CLanguage::Update(
 int id,
 array fields
)

Функция изменяет настройки языка. Возвращает "true" если изменение прошло успешно, при возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
id | Двухсимвольный ID языка.
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля CLanguage
  • CLanguage::Add
  • CLanguage::Delete

Примеры использования

<?
$arFields = Array(
  "ACTIVE"           => "Y",
  "SORT"             => 100,
  "DEF"              => "N",
  "NAME"             => "English",
  "FORMAT_DATE"      => "MM/DD/YYYY",
  "FORMAT_DATETIME"  => "MM/DD/YYYY HH:MI:SS",
  "CHARSET"          => "iso-8859-1"
  );
$obLang = new CLanguage;
$obLang->Update("en", $arFields);
if (strlen($obLang->LAST_ERROR)>0) $strError .= $obLang->LAST_ERROR;
?>


Класс CMain

CMain - главный класс страницы.

При создании каждой страницы создаётся глобальный объект этого класса с именем $APPLICATION.

Методы класса

Заголовок страницы

Метод | Описание
ShowTitle | Отображает заголовок страницы.
GetTitle | Возвращает заголовок страницы.
SetTitle | Устанавливает заголовок страницы.

CSS стили

Метод | Описание
ShowCSS | Отображает HTML для подключения CSS на странице.
GetCSS | Возвращает HTML для подключения CSS на странице.
SetTemplateCSS | Устанавливает путь к файлу с CSS стилями компонента.
SetAdditionalCSS | Устанавливает путь к файлу с CSS стилями.

Навигационная цепочка

Метод | Описание
ShowNavChain | Отображает HTML с навигационной цепочкой.
GetNavChain | Возвращает HTML с навигационной цепочкой.
AddChainItem | Добавляет пункт в конец навигационной цепочки.

Меню

Метод | Описание
GetMenu | Возвращает объект CMenu для текущей папки.
GetMenuHtml | Возвращает строку с меню типа type для текущей папки в виде HTML.
GetMenuHtmlEx | Аналог GetMenuHtml с применением другого типа шаблона меню.

Свойства страниц и разделов

Метод | Описание
ShowProperty | Отображает свойство страницы, учитывая свойства раздела.
GetProperty | Возвращает свойство страницы, учитывая свойства раздела.
GetPageProperty | Возвращает свойство страницы.
GetDirProperty | Возвращает свойство раздела.
GetPagePropertyList | Возвращает массив всех свойств страницы.
GetDirPropertyList | Возвращает массив всех свойств раздела.
SetPageProperty | Устанавливает свойство страницы.
SetDirProperty | Устанавливает свойство раздела.
ShowMeta | Отображает свойство страницы (раздела) обрамленное тегом <meta>.
GetMeta | Возвращает свойство страницы (раздела) обрамленное тегом <meta>.

Файлы

Метод | Описание
SaveFileContent | Сохраняет страницу на диске.
GetFileContent | Возвращает содержимое файла.
GetFileRecursive | Ищет файл с заданным именем последовательно вверх по иерархии каталогов.
GetFileAccessPermission | Определяет права доступа к файлу или каталогу.
SetFileAccessPermission | Устанавливает права доступа к файлу или каталогу.
CopyFileAccessPermission | Копирует права доступа одного файла (каталога) другому файлу (каталогу).
RemoveFileAccessPermission | Удаляет права доступа для файла или каталогу.

Права доступа и роли пользователя в модуле

Метод | Описание
GetUserRight | Возвращает максимальное право пользователя на тот или иной модуль.
GetUserRoles | Возвращает массив ролей пользователя в том или ином модуле.

Текущий адрес страницы

Метод | Описание
GetCurUri | Возвращает адрес текущей страницы с параметрами.
GetCurPage | Возвращает адрес текущей страницы без параметров.
GetCurPageParam | Возвращает URL текущей страницы c добавленными новыми и(или) удаленными параметрами.
GetCurDir | Возвращает раздел текущей страницы.
SetCurPage | Устанавливает адрес текущей страницы.

Панель управления

Метод | Описание
ShowPanel | Отображает HTML представляющий из себя панель управления публичной частью.
GetPanel | Возвращает HTML представляющий из себя панель управления публичной частью.
AddPanelButton | Добавляет кнопку в панель управления публичной частью.

Куки (cookie)

Метод | Описание
set_cookie | Устанавливает значение cookie.
get_cookie | Возвращает значение cookie.
ShowSpreadCookieHTML | Отображает HTML позволяющий установить cookie пользователю.

Компоненты

Метод | Описание
IncludeFile | Подключает произвольные файлы и компоненты.
GetTemplatePath | Возвращает полный путь к файлу следуя алгоритму подключения компонент.

Прочие методы

Метод | Описание
IncludeAdminFile | Подключает скрипт с административным прологом и эпилогом.
IncludeString | Выводит произвольную строку (HTML код) обрамленную рамкой, в правом верхнем углу которой выводятся заданные иконки.
GetShowIncludeAreas | Возвращает состояние кнопки "Показать включаемые области" на панели управления.
AddBufferContent | Позволяет создавать отложенные функции.
ShowBanner | Подключает модуль "Реклама, баннеры" и если подключение успешно, выводит баннер.
GetSiteByDir | Определяет сайт по заданному каталогу и хосту.
AuthForm | Выводит форму авторизации.
IsHTTPS | Возвращает "true" если используемый текущий протокол - HTTPS.


AddBufferContent

CMain::AddBufferContent

CMain::AddBufferContent(
 callback function,
 mixed parameter_1,
 mixed parameter_2,
 ...
 mixed parameter_N
)

Позволяет создавать отложенные функции.

Параметры функции

Параметр | Описание
function | Имя функции выполнение которой необходимо отложить. Если это обычная функция то в данном параметре просто указывается ее имя, если это метод класса, то указывается массив, первым элементом которого будет имя класса (либо объект класса), а вторым - имя метода.
parameter_1 ... parameter_N | Неограниченное количество параметров которые будут впоследствии переданы функции function.

См. также

  • Отложенные функции
  • CMain::ShowTitle
  • CMain::ShowCSS
  • CMain::ShowNavChain
  • CMain::ShowProperty
  • CMain::ShowMeta
  • CMain::ShowPanel

Примеры использования

<?
function myShowProperty($property_id, $default_value=false)
{
    global $APPLICATION;
    echo $APPLICATION->AddBufferContent(Array(&$APPLICATION, "GetProperty"),
    $property_id, $default_value);
}
?>
<?
function myShowTitle($property_name="title", $strip_tags = true)
{
    global $APPLICATION;
    echo $APPLICATION->AddBufferContent(Array(&$APPLICATION, "GetTitle"),
    $property_name, $strip_tags);
}
?>
<?
function myShowPanel()
{
    global $APPLICATION;
    echo $APPLICATION->AddBufferContent(Array(&$APPLICATION, "GetPanel"));
}
?>


AddChainItem

CMain::AddChainItem

CMain::AddChainItem(
 string title,
 string url = "",
 bool convert_html_entity = true
)

Добавляет пункт в конец навигационной цепочки.

Параметры функции

Параметр | Описание
title | Заголовок добавляемого пункта навигационной цепочки.
url | URL на который будет указывать добавляемый пункт навигационной цепочки.
convert_html_entity Если значение - "true", то в title будут произведены следующие замены:
  • &amp; заменяется на &
  • &quot; заменяется на "
  • &#039; заменяется на '
  • &lt; заменяется на <
  • &gt; заменяется на >
В противном случае замены не будут производиться.
Необязательный. По умолчанию - "true".

См. также

  • Навигационная цепочка
  • CMain::ShowNavChain
  • CMain::GetNavChain

Примеры использования

<?
$APPLICATION->AddChainItem("Форум &quot;Отзывы&quot;", "/ru/forum/list.php?FID=3");
?>


AddPanelButton

CMain::AddPanelButton

CMain::AddPanelButton(
 array button
)

Добавляет в панель управления кнопку.

Параметры функции

Параметр Описание
button Массив описывающий добавляемую кнопку. Ключи массива:
  • HREF - ссылка на кнопке
  • SRC - путь от корня сайта к картинке которая будет выведена на кнопке
  • ALT - текст всплывающей подсказки на кнопке
  • MAIN_SORT - индекс сортировки для группы кнопок, для стандартных групп иконок данный параметр имеет следующие значения:
    • 100 - группа иконок модуля управления статикой
    • 200 - группа иконок модуля документооборота
    • 300 - группа иконок модуля информационных блоков
  • SORT - индекс сортировки внутри группы кнопок
Если у пользователя не хватает прав на ту или иную операцию и вы хотите в любом случае вывести кнопку, то необходимо HREF оставлять пустым, при этом кнопка будет выведена черно-белой и без ссылки.

См. также

  • Панель управления
  • CMain::ShowPanel
  • Событие "OnPanelCreate"

Примеры использования

<?
// получим уровень доступа к модулю "Веб-формы"
$FORM_RIGHT = $APPLICATION->GetUserRight("form");
// если доступ есть то
if($FORM_RIGHT>"D"):
    // добавим в панель кнопку ведущую на список веб-форм
    $APPLICATION->AddPanelButton(array(
        "HREF"      => "/bitrix/admin/form_list.php",
        "SRC"       => "/bitrix/images/fileman/panel/web_form.gif",
        "ALT"       => "Редактировать веб-форму",
        "MAIN_SORT" => 400,
        "SORT"      => 100
    ));
endif;
?>


AuthForm

CMain::AuthForm

CMain::AuthForm(
 mixed message,
 bool show_header = true,
 bool show_footer = true,
 string not_show_links = "N"
)

Функция подключает ряд компонентов в зависимости от параметров пришедших на страницу:
Параметр | Значение | Название компонента | Путь к компоненту
forgot_password | yes | "Форма отсылки забытого пароля" | main/auth/forgot_password.php
change_password | yes | "Форма смены забытого пароля" | main/auth/change_password.php
register | yes | "Форма регистрации" | main/auth/registration.php
authorize_registration | yes | "Форма авторизации и регистрации" | main/auth/authorize_registration.php

Если не указан ни один из параметров, то по умолчанию функция подключит компонент "Форма авторизации" (main/auth/authorize.php).

После вывода соответствующего компонента функция завершает выполнение страницы.

Параметры функции

Параметр | Описание
message | Строка - сообщение об ошибке или массив вида Array("MESSAGE" => сообщение, "TYPE" => "ERROR"|"OK") (обрабатывается функцией ShowMessage)
show_header | Если значение "true" - то будет выведен пролог (верх) сайта, "false" - пролог выводиться не будет.
show_footer | Если значение "true" - то будет выведен эпилог (низ) сайта, "false" - эпилог выводиться не будет.
not_show_links | Данный параметр передается в компонент "Форма авторизации" (main/auth/authorize.php). Если значение "Y" - то ссылки ведущие на регистрацию и форму запроса и смены забытого пароля выводиться не будут, если "N" - ссылки выводиться будут (значение по умолчанию).

См. также

  • Компоненты
  • Права доступа
  • ShowMessage

Примеры использования

<?
// определим право чтения на файл "/download/document.doc" у текущего пользователя
$FILE_PERM = $APPLICATION->GetFileAccessPermission("/download/document.doc");
$FILE_PERM = (strlen($FILE_PERM)>0 ? $FILE_PERM : "D");
// если право чтения нет, то выводем форму авторизации
if($FILE_PERM < "R") $APPLICATION->AuthForm("У вас нет права доступа к данному файлу.");
?>


CopyFileAccessPermission

CMain::CopyFileAccessPermission

bool
CMain::CopyFileAccessPermission(
 string path_from,
 string path_to,
 bool overwrite = false
)

Копирует права доступа одного файла (каталогу) другому файлу (каталогу). Возвращает "true" - если права скопированы успешно и "false" - в случае ошибки.

Параметры функции

Параметр Описание
path_from Путь откуда копировать. В случае многосайтовой версии, если DOCUMENT_ROOT у сайтов разный (задается в поле "Путь к корневой папке веб-сервера" в настройках сайта), то в данном параметре необходимо передавать массив вида:
array("ID сайта", "Путь откуда копировать")
path_to Путь куда копировать. В случае многосайтовой версии, если DOCUMENT_ROOT у сайтов разный (задается в поле "Путь к корневой папке веб-сервера" в настройках сайта), то в данном параметре необходимо передавать массив вида:
array("ID сайта", "Путь куда копировать")
overwrite Если значение - "true", то существующие права будут перезаписаны.
Необязателен. По умолчанию - "false".

См. также

  • Права доступа
  • CMain::GetFileAccessPermission
  • CMain::SetFileAccessPermission
  • CMain::RemoveFileAccessPermission

Примеры использования

<?
// установим на файл /ru/index.php следующие права:
// для группы # 23 - право чтения файла
// для группы # 5 - право прямого изменения файла
// для всех остальных групп - доступ к файлу закрыт
if ($APPLICATION->SetFileAccessPermission("/ru/index.php", array("23" => "R", "5" => "W", "*" => "D")))
{
    ShowNote("Права на файл успешно установлены.");

    // скопируем права файла "/ru/index.php" в права файла "/en/index.php"
    if ($APPLICATION->CopyFileAccessPermission("/ru/index.php", "/en/index.php", true))
         ShowNote("Права успешно скопированы.");
}
?>


get_cookie

CMain::get_cookie

CMain::get_cookie(
 string name,
 mixed name_prefix = false
)

Возвращает значение cookie.

Параметры функции

Параметр | Описание
name | Имя cookie переменной.
name_prefix Префикс имени переменной cookie.
Необязательный. По умолчанию - значение параметра "Имя префикса для названия cookies" в настройках главного модуля (значение данного параметра можно получить с помощью функции:
COption::GetOptionString("main", "cookie_name", "BITRIX_SM")

См. также

  • Перенос посетителей
  • CMain::set_cookie
  • CMain::ShowSpreadCookieHTML

Примеры использования

<?
global $APPLICATION;
$VISITOR_ID = $APPLICATION->get_cookie("VISITOR_ID");
?>


GetCSS

CMain::GetCSS

string
CMain::GetCSS(
 bool external = true
)

Возвращает CSS страницы. CSS страницы может быть задан с помощью функций CMain::SetAdditionalCSS и CMain::SetTemplateCSS. Помимо заданных CSS стилей, всегда возвращается CSS текущего шаблона сайта, задаваемого в файле /bitrix/templates/ID шаблона/styles.css.

Параметры функции

Параметр Описание
external Если значение - "true", то выводится HTML представляющий из себя ссылку на внешний CSS, например:
<LINK href="/bitrix/templates/demo/styles.css" type="text/css" rel="stylesheet">
Если значение "false", то выводится HTML представляющий из себя внутренний CSS, например:
<style type="text/css">
body { margin: 0px; padding:0px; background-color: #FFFFFF}
...
</style>
Исключение составляет CSS стили лежащие в каталоге /bitrix/modules/, они всегда подключаются как внутренний CSS (как правило это используется в стандартных компонентах).

См. также

  • CMain::ShowCSS
  • CMain::SetTemplateCSS
  • CMain::SetAdditionalCSS


GetCurDir

CMain::GetCurDir

string
CMain::GetCurDir()

Возвращает каталог текущей страницы относительно корня.

Параметры функции

Без параметров.

См. также

  • CMain::GetCurUri
  • CMain::GetCurPage
  • CMain::GetCurPageParam
  • CMain::SetCurPage
  • GetDirPath
  • GetPagePath

Примеры использования

<?
// текущая страница: /ru/support/index.php?id=3&s=5
global $APPLICATION;
$dir = $APPLICATION->GetCurDir();
// в $dir будет значение "/ru/support/"
?>


GetCurPage

CMain::GetCurPage

string
CMain::GetCurPage()

Возвращает путь к текущей странице относительно корня без параметров.

Если файл текущей страницы явно не определён, то определение индексного файла каталога будет проходить по алгоритму представленному в описании функции GetDirIndex.

Параметры функции

Без параметров.

См. также

  • CMain::GetCurUri
  • CMain::GetCurDir
  • CMain::GetCurPageParam
  • CMain::SetCurPage
  • GetPagePath
  • GetDirPath

Примеры использования

<?
// текущая страница: /ru/?id=3&s=5
$page = $APPLICATION->GetCurPage(); // результат - /ru/index.php
?>


GetCurPageParam

CMain::GetCurPageParam

string
CMain::GetCurPageParam(
  string add_params = "",
  array remove_params = array()
)

Возвращает путь к текущей странице относительно корня c добавленными новыми и(или) удаленными текущими параметрами.

Если файл текущей страницы явно не определён, то определение индексного файла каталога будет проходить по алгоритму представленному в описании функции GetDirIndex.

Параметры функции

Параметр | Описание
add_params | Строка с параметрами которые нужно добавить к возвращаемому значению. Необязательный. По умолчанию "".
remove_params | Массив параметров, которые необходимо удалить из URL-а страницы. Необязательный. По умолчанию - пустой массив.

См. также

  • DeleteParam
  • CMain::GetCurPage
  • CMain::GetCurUri
  • CMain::GetCurDir
  • GetPagePath
  • GetDirPath

Примеры использования

<?
// текущая страница: /ru/?id=3&s=5&d=34
$page = $APPLICATION->GetCurPageParam("id=45", array("id", "d"));
// результат - /ru/index.php?id=45&s=5
?>
// пример формирование ссылок "Logout" и "Регистрация"

<?if ($USER->IsAuthorized()):?>

 <a href="<?echo $APPLICATION->GetCurPageParam("logout=yes", array(
     "login",
     "logout",
     "register",
     "forgot_password",
     "change_password"));?>">Закончить сеанс (logout)</a>

<?else:?>

 <a href="<?echo $APPLICATION->GetCurPageParam("register=yes", array(
     "login",
     "logout",
     "forgot_password",
     "change_password"));?>">Регистрация</a>

<?endif;?>


GetCurUri

CMain::GetCurUri

string
CMain::GetCurUri(
 string add_params = ""
)

Возвращает путь к текущей странице относительно корня вместе с параметрами.

Если файл текущей страницы явно не определён, то определение индексного файла каталога будет проходить по алгоритму представленному в описании функции GetDirIndex.

Параметры функции

Параметр | Описание
add_params | Строка параметров добавляемая к возвращаемому значению. Необязательный. По умолчанию - "".

См. также

  • CMain::GetCurPage
  • CMain::GetCurDir
  • CMain::GetCurPageParam
  • CMain::SetCurPage
  • GetPagePath
  • GetDirPath

Примеры использования

<?
// текущая страница: /ru/?id=3&s=5
$uri = $APPLICATION->GetCurUri("r=1&t=2"); // результат - /ru/index.php?id=3&s=5&r=1&t=2
?>


GetDirProperty

CMain::GetDirProperty

string
CMain::GetDirProperty(
 string property_id,
 mixed path = false,
 mixed default_value = false
)

Возвращает свойство текущего раздела.

Параметры

Параметр | Описание
property_id | Идентификатор свойства.
path Путь к каталогу. В случае многосайтовой версии, если DOCUMENT_ROOT у сайтов разный (задается в поле "Путь к корневой папке веб-сервера" в настройках сайта), то в данном параметре необходимо передавать массив вида:
array("ID сайта", "путь")
Необязателен. По умолчанию - "false" - текущий каталог.
default_value Значение свойства по умолчанию.
Необязательный. По умолчанию - "false" - значение свойства по умолчанию не задано.

См. также

  • Свойства страниц и мета-тэги
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirPropertyList
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Пример использования

<?
$APPLICATION->GetDirProperty("keywords");
?>


GetDirPropertyList

CMain::GetDirPropertyList

array
CMain::GetDirPropertyList(
 string path = false
)

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

Параметры

Параметр Описание
path Путь к каталогу. В случае многосайтовой версии, если DOCUMENT_ROOT у сайтов разный (задается в поле "Путь к корневой папке веб-сервера" в настройках сайта), то в данном параметре необходимо передавать массив вида:
array("ID сайта", "путь")
Необязателен. По умолчанию - "false" - текущий каталог.

См. также

  • Свойства страниц и мета-тэги
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetDirProperty
  • CMain::GetPagePropertyList
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Пример использования

<?
$props = $APPLICATION->GetDirPropertyList();
foreach($props as $key=>$val)
    echo '<meta name="'.$key.'" content="'.htmlspecialchars($val).'">';
?>


GetException

CMain::GetException

CApplicationException
CMain::GetException();

Метод возвращает объект класса CApplicationException, содержащий последнее исключение.

См. также

  • Класс CApplicationException
  • CMain::ThrowException

Примеры использования

<?
if(!$langs->Delete($del_id))
{
   if($ex = $APPLICATION->GetException())
      $strError = $ex->GetString();
}
?>


GetFileAccessPermission

CMain::GetFileAccessPermission

string
CMain::GetFileAccessPermission(
 mixed path,
 array groups
)

Определяет права доступа к файлу или каталогу. Возвращает символ обозначающий то или иное право:

  • D - доступ запрещён
  • R - чтение (право просмотра содержимого файла)
  • U - документооборот (право на редактирование файла в режиме документооборота)
  • W - запись (право на прямое редактирование)
  • X - полный доступ (право на прямое редактирование файла и право на изменение прав доступа на данных файл)

Параметры функции

Параметр Описание
path Путь к файлу или папке относительно корня. В случае многосайтовой версии, если корневой каталог у сайтов разный, то в данном параметре необходимо передавать массив вида:
array("ID сайта", "Путь к файлу или папке относительно корня")
groups Массив ID групп пользователей, для которых необходимо определить права доступа. Если false, то определять группу прав для текущего пользователя.
Необязателен. По умолчанию - "false".

См. также

  • Права доступа
  • CMain::SetFileAccessPermission
  • CMain::CopyFileAccessPermission
  • CMain::RemoveFileAccessPermission

Примеры использования

<?
if ($APPLICATION->GetFileAccessPermission("/ru/index.php") <= "D")
   ShowError("Доступ к файлу запрещён.");
?>


GetFileContent

CMain::GetFileContent

mixed
CMain::GetFileContent(
 string abs_path
)

Возвращает содержимое файла. Если файл не существует - вернет "false".

Параметры функции

Параметр | Описание
abs_path | Абсолютный путь к файлу на диске.

См. также

  • CMain::SaveFileContent

Примеры использования

<?
$APPLICATION->GetFileContent($_SERVER["DOCUMENT_ROOT"]."/ru/index.php");
?>


GetFileRecursive

CMain::GetFileRecursive

mixed
CMain::GetFileRecursive(
 string file,
 mixed dir
)

Ищет файл с заданным именем последовательно вверх по иерархии папок. Если файл найден - возвращает путь к найденному файлу относительно корня, в противном случае возвращает "false".

Параметры функции

Параметр | Описание
file | Имя файла.
dir | Путь к разделу с которого нужно начинать поиск файла. Если "false", то поиск будет начинаться с текущего раздела. Необязателен. По умолчанию - "false".

Примеры использования

<?
// ищем файл params.php вверх по иерархии разделов начиная с текущего каталога
// если файл найден то подключаем его как PHP код
include($_SERVER["DOCUMENT_ROOT"].$APPLICATION->GetFileRecursive("params.php"));
?>


GetMenu

CMain::GetMenu

CMenu
CMain::GetMenu(
 string type = "left",
 bool use_ext = false,
 mixed template_path = false,
 mixed init_dir = false
)

Возвращает объект класса CMenu, инициализированный функцией CMenu::Init. Если произошла ошибка, то текст ошибки будет содержаться в свойстве LAST_ERROR данного объекта.

Параметры функции

Параметр | Описание
type | Тип меню. Необязателен. По умолчанию "left".
use_ext | Если значение - "true", то для формирования массива меню, помимо файлов .тип меню.menu.php будут также подключаться файлы с именами вида .тип меню.menu_ext.php. В которых вы можете манипулировать массивом меню $aMenuLinks произвольно, по вашему усмотрению (например, дополнять пункты меню значениями из инфо-блоков). Необязателен. По умолчанию - "false".
template_path | Путь относительно корня к шаблону меню. Необязателен. По умолчанию - "false", что означает искать по алгоритму указанному на странице "Меню".
init_dir | Каталог для которого будет строится меню. Необязателен. По умолчанию - "false", что означает - текущий каталог.

См. также

  • Меню
  • Класс CMenu
  • CMenu::Init
  • CMain::GetMenuHtml
  • CMain::GetMenuHtmlEx

Примеры использования

<?
// выводим меню типа "left"
// с поддержкой файлов .тип меню.menu_ext.php
// с четким указанием шаблона и
// каталога для которого будет построено меню

$obMenu = $APPLICATION->GetMenu(
    "left",
    true,
    "/bitrix/php_interface/".SITE_ID."/left.menu_template.php",
    SITE_DIR
    );

// выводим меню
echo $obMenu->GetMenuHtml();
?>


GetMenuHtml

CMain::GetMenuHtml

string
CMain::GetMenuHtml(
 string type = "left",
 bool use_ext = false,
 mixed template_path = false,
 mixed init_dir = false
)

Возвращает HTML-код для отображения меню заданного типа. В отличии от функции CMain::GetMenuHtmlEx шаблон меню будет подключаться на каждый пункт меню.

Параметры функции

Параметр | Описание
type | Тип меню. Необязателен. По умолчанию "left".
use_ext | Если значение - "true", то для формирования массива меню, помимо файлов .тип меню.menu.php будут также подключаться файлы с именами вида .тип меню.menu_ext.php. В которых вы можете манипулировать массивом меню $aMenuLinks произвольно, по вашему усмотрению (например, дополнять пункты меню значениями из инфо-блоков). Необязателен. По умолчанию - "false".
template_path | Путь относительно корня к шаблону меню. Необязателен. По умолчанию - "false", что означает искать по алгоритму указанному на странице "Меню".
init_dir | Каталог для которого будет строится меню. Необязателен. По умолчанию - "false", что означает - текущий каталог.

См. также

  • Меню
  • Класс CMenu
  • CMenu::Init
  • CMain::GetMenu
  • CMain::GetMenuHtmlEx

Пример левого меню элементы которого выбираются из инфо-блока

Вывод меню в файле /bitrix/templates/demo/header.php:

<?
echo $APPLICATION->GetMenuHtml("left", true);
?>

Файл /.left.menu.php:

<?
// основной файл меню
// данный файл может редактироваться в редакторе меню
$aMenuLinks = Array(
);
?>

Файл /.left.menu_ext.php:

<?
// дополнительный файл меню
// добавляет в основной массив меню разделы каталога телефонов
if (CModule::IncludeModule("iblock")):

    $IBLOCK_TYPE = "catalog";   // тип инфо-блока
    $IBLOCK_ID = 21;            // ID инфо-блока
    $CACHE_TIME = 3600;         // кэшируем на 1 час

    $aMenuLinksNew = array();

    // создаем объект для кэширования меню
    $CACHE_ID = __FILE__.$IBLOCK_ID;
    $obMenuCache = new CPHPCache;
    // если массив закэширован то
    if($obMenuCache->InitCache($CACHE_TIME, $CACHE_ID, "/"))
    {
        // берем данные из кэша
        $arVars = $obMenuCache->GetVars();
        $aMenuLinksNew = $arVars["aMenuLinksNew"];
    }
    else
    {
        // иначе собираем разделы
        $rsSections = GetIBlockSectionList($IBLOCK_ID, false, array("SORT" => "ASC", "ID" => "ASC"), false, array("ACTIVE"=>"Y"));
        while ($arSection = $rsSections->Fetch())
        {
            $arrAddLinks = array(SITE_DIR."catalog/phone/element.php?SECTION_ID=".$arSection["ID"]);
            // пройдемся по элементам раздела
            if ($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, false, false, array(), false, array("ACTIVE" => "Y", "IBLOCK_ID" => $IBLOCK_ID, "SECTION_ID" => $arSection["ID"]), array("ID", "IBLOCK_ID", "DETAIL_PAGE_URL")))
            {
                while ($arElement = $rsElements->GetNext()) $arrAddLinks[] = $arElement["DETAIL_PAGE_URL"];
            }
            $aMenuLinksNew[] = array(
                $arSection["NAME"],
                SITE_DIR."catalog/phone/section.php?SECTION_ID=".$arSection["ID"],
                $arrAddLinks);
        }
    }
    // сохраняем данные в кэше
    if($obMenuCache->StartDataCache())
    {
        $obMenuCache->EndDataCache(Array("aMenuLinksNew" => $aMenuLinksNew));
    }

    // объединяем основной массив меню с дополнительным
    $aMenuLinks = array_merge($aMenuLinksNew, $aMenuLinks);

endif;
?>

Шаблон меню /bitrix/templates/demo/left.menu_template.php:

<?
// This file is the template for one menu item iteration

// Set item mark: selected folder, folder, page
if ($ITEM_TYPE=="D")
{
    if ($SELECTED)
        $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_folder_open.gif' width='17' border='0'></td>";
    else
        $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_folder.gif' width='17' border='0'></td>";
}
else
{
    if ($SELECTED)
    {
        $strDir = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet.gif' width='17' border='0'></td>";
        $strDir_d = "<td width='0%' bgcolor='#A0C4E0' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet_d.gif' width='17' border='0' alt='Закрытый раздел'></td>";
    }
    else
    {
        $strDir = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet.gif' width='17' border='0'></td>";
        $strDir_d = "<td width='0%' bgcolor='#CCDFEE' valign='middle' align='center'><img height='13' src='/bitrix/templates/demo/images/left_bullet_d.gif' width='17' border='0' alt='Закрытый раздел'></td>";
    }
}

// if $SELECTED then this item is current (active) item
if ($SELECTED)
    $strtext = "leftmenuact";
else
    $strtext = "leftmenu";

//if $PARAMS["SEPARATOR"]=="Y" this item should be shown with different style applied

if ($PARAMS["SEPARATOR"]=="Y")
{
    $strstyle = " style='background-color: #D5ECE6; border-top: 1px solid #A6D0D7; border-bottom: 1px solid #A6D0D7; padding:8;'";
    $strDir = "<img height='13' src='/bitrix/templates/demo/images/1.gif' width='17' border='0'>";
    $strtext = "leftmenu";
}
else
    $strstyle = " style='padding:8;'";

// Content of variable $sMenuProlog is typed just before all menu items iterations
// Content of variable $sMenuEpilog is typed just after all menu items iterations
$sMenuProlog = "<table border='0' cellpadding='0' cellspacing='0' width='100%'>";
$sMenuEpilog = '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr></table>';

// if $PERMISSION > "D" then current user can access this page
if ($PERMISSION > "D")
{
    $sMenuBody = '<tr><td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr><tr>'.$strDir.'<td valign="top"'.$strstyle.' width="100%"><a href="'.$LINK.'" class="'.$strtext.'">'.$TEXT.'</a></td></tr>';
}
else
{
    $sMenuBody = '<td colspan=2 background="/bitrix/templates/demo/images/l_menu_border.gif"><img src="/bitrix/templates/demo/images/1.gif" width="1" height="1"></td></tr><tr>'.$strDir_d.'</td><td valign="top"'.$strstyle.' width="100%"><a href="'.$LINK.'" class='.$strtext.'>'.$TEXT.'</a></td></tr>';

}
?>


GetMenuHtmlEx

CMain::GetMenuHtmlEx

string
CMain::GetMenuHtmlEx(
 string type = "left",
 bool use_ext = false,
 mixed template_path = false,
 mixed init_dir = false
)

Возвращает HTML-код для отображения меню заданного типа. В отличие от функции CMain::GetMenuHtml шаблон меню будет подключаться только один раз.

В шаблоне меню, используемом данной функцией, в обязательном порядке необходимо инициализировать переменную $sMenu, в которой должен храниться HTML представляющий из себя все меню целиком.

Параметры функции

Параметр | Описание
type | Тип меню. Необязателен. По умолчанию "left".
use_ext | Если значение - "true", то для формирования массива меню, помимо файлов .тип меню.menu.php будут также подключаться файлы с именами вида .тип меню.menu_ext.php. В которых вы можете манипулировать массивом меню $aMenuLinks произвольно, по вашему усмотрению (например, дополнять пункты меню значениями из инфо-блоков). Необязателен. По умолчанию - "false".
template_path | Путь относительно корня к шаблону меню. Необязателен. По умолчанию - "false", что означает искать по алгоритму указанному на странице "Меню".
init_dir | Каталог для которого будет строится меню. Необязателен. По умолчанию - "false", что означает - текущий каталог.

См. также

  • Меню
  • Класс CMenu
  • CMenu::Init
  • CMain::GetMenu
  • CMain::GetMenuHtml

Пример выпадающего верхнего меню

Вывод меню в файле /bitrix/templates/demo/header.php:

<script language="JavaScript1.2" src="/bitrix/templates/demo/js/ddnmenu.js"></script>
<?echo $APPLICATION->GetMenuHtmlEx("top");?>

Файл /.top.menu.php:

<?
// основной файл меню
// данный файл может редактироваться в редакторе меню
$aMenuLinks = Array(
    Array(
        "Главная",
        "/index.php",
        Array(),
        Array(),
        ""
    ),
    Array(
        "Каталог",
        "/catalog/",
        Array(),
        Array(),
        ""
    ),
    Array(
        "Поддержка",
        "/support/",
        Array(),
        Array(),
        ""
    ),
    Array(
        "Партнёры",
        "/partners/",
        Array(),
        Array(),
        ""
    ),
    Array(
        "Компания",
        "/about/",
        Array(),
        Array(),
        ""
    )
);
?>

Файл /bitrix/templates/demo/top.menu_template.php:

<?
// шаблон меню
$sMenu = '<table width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td width="0%"><img src="/bitrix/templates/demo/images/top_menu_corner.gif" alt="" width="15" height="19"></td>';

for($i=0; $i<count($arMENU); $i++)
{
    $MENU_ITEM = $arMENU[$i];
    extract($MENU_ITEM);

    if($SELECTED)
        $clrtext = 'topmenuact';
    else
        $clrtext = 'topmenu';

    $sMenu .= '<td>';
    $sMenu .= '<table border="0" cellspacing="0" cellpadding="0"><tr>';
    $sMenu .= '<td bgcolor="#7B9DBB" onmouseover="show('.$i.')" onmouseout="hidden('.$i.')"><a href="'.$LINK.'" class="'.$clrtext.'"><nobr> '.$TEXT.' </nobr></a></td>';
    $sMenu .= '<td width="0%" bgcolor="#7B9DBB">';

    if($i<count($arMENU)-1) //add vertical divider after all items but not after the last one
        $sMenu .= '<img src="/bitrix/templates/demo/images/top_menu_divider.gif" width="15" height="19" alt="">';
    else
        $sMenu .= '<img src="/bitrix/templates/demo/images/1.gif" width="1" height="19" alt="">';

    $sMenu .= '</td></tr></table>';

    //check if menu of left type exists in the folder that the menu item points to
    $popup_menu = new CMenu("left");
    $popup_menu->Init($LINK);
    if(count($popup_menu->arMenu) > 0)
    {
        //if left menu exists then we display it in the hidden layer
        $popup_menu->template = "/bitrix/templates/demo/popup.menu_template.php";
        $sMenu .= '<div style="position:relative; width: 100%;">';
        $sMenu .= '<div onMouseOver="show('.$i.')" onMouseOut="hidden('.$i.')" id="menu'.$i.'" style="visibility: hidden; position: absolute; z-index: +1; top: 0px;" >';
        $sMenu .= $popup_menu->GetMenuHtmlEx();
        $sMenu .= '</div></div>';
    }
    $sMenu .= '</td>';
}
$sMenu .= '<td width="100%" bgcolor="#7B9DBB"><img src="/bitrix/templates/demo/images/1.gif" width="50" height="1" alt=""></td></tr></table>';
?>

Файл /bitrix/templates/demo/popup.menu_template.php:

<?
$sMenu =
    '<table border="0" cellspacing="0" cellpadding="0" width="110">'.
    '<tr><td bgcolor="#E6EFF7" valign="top"><table border="0" cellspacing="0" cellpadding="0" width="100%">';

for($i=0; $i<count($arMENU); $i++)
{
    $MENU_ITEM = $arMENU[$i];
    extract($MENU_ITEM);

    if ($PERMISSION > "D")
    {
        $sMenu .=
        '<tr valign="top"><td nowrap onmouseover="this.className=\'popupmenuact\'" onmouseout="this.className=\'popupmenu\'" onclick="window.location=\''.$LINK.'\'"  class="popupmenu" style="cursor: hand">'.
        '<nobr><a href="'.$LINK.'" style="text-decoration: none;"><font class="popupmenutext">'.$TEXT.'</font></a>'.
        '</nobr></td></tr>';
    }
    else
    {
        $sMenu .=
        '<tr valign="top"><td nowrap onmouseover="this.className=\'popupmenuact\'" onmouseout="this.className=\'popupmenu\'" onclick="window.location=\''.$LINK.'\'"  class="popupmenu" style="cursor: hand">'.
        '<nobr><font class="popupmenuclosed">'.$TEXT.'</font>'.
        '</nobr></td></tr>';
    }
}
$sMenu .= '</table></td></tr></table>';
?>

Файл /bitrix/templates/demo/js/ddnmenu.js:

var brname=navigator.appName, BrVer='';
if(brname.substring(0,2)=="Mi")
    BrVer='E';
var timer = 0;
lastid = -1;

function show(id)
{
    if(!((document.all)?document.all['menu'+id]:document.getElementById('menu'+id)))
        return;
    clearTimeout(timer);
    if((id != lastid) && (lastid!=-1))
        ((document.all)?document.all['menu'+lastid]:document.getElementById('menu'+lastid)).style.visibility = 'hidden';
    hideElement("SELECT", document.getElementById('menu'+lastid));
    lastid = id;
    ((document.all)?document.all['menu'+lastid]:document.getElementById('menu'+lastid)).style.visibility = 'visible';
}

function hidden(id)
{
    if(!((document.all)?document.all['menu'+id]:document.getElementById('menu'+id)))
        return;
    showElement("SELECT");
    timer = setTimeout("if('"+id+"' == '"+lastid+"'){((document.all)?document.all['menu"+lastid+"']:document.getElementById('menu"+lastid+"')).style.visibility = 'hidden';}", 500)
}

function GetPos(el)
{
    if (!el || !el.offsetParent)return false;
    var res=Array()
    res["left"] = el.offsetLeft;
    res["top"] = el.offsetTop;
    var objParent = el.offsetParent;
    while (objParent.tagName.toUpperCase()!="BODY")
    {
        res["left"] += objParent.offsetLeft;
        res["top"] += objParent.offsetTop;
        objParent = objParent.offsetParent;
    }
    res["right"]=res["left"]+el.offsetWidth;
    res["bottom"]=res["top"]+el.offsetHeight;
    return res;
}

function hideElement(elName, Menu)
{
    if(BrVer!='E') return;
    for (i = 0; i < document.all.tags(elName).length; i++)
    {
        Obj = document.all.tags(elName)[i];
        if(!(pMenu=GetPos(Menu)))continue;
        if(!(pObj=GetPos(Obj)))continue;

        if(pObj["left"]<pMenu["right"] && pMenu["left"]<pObj["right"] && pObj["top"]<pMenu["bottom"] && pMenu["top"]<pObj["bottom"])
            Obj.style.visibility = "hidden";
    }
}

function showElement(elName)
{
    if(BrVer!='E') return;
    for (i = 0; i < document.all.tags(elName).length; i++)
    {
        obj = document.all.tags(elName)[i];
        if (!obj || !obj.offsetParent)continue;
        if(obj.style.visibility=="hidden")
            obj.style.visibility = "visible";
    }
}


GetMeta

CMain::GetMeta

string
CMain::GetMeta(
 string property_id,
 string meta_name = false
)

Возвращает свойство страницы обрамленное тегом <meta>. Если на самой страницы свойство не задано, то будет взято значение свойства вышестоящего раздела (рекурсивно до корня сайта). Если свойство не задано, то метод вернет пустую строку.

Параметры

Параметр | Описание
property_id | Идентификатор свойства страницы или раздела, значение которого (value) будет выведено в аттрибуте "content" мета-тега: <meta content="value" ...>
meta_name | Аттрибут "name" мета-тега: <meta name="meta_name" ...> Необязательный. По умолчанию равен идентификатору свойства property_id.

См. также

  • Свойства страниц и мета-теги
  • CMain::ShowMeta
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Пример использования

<?
$meta_keywords = $APPLICATION->GetMeta("keywords_prop", "keywords");
if (strlen($meta_keywords)>0) echo $meta_keywords;
?>


GetNavChain

CMain::GetNavChain

string
CMain::GetNavChain(
 mixed path = false,
 int start_from = 0,
 mixed template_path = false
)

Возвращает HTML представляющий из себя навигационную цепочку.

Если вам не нужно показывать навигационную цепочку на какой либо странице, вам достаточно вставить в теле страницы код, инициализирующий свойство страницы "NOT_SHOW_NAV_CHAIN" значением "Y":

$APPLICATION->SetPageProperty("NOT_SHOW_NAV_CHAIN", "Y");
Поддержка этого свойства встроена в данную функцию.

Параметры функции

Параметр Описание
path Путь для которого будет построена навигационная цепочка. В случае многосайтовой версии, если DOCUMENT_ROOT у сайтов разный (задается в поле "Путь к корневой папке веб-сервера" в настройках сайта), то в данном параметре необходимо передавать массив вида:
array("ID сайта", "путь")
Необязателен. По умолчанию - "false" - текущий путь.
start_from Начиная от какого пункта будет построена навигационная цепочка
Необязателен. По умолчанию - "0".
template_path Путь к шаблону навигационной цепочки.
Необязателен. По умолчанию - "false", что предполагает поиск пути к шаблону навигационной цепочки по алгоритму представленному на странице "Навигационная цепочка"

См. также

  • Навигационная цепочка
  • CMain::ShowNavChain
  • CMain::AddChainItem


GetPageProperty

CMain::GetPageProperty

string
CMain::GetPageProperty(
 string property_id,
 mixed default_value = false
)

Возвращает свойство текущей страницы.

Параметры

Параметр | Описание
property_id | Идентификатор свойства.
default_value | Значение свойства по умолчанию. Необязательный. По умолчанию - "false" - значение свойства по умолчанию не задано.

См. также

  • Свойства страниц и мета-теги
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetDirProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirPropertyList
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Пример использования

<?
$APPLICATION->GetPageProperty("keywords");
?>


GetPagePropertyList

CMain::GetPagePropertyList

array
CMain::GetPagePropertyList()

Возвращает массив всех свойств страницы.

Параметры функции

Без параметров.

См. также

  • Свойства страниц и мета-тэги
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetDirProperty
  • CMain::GetDirPropertyList
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Пример использования

<?
$props = $APPLICATION->GetPagePropertyList();
foreach($props as $key=>$val)
    echo '<meta name="'.$key.'" content="'.htmlspecialchars($val).'">';
?>


GetPanel

CMain::GetPanel

string CMain::GetPanel()

Возвращает HTML представляющий из себя панель управления публичной частью.

Параметры функции

Без параметров.

См. также

  • CMain::ShowPanel
  • CMain::AddPanelButton


GetProperty

CMain::GetProperty

string
CMain::GetProperty(
 string property_id,
 mixed default_value = false
)

Возвращает свойство текущей страницы или раздела. Если на самой странице свойство не задано, то будет возвращено значение свойства вышестоящего раздела (рекурсивно до корня сайта).

Параметры

Параметр | Описание
property_id | Идентификатор свойства.
default_value | Значение свойства по умолчанию. Необязательный. По умолчанию - "false" - значение свойства по умолчанию не задано.

См. также

  • Свойства страниц и мета-теги
  • CMain::ShowProperty
  • CMain::GetPageProperty
  • CMain::GetDirProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirPropertyList
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Пример использования

<?
$keywords = $APPLICATION->GetProperty("keywords");
if (strlen($keywords)>0) echo $keywords;
?>


GetShowIncludeAreas

CMain::GetShowIncludeAreas

bool
CMain::GetShowIncludeAreas()

Возвращает "true", если кнопка "Показать включаемые области" на панели управления нажата, в противном случае - "false".

Параметры функции

Без параметров.

См. также

  • CMain::IncludeString

Примеры использования

<?
$text = "Произвольный HTML";

// если кнопка "Показать включаемые области" нажата, то
if ($APPLICATION->GetShowIncludeAreas())
{
    $arIcons = Array();
    $arIcons[] =
            Array(
                "URL" => "/bitrix/admin/my_script1.php",
                "SRC" => "/images/my_icon1.gif",
                "ALT" => "Текст всплывающей подсказки"
            );
    $arIcons[] =
            Array(
                "URL" => "/bitrix/admin/my_script2.php",
                "SRC" => "/images/my_icon2.gif",
                "ALT" => "Текст всплывающей подсказки"
            );

    // выведется надпись "Произвольный HTML" обрамленная рамкой,
    // в правом верхнем углу которой будут две иконки my_icon1.gif и my_icon2.gif
    // с заданными на них ссылками на скрипты my_script1.php и my_script2.php

    echo $APPLICATION->IncludeString($text, $arIcons);
}
else
{
    // иначе просто выводим надпись "Произвольный HTML"
    echo $text;
}
?>
<?
// файл /bitrix/modules/advertising/classes/general/advertising.php
// класс CAdvBanner

// возвращает HTML произвольного баннера по типу
function Show($TYPE_SID, $HTML_BEFORE="", $HTML_AFTER="")
{
    global $APPLICATION, $USER;
    $arBanner = CAdvBanner::GetRandom($TYPE_SID);
    $strReturn = CAdvBanner::GetHTML($arBanner);
    if (strlen($strReturn)>0)
    {
        CAdvBanner::FixShow($arBanner);
        if ($APPLICATION->GetShowIncludeAreas())
        {
            $isDemo = CAdvContract::IsDemo();
            $arrPERM = CAdvContract::GetUserPermissions($arBanner["CONTRACT_ID"]);
            if (($isDemo || (is_array($arrPERM) && count($arrPERM)>0)) && $USER->IsAuthorized())
            {
                $arIcons = Array();
                $arIcons[] =
                        Array(
                            "URL" => "/bitrix/admin/adv_banner_edit.php?lang=".LANGUAGE_ID."&ID=".$arBanner["ID"]. "&CONTRACT_ID=".$arBanner["CONTRACT_ID"],
                            "SRC" => "/bitrix/images/advertising/panel/edit_ad.gif",
                            "ALT" => GetMessage("AD_PUBLIC_ICON_EDIT_BANNER")
                        );
                $arIcons[] =
                        Array(
                            "URL" => "/bitrix/admin/adv_banner_list.php?lang=".LANGUAGE_ID."&find_id=".$arBanner["ID"]. "&find_id_exact_match=Y&find_contract_id[]=".$arBanner["CONTRACT_ID"]. "&find_type_sid[]=".$arBanner["TYPE_SID"]."&set_filter=Y",
                            "SRC" => "/bitrix/images/advertising/panel/edit_ad_list.gif",
                            "ALT" => GetMessage("AD_PUBLIC_ICON_BANNER_LIST")
                        );
                $strReturn = $APPLICATION->IncludeString($strReturn, $arIcons);
            }
        }
        $strReturn = $HTML_BEFORE.$strReturn.$HTML_AFTER;
        return $strReturn;
    }
    else return false;
}
?>


GetSiteByDir

CMain::GetSiteByDir

array
CMain::GetSiteByDir(
 mixed path = false,
 mixed host = false
)

Возвращает массив описывающий сайт, определяемый по указанному пути и домену. Описание ключей данного массива вы можете найти на странице Поля CSite. Алгоритм работы функции следующий:

  1. Ищем сайты для которых удовлетворяют path и host, если нашли, то возвращаем, иначе
  2. Ищем сайты для которых удовлетворяет path, если нашли, то возвращаем, иначе
  3. Ищем сайты для которых удовлетворяет host, если нашли, то возвращаем, иначе
  4. Возвращаем сайт с установленным флагом "Сайт по умолчанию"

Параметры функции

Параметр | Описание
path | Путь относительно корня. Необязательный. По умолчанию - путь к текущей странице.
host | Имя домена. Необязательный. По умолчанию - текущий домен.

См. также

  • Поля CSite
  • Сайты

Примеры использования

<?
// получим ссылающийся URL, либо последний URL в текущей сессии
if (strlen($_SERVER["HTTP_REFERER"]) <= 0)
    $referer_url = $_SESSION["SESS_HTTP_REFERER"];
else
    $referer_url = $_SERVER["HTTP_REFERER"];

// пропарсим URL чтобы отдельно получить домен и адрес страницы
$arUrl = parse_url($referer_url);

// получим массив описывающий сайт
$arSite = $APPLICATION->GetSiteByDir($arUrl["path"], $arUrl["host"]);
?>


GetTemplatePath

CMain::GetTemplatePath

string
CMain::GetTemplatePath(
 string component_path
)

Возвращает путь от корня сайта к файлу по пути задаваемому для компонента.

Параметры функции

Параметр Описание
component_path Путь к компоненту.

Алгоритм поиска пути от корня сайта следующий:
  1. Сначала файл будет искаться в каталоге
    /bitrix/templates/ID текущего шаблона сайта/component_path
  2. Если файл не найден, он будет искаться в каталоге
    /bitrix/templates/.default/component_path
  3. Затем если файл не найден, он будет искаться в каталоге
    /bitrix/modules/ID модуля/install/templates/component_path
    здесь ID модуля - это первый подкаталог в component_path

См. также

  • Компоненты
  • CMain::IncludeFile

Примеры использования

<?
// получим реальный путь к компоненту
$path = $APPLICATION->GetTemplatePath("iblock/catalog/element.php");
// в переменной $path может быть например, значение
// "/bitrix/templates/.default/iblock/catalog/element.php"
?>


GetTitle

CMain::GetTitle

string
CMain::GetTitle(
 mixed property_name = false,
 bool strip_tags = false
)

Возвращает заголовок страницы.

Параметры функции

Параметр | Описание
property_name | Если указано значение "false", то будет возвращен заголовок страницы, устанавливаемый с помощью функции SetTitle. В противном случае в параметре передается идентификатор свойства страницы, значение которого будет выведено в качестве заголовка (если это значение задано, например, с помощью функции CMain::SetPageProperty). Необязательный. По умолчанию "false".
strip_tags | Если значение - "true", то из заголовка страницы будут удалены все HTML теги. Необязательный. По умолчанию - "false".

См. также

  • CMain::ShowTitle
  • CMain::SetTitle


GetUserRight

CMain::GetUserRight

string
CMain::GetUserRight(
 string module_id,
 mixed groups = false,
 string use_default = "Y",
 string max_for_admin = "Y"
)

Возвращает право в рамках логики модуля установленное для определённого набора групп (по умолчанию - это группы текущего пользователя).

Как правило в каждом модуле определены свои символы означающие то или иной право, в противном случае используются значения по умолчанию:

  • D - доступ к модулю запрещён
  • R - право на просмотр страниц модуля (без права модификации)
  • W - право на модификацию данных модуля
Установка своего уникального набора прав для каждого модуля осуществляется методом GetModuleRightList класса с именем равным ID модуля. Например для модуля веб-форм, это будет метод form::GetModuleRightList() описаный в файле /bitrix/modules/form/install/index.php. Администрирование прав обычно осуществляется в настройках соответствующего модуля.

Для некоторых модулей (например, "информационные блоки") права устанавливаются индивидуально и к ним данная функция не применима, некоторые модули (например, "компрессия") вовсе не имеют прав доступа.

Для любого модуля максимальное право (полный доступ к модулю) всегда обозначается символом "W", минимальное право - символом "D" (доступ к модулю закрыт).

Параметры функции

Параметр | Описание
module_id | ID модуля.
groups | Массив групп для которых необходимо определить максимальное право. Если значение - "false", то будет взят массив групп текущего пользователя. Необязательный. По умолчанию - "false".
use_default | Если значение - "Y", то для определения максимального уровня прав будет учитываться уровень прав установленный по умолчанию. Необязательный. По умолчанию - "Y".
max_for_admin | Если значение - "Y" и groups = false, то пользователю входящему в группу администраторов (группа #1) всегда будет возвращаться максимальное право - "W", независимо от того какие права установлены в настройках модуля. Необязательный. По умолчанию - "Y".

См. также

  • Права доступа
  • CMain::GetUserRoles
  • CModule::GetModuleRightList

Примеры использования

<?
// получим максимальное право доступа к модулю "Веб-формы" для текущего пользователя
if($APPLICATION->GetUserRight("form") <= "D")
    $APPLICATION->AuthForm("Доступ к модулю запрещён.");
?>


GetUserRoles

CMain::GetUserRoles

string
CMain::GetUserRoles(
 string module_id,
 mixed groups = false,
 string use_default = "Y",
 string max_for_admin = "Y"
)

Возвращает массив ролей в рамках логики модуля для определённого набора групп (по умолчанию - это группы текущего пользователя).

Как правило в каждом модуле определены свои символы означающие ту или иную роль. Установка своего уникального набора ролей для каждого модуля осуществляется методом GetModuleRightList класса с именем равным ID модуля. Например, для модуля техподдержки, это будет метод support::GetModuleRightList(), описанный в файле /bitrix/modules/support/install/index.php. Администрирование ролей обычно осуществляется в настройках соответствующего модуля.

Для любого модуля роль с максимальными правами (администратор модуля) всегда обозначается символом "W", с минимальным правами - символом "D" (доступ к модулю закрыт).

Параметры функции

Параметр | Описание
module_id | ID модуля.
groups | Массив групп для которых необходимо определить их роли. Если значение - "false", то будет взят массив групп текущего пользователя. Необязательный. По умолчанию - "false".
use_default | Если значение - "Y", то для определения массива ролей будет учитываться роль установленная по умолчанию. Необязательный. По умолчанию - "Y".
max_for_admin | Если значение - "Y" и groups = false, то пользователю входящему в группу администраторов (группа #1) всегда будет возвращаться массив ролей с обязательно включенной туда ролью с максимальными правами - "W". Необязательный. По умолчанию - "Y".

См. также

  • Права доступа
  • CMain::GetUserRight
  • CModule::GetModuleRightList

Примеры использования

<?
// получим массив ролей текущего пользователя в модуле "Техподдержка"
$arRoles = $APPLICATION->GetUserRoles("support");

if(in_array("R",$arRoles))
    $strNote = "У вас есть право задавать вопросы техподдержке.";

if(in_array("T",$arRoles))
    $strNote = "Вы являетесь сотрудником техподдержки.";

if(in_array("V",$arRoles))
    $strNote = "Вы можете просматривать все обращения техподдержки без права модификации.";

if(in_array("W",$arRoles))
    $strNote = "Вы являетесь администратором техподдержки.";

if ($arRoles==array("D"))
    $APPLICATION->AuthForm("Доступ к модулю техподдержки запрещён.");

ShowNote($strNote);
?>


IncludeAdminFile

CMain::IncludeAdminFile

CMain::IncludeAdminFile(
 string title,
 string abs_path
)

Подключает скрипт с административным прологом и эпилогом.

Параметры функции

Параметр | Описание
title | Заголовок страницы.
abs_path | Абсолютный путь к подключаемому файлу.

См. также

  • Описание модуля

Пример использования

<?
function DoInstall()
{
    global $DB, $APPLICATION, $step;
    $FORM_RIGHT = $APPLICATION->GetGroupRight("form");
    if ($FORM_RIGHT=="W")
    {
        $step = IntVal($step);
        if($step<2)
            $APPLICATION->IncludeAdminFile(GetMessage("FORM_INSTALL_TITLE"),
            $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/install/step1.php");
        elseif($step==2)
            $APPLICATION->IncludeAdminFile(GetMessage("FORM_INSTALL_TITLE"),
            $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/form/install/step2.php");
    }
}
?>


IncludeComponent

CMain::IncludeComponent

mixed
IncludeComponent(
 string componentName ,
 string componentTemplate [,
 array arParams [,
 object parentComponent]]
);

Метод подключает компонент 2.0

Параметры функции

Параметр | Описание
componentName | Имя компонента. Например: "bitrix:news.detail".
componentTemplate | Имя шаблона компонента. Если имя пустое, то подразумевается имя ".default".
arParams | Массив входных параметров компонента.
parentComponent | Объект родительского комплексного компонента, если компонент подключается из шаблона комплексного компонента. В шаблоне комплексного компонента определена переменная $component, которая содержит объект этого комплексного компонента.

Возвращаемое значение

Возвращает код компонента.

Пример

// Подключим компонент каталога с шаблоном "по-умолчанию" на публичной странице сайта
$APPLICATION->IncludeComponent(
    "bitrix:catalog",
    "",
    Array(
        "SEF_MODE" => "N",
        "IBLOCK_TYPE_ID" => "catalog",
        "ACTION_VARIABLE" => "action",
        "CACHE_TIME" => 1*24*60*60,
        "BASKET_PAGE_TEMPLATE" => "/personal/basket.php",
    )
);

// Подключим компонент карточки фотографии с шаблоном "по-умолчанию" в шаблоне
// комплексного компонента "фотогалерея"
$APPLICATION->IncludeComponent(
    "bitrix:photo.detail",
    "",
    Array(
         "IBLOCK_TYPE" => $arParams["IBLOCK_TYPE"],
         "IBLOCK_ID" => $arParams["IBLOCK_ID"],
         "ELEMENT_ID" => $arResult["VARIABLES"]["ELEMENT_ID"],
         "ELEMENT_CODE" => $arResult["VARIABLES"]["ELEMENT_CODE"],
    ),
    $component
);


IncludeFile

CMain::IncludeFile

CMain::IncludeFile(
 string path,
 array params = array(),
 array function_params = array()
)

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

Параметры функции

Параметр Описание
path Путь к подключаемому файлу.

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

Если же в данном параметре задан путь к основному файлу компонента, то он будет найден и подключен по следующему алгоритму:
  1. Сначала файл будет искаться в каталоге
    /bitrix/templates/ID текущего шаблона сайта/path
  2. Если файл не найден, он будет искаться в каталоге
    /bitrix/templates/.default/path
  3. Затем если файл не найден, он будет искаться дистрибутиве модуля, т.е. в следующем каталоге:
    /bitrix/modules/ID модуля/install/templates/path,
    здесь ID модуля - это первый подкаталог в path
params Массив параметров для подключаемого файла. Структура данного массива:
array(
 "ИМЯ_ПАРАМЕТРА_1" => "ЗНАЧЕНИЕ_ПАРАМЕТРА_1",
 "ИМЯ_ПАРАМЕТРА_2" => "ЗНАЧЕНИЕ_ПАРАМЕТРА_2",
 ...)
В подключаемом файле будут инициализированы переменные, имена которых - ключи данного массива, а значения - соответствующие значения данного массива. Данная операция выполняется стандартной PHP функцией extract(params).
function_params Массив настроек данной функции, с ключами:
  • SHOW_BORDER - показывать ли рамку и иконки для редактирования, допустимы следующие значения:
    • true - показать рамку при нажатии на панели кнопки "Показать включаемые области" (значение по умолчанию)
    • false - не показывать рамки
  • NAME - текст всплывающей подсказки на иконке редактирования
  • LANG - двухсимвольный идентификатор языка в котором будет открыт административный раздел в момент редактирования файла (по умолчанию - язык текущего сайта)
  • BACK_URL - куда вернуться после редактирования (по умолчанию - текущая публичная страница)
  • WORKFLOW - участвует ли подключаемый файл в документооборте, возможны следующие значения:
    • true - ссылка ведущая на редактирование будет указывать на страницу модуля документооборота
    • false - ссылка ведущая на редактирование будет указывать на страницу модуля управления статикой (значение по умолчанию)
  • MODE - режим редактирования, допустимы следующие значения:
    • text - файл будет редактироваться как текст (ссылка на страницу редактирования файла в режиме текста)
    • html - файл будет редактироваться как HTML (ссылка на веб-редактор)
    • php - файл будет редактироваться как PHP (ссылка на страницу редактирования исходников файла) (значение по умолчанию)
  • TEMPLATE - если в параметре path указан абсолютный путь к несуществующему файлу, то здесь необходимо указать имя файла-шаблона для создания нового файла (по умолчанию - первый шаблон в порядке сортировки задаваемой в файле: /bitrix/templates/ID текущего шаблона сайта/page_templates/.content.php)

См. также

  • Компоненты
  • IncludeTemplateLangFile
  • CMain::IncludeString

Пример подключения компонента на странице

<?
// компонент выводящий детально элемент инфо-блока
$APPLICATION->IncludeFile("iblock/catalog/element.php", Array(
    "IBLOCK_TYPE"       => "catalog",                          // Тип инфо-блока
    "IBLOCK_ID"         => "21",                               // Инфо-блок
    "ELEMENT_ID"        => $_REQUEST["ID"],                    // ID элемента
    "SECTION_URL"       => "/catalog/phone/section.php?",      // URL ведущий на страницу с содержимым раздела
    "LINK_IBLOCK_TYPE"  => "catalog",                          // Тип инфо-блока, элементы которого связаны с текущим элементом
    "LINK_IBLOCK_ID"    => "22",                               // ID инфо-блока, элементы которого связаны с текущим элементом
    "LINK_PROPERTY_SID" => "PHONE_ID",                         // Свойство в котором хранится связь
    "LINK_ELEMENTS_URL" => "/catalog/accessory/byphone.php?",  // URL на страницу где будут показан список связанных элементов
    "arrFIELD_CODE" => Array(                                  // Поля
         "DETAIL_TEXT",
         "DETAIL_PICTURE"),
    "arrPROPERTY_CODE" => Array(                               // Свойства
         "YEAR",
         "STANDBY_TIME",
         "TALKTIME",
         "WEIGHT",
         "STANDART",
         "SIZE",
         "BATTERY",
         "SCREEN",
         "WAP",
         "VIBRO",
         "VOICE",
         "PC",
         "MORE_PHOTO",
         "MANUAL"),
    "CACHE_TIME"        => "3600",                              // Время кэширования (сек.)
    ));
?>

Пример подключения произвольного файла в эпилоге сайта

<?
// включаемая область для раздела
$APPLICATION->IncludeFile($APPLICATION->GetCurDir()."sect_inc.php", Array(), Array(
    "MODE"      => "html",                                           // будет редактировать в веб-редакторе
    "NAME"      => "Редактирование включаемой области раздела",      // текст всплывающей подсказки на иконке
    "TEMPLATE"  => "section_include_template.php"                    // имя шаблона для нового файла
    ));
?>


IncludeString

CMain::IncludeString

string
CMain::IncludeString(
 string text,
 array icons = array()
)

Выводит произвольную строку (HTML код) обрамленную рамкой, в правом верхнем углу которой выводятся заданные иконки.

Параметры функции

Параметр | Описание
text | Произвольный текст (HTML код).
icons Массив иконок, каждый элемент которого представляет из себя массив описывающий одну иконку, его ключами являются:
  • URL - ссылка на иконке
  • SRC - путь к изображению иконки
  • ALT - текст всплывающей подсказки на иконке

См. также

  • CMain::GetShowIncludeAreas

Примеры использования

<?
$text = "Произвольный HTML";

// если кнопка "Показать включаемые области" нажата, то
if ($APPLICATION->GetShowIncludeAreas())
{
    $arIcons = Array();
    $arIcons[] =
            Array(
                "URL" => "/bitrix/admin/my_script1.php",
                "SRC" => "/images/my_icon1.gif",
                "ALT" => "Текст всплывающей подсказки"
            );
    $arIcons[] =
            Array(
                "URL" => "/bitrix/admin/my_script2.php",
                "SRC" => "/images/my_icon2.gif",
                "ALT" => "Текст всплывающей подсказки"
            );

    // выведется надпись "Произвольный HTML" обрамленная рамкой,
    // в правом верхнем углу которой будут две иконки my_icon1.gif и my_icon2.gif
    // с заданными на них ссылками на скрипты my_script1.php и my_script2.php

    echo $APPLICATION->IncludeString($text, $arIcons);
}
else
{
    // иначе просто выводим надпись "Произвольный HTML"
    echo $text;
}
?>
<?
// файл /bitrix/modules/advertising/classes/general/advertising.php
// класс CAdvBanner

// возвращает HTML произвольного баннера по типу
function Show($TYPE_SID, $HTML_BEFORE="", $HTML_AFTER="")
{
    global $APPLICATION, $USER;
    $arBanner = CAdvBanner::GetRandom($TYPE_SID);
    $strReturn = CAdvBanner::GetHTML($arBanner);
    if (strlen($strReturn)>0)
    {
        CAdvBanner::FixShow($arBanner);
        if ($APPLICATION->GetShowIncludeAreas())
        {
            $isDemo = CAdvContract::IsDemo();
            $arrPERM = CAdvContract::GetUserPermissions($arBanner["CONTRACT_ID"]);
            if (($isDemo || (is_array($arrPERM) && count($arrPERM)>0)) && $USER->IsAuthorized())
            {
                $arIcons = Array();
                $arIcons[] =
                        Array(
                            "URL" => "/bitrix/admin/adv_banner_edit.php?lang=".LANGUAGE_ID."&ID=".$arBanner["ID"]. "&CONTRACT_ID=".$arBanner["CONTRACT_ID"],
                            "SRC" => "/bitrix/images/advertising/panel/edit_ad.gif",
                            "ALT" => GetMessage("AD_PUBLIC_ICON_EDIT_BANNER")
                        );
                $arIcons[] =
                        Array(
                            "URL" => "/bitrix/admin/adv_banner_list.php?lang=".LANGUAGE_ID."&find_id=".$arBanner["ID"]. "&find_id_exact_match=Y&find_contract_id[]=".$arBanner["CONTRACT_ID"]. "&find_type_sid[]=".$arBanner["TYPE_SID"]."&set_filter=Y",
                            "SRC" => "/bitrix/images/advertising/panel/edit_ad_list.gif",
                            "ALT" => GetMessage("AD_PUBLIC_ICON_BANNER_LIST")
                        );
                $strReturn = $APPLICATION->IncludeString($strReturn, $arIcons);
            }
        }
        $strReturn = $HTML_BEFORE.$strReturn.$HTML_AFTER;
        return $strReturn;
    }
    else return false;
}
?>


IsHTTPS

CMain::IsHTTPS

bool
CMain::IsHTTPS()

Определяет является ли текущий протокол защищенным (HTTPS).

Параметры

Без параметров.

Пример использования

<?
global $APPLICATION;
// получим полный URI текущий страницы
$CURRENT_PAGE = (CMain::IsHTTPS()) ? "https://" : "http://";
$CURRENT_PAGE .= $_SERVER["HTTP_HOST"];
$CURRENT_PAGE .= $APPLICATION->GetCurUri();
// в переменной $CURRENT_PAGE значение будет например,
// "http://www.mysite.ru/ru/index.php?id=23"
?>


RemoveFileAccessPermission

CMain::RemoveFileAccessPermission

bool
CMain::RemoveFileAccessPermission(
 string path,
 mixed groups = false
)

Удаляет права доступа для файла или каталога. Возвращает "true" - если удаление произведено успешно и "false" - в случае ошибки.

Параметры функции

Параметр Описание
path Путь к файлу или папке относительно корня. В случае многосайтовой версии, если корневой каталог у сайтов разный, то в данном параметре необходимо передавать массив вида:
array("ID сайта", "Путь к файлу или папке относительно корня")
groups Массив групп для которых удалить права доступа. Если значение - "false", то права доступа будут удалены для всех групп.
Необязательный. По умолчанию - "false".

См. также

  • Права доступа
  • CMain::GetFileAccessPermission
  • CMain::CopyFileAccessPermission
  • CMain::SetFileAccessPermission

Примеры использования

<?
// удалим права на файл /ru/index.php для групп пользователей #5 и #23
if ($APPLICATION->RemoveFileAccessPermission("/ru/index.php", array(5, 23)))
    ShowNote("Права успешно модифицированы.");
?>


ResetException

CMain::ResetException

CMain::ResetException()

Метод очищает последнее исключение.

См. также

  • Класс CApplicationException
  • CMain::ThrowException
  • CMain::GetException

Примеры использования

<?
$events = GetModuleEvents("main", "OnAfterUserLogin");
while($arEvent = $events->Fetch())
{
   $APPLICATION->ResetException();
   ExecuteModuleEvent($arEvent, $login, $password, $remember, $USER_ID);
   if($err = $APPLICATION->GetException())
      $RESULT_MESSAGE = Array("MESSAGE"=>$err->GetString()."<br>", "TYPE"=>"ERROR");
}
?>


SaveFileContent

CMain::SaveFileContent

bool
CMain::SaveFileContent(
 string abs_path,
 string content
)

Сохраняет страницу на диске. Возвращает "true" - если сохранение произведено успешно и "false" - в случае ошибки. Данная функция инициализирует событие "OnChangeFile".

Параметры функции

Параметр | Описание
abs_path | Полный путь к файлу на диске.
content | Содержимое файла.

См. также

  • CMain::GetFileContent
  • Событие "OnChangeFile"
  • RewriteFile

Примеры использования

<?
$file_content = '
    <?
    require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
    $APPLICATION->SetTitle("Title");
    ?>
    Содержимое страницы...
    <?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>
    ';

$abs_path = $_SERVER["DOCUMENT_ROOT"]."/ru/index.php";
if(!$APPLICATION->SaveFileContent($abs_path, $file_content))
    ShowError("Ошибка при сохранениии файла");
?>


set_cookie

CMain::set_cookie

CMain::set_cookie(
 string name,
 string value,
 mixed expire = false,
 string path = "/",
 mixed domain = false,
 bool secure = false,
 bool spread = true,
 mixed name_prefix = false
)

Устанавливает cookie и при необходимости запоминает параметры установленного cookie для дальнейшего распространения по сайтам с разными доменными именами.

Параметры функции

Параметр | Описание
name | Имя cookie переменной.
value | Значение cookie переменной.
expire Дата в Unix-формате после которой cookie будет считаться истекшим и его значение не будет передаваться от посетителя на сайт.
Необязательный. По умолчанию - cookie устанавливается сроком на 1 год.
path Каталог веб-сайта для которого cookie будет действителен.
Необязательный. По умолчанию - весь сайт.
domain Домен для которого cookie будет действительным.
Необязательный. По умолчанию - текущий сайт.
secure Флаг secure для устанавливаемого cookie. Если значение "true", то будет установлен как "защищенный", т.е. его значение будет возвращаться на сайт только если посетитель зашел на сайт по протоколу HTTPS.
Необязательный. По умолчанию - "false".
spread | Если значение "true", то параметры установленного cookie будут запоминаться для дальнейшего его распространения по доменам (административное меню "Сайты", в настройках сайта - поле "Доменное имя").
name_prefix Префикс имени переменной cookie.
Необязательный. По умолчанию - значение параметра "Имя префикса для названия cookies" в настройках главного модуля (значение данного параметра можно получить с помощью функции:
COption::GetOptionString("main", "cookie_name", "BITRIX_SM")

См. также

  • Перенос посетителей
  • CMain::get_cookie
  • CMain::ShowSpreadCookieHTML

Примеры использования

<?
global $APPLICATION;
// устновим cookie на 2 года, действительного только для каталога /ru/
$APPLICATION->set_cookie("RUSSIAN_VISITOR_ID", 156, time()+60*60*24*30*12*2, "/ru/");
?>


SetAdditionalCSS

CMain::SetAdditionalCSS

CMain::SetAdditionalCSS(
 string path
)

Устанавливает CSS стиль для страницы.

Параметры функции

Параметр | Описание
path | Путь относительно корня к файлу с CSS стилями.

См. также

  • CMain::ShowCSS
  • CMain::GetCSS
  • CMain::SetTemplateCSS

Примеры использования

<?
$APPLICATION->SetAdditionalCSS("/bitrix/templates/demo/additional.css");
?>


SetCurPage

CMain::SetCurPage

CMain::SetCurPage(
  string page,
  mixed params = false
)

Устанавливает в объекте класса CMain текущую страницу и ее параметры.

Параметры функции

Параметр | Описание
page | Адрес страницы. Например, "/ru/index.php".
params | Строка параметров. Например, "id=2&s=3&t=4". Параметр необызательный. Если его не задавать, то параметры страницы в объекте класса CMain остаются без изменений.

См. также

  • CMain::GetCurUri
  • CMain::GetCurPage
  • CMain::GetCurPageParam
  • CMain::GetCurDir

Примеры использования

<?
$APPLICATION->SetCurPage("/ru/index.php", "id=2&s=3");
?>


SetDirProperty

CMain::SetDirProperty

CMain::SetDirProperty(
 string property_id,
 string property_value
)

Устанавливает свойство для текущего раздела.

Параметры функции

Параметр | Описание
property_id | Идентификатор свойства.
property_value | Значение свойства.

См. также

  • Свойства страниц и мета-теги
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetDirProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirPropertyList
  • CMain::SetPageProperty

Примеры использования

<?
$APPLICATION->SetDirProperty("keywords", "дизайн, веб, сайт");
?>


SetFileAccessPermission

CMain::SetFileAccessPermission

bool
CMain::SetFileAccessPermission(
 string path,
 array permissions,
 bool overwrite = true
)

Устанавливает права доступа к файлу или каталогу. Возвращает "true" - если установка прав произведена успешно и "false" - в случае ошибки.

Параметры функции

Параметр Описание
path Путь к файлу или папке относительно корня. В случае многосайтовой версии, если корневой каталог у сайтов разный, то в данном параметре необходимо передавать массив вида:
array("ID сайта", "Путь к файлу или папке относительно корня")
permissions Массив с правами доступа вида Array("ID группы пользователей"=>"право доступа" [, ...]). В качестве "право доступа" возможны следующие значения:
  • D - доступ запрещён
  • R - чтение (право просмотра содержимого файла)
  • U - документооборот (право на редактирование файла в режиме документооборота)
  • W - запись (право на прямое редактирование)
  • X - полный доступ (право на прямое редактирование файла и право на изменение прав доступа на данных файл)
В качестве "ID группы пользователей" также может быть задан символ "*", что означает - "для всех групп пользователей".
overwrite Если значение - "true", то существующие права будут перезаписаны.
Необязателен. По умолчанию - "true".

См. также

  • Права доступа
  • CMain::GetFileAccessPermission
  • CMain::CopyFileAccessPermission
  • CMain::RemoveFileAccessPermission
  • Событие "OnChangePermissions"

Примеры использования

<?
// установим на файл /ru/index.php следующие права:
// для группы # 23 - право чтения файла
// для группы # 5 - право прямого изменения файла
// для всех остальных групп - доступ к файлу закрыт
if ($APPLICATION->SetFileAccessPermission("/ru/index.php",
    array("23" => "R", "5" => "W", "*" => "D")))
    ShowNote("Права на файл успешно установлены.");
?>


SetPageProperty

CMain::SetPageProperty

CMain::SetPageProperty(
 string property_id,
 string property_value
)

Устанавливает свойство для текущей страницы.

Параметры функции

Параметр | Описание
property_id | Идентификатор свойства.
property_value | Значение свойства.

См. также

  • Свойства страниц и мета-теги
  • CMain::ShowProperty
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetDirProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirPropertyList
  • CMain::SetDirProperty

Примеры использования

<?
$APPLICATION->SetPageProperty("keywords", "веб, разработка, программирование");
?>


SetTemplateCSS

CMain::SetTemplateCSS

CMain::SetTemplateCSS(
 string rel_path
)

Устанавливает CSS стиль для компоненты.

Параметры функции

Параметр | Описание
rel_path | Относительный путь к CSS стилю компоненты.

См. также

  • CMain::ShowCSS
  • CMain::GetCSS
  • CMain::SetAdditionalCSS

Примеры использования

$APPLICATION->SetTemplateCSS("form/form.css");


SetTitle

CMain::SetTitle

CMain::SetTitle(
 string title
)

Устанавливает заголовок страницы. Если заголовок страницы у вас выводится с помощью функции CMain::ShowTitle, то устанавливать его вы можете уже после того как у вас будет выведена пролог сайта.

Параметры функции

Параметр | Описание
title | Заголовок страницы.

См. также

  • CMain::ShowTitle
  • CMain::GetTitle

Примеры использования

<?
$APPLICATION->SetTitle("Page title");
?>


ShowBanner

CMain::ShowBanner

CMain::ShowBanner(
 string banner_type,
 string html_before = false,
 string html_after = false
)

Подключает модуль рекламы и отображает баннер заданного типа.

Параметры функции

Параметр | Описание
banner_type | Тип баннера (административный пункт меню "Реклама" > "Типы баннеров").
html_before | HTML код выводимый перед баннером.
html_after | HTML код выводимый после баннера.

См. также

Классы модуля Реклама

Примеры использования

<?
// подключим модуль рекламы и выведем баннер типа "LEFT"
$APPLICATION->ShowBanner("LEFT", "<div align=\"center\">", "<br></div><br>");
?>


ShowCSS

CMain::ShowCSS

CMain::ShowCSS(
 bool external = true
)

Отображает CSS страницы.

Данная функция использует технологию "отложенных функций", позволяющую, помимо всего прочего, задавать CSS страницы (например, внутри компонента) уже после того как был выведен пролог сайта.

Параметры функции

Параметр Описание
external Если значение - "true", то выводится HTML представляющий из себя ссылку на внешний CSS, например:
<LINK href="/bitrix/templates/demo/styles.css" type="text/css" rel="stylesheet">
Если значение "false", то выводится HTML представляющий из себя внутренний CSS, например:
<style type="text/css">
body { margin: 0px; padding:0px; background-color: #FFFFFF}
...
</style>
Исключение составляет CSS стили лежащие в каталоге /bitrix/modules/, они всегда подключаются как внутренний CSS (как правило это используется в стандартных компонентах).

См. также

  • Отложенные функции
  • CMain::GetCSS
  • CMain::SetTemplateCSS
  • CMain::SetAdditionalCSS

Примеры использования

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?= LANG_CHARSET;?>">
<META NAME="ROBOTS" content="ALL">
<?$APPLICATION->ShowMeta("keywords")?>
<?$APPLICATION->ShowMeta("description")?>
<title><?$APPLICATION->ShowTitle()?></title>
<?$APPLICATION->ShowCSS();?>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
...


ShowHeadStrings

CMain::ShowHeadStrings

CMain::ShowHeadStrings()

Отображает специальные стили, JavaScript либо произвольный php-код.

Данная функция использует технологию "отложенных функций". Используется в шаблоне сайта для вывода совершенно любого кода, который задается, например, в компонентах с помощью CMain::AddHeadString().

Т.е. эта функция - аналог ShowMeta, ShowTitle, ShowCSS, только более универсальная.

См. также

  • Отложенные функции
  • CMain::AddHeadString()

Примеры использования

<?if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?=LANG_CHARSET;?>" />
<?$APPLICATION->ShowMeta("robots")?>
<?$APPLICATION->ShowMeta("keywords")?>
<?$APPLICATION->ShowMeta("description")?>
<title><?$APPLICATION->ShowTitle()?></title>
<?$APPLICATION->ShowCSS();?>
<?$APPLICATION->ShowHeadStrings()?>
<?$APPLICATION->ShowHeadScripts()?>
</head>
<body>
...

Рассмотрим пример использования CMain::AddHeadString(). В файле \bitrix\modules\main\include\epilog_after.php используется код:

...
if($bShowStat && !$USER->IsAuthorized())
{
require_once($_SERVER["DOCUMENT_ROOT"].BX_ROOT."/modules/main/interface/init_admin.php");
$GLOBALS["APPLICATION"]->AddHeadString($GLOBALS["adminPage"]->ShowScript());
$GLOBALS["APPLICATION"]->AddHeadString('<script type="text/javascript" src="/bitrix/js/main/public_tools.js"></script>');
$GLOBALS["APPLICATION"]->AddHeadString('<link rel="stylesheet" type="text/css" href="/bitrix/themes/.default/pubstyles.css" />');
}
...


ShowMeta

CMain::ShowMeta

CMain::ShowMeta(
 string property_id,
 string meta_name = false
)

Отображает свойство страницы в виде мета-тега.

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

Данная функция использует технологию "отложенных функций", позволяющую, помимо всего прочего, задавать значения мета-тегов через свойства страницы или раздела (с помощью функций CMain::SetPageProperty, CMain::SetDirProperty) уже после того как был выведен пролог сайта.

Параметры функции

Параметр | Описание
property_id | Идентификатор свойства страницы или раздела, значение которого (value) будет выведено в аттрибуте "content" мета-тега: <meta content="value" ...>
meta_name | Аттрибут "name" мета-тега: <meta name="meta_name" ...> Необязательный. По умолчанию равен идентификатору свойства property_id.

См. также

  • Отложенные функции
  • Свойства страниц и мета-теги
  • CMain::GetMeta
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Примеры использования

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?=LANG_CHARSET?>">
<META NAME="ROBOTS" content="ALL">
<?$APPLICATION->ShowMeta("keywords")?>
<?$APPLICATION->ShowMeta("description")?>
<title><?$APPLICATION->ShowTitle()?></title>
<?$APPLICATION->ShowCSS();?>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
...


ShowNavChain

CMain::ShowNavChain

CMain::ShowNavChain(
 mixed path = false,
 int start_from = 0,
 mixed template_path = false
)

Отображает навигационную цепочку.

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

Если вам не нужно показывать навигационную цепочку на какой либо странице, вам достаточно вставить в теле страницы код, инициализирующий свойство страницы "NOT_SHOW_NAV_CHAIN" значением "Y":

$APPLICATION->SetPageProperty("NOT_SHOW_NAV_CHAIN", "Y");
Поддержка этого свойства встроена в данную функцию.

Параметры функции

Параметр Описание
path Путь для которого будет построена навигационная цепочка. В случае многосайтовой версии, если DOCUMENT_ROOT у сайтов разный (задается в поле "Путь к корневой папке веб-сервера" в настройках сайта), то в данном параметре необходимо передавать массив вида:
array("ID сайта", "путь")
Необязателен. По умолчанию - "false" - текущий путь.
start_from Номер пункта начиная с которого будет построена навигационная цепочка. Пункты навигационной цепочки нумеруются с нуля.
Необязателен. По умолчанию - "0".
template_path Путь к шаблону навигационной цепочки.
Необязателен. По умолчанию - "false", что предполагает поиск пути к шаблону навигационной цепочки по алгоритму представленному на странице "Навигационная цепочка"

См. также

  • Навигационная цепочка
  • Отложенные функции
  • CMain::AddChainItem
  • CMain::GetNavChain

Примеры использования

<?
// выведем цепочку навигации для текущей страницы начиная
// со первого пункта по шаблону "chain_template.php"
// лежащему либо в каталоге "/bitrix/templates/<текущий шаблон сайта>/",
// либо в каталоге "/bitrix/templates/.default/".
$APPLICATION->ShowNavChain();
?>
<?
// выведем цепочку навигации для текущей страницы начиная
// со 2-го пункта по шаблону chain_template_bottom.php
$APPLICATION->ShowNavChain(false, 2, "/bitrix/templates/.default/chain_template_bottom.php");
?>

Пример шаблона навигационной цепочки

<?
// файл /bitrix/templates/.default/chain_template.php

$sChainProlog = "";   // HTML выводимый перед навигационной цепочкой
$sChainBody = "";     // пункт навигационной цепочки
$sChainEpilog = "";   // HTML выводимый после навигационной цепочки

// разделитель
if ($ITEM_INDEX > 0)
   $sChainBody = "<font class=\"chain\">&nbsp;/&nbsp;</font>";

// если указана ссылка то
if (strlen($LINK)>0)
{
    // выводим ссылку
    $sChainBody .= "<a href=\"".$LINK."\" class=\"chain\">".htmlspecialchars($TITLE)."</a>";
}
else // иначе
{
    // текст
    $sChainBody .= "<font class=\"chain\">".htmlspecialchars($TITLE)."</font>";
}
?>


ShowPanel

CMain::ShowPanel

CMain::ShowPanel()

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

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

$APPLICATION->ShowPanel = true;
Если вам необходимо определить выводилась ли панель управления, то необходимо обратиться к свойству PanelShowed объекта $APPLICATION:

if ($APPLICATION->PanelShowed) echo "Панель выведена!"

Параметры функции

Без параметров.

См. также

  • Панель управления
  • Отложенные функции
  • CMain::AddPanelButton
  • Событие "OnPanelCreate"

Примеры использования

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?=LANG_CHARSET;?>">
<META NAME="ROBOTS" content="ALL">
<?$APPLICATION->ShowMeta("keywords")?>
<?$APPLICATION->ShowMeta("description")?>
<title><?$APPLICATION->ShowTitle()?></title>
<?$APPLICATION->ShowCSS();?>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
<?$APPLICATION->ShowPanel();?>
...


ShowProperty

CMain::ShowProperty

CMain::ShowProperty(
 string property_id,
 mixed default_value = false
)

Отображает свойство страницы, учитывая свойства раздела.

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

Параметры функции

Параметр | Описание
property_id | Идентификатор свойства.
default_value | Значение свойства по умолчанию. Необязательный. По умолчанию - "false" - значение свойства по умолчанию не задано.

См. также

  • Отложенные функции
  • Свойства страниц и мета-теги
  • CMain::GetProperty
  • CMain::GetPageProperty
  • CMain::GetDirProperty
  • CMain::GetPagePropertyList
  • CMain::GetDirPropertyList
  • CMain::SetPageProperty
  • CMain::SetDirProperty

Примеры использования

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?=LANG_CHARSET;?>">
<META NAME="ROBOTS" content="ALL">
<?$APPLICATION->ShowMeta("keywords")?>
<?$APPLICATION->ShowMeta("description")?>
<title><?$APPLICATION->ShowProperty("page_title")?></title>
<?$APPLICATION->ShowCSS();?>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
...


ShowSpreadCookieHTML

CMain::ShowSpreadCookieHTML

CMain::ShowSpreadCookieHTML()

Отображает HTML представляющий из себя набор IFRAME'ов предназначенный для распространения cookie по доменам. Данная функция используется в технологии переноса посетителей между разными сайтами. Она стандартно включена в визуальную часть эпилога.

Параметры функции

Без параметров.

См. также

  • Перенос посетителей
  • CMain::set_cookie
  • CMain::get_cookie


ShowTitle

CMain::ShowTitle

CMain::ShowTitle(
 string property_name = "title",
 bool strip_tags = true
)

Отображает заголовок страницы.

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

Параметры функции

Параметр | Описание
property_name | Идентификатор свойства страницы, значение которого будет выведено в качестве заголовка (если это значение задано например, с помощью функции CMain::SetPageProperty). Необязательный. По умолчанию "title".
strip_tags | Если значение - "true", то из заголовка страницы будут удалены все HTML теги. Необязательный. По умолчанию - "true".

См. также

  • Отложенные функции
  • CMain::GetTitle
  • CMain::SetTitle

Примеры использования

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?= LANG_CHARSET;?>">
<META NAME="ROBOTS" content="ALL">
<?$APPLICATION->ShowMeta("keywords")?>
<?$APPLICATION->ShowMeta("description")?>
<title><?$APPLICATION->ShowTitle()?></title>
<?$APPLICATION->ShowCSS();?>
</head>
<body link="#525252" alink="#F1555A" vlink="#939393" text="#000000">
...


ThrowException

CMain::ThrowException

CMain::ThrowException(
 mixed msg,
 mixed id = false
)

Метод фиксирует исключение msg c кодом id. Получить последнее исключение можно методом $APPLICATION->GetException()

Параметры

Параметр | Описание
msg | Текст ошибки или объект класса, наследованного от CApplicationException.
id | Идентификатор ошибки.

См. также

  • CMain::ResetException
  • CMain::GetException

Примеры использования

<?
if($login=='')
{
   global $APPLICATION;
   $APPLICATION->ThrowException('Имя входа должно быть заполнено.');
   return false;
}
?>


Класс CMainPage

CMainPage - класс для использования на индексной странице портала.

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

Методы класса

Метод | Описание
GetSiteByHost | Возвращает идентификатор сайта, определяя его по текущему хосту.
GetSiteByAcceptLanguage | Возвращает идентификатор сайта, определяя его по переменной Accept-Language в настройках браузера посетителя.
RedirectToSite | Перенаправляет на индексную страницу сайта.
GetIncludeSitePage | Возвращает полный путь на индексную страницу заданного сайта, для дальнейшего ее подключения при помощи require() или include().

См. также

  • Список терминов
  • Многосайтовость: способы организации


GetIncludeSitePage

CMainPage::GetIncludeSitePage

mixed
CMainPage::GetIncludeSitePage(
 string site_id
)

Возвращает абсолютный путь на индексную страницу заданного сайта, для дальнейшего ее подключения при помощи require() или include(). Если ни один из сайтов не найден по хосту, то функция вернет - "false".

Параметры функции

Параметр | Описание
site_id | Идентификатор сайта.

См. также

  • Список терминов
  • Многосайтовость: способы организации

Пример индексной страницы портала

<?
require($_SERVER['DOCUMENT_ROOT']."/bitrix/modules/main/include/mainpage.php");

if($page = CMainPage::GetIncludeSitePage(CMainPage::GetSiteByHost()))
    require_once($page);

require($_SERVER['DOCUMENT_ROOT']."/bitrix/header.php");?>
<?require($_SERVER['DOCUMENT_ROOT']."/bitrix/footer.php");?>


GetSiteByAcceptLanguage

CMainPage::GetSiteByAcceptLanguage

mixed
CMainPage::GetSiteByAcceptLanguage(
 bool compare_site_id = false
)

Возвращает идентификатор сайта, определяя его по переменной Accept-Language в настройках браузера посетителя. Приоритетным для данной функции является порядок языков установленный в настройках браузера посетителя. Если ни один из этих языков не подойдет, то будет выбран сайт с установленным флагом "Сайт по умолчанию".

Параметры функции

Параметр | Описание
compare_site_id | Если значение "true", то поиск сайта будет осуществляться через сравнение идентификатора языка из Accept-Language и идентификатора сайта, если значение "false" - то сравнение будет между идентификатором языка из Accept-Language и идентификатором языка выбранного в настройках сайта. Необязательный. По умолчанию - "false".

См. также

  • Список терминов
  • Многосайтовость: способы организации

Пример индексной страницы портала

Для использования данного примера в качестве индексной страницы портала необходимо убедиться что:
1. Многосайтовость организована по способу 1.
2. Ни у одного из сайтов в поле "Папка сайта" не указано значение - "/".

<?
require($_SERVER['DOCUMENT_ROOT']."/bitrix/modules/main/include/mainpage.php");

if ($sid = CMainPage::GetSiteByAcceptLanguage())
    CMainPage::RedirectToSite($sid);

require($_SERVER['DOCUMENT_ROOT']."/bitrix/header.php");?>
<?require($_SERVER['DOCUMENT_ROOT']."/bitrix/footer.php");?>


GetSiteByHost

CMainPage::GetSiteByHost

mixed
CMainPage::GetSiteByHost()

Возвращает идентификатор сайта, определяя его по текущему хосту. Если идентификатор сайта неверный, то вернет - "false".

Параметры функции

Без параметров.

См. также

  • Список терминов
  • Многосайтовость: способы организации

Пример индексной страницы портала

<?
require($_SERVER['DOCUMENT_ROOT']."/bitrix/modules/main/include/mainpage.php");

if($page = CMainPage::GetIncludeSitePage(CMainPage::GetSiteByHost()))
    require_once($page);

require($_SERVER['DOCUMENT_ROOT']."/bitrix/header.php");?>
<?require($_SERVER['DOCUMENT_ROOT']."/bitrix/footer.php");?>


RedirectToSite

CMainPage::RedirectToSite

mixed
CMainPage::RedirectToSite(
 string site_id
)

Перенаправляет на индексную страницу сайта.

Параметры функции

Параметр | Описание
site_id | Идентификатор сайта.

См. также

  • Список терминов
  • Многосайтовость: способы организации

Пример индексной страницы портала

Для использования данного примера в качестве индексной страницы портала необходимо убедиться что:
1. Многосайтовость организована по способу 1.
2. Ни у одного из сайтов в поле "Папка сайта" не указано значение - "/". Т.е. корень каждого сайта - отдельный подкаталог.

<?
require($_SERVER['DOCUMENT_ROOT']."/bitrix/modules/main/include/mainpage.php");

if ($sid = CMainPage::GetSiteByAcceptLanguage())
    CMainPage::RedirectToSite($sid);

require($_SERVER['DOCUMENT_ROOT']."/bitrix/header.php");?>
<?require($_SERVER['DOCUMENT_ROOT']."/bitrix/footer.php");?>


Класс CMenu

CMenu - класс для работы с меню.

Свойства класса

Параметр | Описание
type | Тип меню.
arMenu | Массив пунктов меню (доступен только после CMenu::Init)
MenuDir | Папка, в которой находится файл содержащий параметры и пункты меню (доступен только после CMenu::Init)
template | Путь к файлу с шаблоном (доступен только после CMenu::Init)

Методы класса

Метод | Описание
CMenu | (конструктор) инициализирует меню заданного типа.
Init | Ищет рекурсивно меню начиная c папки.
GetMenuHtml | Возвращает меню трансформированное в HTML.
GetMenuHtmlEx | Возвращает меню трансформированное в HTML.

См. также

  • Меню


Конструктор CMenu

CMenu::Конструктор CMenu

CMenu(
 string type = "left"
)

Создает объект класса CMenu.

Параметры конструктора

Параметр | Описание
type | Тип меню. Типы меню задаются в настройках модуля "Управление структурой сайта". Необязательный. По умолчанию "left".

См. также

  • Меню
  • CMain::GetMenu

Примеры использования

<?
$lm = new CMenu("left");
$lm->Init($APPLICATION->GetCurDir(), true);
$lm->template = "/bitrix/templates/demo/left.menu_template.php";
echo $lm->GetMenuHtml();
?>


GetMenuHtml

CMenu::GetMenuHtml

string
CMenu::GetMenuHtml()

Возвращает HTML представляющий из себя меню.

Параметры функции

Без параметров.

См. также

  • Меню
  • CMenu::GetMenuHtmlEx
  • CMain::GetMenuHtml
  • CMain::GetMenuHtmlEx

Примеры использования

<?
$lm = new CMenu("left");
$lm->Init($APPLICATION->GetCurDir(), true);
$lm->template = "/bitrix/templates/demo/left.menu_template.php";
echo $lm->GetMenuHtml();
?>


GetMenuHtmlEx

CMenu::GetMenuHtmlEx

string
CMenu::GetMenuHtmlEx()

Возвращает HTML представляющий из себя меню. В отличие от функции CMenu::GetMenuHtml шаблон меню будет подключаться только один раз.

В шаблоне меню, используемом данной функцией, в обязательном порядке необходимо инициализировать переменную $sMenu, в которой должен храниться HTML представляющий из себя все меню целиком.

Параметры функции

Без параметров.

См. также

  • Меню
  • CMenu::GetMenuHtml
  • CMain::GetMenuHtml
  • CMain::GetMenuHtmlEx

Примеры использования

<?
$lm = new CMenu("left");
$lm->Init($APPLICATION->GetCurDir(), true);
$lm->template = "/bitrix/templates/demo/left.menu_template.php";
echo $lm->GetMenuHtmlEx();
?>


Init

CMenu::Init

bool
CMenu::Init(
 string dir
 bool use_ext = false,
 string template_path = false
)

Инициализирует (заполняет пунктами) объект класса CMenu. Возвращает "true" если в каталоге сайта найден файл меню .тип меню.menu.php (поиск идет вверх по иерархии начиная с каталога dir), и "false" в противном случае.

Параметры функции

Параметр | Описание
dir | Папка, начиная с которой, объект будет искать файл .тип меню.menu.php (файл с параметрами и пунктами меню).
use_ext Если значение - "true", то для формирования массива меню, помимо файлов .тип меню.menu.php будут также подключаться файлы с именами вида .тип меню.menu_ext.php. В которых вы можете манипулировать массивом меню $aMenuLinks произвольно, по вашему усмотрению (например, дополнять пункты меню значениями из инфо-блоков).
Необязателен. По умолчанию - "false".
template_path Шаблон для вывода меню.
Необязателен. По умолчанию - "false", что означает искать шаблон меню сначала в файле /bitrix/templates/ID текущего шаблона сайта/тип меню.menu_template.php, затем если шаблон не будет найден, то искать в файле /bitrix/templates/.default/тип меню.menu_template.php. В самом шаблоне меню вам будут доступны следующие предустановленные переменные:
  • $arMENU - копия массива меню
  • $arMENU_LINK - ссылка на текущий массив меню
  • $TEXT - текст текущего пункта меню
  • $LINK - ссылка текущего пункта меню
  • $SELECTED - выбран ли пункт меню в данный момент
  • $PERMISSION - доступ на страницу указанную в $LINK, возможны следующие значения:
    • D - доступ запрещён
    • R - чтение (право просмотра содержимого файла)
    • U - документооборот (право на редактирование файла в режиме документооборота)
    • W - запись (право на прямое редактирование)
    • X - полный доступ (право на прямое редактирование файла и право на изменение прав доступа на данных файл)
  • $ADDITIONAL_LINKS - дополнительные ссылки для подсветки меню
  • $ITEM_TYPE - "D" - директория (если $LINK заканчивается на "/"), иначе "P" - страница
  • $ITEM_INDEX - порядковый номер пункта меню
  • $PARAMS - параметры пунктов меню
При этом в шаблоне для построения меню необходимо будет инициализировать следующие перменные:
  • $sMenuProlog - HTML который будет добавлен перед пунктами меню
  • $sMenuEpilog - HTML который будет добавлен после пунктов меню
  • $sMenuBody - HTML представляющий из себя один пункт меню
  • $sMenu - HTML представляющий из себя все меню целиком (только для функций GetMenuHtmlEx)

См. также

  • Меню
  • CMain::GetMenu

Примеры использования

<?
$lm = new CMenu("left");
$lm->Init($APPLICATION->GetCurDir(), true);
$lm->template = "/bitrix/templates/demo/left.menu_template.php";
echo $lm->GetMenuHtml();
?>


Класс CModule

CModule - класс для работы с модулями.

Все классы представляющие из себя описание конкретных модулей системы должны наследоваться от класса CModule. Классы описывающие тот или иной модуль должны иметь имя равное ID модуля и их описание должно располагаться в файле /bitrix/modules/ID модуля/install/index.php.

Свойства класса

Параметр | Описание
MODULE_ID | Идентификатор модуля.
MODULE_VERSION | Текущая версия модуля.
MODULE_VERSION_DATE | Дата текущей версии модуля.
MODULE_NAME | Наименование модуля.
MODULE_DESCRIPTION | Описание модуля.
MODULE_GROUP_RIGHTS | Если значение "Y", то модуль поддерживает схему распределения прав настраиваемую как правило в настройках модуля.

Методы класса

Метод | Описание
GetList | Возвращает список установленных модулей системы.
GetDropDownList | Возвращает выборку из базы для применения в функции SelectBox, предназначенной для вывода HTML выпадающего списка.
Add | Вставляет идентификатор модуля в таблицу b_module.
Remove | Удаляет идентификатор модуля из таблицы b_module.
GetModuleRightList | Возвращает массив описывающий индивидуальную схему распределения прав модуля.
DoInstall | Запускает процедуру инсталляции модуля.
DoUninstall | Запускает процедуру деинсталляции модуля.
IncludeModule | Проверяет установлен ли модуль и если установлен, то подключает его (точнее подключает файл /bitrix/modules/ID модуля/include.php).
IsInstalled | Проверяет установлен ли модуль.

См. также

  • Описание концепции модулей
  • Идентификаторы модулей
  • Функции для работы с модулями


Add

CModule::Add

CModule::Add()

Вставляет идентификатор модуля в таблицу b_module.

Параметры функции

Без параметров.

См. также

  • RegisterModule
  • CModule::Remove

Примеры использования

<?
$m = new CModule;
$m->MODULE_ID = "iblock";
$m->Add();
?>


DoInstall

CModule::DoInstall

CModule::DoInstall()

Запускает процедуру инсталляции модуля.

Параметры функции

Без параметров.

См. также

  • RegisterModule

Примеры использования

<?
// если нажали кнопку "Установить" или "Деинсталлировать" то
if(strlen($uninstall)>0 || strlen($install)>0)
{
    // проверим наличие обязательного файла в каталоге модуля
    if(@file_exists($DOCUMENT_ROOT."/bitrix/modules/".$module_id."/install/index.php"))
    {
        include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/".$module_id."/install/index.php");
        $obModule = new $module_id;
        if($obModule->IsInstalled() && strlen($uninstall)>0) $obModule->DoUninstall();
        elseif(!$obModule->IsInstalled() && strlen($install)>0) $obModule->DoInstall();
    }
}
?>


DoUninstall

CModule::DoUninstall

CModule::DoUninstall()

Запускает процедуру деинсталляции модуля.

Параметры функции

Без параметров.

См. также

  • UnRegisterModule

Примеры использования

<?
// если нажали кнопку "Установить" или "Деинсталлировать" то
if(strlen($uninstall)>0 || strlen($install)>0)
{
    // проверим наличие обязательного файла в каталоге модуля
    if(@file_exists($DOCUMENT_ROOT."/bitrix/modules/".$module_id."/install/index.php"))
    {
        include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/".$module_id."/install/index.php");
        $obModule = new $module_id;
        if($obModule->IsInstalled() && strlen($uninstall)>0) $obModule->DoUninstall();
        elseif(!$obModule->IsInstalled() && strlen($install)>0) $obModule->DoInstall();
    }
}
?>


GetDropdownList

CModule::GetDropdownList

CDBResult
CModule::GetDropdownList(
 string sql = "ORDER BY ID"
)

Возвращает список модулей в виде объекта класса CDBResult для применения в функциях SelectBox или SelectBoxM, выводящих HTML тег <select> (список).

Параметры функции

Параметр | Описание
sql | SQL код который может применяться для задания сортировки выбираемых ID модулей. Необязательный. По умолчанию - сортируем в порядка убывания по полю ID модуля.

См. также

  • CModule::GetList
  • SelectBox
  • SelectBoxM

Примеры использования

<?
$rs = CModule::GetDropdownList();
echo SelectBoxFromArray("module_id", $rs, $module_id);
?>


GetList

CModule::GetList

CDBResult
CModule::GetList()

Возвращает список модулей в виде объекта класса CDBResult.

Параметры функции

Без параметров.

См. также

  • CModule::GetDropDownList

Примеры использования

<?
$rsInstalledModules = CModule::GetList();
while ($ar = $rsInstalledModules->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetModuleRightList

CModule::GetModuleRightList

array
CModule::GetModuleRightList()

Возвращает массив описывающий индивидуальную схему распределения прав модуля. Данная функция является методом класса описывающего конкретный модуль. Если модуль поддерживает индивидуальную схему распределения прав, то данный метод будет существовать. Возможна ситуация когда модуль поддерживает схему распределения прав (свойство MODULE_GROUP_RIGHTS="Y"), но она не отличается от стандартной и поэтому используется схема по умолчанию, в этом случае массив описывающий схему по умолчанию можно получить с помощью функции CMain::GetDefaultRightList().

Для главного модуля, массив описывающий схему распределения прав можно получить с помощью функции CMain::GetMainRightList()

Параметры функции

Без параметров.

См. также

  • Права доступа
  • CMain::GetUserRight
  • CMain::GetUserRoles

Примеры использования

<?
// выведем списки прав установленных модулей
$rs = CModule::GetList();
while ($ar = $rs->Fetch()) :
    $MID = $ar["ID"];
    if ($MID!="main") :
        include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/".$MID."/install/index.php");
        if (class_exists($MID)) :
            $obModule = new $MID;
            if ($obModule->MODULE_GROUP_RIGHTS=="Y") :
                if (method_exists($obModule, "GetModuleRightList"))
                    $arRights = call_user_method("GetModuleRightList",$obModule);
                else
                    $arRights = $APPLICATION->GetDefaultRightList();

                echo $MID.": ".SelectBoxFromArray("RIGHTS_MODULE_".$MID, $arRights, ${"RIGHTS_MODULE_".$MID}, "<по умолчанию>");
            endif;
        endif;
    else:
        $arRights = $APPLICATION->GetMainRightList();
        echo $MID.": ".SelectBoxFromArray("RIGHTS_MODULE_".$MID, $arRights, ${"RIGHTS_MODULE_".$MID}, "<по умолчанию>");
    endif;
endwhile;
?>


IncludeModule

CModule::IncludeModule

bool
CModule::IncludeModule(
 string module_id
)

Проверяет установлен ли модуль и если установлен, то подключает его (точнее подключает файл /bitrix/modules/ID модуля/include.php). Возвращает "true", если модуль установлен, иначе - "false".

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.

См. также

  • IsModuleInstalled
  • CModule::IsInstalled
  • Идентификаторы модулей

Примеры использования

<?
// проверим установлен ли модуль "Информационные блоки" и если да то подключим его
if (CModule::IncludeModule("iblock")):
    // здесь необходимо использовать функции модуля "Информационные блоки"
    ...
endif;
?>


IsInstalled

CModule::IsInstalled

mixed
CModule::IsInstalled()

Определяет установлен ли модуль. Возвращает "true", если модуль установлен и "false" - в противном случае.

Для использования функций и классов того или иного модуля, его необходимо предварительно подключить с помощью функции CModule::IncludeModule.

Параметры функции

Без параметров.

См. также

  • IsModuleInstalled
  • CModule::IncludeModule
  • Идентификаторы модулей

Примеры использования

<?
// если нажали кнопку "Установить" или "Деинсталлировать" то
if(strlen($uninstall)>0 || strlen($install)>0)
{
    // проверим наличие обязательного файла в каталоге модуля
    if(@file_exists($DOCUMENT_ROOT."/bitrix/modules/".$module_id."/install/index.php"))
    {
        include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/".$module_id."/install/index.php");
        $obModule = new $module_id;
        if($obModule->IsInstalled() && strlen($uninstall)>0) $obModule->DoUninstall();
        elseif(!$obModule->IsInstalled() && strlen($install)>0) $obModule->DoInstall();
    }
}
?>


Remove

CModule::Remove

CModule::Remove()

Удаляет регистрационную запись о модуле из базы данных.

Параметры функции

Без параметров.

См. также

  • UnRegisterModule
  • CModule::Add

Примеры использования

<?
function UnRegisterModule($id)
{
    $m = new CModule;
    $m->MODULE_ID = $id;
    $m->Remove();
    CAllMain::DelGroupRight($id);
}
?>


Класс COption

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

Как правило управление параметрами модулей осуществляется в административном интерфейсе в настройках соответствующих модулей.

Методы класса

Метод | Описание
GetOptionString | Возвращает строковое значение параметра.
SetOptionString | Устанавливает строковое значение параметра.
GetOptionInt | Возвращает числовое значение параметра.
SetOptionInt | Устанавливает числовое значение параметра.
RemoveOption | Удаляет параметр из базы.

См. также

  • Параметры модуля
  • Класс CPageOption


GetOptionInt

COption::GetOptionInt

int
COption::GetOptionInt(
 string module_id,
 string option_id,
 mixed default_value = false,
 string site_id = false
)

Возвращает числовое значение параметра option_id, принадлежащего модулю module_id. Если не установлен параметр site_id то делается попытка найти числовой параметр option_id, принадлежащий модулю module_id для текущего сайта. Если такого параметра нет, возвращается параметр, общий для всех сайтов.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
option_id | Идентификатор параметра.
default_value | Значение по умолчанию. Если default_value не задан, то значение для default_value будет браться из массива с именем ${module_id."_default_option"} заданного в файле /bitrix/modules/module_id/default_option.php.
site_id | Идентификатор сайта для которого будут возвращены параметры. Необязательный. По умолчанию - false (для текущего сайта или если не установлены то общие для всех сайтов)

См. также

  • Параметры модуля
  • Настройки главного модуля
  • COption::GetOptionString

Примеры использования

<?
// получим поле "Ответственный по умолчанию"
// из настроек модуля "Техподдержка"
$RESPONSIBLE_USER_ID = COption::GetOptionInt("support", "DEFAULT_RESPONSIBLE_ID"));
?>


GetOptionString

COption::GetOptionString

string
COption::GetOptionString(
 string module_id,
 string option_id,
 mixed default_value = false
 string site_id = false
)

Возвращает строковое значение параметра option_id, принадлежащего модулю module_id. Если не установлен параметр site_id то делается попытка найти числовой параметр option_id, принадлежащий модулю module_id для текущего сайта. Если такого параметра нет, возвращается параметр, общий для всех сайтов.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
option_id | Идентификатор параметра.
default_value | Значение по умолчанию. Если default_value не задан, то значение для default_value будет браться из массива с именем ${module_id."_default_option"} заданного в файле /bitrix/modules/module_id/default_option.php.
site_id | Идентификатор сайта для которого будут возвращены параметры. Необязательный. По умолчанию - false (для текущего сайта или если не установлены то общие для всех сайтов)

См. также

  • Параметры модуля
  • Настройки главного модуля
  • COption::GetOptionInt

Примеры использования

<?
// получим поле "При регистрации добавлять в группу"
// из настроек главного модуля
$default_group = COption::GetOptionString("main", "new_user_registration_def_group", "2");
if($default_group!="")
    $arrGroups = explode(",",$default_group);
?>


RemoveOption

COption::RemoveOption

bool
COption::RemoveOption(
 string module_id,
 string option_id = "",
 string site_id = false
)

Удаляет значение одного (option_id) или всех параметров модуля module_id из базы. Если не установлен параметр site_id то делается попытка найти числовой параметр option_id, принадлежащий модулю module_id для текущего сайта. Если такого параметра нет, возвращается параметр, общий для всех сайтов.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
option_id | Идентификатор параметра. Необязательный. По умолчанию - "" (удалить все значения параметров модуля).
site_id | Идентификатор сайта для которого будут возвращены параметры. Необязательный. По умолчанию - false (для текущего сайта или если не установлены то общие для всех сайтов)

См. также

  • Параметры модуля
  • Настройки главного модуля

Примеры использования

<?
// удалим значение параметра "Количество результатов на одной странице"
// для модуля "Веб-формы" из базы
COption::RemoveOption("form", "RESULTS_PAGEN");
?>


SetOptionInt

COption::SetOptionInt

bool
COption::SetOptionInt(
 string module_id,
 string option_id,
 mixed value = "",
 mixed description = false,
 string site_id = false
)

Устанавливает числовое значение параметра option_id для модуля module_id. Если указан site_id, параметр установится только для этого сайта и не будет влиять на аналогичный параметр другого сайта. Возвращает "true", если операция прошла успешна, в противном случае - "false".

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
option_id | Идентификатор параметра.
value | Значение параметра. Необязательный. По умолчанию - "".
description | Описание параметра. Необязательный. По умолчанию - "false" (описание отсутствует).
site_id | Идентификатор сайта, для которого устанавливается параметр. Необязательный. По умолчанию - false (общий для всех сайтов параметр).

См. также

  • Параметры модуля
  • Настройки главного модуля
  • COption::SetOptionString

Примеры использования

<?
// установим значение для поля
// "Количество дополнительных параметров меню"
// из настроек модуля "Управление структурой сайта"
COption::SetOptionInt("fileman", "num_menu_param", 2);
?>


SetOptionString

COption::SetOptionString

bool
COption::SetOptionString(
 string module_id,
 string option_id,
 string value = "",
 mixed description = false,
 string site_id = false
)

Устанавливает строковое значение параметра option_id для модуля module_id. Если указан site_id, параметр установится только для этого сайта и не будет влиять на аналогичный параметр другого сайта. Возвращает "true", если операция прошла успешна, в противном случае - "false".

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
option_id | Идентификатор параметра.
value | Значение параметра. Необязательный. По умолчанию - "".
description | Описание параметра. Необязательный. По умолчанию - "false" (описание отсутствует).
site_id | Идентификатор сайта, для которого устанавливается параметр. Необязательный. По умолчанию - false (общий для всех сайтов параметр).

См. также

  • Параметры модуля
  • Настройки главного модуля
  • COption::SetOptionInt

Примеры использования

<?
// установим значение для поля
// "E-Mail администратора сайта (отправитель по умолчанию)"
// из настроек главного модуля
COption::SetOptionString("main","email_from","admin@site.com");
?>


Класс CPageCache

CPageCache - класс для кеширования HTML результата выполнения скрипта.

Методы класса

Метод | Описание
StartDataCache | Инициализирует механизм кеширования и начинает буферизацию или выводит содержимое из кеша.
EndDataCache | Сохраняет буферизированный HTML в файле кеша.
InitCache | Инициализирует механизм кеширования.
Output | Выводит сохраненный в кеше HTML результат.
IsCacheExpired | Проверяет истек ли период жизни кеша.

См. также

  • Кеширование
  • Класс CPHPCache
  • Специальный параметры


EndDataCache

CPageCache::EndDataCache

CPageCache::EndDataCache()

Выводит буферизированный HTML и сохраняет его на диске в файл кеша.

Параметры функции

Без параметров.

См. также

  • Кеширование
  • CPageCache::StartDataCache

Пример использования

<?
// создаем объект
$obCache = new CPageCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$IBLOCK_TYPE.$USER->GetUserGroupString();

// инициализируем буферизирование вывода
if($obCache->StartDataCache($life_time, $cache_id, "/")):
    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;
    // записываем буферизированный результат на диск в файл кеша
    $obCache->EndDataCache();
endif;
?>


InitCache

CPageCache::InitCache

bool
CPageCache::InitCache(
 int cache_life_time,
 string cache_id,
 mixed init_dir = false
)

Инициализирует ряд свойств объекта класса CPageCache. Если файл кеша отсутствует или истек период его жизни, то функция вернет "false", в противном случае функция вернет "true".

Параметры функции

Параметр | Описание
cache_life_time | Время жизни кеша в секундах.
cache_id | Уникальный идентификатор кеша. В этот идентификатор должны входить все параметры которые могут повлиять на результат исполнения кешируемого кода.
init_dir | Имя каталога на сайте для которого кеш будет действительным. Если значение - "/", то кеш будет действительным для всех каталогов сайта. Необязательный. По умолчанию - текущий каталог.

См. также

  • Кеширование
  • CPageCache::Output
  • CDBResult::NavStringForCache


IsCacheExpired

CPageCache::IsCacheExpired

bool
CPageCache::IsCacheExpired(
 string full_path
)

Проверяет не истек ли период жизни кеша. Функция как правило используется для удаления файлов кеша, период жизни которых истек.

Файл кеша создаваемый функциями класса CPageCache имеет расширение ".html"

Параметры функции

Параметр | Описание
full_path | Полный путь к файлу кеша.

См. также

  • Кеширование
  • CPageCache::InitCache
  • BXClearCache

Пример использования

<?
$path = $_SERVER["DOCUMENT_ROOT"]."/bitrix/cache/";
if($handle = @opendir($path))
{
    while(($file=readdir($handle))!==false)
    {
        if($file == "." || $file == "..") continue;
        if(!is_dir($path."/".$file))
        {
            if(substr($file, -5)==".html")
                $expired = CPageCache::IsCacheExpired($path."/".$file);
            elseif(substr($file, -4)==".php")
                $expired = CPHPCache::IsCacheExpired($path."/".$file);
        }
    }
}
?>


Output

CPageCache::Output

CPageCache::Output()

Выводит содержимое кеша. HTML-содержимое кэша доступно, только если файл кеша существует и предварительно был вызван метод CPageCache::InitCache или CPageCache::StartDataCache.

Параметры функции

Без параметров.

См. также

  • Кеширование
  • CPageCache::InitCache
  • CPageCache::StartDataCache


StartDataCache

CPageCache::StartDataCache

bool
CPageCache::StartDataCache(
 int cache_life_time,
 string cache_id,
 mixed init_dir = false
)

Начинает буферизацию выводимого HTML, либо выводит содержимое кеша если он ещё не истек. Если файл кеша истек, то функция возвращает "true", в противном случае - "false".

Параметры функции

Параметр | Описание
cache_life_time | Время жизни кеша в секундах.
cache_id | Уникальный идентификатор кеша. В этот идентификатор должны входить все параметры которые могут повлиять на результат исполнения кэшируемого кода.
init_dir | Имя каталога на сайте для которого кеш будет действительным. Если значение - "/", то кеш будет действительным для всех каталогов сайта. Необязательный. По умолчанию - текущий каталог.

См. также

  • Кеширование
  • CPageCache::EndDataCache
  • CDBResult::NavStringForCache

Примеры использования

<?
// создаем объект
$obCache = new CPageCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$IBLOCK_TYPE.$USER->GetUserGroupString();

// инициализируем буферизирование вывода
if($obCache->StartDataCache($life_time, $cache_id, "/")):
    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;
    // записываем предварительно буферизированный вывод в файл кеша
    $obCache->EndDataCache();
endif;
?>


Класс CPageOption

CPageOption - класс для работы с параметрами страницы.

Методы класса

Метод | Описание
GetOptionString | Возвращает строковое значение параметра страницы.
SetOptionString | Устанавливает строковое значение параметра страницы.
GetOptionInt | Возвращает числовое значение параметра страницы.
SetOptionInt | Устанавливает числовое значение параметра страницы.
RemoveOption | Удаляет параметр страницы.

См. также

  • Параметры страницы
  • Класс COption


GetOptionInt

CPageOption::GetOptionInt

int
CPageOption::GetOptionInt(
 string module_id,
 string page_option_id,
 mixed default_value = false
)

Возвращает числовое значение параметра page_option_id, принадлежащего модулю module_id.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
page_option_id | Произвольный идентификатор параметра страницы.
default_value | Значение по умолчанию.

См. также

  • Параметры страницы
  • CPageOption::GetOptionString

Примеры использования

<?
$my_parameter = CPageOption::GetOptionInt("main", "MY_PARAMETER", 21);
?>


GetOptionString

CPageOption::GetOptionString

string
CPageOption::GetOptionString(
 string module_id,
 string page_option_id,
 mixed default_value = false
)

Возвращает строковое значение параметра page_option_id, принадлежащего модулю module_id.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
page_option_id | Произвольный идентификатор параметра страницы.
default_value | Значение по умолчанию.

См. также

  • Параметры страницы
  • CPageOption::GetOptionInt

Примеры использования

<?
$my_parameter = CPageOption::GetOptionString("main", "MY_PARAMETER", "Y");
?>


RemoveOption

CPageOption::RemoveOption

bool
CPageOption::RemoveOption(
 string module_id,
 string page_option_id = ""
)

Удаляет значение одного (page_option_id) или всех параметров модуля module_id для данной страницы.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
page_option_id | Произвольный идентификатор параметра страницы. Необязательный. По умолчанию - "" (удалить все значения параметров страницы для модуля module_id).

См. также

  • Параметры страницы

Примеры использования

<?
// удалим значение параметра MY_PARAMETER для текущей страницы
CPageOption::RemoveOption("main", "MY_PARAMETER");
?>


SetOptionInt

CPageOption::SetOptionInt

bool
CPageOption::SetOptionInt(
 string module_id,
 string page_option_id,
 mixed value = ""
)

Устанавливает числовое значение параметра page_option_id для модуля module_id. Возвращает "true", если операция прошла успешна, в противном случае - "false".

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
page_option_id | Произвольный идентификатор параметра страницы.
value | Значение параметра. Необязательный. По умолчанию - "".

См. также

  • Параметры страницы
  • CPageOption::SetOptionString

Примеры использования

<?
CPageOption::SetOptionInt("main", "MY_PARAMETER", 2);
?>


SetOptionString

CPageOption::SetOptionString

bool
CPageOption::SetOptionString(
 string module_id,
 string page_option_id,
 string value = ""
)

Устанавливает строковое значение параметра page_option_id для модуля module_id. Возвращает "true", если операция прошла успешна, в противном случае - "false".

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
page_option_id | Произвольный идентификатор параметра страницы.
value | Значение параметра. Необязательный. По умолчанию - "".

См. также

  • Параметры страницы
  • CPageOption::SetOptionInt

Примеры использования

<?
// Пример запрещает сохранение в сессии номера последней страницы
// при стандартной постраничной навигации.
// По умолчанию в сессии запоминается последняя открытая страница постраничной навигации.
// Если вы хотите изменить такое поведение для данной текущей страницы,
// то до вызова функции CDBResult::NavPrint необходимо воспользоваться следующим кодом:
CPageOption::SetOptionString("main", "nav_page_in_session", "N");

// Для того чтобы вернуть режим по умолчанию:
CPageOption::SetOptionString("main", "nav_page_in_session", "Y");
?>


Класс CPHPCache

CPHPCache - класс для кеширования PHP переменных и HTML результата выполнения скрипта.

Методы класса

Метод | Описание
StartDataCache | Инициализирует механизм кеширования и начинает буферизацию или выводит содержимое из кеша.
EndDataCache | Сохраняет буферизированный HTML и PHP переменные файле кеша.
InitCache | Инициализирует механизм кеширования.
GetVars | Возвращает сохраненные в кеше PHP переменные.
Output | Выводит сохраненный в кеше HTML результат.
IsCacheExpired | Проверяет истек ли период жизни кэша.

Дополнительно

  • Кеширование
  • Класс CPageCache
  • Специальный параметры
    • © «Битрикс», 2001-2008, «1C-Битрикс», 2008 1С-Битрикс: Управление сайтом


EndDataCache

CPHPCache::EndDataCache

CPHPCache::EndDataCache(
 mixed vars = false
)

Выводит буферизированный HTML и сохраняет его на диске вместе с заданным массивом переменных в файл кеша.

Параметры функции

Параметр Описание
vars Массив переменных, значения которых необходимо записать в файл кэша, вида:
array(
 "ИМЯ ПЕРЕМЕННОЙ 1" => "ЗНАЧЕНИЕ ПЕРЕМЕННОЙ 1",
 "ИМЯ ПЕРЕМЕННОЙ 2" => "ЗНАЧЕНИЕ ПЕРЕМЕННОЙ 2",
 ...)
Необязательный. По умолчанию - массив переменных предварительно заданный в функции CPHPCache::StartDataCache.

См. также

  • Кеширование
  • CPHPCache::StartDataCache

Пример использования

<?
// создаем объект
$obCache = new CPHPCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$SECTION_ID.$USER->GetUserGroupString();

// если кэш есть и он ещё не истек то
if($obCache->InitCache($life_time, $cache_id, "/") :
    // получаем закешированные переменные
    $vars = $obCache->GetVars();
    $SECTION_TITLE = $vars["SECTION_TITLE"];
else :
    // иначе обращаемся к базе
    $arSection = GetIBlockSection($SECTION_ID);
    $SECTION_TITLE = $arSection["NAME"];
endif;

// добавляем пункт меню в навигационную цепочку
$APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

// начинаем буферизирование вывода
if($obCache->StartDataCache()):

    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;

    // записываем предварительно буферизированный вывод в файл кеша
    // вместе с дополнительной переменной
    $obCache->EndDataCache(array(
        "SECTION_TITLE"    => $SECTION_TITLE
        ));
endif;
?>


GetVars

CPHPCache::GetVars

array
CPHPCache::GetVars()

Возвращает PHP переменные сохраненные в кеше.

Параметры функции

Без параметров.

См. также

  • Кеширование
  • CPHPCache::InitCache
  • CPHPCache::StartDataCache

Примеры использования

<?
// создаем объект
$obCache = new CPHPCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$SECTION_ID.$USER->GetUserGroupString();

// если кэш есть и он ещё не истек то
if($obCache->InitCache($life_time, $cache_id, "/") :
    // получаем закешированные переменные
    $vars = $obCache->GetVars();
    $SECTION_TITLE = $vars["SECTION_TITLE"];
else :
    // иначе обращаемся к базе
    $arSection = GetIBlockSection($SECTION_ID);
    $SECTION_TITLE = $arSection["NAME"];
endif;

// добавляем пункт меню в навигационную цепочку
$APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

// начинаем буферизирование вывода
if($obCache->StartDataCache()):

    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;

    // записываем предварительно буферизированный вывод в файл кэша
    // вместе с дополнительной переменной
    $obCache->EndDataCache(array(
        "SECTION_TITLE"    => $SECTION_TITLE
        ));
endif;
?>


InitCache

CPHPCache::InitCache

bool
CPHPCache::InitCache(
 int cache_life_time,
 string cache_id,
 mixed init_dir = false
)

Инициализирует ряд свойств объекта класса CPHPCache. Если файл кеша отсутствует или истек период его жизни, то функция вернет "false", в противном случае функция вернет "true".

Параметры функции

Параметр | Описание
cache_life_time | Время жизни кеша в секундах.
cache_id | Уникальный идентификатор кеша. В этот идентификатор должны входить все параметры которые могут повлиять на результат исполнения кешируемого кода.
init_dir | Имя каталога на сайте для которого кеш будет действительным. Если значение - "/", то кеш будет действительным для всех каталогов сайта. Необязательный. По умолчанию - текущий каталог.

См. также

  • Кеширование
  • CPHPCache::Output
  • CDBResult::NavStringForCache

Примеры использования

<?
// создаем объект
$obCache = new CPHPCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$SECTION_ID.$USER->GetUserGroupString();

// если кеш есть и он ещё не истек то
if($obCache->InitCache($life_time, $cache_id, "/") :
    // получаем закешированные переменные
    $vars = $obCache->GetVars();
    $SECTION_TITLE = $vars["SECTION_TITLE"];
else :
    // иначе обращаемся к базе
    $arSection = GetIBlockSection($SECTION_ID);
    $SECTION_TITLE = $arSection["NAME"];
endif;

// добавляем пункт меню в навигационную цепочку
$APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

// начинаем буферизирование вывода
if($obCache->StartDataCache()):

    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;

    // записываем предварительно буферизированный вывод в файл кеша
    // вместе с дополнительной переменной
    $obCache->EndDataCache(array(
        "SECTION_TITLE"    => $SECTION_TITLE
        ));
endif;
?>


IsCacheExpired

CPHPCache::IsCacheExpired

bool
CPHPCache::IsCacheExpired(
 string full_path
)

Проверяет не истек ли период жизни кеша. Функция как правило используется для удаления файлов кеша, период жизни которых истек.

Файл кеша создаваемый функциями класса CPHPCache имеет расширение ".php"

Параметры функции

Параметр | Описание
full_path | Полный путь к файлу кеша.

См. также

  • Кеширование
  • CPHPCache::InitCache
  • BXClearCache

Пример использования

<?
$path = $_SERVER["DOCUMENT_ROOT"]."/bitrix/cache/";
if($handle = @opendir($path))
{
    while(($file=readdir($handle))!==false)
    {
        if($file == "." || $file == "..") continue;
        if(!is_dir($path."/".$file))
        {
            if(substr($file, -5)==".html")
                $expired = CPageCache::IsCacheExpired($path."/".$file);
            elseif(substr($file, -4)==".php")
                $expired = CPHPCache::IsCacheExpired($path."/".$file);
        }
    }
}
?>


Output

CPHPCache::Output

CPHPCache::Output()

Выводит HTML содержимое кеша.

Параметры функции

Без параметров.

См. также

  • Кеширование
  • CPHPCache::InitCache
  • CPHPCache::StartDataCache

Примеры использования

<?
// создаем объект
$obCache = new CPHPCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$SECTION_ID.$USER->GetUserGroupString();

// если кеш есть и он ещё не истек то
if($obCache->InitCache($life_time, $cache_id, "/") :

    // получаем закешированные переменные
    $vars = $obCache->GetVars();
    $SECTION_TITLE = $vars["SECTION_TITLE"];

    // добавляем пункт меню в навигационную цепочку
    $APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

    // выводим на экран содержимое кеша
    $obCache->Output();

else :

    // иначе обращаемся к базе
    $arSection = GetIBlockSection($SECTION_ID);
    $SECTION_TITLE = $arSection["NAME"];

    // добавляем пункт меню в навигационную цепочку
    $APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

    // начинаем буферизирование вывода
    if($obCache->StartDataCache()):

        // выбираем из базы параметры элемента инфо-блока
        if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
            echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
        endif;

        // записываем предварительно буферизированный вывод в файл кеша
        // вместе с дополнительной переменной
        $obCache->EndDataCache(array(
            "SECTION_TITLE"        => $SECTION_TITLE
            ));
    endif;
endif;
?>


StartDataCache

CPHPCache::StartDataCache

bool
CPHPCache::StartDataCache(
 int cache_life_time = false,
 string cache_id = false,
 mixed init_dir = false,
 array vars = array()
)

Начинает буферизацию выводимого HTML, либо выводит содержимое кеша если он ещё не истек. Если файл кеша истек, то функция возвращает "true", в противном случае - "false".

Параметры функции

Параметр Описание
cache_life_time Время жизни кеша в секундах.
Необязательный. По умолчанию - время жизни кеша предварительно заданное в функции InitCache.
cache_id Уникальный идентификатор кеша. В этот идентификатор должны входить все параметры которые могут повлиять на результат исполнения кешируемого кода.
Необязательный. По умолчанию - уникальный идентификатор кеша предварительно заданный в функции CPHPCache::InitCache.
init_dir Имя каталога на сайте для которого кеш будет действительным. Если значение - "/", то кеш будет действительным для всех каталогов сайта.
Необязательный. По умолчанию - имя каталога предварительно заданное в функции CPHPCache::InitCache.
vars Массив переменных, которые необходимо закешировать, вида:
array(
 "ИМЯ ПЕРЕМЕННОЙ 1" => "ЗНАЧЕНИЕ ПЕРЕМЕННОЙ 1",
 "ИМЯ ПЕРЕМЕННОЙ 2" => "ЗНАЧЕНИЕ ПЕРЕМЕННОЙ 2",
 ...)
Непосредственно запись переменных в файл кеша осуществляется функцией CPHPCache::EndDataCache.
Необязательный. По умолчанию - пустой массив.

См. также

  • Кеширование
  • CPHPCache::EndDataCache
  • CDBResult::NavStringForCache

Примеры использования

<?
// создаем объект
$obCache = new CPHPCache;

// время кеширования - 30 минут
$life_time = 30*60;

// формируем идентификатор кеша в зависимости от всех параметров
// которые могут повлиять на результирующий HTML
$cache_id = $ELEMENT_ID.$SECTION_ID.$USER->GetUserGroupString();

// если кеш есть и он ещё не истек, то
if($obCache->InitCache($life_time, $cache_id, "/") :
    // получаем закешированные переменные
    $vars = $obCache->GetVars();
    $SECTION_TITLE = $vars["SECTION_TITLE"];
else :
    // иначе обращаемся к базе
    $arSection = GetIBlockSection($SECTION_ID);
    $SECTION_TITLE = $arSection["NAME"];
endif;

// добавляем пункт меню в навигационную цепочку
$APPLICATION->AddChainItem($SECTION_TITLE, $SECTION_URL."SECTION_ID=".$SECTION_ID);

// начинаем буферизирование вывода
if($obCache->StartDataCache()):

    // выбираем из базы параметры элемента инфо-блока
    if($arIBlockElement = GetIBlockElement($ELEMENT_ID, $IBLOCK_TYPE)):
        echo "<pre>"; print_r($arIBlockElement); echo "</pre>";
    endif;

    // записываем предварительно буферизированный вывод в файл кеша
    // вместе с дополнительной переменной
    $obCache->EndDataCache(array(
        "SECTION_TITLE"    => $SECTION_TITLE
        ));
endif;
?>


Класс CSite

CSite - класс для работы с сайтами.

Поля

Поле | Тип | Описание
LID | char (2) | ID сайта.
SORT | int | Порядок сортировки.
DEF | char | Сайт по умолчанию (Y|N).
ACTIVE | char | Активность (Y|N).
NAME | varchar (50) | Краткое название сайта.
DIR | varchar (50) | Папка от которой начинается содержимое сайта.
FORMAT_DATE | varchar (50) | Формат даты.
FORMAT_DATETIME | varchar (50) | Формат даты-время.
CHARSET | varchar (255) | Кодировка страниц данного сайта.
LANGUAGE_ID | char (2) | Идентификатор языка сайта.
DOC_ROOT | varchar (255) | Полный путь на диске к корневой папке веб-сервера для этого сайта (в случае если сайты имеют различные DOCUMENT_ROOT).
SERVER_NAME | varchar (255) | URL сайта.
SITE_NAME | varchar (255) | Полное название сайта.
EMAIL | varchar (255) | E-Mail адрес по умолчанию.

Методы класса

Метод | Описание
GetList | Получает список сайтов.
GetByID | Получает данные об одном сайте.
GetDateFormat | Возвращает формат даты для языка сайта.
Add | Добавляет новый сайт.
Update | Изменяет существующий сайт.
Delete | Удаляет сайт.

См. также

  • Сайты


Add

CSite::Add

mixed
CSite::Add(
 array fields
)

Функция добавляет новый сайт. Возвращает ID вставленного сайта. При возникновении ошибки функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля CSite
  • CSite::Update
  • CSite::Delete

Примеры использования

<?
$arFields = Array(
  "LID"              => "ru",
  "ACTIVE"           => "Y",
  "SORT"             => 200,
  "DEF"              => "N",
  "NAME"             => "www.site.com",
  "DIR"              => "/ru/",
  "FORMAT_DATE"      => "DD.MM.YYYY",
  "FORMAT_DATETIME"  => "DD.MM.YYYY HH:MI:SS",
  "CHARSET"          => "windows-1251",
  "SITE_NAME"        => "My site",
  "SERVER_NAME"      => "www.site.com",
  "EMAIL"            => "admin@site.com",
  "LANGUAGE_ID"      => "ru",
  "DOC_ROOT"         => "",
  "DOMAINS"          => "www.site.com \n site.com"
  );
$obSite = new CSite;
$obSite->Add($arFields);
if (strlen($obSite->LAST_ERROR)>0) $strError .= $obSite->LAST_ERROR;
?>


Delete

CSite::Delete

mixed
CSite::Delete(
 string id
)

Функция удаляет сайт. Если удаление успешно, то возвращает объект CDBResult, иначе "false".

Параметры функции

Параметр | Описание
id | ID удаляемого сайта.

См. также

  • CSite::Add
  • CSite::Update
  • Событие "OnBeforeSiteDelete"
  • Событие "OnSiteDelete"

Примеры использования

<?
if (CSite::Delete("ru")===false)
  echo "Сайт удалить нельзя т.к. найдены связанные записи.";
?>


GetByID

CSite::GetByID

CDBResult
CSite::GetByID(
 string id
)

Возвращает информацию по сайту в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
id | ID сайта.

См. также

  • Поля CSite
  • Класс CDBResult
  • CSite::GetList

Примеры использования

<?
$rsSites = CSite::GetByID("ru");
$arSite = $rsSites->Fetch();
echo "<pre>"; print_r($arSite); echo "</pre>";
?>


GetDateFormat

CSite::GetDateFormat

string
CSite::GetDateFormat(
  string format_type = "FULL",
  mixed site_id = false
)

Возвращает формат даты (времени) сайта.

Параметры функции

Параметр Описание
format_type Тип формата. Допустимы следующие значения:
  • FULL - для дата-время
  • SHORT - для даты
Необязательный. По умолчанию "FULL".
site_id ID сайта.
Необязательный. По умолчанию используется ID текущего сайта.

См. также

  • Методы класса CDataBase для работы с датой и временем
  • Функции для работы с датой и временем

Примеры использования

<?
// выводит текущую дату в формате текущего сайта
echo date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")), time());
?>


GetList

CSite::GetList

CDBResult
CSite::GetList(
 string &by = "sort",
 string &order = "asc",
 array filter = array()
)

Возвращает список сайтов в виде объекта класса CDBResult.

Параметры функции

Параметр Описание
by По какому полю сортируем. Допустимы следующие значения:
  • id - по ID сайта
  • active - по флагу активности
  • name - по краткому названию сайта
  • dir - по каталогу от которого начинается содержимое сайта
  • lendir - по длине имени каталога от которого начинается содержимое сайта
  • def - по флагу "Сайт по умолчанию"
  • sort - по индексу сортировки
Параметр необязательный. По умолчанию - "sort".
оrder Порядок сортировки. Допустимы следующие значения:
  • asc - по возрастанию
  • desc - по убыванию
Параметр необязательный. По умолчанию - "asc".
filter Массив вида array("фильтруемое поле"=>"значение" [, ...]). "Фильтруемое поле" может принимать следующие значения:
  • ID - ID сайта
  • NAME - поле "Название" из настроек сайта
  • DOMAIN - поле "Доменное имя" из настроек сайта
  • IN_DIR - префикс для поля "Папка сайта" из настроек сайта
  • LANGUAGE_ID - двухсимвольный ID языка сайта
  • ACTIVE - флаг активности (Y|N)

См. также

  • Поля CSite
  • CSite::GetByID
  • Класс CDBResult

Примеры использования

<?
$rsSites = CSite::GetList($by="sort", $order="desc", Array("NAME" => "www.mysite.ru"));
while ($arSite = $rsSites->Fetch())
{
  echo "<pre>"; print_r($arSite); echo "</pre>";
}
?>


Update

CSite::Update

bool
CSite::Update(
 int id,
 array fields
)

Функция изменяет параметры сайта. Возвращает "true", если изменение прошло успешно, при возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
id | ID сайта.
fields | Массив значений полей вида array("поле"=>"значение" [, ...]).

См. также

  • Поля CSite
  • CSite::Add
  • CSite::Delete

Примеры использования

<?
$arFields = Array(
  "ACTIVE"           => "Y",
  "SORT"             => 200,
  "DEF"              => "N",
  "NAME"             => "www.site.com",
  "DIR"              => "/ru/",
  "FORMAT_DATE"      => "DD.MM.YYYY",
  "FORMAT_DATETIME"  => "DD.MM.YYYY HH:MI:SS",
  "CHARSET"          => "windows-1251",
  "SITE_NAME"        => "My site",
  "SERVER_NAME"      => "www.site.com",
  "EMAIL"            => "admin@site.com",
  "LANGUAGE_ID"      => "ru",
  "DOC_ROOT"         => "",
  "DOMAINS"          => "www.site.com \n site.com"
  );
$obSite = new CSite;
$obSite->Update("ru", $arFields);
if (strlen($obSite->LAST_ERROR)>0) $strError .= $obSite->LAST_ERROR;
?>


Класс CUser

CUser - класс для работы с пользователями.

При запуске каждой страницы автоматически создаётся объект этого класса $USER - данные о текущем пользователе.

Поля

Поле | Тип | Описание
ID | int | ID пользователя.
XML_ID | int | ID пользователя для связи с внешними источниками (например, ID пользователя в какой-либо внешний базе).
TIMESTAMP_X | datetime | Последнее изменение.
LOGIN | varchar (50) | Имя входа.
PASSWORD | varchar (50) | Хеш от пароля.
STORED_HASH | varchar (32) | Хеш от пароля хранимый в куках пользователя.
CHECKWORD | varchar (50) | Контрольная строка для смены пароля.
ACTIVE | char | Активен (Y|N).
NAME | varchar (50) | Имя.
LAST_NAME | varchar (50) | Фамилия.
EMAIL | varchar (255) | E-mail адрес.
LAST_LOGIN | datetime | Дата последней авторизации.
DATE_REGISTER | datetime | Дата регистрации.
LID | char (2) | ID сайта по умолчанию для уведомлений.
ADMIN_NOTES | varchar (2000) | Заметки администратора.
EXTERNAL_AUTH_ID | varchar (255) | Код источника внешней авторизации.
Личные данные:
PERSONAL_PROFESSION | varchar (255) | Профессия.
PERSONAL_WWW | varchar (255) | WWW-страница.
PERSONAL_ICQ | varchar (255) | ICQ.
PERSONAL_GENDER | char (1) | Пол.
PERSONAL_BIRTHDAY | date | Дата рождения.
PERSONAL_PHOTO | int | Фотография.
PERSONAL_PHONE | varchar (255) | Телефон.
PERSONAL_FAX | varchar (255) | Факс.
PERSONAL_MOBILE | varchar (255) | Мобильный телефон.
PERSONAL_PAGER | varchar (255) | Пэйджер.
PERSONAL_STREET | varchar (2000) | Улица, дом.
PERSONAL_MAILBOX | varchar (255) | Почтовый ящик.
PERSONAL_CITY | varchar (255) | Город.
PERSONAL_STATE | varchar (255) | Область / край.
PERSONAL_ZIP | varchar (255) | Индекс.
PERSONAL_COUNTRY | varchar (255) | Страна.
PERSONAL_NOTES | varchar (2000) | Дополнительные заметки.
Информация о работе:
WORK_COMPANY | varchar (255) | Наименование компании.
WORK_DEPARTMENT | varchar (255) | Департамент / Отдел.
WORK_POSITION | varchar (255) | Должность.
WORK_WWW | varchar (255) | WWW-страница.
WORK_PHONE | varchar (255) | Телефон.
WORK_FAX | varchar (255) | Факс.
WORK_PAGER | varchar (255) | Пэйджер.
WORK_STREET | varchar (2000) | Улица, дом.
WORK_MAILBOX | varchar (255) | Почтовый ящик.
WORK_CITY | varchar (255) | Город.
WORK_STATE | varchar (255) | Область / край.
WORK_ZIP | varchar (255) | Индекс.
WORK_COUNTRY | varchar (255) | Страна.
WORK_PROFILE | varchar (2000) | Направления деятельности.
WORK_LOGO | int | Логотип.
WORK_NOTES | varchar (2000) | Дополнительные заметки.

Методы класса

Метод | Описание
GetList | Возвращает список пользователей.
GetByID | Возвращает пользователя по его ID.
GetByLogin | Возвращает пользователя по его логину.
GetUserGroup | Возвращает ID всех групп, которым принадлежит пользователь.
Add | Создает нового пользователя.
Update | Изменяет параметры пользователя.
Delete | Удаляет пользователя.
GetID | Возвращает ID текущего авторизованного пользователя.
GetLogin | Возвращает логин текущего авторизованного пользователя.
GetEmail | Возвращает E-Mail текущего авторизованного пользователя.
GetFullName | Возвращает имя и фамилию текущего авторизованного пользователя.
GetFirstName | Возвращает имя текущего авторизованного пользователя.
GetLastName | Возвращает фамилию текущего авторизованного пользователя.
GetParam | Возвращает один из параметров пользователя.
GetUserGroupArray | Возвращает ID всех групп которым принадлежит текущий пользователь.
GetUserGroupString | Возвращает строку с перечисленными группами пользователя.
IsAdmin | Проверяет принадлежность пользователя группе администраторов.
IsAuthorized | Проверяет авторизован ли пользователь.
Login | Авторизует пользователя по введенному логину.
LoginByHash | Авторизует пользователя по хранимому в куках хешу.
SavePasswordHash | Сохраняет специальный хеш в куках пользователя в целях дальнейшей автоматической авторизации.
GetPasswordHash | Возвращает специальный хеш от пароля пользователя который может быть использован в функциях LoginByHash и SavePasswordHash.
Authorize | Непосредственно осуществляет процесс авторизации пользователя. Инициализирует необходимые сессионные переменные и переменные объекта класса CUser.
Logout | Заканчивает сеанс авторизации пользователя.
Register | Создает нового пользователя, авторизует его и отсылает письмо по шаблону типа NEW_USER.
SimpleRegister | Создает нового пользователя с генерацией логина и пароля, затем авторизует его. На вход функции поступает только E-Mail.
ChangePassword | Изменяет пароль пользователя.
SendPassword | Создает почтовое событие для отправки пользователю сообщения для смены пароля.
SendUserInfo | Создает почтовое событие для отправки пользователю сообщения с его параметрами.
GetCount | Возвращает количество пользователей в базе.


SendPassword

CUser::SendPassword

array
CUser::SendPassword(
 string login,
 string email,
 string site_id = SITE_ID
)

Отсылает пользователю почтовое сообщение с контрольной строкой для смены пароля. Сообщение отсылается по шаблону типа USER_INFO. Пользователь определяется по логину login или E-Mail адресу - параметр email. Возвращает массив с сообщением о результате выполнения (массив может быть обработан функцией ShowMessage).

Параметры функции

Параметр | Описание
login | Логин пользователя.
email | E-Mail адрес пользователя.
site_id | ID сайта почтового шаблона типа USER_INFO. Необязательный. По умолчанию - текущий сайт.

См. также

  • CUser::SendUserInfo
  • CUser::ChangePassword

Примеры использования

<?
global $USER;
$arResult = $USER->SendPassword($USER->GetLogin(), $USER->GetParam("EMAIL"));
if($arResult["TYPE"] == "OK") echo "Контрольная строка для смены пароля выслана.";
else echo "Введенные логин (email) не найдены.";
?>


SendUserInfo

CUser::SendUserInfo

CUser::SendUserInfo(
 int user_id,
 string site_id,
 string message
)

Отсылает почтовое сообщение с параметрами пользователя по шаблону типа USER_INFO.

Параметры функции

Параметр | Описание
user_id | ID пользователя.
site_id | ID сайта почтового шаблона.
message | Произвольный текст сообщения (#MESSAGE#).

См. также

  • SendPassword

Примеры использования

<?
$USER_ID = 1;
// отсылаем почтовое сообщение пользователю с ID=1,
// по шаблону привязанному к текущему сайту
CUser::SendUserInfo($USER_ID, SITE_ID, "Приветствуем Вас как нового пользователя нашего сайта!");
?>


SetParam

CUser::SetParam

CUser::SetParam(
 string param_name,
 mixed param_value
)

Метод устанавливает произвольный параметр пользователя param_name для хранения в сессии авторизации (как правило вызывается для объекта $USER). Получить значение установленного параметра можно методом CUser::GetParam.

Параметры функции

Параметр | Описание
param_name | Произвольный параметр.
param_value | Значение параметра.

См. также

  • CUser::GetParam

Примеры использования

<?
global $USER;
$USER->SetParam("IP_LOGIN", $_SERVER['REMOTE_ADDR']);
?>


SetUserGroup

CUser::SetUserGroup

CUser::SetUserGroup(
   int user_id,
   array groups
);

Метод устанавливает привязку пользователя user_id к группам groups. Привязка к группам сохраняется в базе данных, но не влияет на уже авторизованного посетителя user_id.

Параметры функции

Параметр | Описание
user_id | Идентификатор пользователя.
groups | Массив со значениями идентификаторов групп пользователей.

См. также

  • CUser::GetUserGroup

Примеры использования

<?
// привязка пользователя с кодом 10 дополнительно к группе c кодом 5
$arGroups = СUser::GetUserGroup(10);
$arGroups[] = 5;
CUser::SetUserGroup(10, $arGroups);
?>


SetUserGroupArray

CUser::SetUserGroupArray

CUser::SetUserGroupArray(
   array groups
);

Метод устанавливает привязку текущего пользователя к группам groups (как правило вызывается для объекта $USER). Привязка к группам не сохраняется в базе данных и при следующей авторизации теряется. Для сохранения привязки в базе данных воспользуйтесь функцией CUser::SetUserGroup.

Параметры функции

Параметр | Описание
groups | Массив со значениями идентификаторов групп пользователей.

См. также

  • CUser::GetUserGroupArray

Примеры использования

<?
// привязка текущего пользователя дополнительно к группе c кодом 5
global $USER;
$arGroups = $USER->GetUserGroupArray();
$arGroups[] = 5;
$USER->SetUserGroupArray($arGroups);
?>


SimpleRegister

CUser::SimpleRegister

array
CUser::SimpleRegister(
 string email,
 string site_id = SITE_ID
)

Создает нового пользователя предварительно сгенерировав случайный логин и пароль. Возвращает массив с сообщением о результате выполнения (массив может быть обработан функцией ShowMessage).

Функция может использоваться только в публичной части сайта!

Параметры функции

Параметр | Описание
email | E-Mail нового пользователя (не менее 3-х символов). E-Mail будет проверен функцией check_email.
site_id | ID сайта почтового шаблона для отсылки уведомлений (NEW_USER, USER_INFO и др.). Необязательный. По умолчанию - текущий сайт.

См. также

  • CUser::Register
  • CUser::Login
  • CUser::Add
  • CUser::Authorize
  • Событие "OnAfterUserSimpleRegister"
  • Событие "OnBeforeUserSimpleRegister"

Примеры использования

<?
global $USER;
$arResult = $USER->SimpleRegister("admin@mysite.ru");
ShowMessage($arResult); // выводим результат в виде сообщения
echo $USER->GetID(); // ID нового пользователя
?>


Update

CUser::Update

bool
CUser::Update(
 int id,
 array fields
)

Функция изменяет параметры пользователя с идентификатором id. Возвращает "true", если изменение прошло успешно, при возникновении ошибки функция вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

Параметры функции

Параметр | Описание
id | ID пользователя.
fields | Массив значений полей вида array("поле"=>"значение" [, ...]). В качестве полей могут быть использованы все поля CUser, а также GROUP_ID - массив с ID групп пользователей, в которые входит этот пользователь.

См. также

  • Поля CUser
  • CUser::Add
  • CUser::Delete

Примеры использования

<?
$user = new CUser;
$fields = Array(
  "NAME"              => "Сергей",
  "LAST_NAME"         => "Иванов",
  "EMAIL"             => "ivanov@microsoft.com",
  "LOGIN"             => "ivan",
  "LID"               => "ru",
  "ACTIVE"            => "Y",
  "GROUP_ID"          => array(1,2),
  "PASSWORD"          => "123456",
  "CONFIRM_PASSWORD"  => "123456",
  );
$user->Update($ID, $fields);
$strError .= $user->LAST_ERROR;
?>


Add

CUser::Add

mixed
CUser::Add(
 array fields
)

Функция добавляет нового пользователя. При успешном выполнении возвращает ID нового пользователя, в противном случае - вернет "false", а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

CUser::Add() можно вызывать только как метод инициализированного объекта, а не как статический метод класса CUser.

Параметры функции

Параметр Описание
fields Массив значений полей, в качестве ключей данного массива допустимо использовать:
  • LOGIN* - логин (имя входа)
  • NAME - имя пользователя
  • LAST_NAME - фамилия пользователя
  • EMAIL* - E-Mail адрес пользователя
  • PASSWORD* - пароль пользователя
  • CONFIRM_PASSWORD* - подтверждение пароля (должно быть равным PASSWORD)
  • GROUP_ID - массив ID групп к которым будет приписан пользователь
  • ACTIVE - флаг активности пользователя [Y|N]
  • LID - ID сайта по умолчанию для уведомлений
  • ADMIN_NOTES - заметки администратора
  • XML_ID - ID пользователя для связи с внешними источниками (например, ID пользователя в какой-либо внешний базе)
  • EXTERNAL_AUTH_ID - код источника внешней авторизации
  • PERSONAL_PROFESSION - наименование профессии
  • PERSONAL_WWW - персональная WWW-страница
  • PERSONAL_ICQ - ICQ
  • PERSONAL_GENDER - пол ["M" - мужчина; "F" - женщина]
  • PERSONAL_BIRTHDAY - дата рождения в формате текущего сайта (или текущего языка для административной части)
  • PERSONAL_PHOTO - массив описывающий фотографию, допустимы следующие ключи этого массива:
    • name - имя файла
    • size - размер файла
    • tmp_name - временный путь на сервере
    • type - тип загружаемого файла
    • del - если значение равно "Y", то изображение будет удалено
    • MODULE_ID - идентификатор главного модуля - "main"
  • PERSONAL_PHONE - телефон
  • PERSONAL_FAX - факс
  • PERSONAL_MOBILE - мобильный телефон
  • PERSONAL_PAGER - пэйджер
  • PERSONAL_STREET - улица, дом
  • PERSONAL_MAILBOX - почтовый ящик
  • PERSONAL_CITY - город
  • PERSONAL_STATE - область / край
  • PERSONAL_ZIP - индекс
  • PERSONAL_COUNTRY - страна
  • PERSONAL_NOTES - личные заметки
  • WORK_COMPANY - наименование компании
  • WORK_DEPARTMENT - департамент / отдел
  • WORK_POSITION - должность
  • WORK_WWW - WWW-страница компании
  • WORK_PHONE - рабочий телефон
  • WORK_FAX - рабочий факс
  • WORK_PAGER - рабочий пэйджер
  • WORK_STREET - улица, дом компании
  • WORK_MAILBOX - почтовый ящик компании
  • WORK_CITY - город компании
  • WORK_STATE - область / край компании
  • WORK_ZIP - индекс компании
  • WORK_COUNTRY - страна компании
  • WORK_PROFILE - направления деятельности компании
  • WORK_LOGO - массив описывающий логотип компании, допустимы следующие ключи этого массива:
    • name - имя файла
    • size - размер файла
    • tmp_name - временный путь на сервере
    • type - тип загружаемого файла
    • del - если значение равно "Y", то изображение будет удалено
    • MODULE_ID - идентификатор главного модуля - "main"
  • WORK_NOTES - заметки касаемо работы пользователя
* - обязательные поля.

См. также

  • Поля CUser
  • CUser::Update
  • CUser::Delete

Примеры использования

<?
// создадим массив описывающий изображение
// находящееся в файле на сервере
$arIMAGE = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/photo.gif");
$arIMAGE["MODULE_ID"] = "main";

$user = new CUser;
$arFields = Array(
  "NAME"              => "Сергей",
  "LAST_NAME"         => "Иванов",
  "EMAIL"             => "ivanov@microsoft.com",
  "LOGIN"             => "ivan",
  "LID"               => "ru",
  "ACTIVE"            => "Y",
  "GROUP_ID"          => array(1,2),
  "PASSWORD"          => "123456",
  "CONFIRM_PASSWORD"  => "123456",
  "PERSONAL_PHOTO"    => $arIMAGE
);

$ID = $user->Add($arFields);
if (intval($ID) > 0)
    echo "Пользователь успешно добавлен.";
else
    echo $user->LAST_ERROR;
?>


Authorize

CUser::Authorize

bool
CUser::Authorize(
 int user_id
)

Функция непосредственно осуществляет процесс авторизации пользователя. Инициализирует необходимые сессионные переменные и переменные объекта класса CUser. Если авторизация успешна, то возвращает "true", иначе - "false".

Параметры функции

Параметр | Описание
user_id | ID пользователя.

См. также

  • CUser::Login
  • CUser::LoginByHash
  • CUser::IsAuthorized
  • Событие "OnAfterUserAuthorize"

Примеры использования

<?
// пример динамического добавления текущего пользователя в группу
// и его дальнейшая переавторизация
global $USER;
$arrGroups_new = array(3,4); // в какие группы хотим добавить
$arrGroups_old = $USER->GetUserGroupArray(); // получим текущие группы
$arrGroups = array_unique(array_merge($arrGroups_old, $arrGroups_new)); // объединим два массива и удалим дубли
$USER->Update($USER->GetID(), array("GROUP_ID" => $arrGroups)); // обновим профайл пользователя в базе
$USER->Authorize($USER->GetID()); // авторизуем
?>


ChangePassword

CUser::ChangePassword

array
CUser::ChangePassword(
 string login,
 string checkword,
 string new_password,
 string new_password_confirmation,
 string site_id = SITE_ID
)

Изменяет пароль пользователя, затем вызывает на исполнение функцию CUser::SendUserInfo, которая в свою очередь отсылает почтовое сообщение по шаблону типа USER_INFO. Возвращает массив с сообщением о результате выполнения (массив может быть обработан функцией ShowMessage).

Параметры функции

Параметр | Описание
login | Логин пользователя.
checkword | Контрольная строка для смены пароля.
new_password | Новый пароль.
new_password_confirmation | Подтверждение пароля (для успешной смены пароля он должен совпадать с new_password).
site_id | ID сайта почтового шаблона типа USER_INFO для отсылки уведомления. Необязательный. По умолчанию - текущий сайт.

См. также

  • CUser::SendPassword
  • CUser::SendUserInfo
  • CUser::Update

Примеры использования

<?
global $USER;
$arResult = $USER->ChangePassword("admin", "WRD45GT", "123456", "123456");
if($arResult["TYPE"] == "OK") echo "Пароль успешно сменен.";
else ShowMessage($arResult);
?>


Delete

CUser::Delete

CDBResult
CUser::Delete(
 int id
)

Функция удаляет пользователя. Возвращается объект CDBResult.

Параметры функции

Параметр | Описание
id | ID пользователя.

См. также

  • CUser::Add
  • CUser::Update
  • Событие "OnBeforeUserDelete"
  • Событие "OnUserDelete"

Примеры использования

<?
if (CUser::Delete(1)) echo "Пользователь удален.";
?>


GetByID

CUser::GetByID

CDBResult
CUser::GetByID(
 int id
)

Возвращает пользователя по его коду id в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
id | ID пользователя.

См. также

  • Поля CUser
  • CUser::GetList
  • CUser::GetByLogin

Примеры использования

<?
$rsUser = CUser::GetByID(23);
$arUser = $rsUser->Fetch();
echo "<pre>"; print_r($arUser); echo "</pre>";
?>


GetByLogin

CUser::GetByLogin

CDBResult
CUser::GetByLogin(
 string login
)

Возвращает пользователя по его логину login в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
login | Логин пользователя.

См. также

  • Поля CUser
  • CUser::GetList
  • CUser::GetByID

Примеры использования

<?
$rsUser = CUser::GetByLogin("admin");
$arUser = $rsUser->Fetch();
echo "<pre>"; print_r($arUser); echo "</pre>";
?>


GetCount

CUser::GetCount

int
CUser::GetCount()

Возвращает количество всех пользователей зарегистрированных на сайте.

Параметры функции

Без параметров.

Примеры использования

<?
echo "На сегодняшний день у нас зарегистрировалось пользователей: ".CUser::GetCount();
?>


GetEmail

CUser::GetEmail

string
CUser::GetEmail()

Возвращает E-Mail текущего авторизованного пользователя (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Поля CUser
  • CUser::GetID
  • CUser::GetFullName
  • CUser::GetFirstName
  • CUser::GetLastName
  • CUser::GetParam
  • CUser::GetUserGroup
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "Ваш E-Mail: ".$USER->GetEmail();
?>


GetExternalAuthList

CUser::GetExternalAuthList

CDBResult CUser::GetExternalAuthList();

Возвращает список всех источников внешней авторизации. Чтобы зарегистрировать свой внешний источник авторизации, необходимо установить обработчик события OnExternalAuthList.

Возвращаемое значение

Возвращается объект CDBResult, каждая запись которого состоит из двух полей ID - идентификатор внешнего источника, NAME - название внешнего источника.

См. также

  • Внешняя авторизация
  • OnExternalAuthList
  • Класс CDBResult

Примеры использования

<?
$rExtAuth = CUser::GetExternalAuthList();
if($arExtAuth = $rExtAuth->GetNext()):
    ?><select name="EXTERNAL_AUTH_ID">
    <option value="">(внутренняя авторизация)</option>
    <?do{?>
        <option value="<?=$arExtAuth['ID']?>"<?
            if($str_EXTERNAL_AUTH_ID==$arExtAuth['ID']) echo ' selected';
        ?>><?=$arExtAuth['NAME']?></option>
    <?}while($arExtAuth = $rExtAuth->GetNext());?>
    </select>
<?endif?>


GetFirstName

CUser::GetFirstName

string
CUser::GetFirstName()

Возвращает имя авторизованного пользователя (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Поля CUser
  • CUser::GetID
  • CUser::GetLogin
  • CUser::GetEmail
  • CUser::GetFullName
  • CUser::GetLastName
  • CUser::GetParam
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "[".$USER->GetID()."] (".$USER->Login().") ".$USER->GetFirstName()." ".$USER->GetLastName();
?>


GetFullName

CUser::GetFullName

string
CUser::GetFullName()

Возвращает имя и фамилию авторизованного пользователя разделенные пробелом (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Поля CUser
  • CUser::GetID
  • CUser::GetLogin
  • CUser::GetEmail
  • CUser::GetFirstName
  • CUser::GetLastName
  • CUser::GetParam
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "[".$USER->GetID()."] (".$USER->Login().") ".$USER->GetFullName();
?>


GetID

CUser::GetID

int
CUser::GetID()

Возвращает ID текущего авторизованного пользователя (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Поля CUser
  • CUser::GetLogin
  • CUser::GetEmail
  • CUser::GetFullName
  • CUser::GetFirstName
  • CUser::GetLastName
  • CUser::GetParam
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "[".$USER->GetID()."] (".$USER->GetLogin().") ".$USER->GetFullName();
?>


GetLastName

CUser::GetLastName

string
CUser::GetLastName()

Возвращает фамилию авторизованного пользователя (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Поля CUser
  • CUser::GetID
  • CUser::GetLogin
  • CUser::GetEmail
  • CUser::GetFullName
  • CUser::GetFirstName
  • CUser::GetParam
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "[".$USER->GetID()."] (".$USER->Login().") ".$USER->GetFirstName()." ".$USER->GetLastName();
?>


GetList

CUser::GetList

CDBResult
CUser::GetList(
 string &by = "timestamp_x",
 string &order = "desc",
 array filter
)

Возвращает список пользователей в виде объекта класса CDBResult.

Параметры функции

Параметр Описание
by ссылка на переменную с полем для сортировки, может принимать значения:
  • id - ID пользователя
  • active - активность
  • last_login - дата последней авторизации
  • login - имя входа
  • email - E-Mail адрес
  • name - имя
  • last_name - фамилия
  • timestamp_x - дата изменения
  • date_register - дата регистрации
  • personal_profession - профессия
  • personal_www - WWW-страница
  • personal_icq - номер ICQ
  • personal_gender - пол ("M" - мужской; "F" - женский)
  • personal_birthday - день рождения
  • personal_photo - ID файла-фотографии
  • personal_phone - номер телефона
  • personal_fax - номер факса
  • personal_mobile - номер мобильного
  • personal_pager - номер пейджера
  • personal_street - улица
  • personal_mailbox - почтовый ящик
  • personal_city - город
  • personal_state - область / край
  • personal_zip - почтовый индекс
  • personal_country - код страны
  • personal_notes - дополнительные заметки
  • work_company - наименования компании
  • work_department - отдел
  • work_position - должность
  • work_www - WWW-страница компании
  • work_phone - рабочий телефон
  • work_fax - рабочий факс
  • work_pager - рабочий пейджер
  • work_street - улица компании
  • work_mailbox - почтовый ящик компании
  • work_city - город компании
  • work_state - область / край компании
  • work_zip - почтовый индекс компании
  • work_country - код страны компании
  • work_profile - направление деятельности компании
  • work_notes - дополнительные заметки касаемо места работы
  • admin_notes - комментарий администратора
оrder Ссылка на переменную с порядком сортировки
может принимать значения
  • asc - по возрастанию
  • desc - по убыванию
filter Массив для фильтрации пользователей. В массиве допустимы следующие индексы:
  • 1ID - по ID пользователя
  • TIMESTAMP_1 - дата изменения профайла пользователя "с"
  • TIMESTAMP_2 - дата изменения профайла пользователя "по"
  • LAST_LOGIN_1 - дата последнего логина пользователя "с"
  • LAST_LOGIN_2 - дата последнего логина пользователя "по"
  • ACTIVE - фильтр по активности (Y|N)
  • 1LOGIN_EQUAL - по имени входа (ищет прямое совпадение с логином)
  • 1LOGIN - по имени входа (ищет подстроку в логине)
  • 1NAME - по имени и фамилии
  • 1EMAIL - по E-Mail адресу
  • 1COUNTRY_ID - по коду страны
  • GROUPS_ID - по группам (массив с кодами групп пользователей)
  • PERSONAL_BIRTHDAY_1 - день рождения "с"
  • PERSONAL_BIRTHDAY_2 - день рождения "по"
  • 1KEYWORDS - по нижеследующим полям профайла помеченных символом - *
  • 1* PERSONAL_PROFESSION - профессия
  • 1* PERSONAL_WWW - WWW-страница
  • 1* PERSONAL_ICQ - номер ICQ
  • 1* PERSONAL_GENDER - пол ("M" - мужской; "F" - женский)
  • 1* PERSONAL_PHOTO - ID файла - фотографии (таблица b_file)
  • 1* PERSONAL_PHONE - номер телефона
  • 1* PERSONAL_FAX - номер факса
  • 1* PERSONAL_MOBILE - номер мобильного
  • 1* PERSONAL_PAGER - номер пейджера
  • 1* PERSONAL_STREET - улица
  • 1* PERSONAL_MAILBOX - почтовый ящик
  • 1* PERSONAL_CITY - город
  • 1* PERSONAL_STATE - область / край
  • 1* PERSONAL_ZIP - почтовый индекс
  • 1* PERSONAL_COUNTRY - код страны (хранится в файлах \bitrix\modules\main\lang\ru\tools.php, \bitrix\modules\main\lang\en\tools.php)
  • 1* PERSONAL_NOTES - дополнительные заметки
  • 1* WORK_COMPANY - наименования компании
  • 1* WORK_DEPARTMENT - отдел
  • 1* WORK_POSITION - должность
  • 1* WORK_WWW - WWW-страница компании
  • 1* WORK_PHONE - рабочий телефон
  • 1* WORK_FAX - рабочий факс
  • 1* WORK_PAGER - рабочий пейджер
  • 1* WORK_STREET - улица компании
  • 1* WORK_MAILBOX - почтовый ящик компании
  • 1* WORK_CITY - город компании
  • 1* WORK_STATE - область / край компании
  • 1* WORK_ZIP - почтовый индекс компании
  • 1* WORK_COUNTRY - код страны компании (хранится в файлах \bitrix\modules\main\lang\ru\tools.php, \bitrix\modules\main\lang\en\tools.php)
  • 1* WORK_PROFILE - направление деятельности компании
  • 1* WORK_NOTES - дополнительные заметки касаемо места работы
  • 1* ADMIN_NOTES - комментарий администратора (доступен для просмотра и редактирования только администратору сайта)
1 - в данных полях допускается сложная логика
* - поиск по "KEYWORDS" по сути является поиском по полям отмеченных символом "*"

См. также

  • Поля CUser
  • CUser::GetByID
  • CUser::GetByLogin

Примеры использования

<?
$filter = Array
(
    "ID"                  => "1 | 2",
    "TIMESTAMP_1"         => "04.02.2004", // в формате текущего сайта
    "TIMESTAMP_2"         => "04.02.2005",
    "LAST_LOGIN_1"        => "01.02.2004",
    "ACTIVE"              => "Y",
    "LOGIN"               => "nessy | admin",
    "NAME                 => "Виталий & Соколов",
    "EMAIL"               => "mail@server.com | mail@server.com",
    "KEYWORDS"            => "www.bitrix.ru",
    "PERSONAL_PROFESSION" => "системотехник",
    "PERSONAL_GENDER"     => "M",
    "PERSONAL_COUNTRY"    => "4 | 1", // Беларусь или Россия
    "ADMIN_NOTES"         => "\"UID = 145\"",
    "GROUPS_ID"           => Array(1,4,10)
);
$rsUsers = CUser::GetList(($by="personal_country"), ($order="desc"), $filter); // выбираем пользователей
$is_filtered = $rsUsers->is_filtered; // отфильтрована ли выборка ?
$rsUsers->NavStart(50); // разбиваем постранично по 50 записей
echo $rsUsers->NavPrint(GetMessage("PAGES")); // печатаем постраничную навигацию
while($rsUsers->NavNext(true, "f_")) :
    echo "[".$f_ID."] (".$f_LOGIN.") ".$f_NAME." ".$f_LAST_NAME."<br>";
endwhile;
?>


GetLogin

CUser::GetLogin

string
CUser::GetLogin()

Возвращает логин текущего авторизованного пользователя (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Поля CUser
  • CUser::GetID
  • CUser::GetEmail
  • CUser::GetFullName
  • CUser::GetFirstName
  • CUser::GetLastName
  • CUser::GetParam
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "[".$USER->GetID()."] (".$USER->GetLogin().") ".$USER->GetFullName();
?>


GetParam

CUser::GetParam

mixed
CUser::GetParam(
 string param_name
)

Возвращает один из параметров пользователя хранимых в сессии авторизации (как правило вызывается с объекта $USER).

Параметры функции

Параметр Описание
param_name Название параметра. Возможны следующие значения:
  • AUTHORIZED - если пользователь авторизован, то "Y"
  • USER_ID - ID пользователя
  • LOGIN - логин
  • EMAIL - E-mail
  • NAME - полное имя
  • GROUPS - массив групп, которым принадлежит пользователь
  • ADMIN - true, если пользователь принадлежит группе администраторов
  • PASSWORD_HASH - хэш от пароля пользователя (md5)
  • FIRST_NAME - имя пользователя
  • LAST_NAME - фамилия пользователя

См. также

  • Поля CUser
  • CUser::IsAdmin
  • CUser::IsAuthorized
  • CUser::GetID
  • CUser::GetLogin
  • CUser::GetEmail
  • CUser::GetFullName
  • CUser::GetFirstName
  • CUser::GetLastName
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
global $USER;
echo "E-Mail: ".$USER->GetParam("EMAIL");
?>


GetPasswordHash

CUser::GetPasswordHash

string
CUser::GetPasswordHash(
 string password_md5
)

Возвращает специальный хеш от пароля пользователя который может быть использован в функциях LoginByHash и SavePasswordHash.

Параметры функции

Параметр | Описание
password_md5 | Хtш (MD5) от реального пароля пользователя. Для текущего авторизованного пользователя MD5 от реального пароля можно получить с помощью функции $USER->GetParam("PASSWORD_HASH"). Для произвольного пользователя MD5 от пароля можно получить с помомщью функции CUser::GetByID (поле "PASSWORD").

См. также

  • CUser::LoginByHash
  • CUser::SavePasswordHash

Примеры использования

<?
function SetCurrentUserAuthCookie()
{
  global $USER;
  $hash = CUser::GetPasswordHash($USER->GetParam("PASSWORD_HASH"));
  $name = COption::GetOptionString("main", "cookie_name", "BITRIX_SM")."_UIDH";
  @setcookie($name, $hash, time()+60*60*24*30*60, "/");
}
?>


GetUserGroup

CUser::GetUserGroup

array
CUser::GetUserGroup(
 int id
)

Возвращает массив ID групп, которым принадлежит пользователь с кодом id.

Параметры функции

Параметр | Описание
id | ID пользователя.

См. также

  • Класс CGroup
  • CUser::GetUserGroupArray
  • CUser::GetUserGroupString

Примеры использования

<?
// получим массив групп пользователя ID=12
$arGroups = CUser::GetUserGroup(12);
echo "<pre>"; print_r($arGroups); echo "</pre>";
?>


GetUserGroupArray

CUser::GetUserGroupArray

array
CUser::GetUserGroupArray()

Метод возвращает ID групп которым принадлежит текущий авторизованный пользователь (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Класс CGroup
  • CUser::GetUserGroupString
  • CUser::GetUserGroup

Примеры использования

<?
// получим массив групп текущего пользователя
global $USER;
$arGroups = $USER->GetUserGroupArray();
echo "<pre>"; print_r($arGroups); echo "</pre>";
?>


GetUserGroupString

CUser::GetUserGroupString

string
CUser::GetUserGroupString()

Метод возвращает строку c перечисленными через запятую ID всех групп которым принадлежит текущий авторизованный пользователь (как правило вызывается с объекта $USER).

Параметры функции

Без параметров.

См. также

  • Класс CGroup
  • CUser::GetUserGroupArray
  • CUser::GetUserGroup

Примеры использования

<?
// получим массив групп текущего пользователя
global $USER;
$strGroups = $USER->GetUserGroupString();
echo $strGroups; // "1,2,3"
?>


IsAdmin

CUser::IsAdmin

bool
CUser::IsAdmin()

Проверяет принадлежность текущего авторизованного пользователя группе администраторов (как правило вызывается с объекта $USER). Возращает "true" - если пользователь принадлежит группе администраторов, в противном случае вернет "false".

Параметры функции

Без параметров.

См. также

  • CUser::IsAuthorized
  • CUser::GetParam

Примеры использования

<?
global $USER;
if ($USER->IsAdmin()) echo "Вы администратор!";
?>


IsAuthorized

CUser::IsAuthorized

bool
CUser::IsAuthorized()

Проверяет авторизован ли посетитель сайта (как правило вызывается с объекта $USER). Возвращает "true" если посетитель авторизован, иначе "false".

Параметры функции

Без параметров.

См. также

  • CUser::Authorize
  • CUser::Login
  • CUser::LoginByHash
  • CUser::IsAdmin

Примеры использования

<?
global $USER;
if ($USER->IsAuthorized()) echo "Вы авторизованы!";
?>


Login

CUser::Login

mixed
CUser::Login(
 string login,
 string password,
 string set_auth_cookie = "N",
 string convert_password_to_md5 = "Y"
)

Функция проверяет логин и пароль и если они корректные, то авторизует пользователя. Если авторизация успешная, то возвращает "true", иначе если логин и пароль некорректные, то возвращает массив с ошибкой для функции ShowMessage.

Параметры функции

Параметр | Описание
login | Логин пользователя.
password | Пароль. Если параметр convert_password_to_md5 = "Y", то в данном параметре необходимо передавать оригинальный пароль, в противном случае необходимо передавать md5 от оригинального пароля.
set_auth_cookie | Если значение равно "Y", то авторизация пользователя будет сохранена в куках (при следующем заходе посетитель будет автоматически авторизован), в противном случае - авторизация не будет сохранена в куках. В куках сохраняется специальный хеш получаемый с помощью функции CUser::GetPasswordHash. Затем когда посетитель снова приходит на сайт, система его автоматически авторизует используя функцию CUser::LoginByHash Необязательный. По умолчанию "N".
convert_password_to_md5 | Если значение равно "Y", то это означает что password ещё не сконвертирован в MD5 (т.е. в параметре password передается реальный пароль вводимый пользователем с клавиатуры), если значение равно "N", то это означает что password уже сконвертирован в MD5. Для текущего авторизованного пользователя MD5 от реального пароля можно получить с помощью функции $USER->GetParam("PASSWORD_HASH"). Для произвольного пользователя MD5 от пароля можно получить с помомщью функции CUser::GetByID (поле "PASSWORD"). Необязательный. По умолчанию "Y".

См. также

  • CUser::Authorize
  • CUser::IsAuthorized
  • CUser::LoginByHash
  • CUser::Logout
  • Событие "OnBeforeUserLogin"
  • Событие "OnAfterUserLogin"

Примеры использования

<?
global $USER;
if (!is_object($USER)) $USER = new CUser;
$arAuthResult = $USER->Login("admin", "123456", "Y");
$APPLICATION->arAuthResult = $arAuthResult;
?>
<?
global $USER;
if (!is_object($USER)) $USER = new CUser;
$arAuthResult = $USER->Login("admin", md5("123456"), "Y", "N");
$APPLICATION->arAuthResult = $arAuthResult;
?>


LoginByHash

CUser::LoginByHash

mixed
CUser::LoginByHash(
 string login,
 string cookie_hash
)

Функция проверяет логин и специальный хеш от пароля, который можно получить с помощью функции CUser::GetPasswordHash и если они корректные, то авторизует пользователя. Если авторизация успешная, то возвращает "true", иначе возвращает массив с ошибкой для функции ShowMessage.

Параметры функции

Параметр | Описание
login | Логин пользователя.
cookie_hash | Специальный хеш от пароля пользователя, получаемый с помощью функции CUser::GetPasswordHash. Данный хеш хранится в куках пользователя.

См. также

  • CUser::SavePasswordHash
  • CUser::GetPasswordHash
  • Событие "OnBeforeUserLoginByHash"
  • Событие "OnAfterUserLoginByHash"

Примеры использования

<?
global $USER;
if (!is_object($USER)) $USER = new CUser;
$cookie_login = ${COption::GetOptionString("main", "cookie_name", "BITRIX_SM")."_LOGIN"};
$cookie_md5pass = ${COption::GetOptionString("main", "cookie_name", "BITRIX_SM")."_UIDH"};
$USER->LoginByHash($cookie_login, $cookie_md5pass);
?>


Logout

CUser::Logout

CUser::Logout()

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

Параметры функции

Без параметров.

См. также

  • CUser::Login
  • CUser::Authorize
  • Событие "OnBeforeUserLogout"
  • Событие "OnAfterUserLogout"

Примеры использования

<?
$USER->Logout();
?>


Register

CUser::Register

array
CUser::Register(
 string login,
 string first_name,
 string last_name,
 string password,
 string password_confirmation,
 string email,
 string site_id = SITE_ID
)

Регистрирует нового пользователя, авторизует его и отсылает письмо по шаблону типа NEW_USER. Возвращает массив с сообщением о результате выполнения (массив может быть обработан функцией ShowMessage).

Функция может использоваться только в публичной части сайта!

Параметры функции

Параметр | Описание
login | Логин нового пользователя (не менее 3-х символов).
first_name | Имя нового пользователя (может быть пустым).
last_name | Фамилия нового пользователя (может быть пустым).
password | Пароль (не менее 3-х символов).
password_confirmation | Подтверждение пароля (для успешной регистрации должен совпадать с password).
email | E-Mail нового пользователя (не менее 3-х символов). E-Mail будет проверен функцией check_email.
site_id | ID сайта почтового шаблона для отсылки уведомлений (NEW_USER, USER_INFO и др.). Необязательный. По умолчанию - текущий сайт.

См. также

  • CUser::SimpleRegister
  • CUser::Login
  • CUser::Add
  • CUser::Authorize
  • Событие "OnAfterUserRegister"
  • Событие "OnBeforeUserRegister"

Примеры использования

<?
global $USER;
$arResult = $USER->Register("admin", "", "", "123456", "123456", "admin@mysite.ru");
ShowMessage($arResult); // выводим результат в виде сообщения
echo $USER->GetID(); // ID нового пользователя
?>


SavePasswordHash

CUser::SavePasswordHash

CUser::SavePasswordHash()

Сохраняет специальный хеш в куках пользователя в целях дальнейшей автоматической авторизации. Для разных сайтов на базе "Битрикс: Управление сайтом", функция всегда сохраняет свой уникальный хеш от одного и того же пароля. Таким образом достигается невозможность использовать одно и тоже значение для авторизации на различных сайтах.

Параметры функции

Нет параметров.

См. также

  • CUser::LoginByHash
  • CUser::GetPasswordHash

Примеры использования

<?
global $USER;
if ($USER->IsAuthorized()) $USER->SavePasswordHash();
?>


Класс CUserFieldEnum

CUserFieldEnum - класс для работы с пользовательскими полями типа "список".

Может быть использован для получения отображаемых значений списка по коду. Значения данного класса кешируются управляемым кешем. Управление происходит через константу CACHED_b_user_field_enum. По умолчанию время кеширования 1 час. Для отключения кеширования достаточно определить константу CACHED_b_user_field_enum равной false.

Поля

Поле | Тип | Описание
ID | int | ID значения.
XML_ID | int | ID пользователя для связи с внешними источниками (например, ID пользователя в какой-либо внешний базе)
USER_FIELD_ID | int | Идентификатор пользовательского поля.
VALUE | varchar (255) | Отображаемое значение.
DEF | char | Является значением по умолчанию (Y|N).
SORT | int | Сортировка. Используется при выводе элемента формы.
XML_ID | varchar (255) | ID значения для связи с внешними источниками (например, ID значения в какой-либо внешний базе). Должен быть уникален в пределах одного USER_FIELD_ID.

Методы класса

Метод | Описание
GetList | Возвращает список значений.
SetEnumValues | Изменяет список значений.
DeleteFieldEnum | Полная очиска списка заданного поля.


GetList

CUserFieldEnum::GetList

CDBResult CUserFieldEnum::GetList(
 array aSort = array(),
 array aFilter = array()
)

Возвращает значения списка пользовательского поля в виде объекта класса CDBResult. Для параметра aSort по умолчанию является сортировка по полю SORT, а затем по полю ID по возрастанию.

Параметры функции

Параметр Описание
aSort Массив для сортировки значений. В массиве допустимы следующие ключи:
  • ID - ID значения списка;
  • USER_FIELD_ID - идентификатор пользовательского поля;
  • VALUE - значение для отображения;
  • DEF - флаг умолчания;
  • SORT - сортировка;
  • XML_ID - код внешнего источника.
Значения ключей могут принимать значения:
  • ASC - по возрастанию
  • DESC - по убыванию
aFilter Массив для фильтрации значений. В массиве допустимы следующие ключи:
  • ID - ID значения списка;
  • USER_FIELD_ID - идентификатор пользовательского поля;
  • VALUE - значение для отображения;
  • DEF - флаг умолчания;
  • SORT - сортировка;
  • XML_ID - код внешнего источника.
Значения ключей задают точное соответствие для фильтрации.

См. также

  • Поля CUserFieldEnum

Примеры использования

<?
//Пусть для пользователей определено пользовательское свойство
// типа список с кодом UF_GENDER. Выведем отображаемое значение для
// текущего пользователя.

//Сначала получим значение пользовательского поля:
global $USER;
if(is_object($USER))
{
    $rsUser = CUser::GetList($by, $order,
        array(
            "ID" => $USER->GetID(),
        ),
        array(
            "SELECT" => array(
                "UF_GENDER",
            ),
        )
    );
    if($arUser = $rsUser->Fetch())
    {
        $rsGender = CUserFieldEnum::GetList(array(), array(
            "ID" => $arUser["UF_GENDER"],
        ));
        if($arGender = $rsGender->GetNext())
            echo $arGender["VALUE"];
    }
}
?>


SetEnumValues

CUserFieldEnum::SetEnumValues

CUserFieldEnum::SetEnumValues(
 int FIELD_ID,
 array values
)

Изменение значений списка пользовательского поля.

Параметры функции

Параметр Описание
FIELD_ID Идентификатор пользовательского поля.
values
Массив устанавливаемых значений. Ключами массива служат идентификаторы значений списка, а значения ключей определяют новое содержимое списка.

Если ключ начинается с символа "n", то это будет новое значение списка.

Значение ключа в с вою очередь представляет собой массив. Ключи данного массива:
  • VALUE - значение для отображения, если задана пустая строка, то значение будет удалено из списка;
  • DEF - флаг умолчания (Y|N);
  • SORT - сортировка;
  • XML_ID - код внешнего источника, если не задан, то будет вычислен как md5 от VALUE.
  • DEL - если равен Y, то данное значение будет удалено из списка.
Значения ключей задают точное соответствие для фильтрации.

См. также

  • Поля CUserFieldEnum

Примеры использования

<?
//Пусть для пользователей определено пользовательское свойство
// типа список с кодом UF_GENDER.

//0. определим идентификатор поля.
$arFields = $GLOBALS['USER_FIELD_MANAGER']->GetUserFields("USER");
if(array_key_exists("UF_GENDER", $arFields))
{
    $FIELD_ID = $arFields["UF_GENDER"]["ID"];

    //1. Добавим значение выпадающего списка: "не знаю"

    $obEnum = new CUserFieldEnum;
    $obEnum->SetEnumValues($FIELD_ID, array(
        "n0" => array(
            "VALUE" => "не знаю",
        ),
    ));

    //2. Изменим "не знаю" на "не помню"
    $rsEnum = CUserFieldEnum::GetList(array(), array(
        "VALUE" => "не знаю",
    ));
    if($arEnum = $rsEnum->Fetch())
    {
        $obEnum = new CUserFieldEnum;
        $obEnum->SetEnumValues($FIELD_ID, array(
            $arEnum["ID"] => array(
                "VALUE" => "не помню",
            ),
        ));
    }

    //3. удалим значение "не помню" из списка
    $rsEnum = CUserFieldEnum::GetList(array(), array(
        "VALUE" => "не помню",
    ));
    if($arEnum = $rsEnum->Fetch())
    {
        $obEnum = new CUserFieldEnum;
        $obEnum->SetEnumValues($FIELD_ID, array(
            $arEnum["ID"] => array(
                "DEL" => "Y",
            ),
        ));
    }

}
?>


DeleteFieldEnum

CUserFieldEnum::DeleteFieldEnum

CUserFieldEnum::DeleteFieldEnum(
 int FIELD_ID
)

Удаление ВСЕХ значений списка пользовательского поля. Фактически это удаление справочника.

Параметры функции

Параметр | Описание
FIELD_ID | Идентификатор пользовательского поля.

См. также

  • Поля CUserFieldEnum

Примеры использования

<?
//Пусть для пользователей определено пользовательское свойство
// типа список с кодом UF_GENDER.

//0. определим идентификатор поля.
$arFields = $GLOBALS['USER_FIELD_MANAGER']->GetUserFields("USER");
if(array_key_exists("UF_GENDER", $arFields))
{
    $FIELD_ID = $arFields["UF_GENDER"]["ID"];

    //1. Очистим выпадающий список
    CUserFieldEnum::DeleteFieldEnum($FIELD_ID);
}
?>


Функции главного модуля

При разработке сайта на базе системы "1С-Битрикс: Управление сайтом" можно применять функции следующих групп:

  • Строки - функции для работы со строками и текстом.
  • Массивы - функции для работы с массивами.
  • Даты и время - функции для работы с датами, временем и календарем.
  • Файлы и каталоги - функции для работы с файловой системой сайта.
  • Элементы HTML - функции для автоматического построения элементов форм.
  • Фильтр и сортировка - функции для построения и работы с фильтрами и сортировками.
  • Модули - функции для работы с модульной системой сайта.
  • Языковые файлы - функции для локализации скриптов сайта (для показа сайта на разных языках).
  • Отладка - функции для облегчения отладки сайта.
  • Прочее - прочие функции.


Обзор функций

Функции для обработки строк и текста:

Метод | Описание
TxtToHTML | Конвертирует обычный текст в HTML-код форматирующий исходный текст.
HTMLToTxt | Преобразует исходный HTML-код в обычный текст путём удаления тегов или замены их на эквивалентное текстовое форматирование.
TruncateText | Отсекает от строки все символы свыше указанной длины. Если отсечение произошло, то к строке справа дописывается многоточие.
InsertSpaces | Разбивает длинные слова тексте. Возвращает текст в котором максимальная длина каждого слова не превышает заданной длины.
RandString | Возвращает строку указанной длины, состоящую из случайных символов.
ToUpper | Преобразует символы исходной строки в верхний регистр.
ToLower | Преобразует символы исходной строки в нижний регистр.
htmlspecialcharsEx | Переводит текст в HTML-безопасный вид, заменяя специальные символы их визуальным HTML представлением.
htmlspecialcharsBack | Переводит текст из HTML-безопасного вида в исходное представление.
utf8win1251 | Конвертирует строку из кодировки UTF-8 в Windows-1251.


htmlspecialcharsBack

string
htmlspecialcharsBack(
 string text
);

Переводит текст из HTML-безопасного вида в исходное представление, заменяя в тексте:
Исходные символы | После замены
&lt; | <
&gt; | >
&quot; | "
&amp; | &

Параметры функции

Параметр | Описание
text | Текст для преобразования.

См. также

  • htmlspecialcharsEx

Примеры использования

<?
$text = '&quot;если a&gt;b и b&gt;c, то a&gt;c&quot;'
$res = htmlspecialcharsBack($str);
// в переменной $res будет:
// "если a>b и b>c, то a>c"
?>


htmlspecialcharsEx

string
htmlspecialcharsEx(
 string text
);

Переводит текст в HTML-безопасный вид, заменяя специальные символы их визуальным HTML представлением:
Исходные символы | После замены
< | &lt;
> | &gt;
" | &quot;
&quot; | &amp;quot;
&amp; | &amp;amp;
&lt; | &amp;lt;
&gt; | &amp;gt;

в отличии от стандартной PHP функции htmlspecialchars, данная функция позволяет задавать в тексте символы в виде: &код_символа;

Параметры функции

Параметр | Описание
text | Текст для преобразования.

См. также

  • htmlspecialcharsBack

Примеры использования

<?
$text = '"если a>b и b>c, то a>c"';

$res = htmlspecialcharsEx($text);
// в переменной $res будет:
// &quot;если a&gt;b и b&gt;c, то a&gt;c&quot;

echo $res;
// на экране будет:
// "если a>b и b>c, то a>c"
?>


HTMLToTxt

string
HTMLToTxt(
 string text,
 string host = "",
 array delete = array()
);

Преобразует исходный HTML-код в обычный текст путём удаления тегов или замены их на эквивалентное текстовое форматирование.

Параметры функции

Параметр | Описание
text | Исходный текст в формате HTML.
host | Web-адрес сайта. Если задан, то дописывается перед каждой ссылкой в HTML для формирования абсолютной ссылки. Необязательный параметр. По умолчанию равен - "".
delete | Массив шаблонов регулярных выражений, которые удаляются из текста. Необязательный параметр. По умолчанию - пустой массив.

См. также

  • TxtToHTML

Пример использования

Вызов:
<?
$str = '
<table>
  <tr>
    <td valign=top><b><a href="/ru/products/sitemanager/editions/business.php">Бизнес</a>
  - </B>полная версия продукта для управления интернет-магазином, интеграция
  с "1С:Торговля и Склад", поддержка дилерских сетей.<BR><FONT class=smalltext><b>$1699</B>
  (MySQL-версия)<br><b>$24500</b>
  (Oracle-версия)</font></td>
  </tr>
</table>
<ul>
  <li>Пункт 1</li>
  <li>Пункт 2</li>
  <li>Пункт 3</li>
</ul>
';
echo HTMLToTxt($str, "http://www.bitrix.ru");
?>
Результат:
Бизнес [ http://www.bitrix.ru/ru/products/sitemanager/editions/business.php ]
- полная версия продукта для управления интернет-магазином, интеграция с
"1С:Торговля и Склад", поддержка дилерских сетей.
$1699(MySQL-версия)
$24500 (Oracle-версия)

- Пункт 1
- Пункт 2
- Пункт 3


InsertSpaces

string
InsertSpaces(
 string text,
 int max_length = 80,
 string symbol = " "
);

Разбивает длинные слова тексте. Возвращает текст в котором максимальная длина каждого слова не превышает заданной длины.

Параметры функции

Параметр | Описание
text | Исходный текст.
max_length | Максимальное количество символов в слове. Более длинные слова разбиваются символом заданным в параметре symbol.
symbol | Символ которым будут разбиты слова длина которых превышает max_length.

См. также

  • TruncateText

Примеры использования

<?
$str = "1234567890 1234 123456";
echo InsertSpaces($str, 5);
// результатом будет строчка "12345 67890 1234 12345 6"
?>


RandString

string
RandString(
 int length = 10
);

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

Параметры функции

Параметр | Описание
length | Длина результирующей случайной строки.

Примеры использования

<?
$new_password = RandString(7);
echo "Новый пароль: ".$new_password;
// выводит строку "Новый пароль: fK4ftTP"
?>


ToLower

string
ToLower(
  string text
);

Преобразует символы исходной строки в нижний регистр. Данная функция, помимо символов других алфавитов, корректно конвертирует кириллические символы (русские символы) в нижний регистр.

Данную функцию можно использовать в случае если возникают проблемы с преобразованием кириллических символов стандартной PHP функцией strtolower. Иногда это происходит на некоторых хостингах.

Параметры функции

Параметр | Описание
text | Исходная строка.

См. также

  • ToUpper

Примеры использования

<?
$lower = ToLower("АБВГД ABCDEF");
echo "Нижний регистр: ".$lower;
// выводит строку "Нижний регистр: абвгд abcdef"
?>


ToUpper

string
ToUpper(
  string text
);

Преобразует символы исходной строки в верхний регистр. Данная функция, помимо символов других алфавитов, корректно конвертирует кириллические символы (русские символы) в верхний регистр.

Данную функцию можно использовать в случае если возникают проблемы с преобразованием кириллических символов стандартной PHP функцией strtoupper. Иногда это происходит на некоторых хостингах.

Параметры функции

Параметр | Описание
text | Исходная строка.

См. также

  • ToLower

Примеры использования

<?
$upper = ToUpper("абвгд abcdef");
echo "Верхний регистр: ".$upper;
// выводит строку "Верхний регистр: АБВГД ABCDEF"
?>


TruncateText

string
TruncateText(
 string text,
 int max_length
);

Отсекает от строки все символы свыше указанной длины. Если отсечение произошло, то к строке справа дописывается многоточие.

Параметры функции

Параметр | Описание
text | Исходная строка.
max_length | Длина конечной строки.

См. также

  • InsertSpaces

Примеры использования

<?
$str = "1234567890";
echo TruncateText($str, 7);
// результатом будет строка "1234567..."
?>


TxtToHTML

string
TxtToHTML(
 string text,
 bool make_url = true,
 int max_string = 0,
 string quote_tag_enabled = "N",
 string not_convert_amp = "Y",
 string code_tag_enabled = "N",
 string biu_tags_enabled = "N",
 string quote_table_class = "quotetable",
 string quote_head_class = "tdquotehead",
 string quote_body_class = "tdquote",
 string code_table_class = "codetable",
 string code_head_class = "tdcodehead",
 string code_body_class = "tdcodebody",
 string code_textarea_class = "codetextarea",
 string link_class = "txttohtmllink",
 array  event = array()
);

Конвертирует обычный текст в HTML-код форматирующий исходный текст.

Параметры функции

Параметр | Описание
text | Исходный текст.
make_url Если значение "true", то - преобразовывать подстроки, которые представляют собой web-адреса (http://... или mailto:), в HTML ссылки.
Необязательный параметр. По умолчанию - "true".
max_string Максимальная длина слова. Все слова длиннее этого параметра разбиваются пробелами. Значение "0" - означает "не разбивать слова".
Необязательный параметр. По умолчанию - "0".
quote_tag_enabled Если значение - "Y", то спец. тег <QUOTE>...</QUOTE> (цитата) будет преобразован в HTML таблицу (визуально цитата будет обрамлена рамкой).
Необязательный параметр. По умолчанию - "N".
not_convert_amp Если значение - "Y", то "&" не будет преобразован "&amp;".
Необязательный параметр. По умолчанию - "Y".
code_tag_enabled Если значение - "Y", то спец. тег <CODE>...</CODE> (код) будет преобразован в HTML элемент textarea, в свою очередь обрамленный таблицей (визуально код будет обрамлен рамкой и выведен в textarea).
Необязательный параметр. По умолчанию - "N".
biu_tags_enabled | Если значение - "Y", то спец. теги <b>...</b>, <i>...</i>, <u>...</u> будут преобразованы в соответствующие им HTML теги.
quote_table_class CSS класс на таблицу цитаты (<quote>).
Необязательный параметр. По умолчанию - "quotetable".
quote_head_class CSS класс на первую ячейку (TD) таблицы цитаты (<quote>).
Необязательный параметр. По умолчанию - "tdquotehead".
quote_body_class CSS класс на вторую ячейку (TD) таблицы цитаты (<quote>):
<table class="quote_table_class">
    <tr>
         <td class="quote_head_class"> ...
         </td>
    </tr>
    <tr>
         <td class="quote_body_class"> ...
         </td>
    </tr>
</table>
Необязательный параметр. По умолчанию - "tdquote".
code_table_class CSS класс на таблицу кода (<code>).
Необязательный параметр. По умолчанию - "codetable".
code_head_class CSS класс на первую TD таблицы кода (<code>).
Необязательный параметр. По умолчанию - "tdcodehead".
code_body_class CSS класс на вторую TD таблицы кода (<code>).
Необязательный параметр. По умолчанию - "tdcodebody".
code_textarea_class CSS класс на textarea в таблице кода (<code>):
<table class="code_table_class">
    <tr>
         <td class="code_head_class"> ... </td>
    </tr>
    <tr>
         <td class="code_body_class">
             <textarea class="code_textarea_class"> ...
             </textarea>
         </td>
    </tr>
</table>
Необязательный параметр. По умолчанию - "codetextarea".
link_class CSS класс на ссылках:
<a class="link_class"> ... </a>
Необязательный параметр. По умолчанию - "txttohtmllink".
event В данном массиве можно задать идентификаторы типа события, которое будет фиксироваться при клике на HTML ссылке. Параметр работает, только если make_url == true.

Допустимы следующие ключи данного массива:
  • EVENT1 - идентификатор event1 типа события;
  • EVENT2 - идентификатор event2 типа события;
  • EVENT3 - идентификатор event3 типа события;
  • SCRIPT - путь относительно корня к скрипту фиксирующему событие и осуществляющему редирект.

См. также

  • HTMLToTxt

Пример работы функции

Вызов:

$text = "
текст текст текст текст
текст текст текст текст
длиннноесловодлиннноеслово
<code>код код код</code>
<quote>цитата цитата цитата</quote>
<b>жирный текст</b>
<i>курсив</i>
<u>подчёркнутый</u>
ссылка: http://www.1c-bitrix.ru
email: support@1c-bitrix.ru
";
echo TxtToHTML(
    $text,
    true,
    20,
    "Y",
    "N",
    "Y",
    "Y",
    "quotetable",
    "tdquotehead",
    "tdquote",
    "codetable",
    "tdcodehead",
    "tdcodebody",
    "codetextarea"
    );

Результат:

текст текст текст текст <br>
текст текст текст текст <br>
длиннноесловодлиннн оеслово<br>
<table class='codetable'>
  <tr>
    <td class='tdcodehead'>Код</td>
  </tr>
  <tr>
    <td class='tdcodebody'>
      <textarea class='codetextarea' contentEditable=false cols=60 rows=15 wrap=virtual>код код код</textarea></td>
    </tr>
</table><br>
<table class='quotetable' width='95%' border='0' cellpadding='3' cellspacing='1'>
  <tr>
    <td class='tdquotehead'>Цитата</td>
  </tr>
  <tr>
    <td class='tdquote'>цитата цитата цитата</td>
  </tr>
</table><br>
<b>жирный текст</b><br>
<i>курсив</i><br>
<u>подчёркнутый</u><br>
ссылка: <a class="txttohtmllink" href="http://www.1c-bitrix.ru">http://www.1c-bitrix.ru</a><br>
email: <a class="txttohtmllink" href="mailto:support@1c-bitrix.ru">support@1c-bitrix.ru</a>

CSS (его предварительно необходимо подключить до вызова функции):

.quotetable, .codetable {width:90%}

.quotetable .tdquotehead,
.quotetable .tdquote,
.codetable  .tdcodehead,
.codetable  .tdcodebody,
.codetextarea {padding: 2px; font-family: Arial; font-size:12px; color:#000000}

.quotetable .tdquotehead,
.codetable  .tdcodehead {font-weight:bold}

.quotetable .tdquote,
.codetable  .tdcodebody {border: 1px solid Black}

.quotetable .tdquotehead,
.quotetable .tdquote,
.codetable  .tdcodehead,
.codetable  .tdcodebody,
.codetextarea {background-color: #FFFFFF}

.codetextarea {
  border: solid 0px;
  width: 100%;
  overflow: auto;
  scrollbar-shadow-color: #000000;
  scrollbar-arrow-color:  #000000;
  scrollbar-base-color:   #000000}

.codetextarea {
  scrollbar-face-color:       #FFFFFF;
  scrollbar-highlight-color:  #FFFFFF;
  scrollbar-track-color:      #FFFFFF;
  scrollbar-darkshadow-color: #FFFFFF}

Визуальное представление (то, что мы увидим на экране монитора):

текст текст текст текст
текст текст текст текст
длиннноесловодлиннн оеслово
Код.

Цитата.
цитата цитата цитата.

жирный текст
курсив
подчёркнутый
ссылка: http://www.1c-bitrix.ru
email: support@1c-bitrix.ru


utf8win1251

string
utf8win1251(
  string text
);

Конвертирует строку из кодировки UTF-8 в кодировку Windows 1251.

Параметры функции

Параметр | Описание
text | Исходная строка.

Примеры использования

<?
echo utf8win1251("Р±РёС‚СЂРёРєСЃ");
// выводит строку "битрикс"
?>


Обзор функций

Функции для работы с массивами:

Метод | Описание
TrimArr | Удаляет из массива все элементы с пустыми значениями.
is_set | Проверяет переменную (или ключ массива) на существование.


is_set

bool
is_set(
 mixed &var,
 string key = false
);

Проверяет переменную (или ключ массива) на существование. Возвращает "true", если переменная var установлена, либо найден ключ key среди ключей массива var. В противном случае возвращает "false".

При проверке на существование элемента массива, необходимо учитывать, что в отличии от стандартной функции isset, данная функция возвратит "true", даже если найденный элемент массива имеет значение "null" (см. пример ниже).

Параметры функции

Параметр | Описание
var | В данном параметре может задаваться переменная произвольного типа. Если это массив, то в key необходимо задать ключ, существование которого будет проверено. Если в var задать не массив, то функция просто проверит инициализирована ли данная переменная или нет (в этом случае работа функции будет идентичная стандартной PHP функции isset).
key | Если в var задан массив, то в данном параметре необходимо задать ключ для проверки его наличия в массиве var.

Пример использования

<?

/********************************************
            пример на массиве
********************************************/

$ar = array("a" => "", "b" => null);

if (is_set($ar, "a")) echo 'Ключ "a" в массиве $ar найден.';
else echo 'Ключ "a" в массиве $ar не найден.';
// на экране будет: "Ключ "a" в массиве $ar найден."

if (isset($ar["a"])) echo 'Элемент массива $ar с ключом "a" инициализирован.';
else echo 'Элемент массива $ar с ключом "a" не инициализирован.';
// на экране будет: "Элемент массива $ar с ключом "a" инициализирован."

if (is_set($ar, "b")) echo 'Ключ "b" в массиве $ar найден.';
else echo 'Ключ "b" в массиве $ar не найден.';
// на экране будет: "Ключ "b" в массиве $ar найден."

// НО!
if (isset($ar["b"])) echo 'Элемент массива $ar с ключом "b" инициализирован.';
else echo 'Элемент массива $ar с ключом "b" не инициализирован.';
// (!) на экране будет: "Элемент массива $ar с ключом "b" не инициализирован."

if (is_set($ar, "с")) echo 'Ключ "с" в массиве $ar найден.';
else echo 'Ключ "с" в массиве $ar не найден.';
// на экране будет: "Ключ "с" в массиве $ar не найден."

/********************************************
  пример на обычной переменной (не массиве)
********************************************/

$init_var = "A";
if (is_set($init_var)) echo 'Переменная $init_var инициализированна.';
else echo 'Переменная $init_var не инициализированна.';
// на экране будет: "Переменная $init_var инициализированна."

if (is_set($not_init_var)) echo 'Переменная $init_var инициализированна.';
else echo 'Переменная $init_var не инициализированна.';
// на экране будет: "Переменная $init_var не инициализированна."
?>


TrimArr

bool
TrimArr(
 array &arr
);

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

Параметры функции

Параметр | Описание
arr | Исходный массив. Данный параметр задается в виде ссылки на исходную переменную.

Пример использования

<?
$ar = array(
  "a" => "1",
  "b" => " ",
  "c" => "",
  "d" => "2"
);
TrimArr($ar);
// массив $ar будет выглядеть как array("a" => "1", "d" => "2")
?>


Обзор функций

Функции для работы с датами, временем и календарем:

Метод | Описание
Calendar | Возвращает иконку, при нажатии на которую появляется стандартное окно выбора даты. Выбранная в этом окне дата вставляется в указанное поле формы (либо, в случае выбора интервала - в два поля).
CalendarDate | Возвращает поле ввода и иконку, при нажатии на которую появляется стандартное окно выбора даты. Выбранная в этом окне дата вставляется в поле ввода.
CalendarPeriod | Отображает два поля ввода для дат "с" и "по" с иконками, при нажатии на которые появляется стандартное окно выбора даты, помимо этого рядом с первым полем выводится выпадающий список дней для быстрого выбора даты "с".
ParseDateTime | Разбивает дату и время на части в соответствии с заданным форматом.
ConvertDateTime | Конвертирует дату из формата одного из сайтов в строку произвольного формата.
MakeTimeStamp | Конвертирует время из строки в Unix-формат.
ConvertTimeStamp | Конвертирует время из Unix-формата в строку в формате сайта.
AddToTimeStamp | Добавляет к дате в Unix-формате заданный интервал времени.
getmicrotime | Возвращает текущее время в Unix-формате.

См. также

  • Работа с датой и временем
  • Методы класса CDataBase для работы с датой и временем
  • CheckFilterDates


AddToTimeStamp

int
AddToTimeStamp(
 array add,
 int timestamp = false
);

Добавляет к дате в Unix-формате заданный интервал времени. Возвращает новую дату также в Unix-формате.

Параметры функции

Параметр Описание
add Массив, описывающий добавляемый интервал времени. Допустимы следующие ключи данного массива:
  • DD - дни
  • MM - месяцы
  • YYYY - годы
  • HH - часы
  • MI - минуты
  • SS - секунды
timestamp Время, к которому будет добавляться интервал в Unix-формате.
Необязательный параметр, по умолчанию - текущее время.

См. также

  • MakeTimeStamp
  • ConvertTimeStamp

Примеры использования

$date = "07.04.2005 11:32:00";
echo "Исходная дата: ".$date."<br>";

// получим Unix timestamp из заданной даты
$stmp = MakeTimeStamp($date, "DD.MM.YYYY HH:MI:SS");

// добавим к полученному Unix timestamp
// 1 день, 1 месяц, 1 год, 1 час, 1 минуту, 1 секунду
$arrAdd = array(
    "DD"	=> 1,
    "MM"	=> -1,
    "YYYY"	=> 1,
    "HH"	=> 1,
    "MI"	=> 1,
    "SS"	=> 1,
);
$stmp = AddToTimeStamp($arrAdd, $stmp);

// выведем полученную дату
echo "Результат: ".date("d.m.Y H:i:s", $stmp); // 07.03.2006 12:33:01
?>


Calendar

string
Calendar(
 string field,
 string form = "skform",
 string field_from = "",
 string field_to = ""
);

Возвращает иконку, при нажатии на которую появляется стандартное окно выбора даты. Выбранная в этом окне дата вставляется в указанное поле формы (либо, в случае выбора интервала - в два поля). Работает на JavaScript.

Параметры функции

Параметр | Описание
field | Имя поля, в которое будет вставлена выбранная дата.
form | Имя формы, в которой находится поле для вставки даты. Необязательный параметр, по умолчанию принимает значение "skform".
field_form | Имя поля, в которое будет вставлена первая дата из выбранного интервала (дата "с"). Необязательный параметр, по умолчанию - "".
field_to | Имя поля, в которое будет вставлена вторая дата из выбранного интервала (дата "по"). Необязательный параметр, по умолчанию - "".

См. также

  • CalendarDate
  • CalendarPeriod

Пример использования

<form action="<?=$APPLICATION->GetCurPage()?>" method="POST" name="curform">
<input type="text" class="typeinput" name="DATE" size="12">
<?=Calendar("DATE", "curform")?>
</form>


CalendarDate

string
CalendarDate(
 string field_name,
 string field_value,
 string form = "skform",
 string field_size = "10",
 string field_param = "class=\"typeinput\""
);

Возвращает поле ввода и иконку, при нажатии на которую появляется стандартное окно выбора даты. Выбранная в этом окне дата вставляется в поле ввода. Работает на JavaScript.

Параметры функции

Параметр Описание
field_name Имя поля ввода:
<input type="text" name="field_name" ... >
field_value Начальное значение для поля ввода:
<input type="text" value="field_value" ... >
form Имя формы, в которой находится поле ввода для вставки даты:
<form name="form">
Необязательный параметр, по умолчанию принимает значение - "skform".
field_size Ширина поля ввода:
<input type="text" size="field_size" ... >
Необязательный параметр, по умолчанию принимает значение - "10".
field_param Строка дополнительных атрибутов поля ввода:
<input type="text" field_param ... >
Необязательный параметр, по умолчанию принимает значение - class="typeinput".

См. также

  • Calendar
  • CalendarPeriod

Примеры использования

<form action="<?=$APPLICATION->GetCurPage()?>" method="POST" name="form1">
<?echo CalendarDate("birthdate", "25.11.1975", "form1", "15", "class=\"my_input\"")?>
</form>


CalendarPeriod

string
CalendarPeriod(
 string field_from_name,
 string field_from_value,
 string field_to_name,
 string field_to_value,
 string form = "skform",
 string select_enabled = "N",
 string select_param = "class=\"typeselect\"",
 string fields_param = "class=\"typeinput\"",
 string fields_size = "10"
);

Отображает два поля ввода для дат "с" и "по" с иконками, при нажатии на которые появляется стандартное окно выбора даты, помимо этого рядом с первым полем выводится выпадающий список дней от 1 до 90, если выбрать какое-либо значение из этого списка, то в первое поле ввода будет установлена текущая дата минус то количество дней которое было выбрано. Работает на JavaScript.

Параметры функции

Параметр Описание
field_from_name Имя поля ввода для первой даты ("с"):
<input type="text" name="field_from_name" ... >
field_from_value Начальное значение для первой даты ("с"):
<input type="text" value="field_from_value" ... >
field_to_name Имя поля ввода для второй даты ("по"):
<input type="text" name="field_to_name" ... >
field_to_value Начальное значение для второй даты ("по"):
<input type="text" value="field_to_value" ... >
form Имя формы, в которой находятся поля ввода для вставки дат:
<form name="form">
Необязательный параметр, по умолчанию принимает значение - "skform".
select_enabled Если значение "Y", то список дней, состоящий из цифр от 1 до 90, для быстрого выбора даты, будет выведен.
Необязательный параметр, по умолчанию принимает значение "N" - список не выводить.
select_param Строка дополнительных аттрибутов для списка дней:
<select name="field_from_name_DAYS_TO_BACK" select_param ... >
Необязательный параметр, по умолчанию принимает значение - class="typeselect".
fields_param Строка дополнительных аттрибутов для полей ввода дат:
<input type="text" fields_param ... >
Необязательный параметр, по умолчанию принимает значение - class="typeinput".
fields_size Ширина полей ввода:
<input type="text" size="fields_size" ... >
Необязательный параметр, по умолчанию принимает значение - "10".

См. также

  • Calendar
  • CalendarDate

Примеры использования

<form action="<?=$APPLICATION->GetCurPage()?>" method="POST" name="form1">
<?echo CalendarPeriod("date_from", "25.10.2003", "date_to", "29.10.2003", "form1", "Y")?>
</form>


ConvertDateTime

string
ConvertDateTime(
 string datetime,
 string format = FORMAT_DATETIME,
 mixed site_id = false
);

Конвертирует время из строки в формате сайта в строку произвольного формата.

Параметры функции

Параметр | Описание
datetime | Время в формате сайта site_id.
format Формат времени, в который необходимо сконвертировать. При задании формата допустимо использовать следующие обозначения:
  • YYYY - год
  • MM - месяц
  • DD - день
  • HH - часы
  • MI - минуты
  • SS - секунды
Необязательный параметр. По умолчанию равен константе FORMAT_DATETIME, хранящей текущий формат времени сайта или языка (для административной части).
site_id Идентификатор сайта, в формате которого было задано время time.
Необязательный параметр. По умолчанию - текущий сайт.

См. также

  • CSite::GetDateFormat
  • CDataBase::FormatDate

Примеры использования

<?
echo ConvertDateTime("25.12.2003", "YYYY-MM-DD", "ru"); // 2003-12-25
?>


ConvertTimeStamp

string
ConvertTimeStamp(
 int timestamp = false,
 string format_type = "SHORT",
 mixed site_id = false
);

Конвертирует время из Unix-формата в строку в формате сайта.

Параметры функции

Параметр Описание
timestamp Время в Unix-формате.
Необязательный параметр, по умолчанию - текущее время.
format_type Тип формата. Допустимы следующие значения:
  • FULL - полный (дата и время)
  • SHORT - короткий (дата)
Необязательный параметр, по умолчанию равен "SHORT".
site_id Идентификатор сайта, в формате которого необходимо вернуть дату.
Необязательный параметр. По умолчанию - текущий сайт.

См. также

  • MakeTimeStamp
  • AddToTimeStamp
  • CSite::GetDateFormat
  • CDataBase::DateFormatToPHP

Примеры использования

<?
echo "Сегодня: ".ConvertTimeStamp();
echo "Вчера: ".ConvertTimeStamp(time()-86400);
echo "Позавчера: ".ConvertTimeStamp(time()-(86400*2));
?>
<?
echo ConvertTimeStamp(mktime(0, 0, 0, 10, 25, 2003), "SHORT", "ru"); // 25.10.2003
?>


getmicrotime

float
getmicrotime()

Возвращает текущее время в Unix-формате.

Параметры функции

Без параметров.

Примеры использования

<?
// Алгоритм организации временных засечек
$ptime = getmicrotime();

for ($i=0; $i<10000; $i++);

echo "Цикл выполнялся ".round(getmicrotime()-$ptime, 3)." секунд";
?>


MakeTimeStamp

int
MakeTimeStamp(
 string datetime,
 string format = FORMAT_DATETIME
);

Конвертирует время из строки в Unix-формат.

Параметры функции

Параметр | Описание
datetime | Исходное время.
format_type Формат времени заданном в параметре datetime. В формате допустимы следующие обозначения:
  • YYYY - год
  • MM - месяц
  • DD - день
  • HH - часы
  • MI - минуты
  • SS - секунды
Необязательный параметр. По умолчанию равен константе FORMAT_DATETIME, хранящей текущий формат времени сайта или языка (для административной части).

См. также

  • ConvertTimeStamp
  • AddToTimeStamp
  • ParseDateTime

Примеры использования

<?
// зададим дату
$date = "07.04.2005 11:32:00";

// преобразуем ее в Unix-timestamp
if ($stmp = MakeTimeStamp($date, "DD.MM.YYYY HH:MI:SS"))
{
    // для проверки выведем на экран ту же дату
    // полученную из Unix-timestamp
    echo date("d.m.Y H:i:s", $stmp);
}
else // если функция вернула false то
{
    // выведем сообщение об ошибке
    echo "Некорректная дата!";
}
?>
<?
// вывод даты активности элемента информационного блока
// в произвольном формате

// подключим модуль информационных блоков
if (CModule::IncludeModule("iblock"))
{
    // выберем произвольный элемент информационного блока
    $rsElement = CIBlockElement::GetByID(32675);
    $arElement = $rsElement->Fetch();

    // получим дату активности выбранного элемента
    // выбранную в соответствии с форматом времени текущего сайта
    $date_active = $arElement["ACTIVE_FROM"]; // 28.01.2005

    // получим формат времени текущего сайта
    $site_format = CSite::GetDateFormat(); // DD.MM.YYYY HH:MI:SS

    // преобразуем дату в Unix формат
    if ($stmp = MakeTimeStamp($date_active, $site_format))
    {
        // выведем дату активности выбранного элемента в произвольном виде
        // с помощью стандартной PHP функции date
        echo date("d F Y", $stmp); // 28 January 2005
    }
    else // если преобразование безуспешно то
    {
        // выведем сообщение об ошибке
        ShowError("Некорректная дата активности элемента 32675!");
    }
}
?>


ParseDateTime

mixed
ParseDateTime(
 string datetime,
 string format = FORMAT_DATETIME
);

Разбивает дату и время на части в соответствии с заданным форматом. Функция возвращает массив описывающий дату и время в соответствии с заданным форматом, если произошла ошибка - возвращает "false".

Параметры функции

Параметр | Описание
datetime | Дата и время заданные в соответствии с форматом указанным в параметре format.
format Формат даты и времени. Вы можете использовать любые обозначения, но желательно использовать символы формата даты и времени допустимые в системе, а именно:
  • YYYY - год
  • MM - месяц
  • DD - день
  • HH - часы
  • MI - минуты
  • SS - секунды
Необязательный параметр. По умолчанию равен константе FORMAT_DATETIME, хранящей текущий формат времени сайта или языка (для административной части).

См. также

  • CSite::GetDateFormat
  • CDatabase::DateFormatToPHP
  • CDatabase::FormatDate

Примеры использования

<?
$datetime = "21.01.2004 23:44:15";
$format = "DD.MM.YYYY HH:MI:SS";
echo "Исходное время: ".$datetime."<br>";
echo "Формат: ".$format."<hr>";
if ($arr = ParseDateTime($datetime, $format))
{
    echo "День:    ".$arr["DD"]."<br>";    // День: 21
    echo "Месяц:   ".$arr["MM"]."<br>";    // Месяц: 1
    echo "Год:     ".$arr["YYYY"]."<br>";  // Год: 2004
    echo "Часы:    ".$arr["HH"]."<br>";    // Часы: 23
    echo "Минуты:  ".$arr["MI"]."<br>";    // Минуты: 44
    echo "Секунды: ".$arr["SS"]."<br>";    // Секунды: 15
}
else echo "Ошибка!";
?>
<?
// выведем дату в формате вида "21 января, 2004"

$datetime = "21.01.2004"; // дата задана в формате текущего сайта

// FORMAT_DATETIME - константа содержащая формат времени текущего сайта
$arr = ParseDateTime($datetime, FORMAT_DATETIME);

// 21 января, 2004
echo $arr["DD"]." ".ToLower(GetMessage("MONTH_".intval($arr["MM"])."_S")).", ".$arr["YYYY"];
?>
<?
// вывод даты активности элемента информационного блока
// в произвольном формате

// подключим модуль информационных блоков
if (CModule::IncludeModule("iblock"))
{
    // выберем произвольный элемент информационного блока
    $rsElement = CIBlockElement::GetByID(32675);
    $arElement = $rsElement->Fetch();

    // получим дату активности выбранного элемента
    // выбранную в соответствии с форматом времени текущего сайта
    $date_active = $arElement["ACTIVE_FROM"]; // 28.01.2005

    // получим формат времени текущего сайта
    $site_format = CSite::GetDateFormat(); // DD.MM.YYYY HH:MI:SS

    // получим массив описывающий дату активности выбранного элемента
    if ($arr = ParseDateTime($date_active, $site_format))
    {
        /*
        структура полученного массива $arr:
        Array
        (
            [DD] => 28
            [MM] => 1
            [YYYY] => 2005
            [HH] => 0
            [MI] => 0
            [SS] => 0
        )
        */

        // переведем дату активности в Unix-формат
        $stmp = mktime(
            $arr["HH"], $arr["MI"], $arr["SS"],
            $arr["MM"], $arr["DD"], $arr["YYYY"]
            );

        // выведем дату активности выбранного элемента в произвольном виде
        // с помощью стандартной PHP функции date
        echo date("d F Y", $stmp); // 28 January 2005
    }
}
?>


Обзор функций

Функции для работы с файловой системой сайта:

Метод | Описание
CheckDirPath | Проверяет физическое существование указанного пути. При необходимости - создает все каталоги входящие в данный путь.
CopyDirFiles | Копирует файлы и каталоги.
DeleteDirFiles | Удаление из каталога всех файлов, содержащихся в другом каталоге.
DeleteDirFilesEx | Рекурсивное удаление каталога или файла.
RewriteFile | Перезапись файла.
GetDirPath | Получение каталога по полному пути.
GetPagePath | Получение пути к файлу по заданному URL'у.
GetDirIndex | Определение индексного файла каталога.

См. также

  • Класс CFile
  • Принципы распределения прав в Unix системах
  • Права для новых файлов и каталогов


CheckDirPath

CheckDirPath(
 string abs_path,
 bool set_permissions = true
);

Проверяет физическое существование указанного пути. При необходимости - создает все каталоги входящие в данный путь.

Права на каталоги, которые будут устанавливаться этой функцией, должны быть предварительно определены в константе BX_DIR_PERMISSIONS (в файлах /bitrix/php_interface/dbconn.php или /bitrix/php_interface/ID сайта/init.php). Если константа не определена, то она автоматически инициализируется значением 0777 и далее это значение используется везде когда дело касается установки Unix прав на файлы и каталоги.

Параметры функции

Параметр | Описание
abs_path | Абсолютный путь к папке.
set_permissions | Если значение данного параметра равно "true" и если последний каталог пути указанного в параметре abs_path не доступен для записи, то будет предпринята попытка установить новые права на данный каталог. Значения для этих прав будут браться либо из константы BX_DIR_PERMISSIONS, либо если константа не определена, то она автоматически инициализируется значением 0777 и далее это значение используется везде когда дело касается установки Unix прав на файлы и каталоги.

См. также

  • Принципы распределения прав в Unix системах
  • Права для новых файлов и каталогов

Примеры использования

<?
// файл /bitrix/php_interface/dbconn.php

// определим константы для прав на каталоги и файлы
define("BX_FILE_PERMISSIONS", 0775);
define("BX_DIR_PERMISSIONS", 0775);
?>
<?
// Создадим путь "/temp/data/" начиная от корня сайта, если этого пути нет
CheckDirPath($_SERVER["DOCUMENT_ROOT"]."/temp/data");
?>


CopyDirFiles

bool
CopyDirFiles(
 string from,
 string to,
 bool rewrite = true,
 bool recursive = false,
 bool delete_after_copy = false,
 string exclude = ""
);

Копирует файлы и каталоги. Возвращает "true" при успешном завершении копирования и "false" - в противном случае.

Параметры функции

Параметр | Описание
from | Абсолютный путь к каталогу (файлу), содержимое которой нужно скопировать.
to | Абсолютный путь к каталогу, в который надо скопировать. Путь указанный в данном параметре будет предварительно проверен функцией CheckDirPath.
rewrite | Перезаписывать ли существующие файлы. Необязательный параметр, по умолчанию равен "true" (перезаписывать).
recursive | Копировать ли рекурсивно все подкаталоги и файлы входящие в путь указанный в параметре from. Необязательный параметр, по умолчанию равен "false" (копировать не рекурсивно).
delete_after_copy | Удалить ли путь указанный в параметре from после того как копирование будет завершено (т.е. по сути - сделать перенос каталогов и файлов). Необязательный параметр, по умолчанию равен "false" (не удалять).
exclude | Если данный параметр задан, то из копирования будут исключены файлы / папки, название которых начинается со значения данного параметра.

См. также

  • CFile::CopyFile

Примеры использования

<?
// копируем файлы из папки /temp1/ в папку /temp2/
CopyDirFiles($_SERVER["DOCUMENT_ROOT"]."/temp1", $_SERVER["DOCUMENT_ROOT"]."/temp2");
?>


DeleteDirFiles

DeleteDirFiles(
 string check,
 string delete,
 array exclude = array()
);

Удаляет из каталога все файлы, которые содержатся в другом каталоге.

Параметры функции

Параметр | Описание
check | Абсолютный путь к каталогу, файлы которого проверяются на наличие в каталоге задаваемом в параметре delete.
delete | Абсолютный путь к каталогу, в котором будут удалены файлы с именами найденными в каталоге задаваемом в параметре check.
exclude | Массив исключений. Содержит краткие имена файлов, которые не будут удалены.

См. также

  • DeleteDirFilesEx
  • CFile::Delete

Примеры использования

<?
// удалим из папки /temp1/ все файлы, которые есть в папке /temp2/,
// за исключением файла index.php
DeleteDirFiles(
    $_SERVER["DOCUMENT_ROOT"]."/temp2",
    $_SERVER["DOCUMENT_ROOT"]."/temp1",
    array("index.php")
    );
?>


DeleteDirFilesEx

bool
DeleteDirFilesEx(
 string path
);

Удаляет рекурсивно указанный каталог (файл). Возвращает "true" в случае успешного выполнения.

Параметры функции

Параметр | Описание
path | Путь относительно корня к удаляемому каталогу (файлу).

См. также

  • DeleteDirFiles
  • CFile::Delete

Примеры использования

<?
// удалим каталог /temp1/ и все что в нем находится
DeleteDirFilesEx("/temp1");
?>


GetDirIndex

string
GetDirIndex(
 string path,
 string index = false
);

Возвращает имя индексного файла каталога.

Параметры функции

Параметр | Описание
path | Путь к каталогу относительно корня для которого необходимо определить индексный файл.
index | Разделенные пробелом возможные имена индексных файлов в порядке убывания приоритета. Для корректной работы функции в данный параметр необходимо передавать значение из поля DirectoryIndex настроек веб-сервера Apache, для IIS данный параметр можно найти в свойствах сайта, закладка "Documents" -> "Enable default content page". Необязательный параметр. По умолчанию - "false" (значение будет взято из константы DIRECTORY_INDEX, если константа не определена, то будет взято значение по умолчанию - "index.php index.html index.htm index.phtml default.html index.php3").

Алгоритм определения индексного файла каталога следующий:

  1. Берется значение из параметра index. Если параметр не задан, то берется значение константы DIRECTORY_INDEX (данную константу можно определить в файле /bitrix/php_interface/dbconn.php или в файлах /bitrix/php_interface/ID сайта/init.php). Если значение константы не задано, то берется значение по умолчанию - "index.php index.html index.htm index.phtml default.html index.php3"
  2. Полученное значение разбивается по пробелу на отдельные имена файлов
  3. Каждый полученный файл проверяется на физическое существование в каталоге.
  4. Первый найденный файл будет считаться индексной страницей каталога

См. также

  • GetPagePath
  • CMain::GetCurPage
  • CMain::GetCurPageParam
  • CMain::GetCurUri


GetDirPath

string
GetDirPath(
 string path
);

Возвращает каталог файла по пути к этому файлу.

Параметры функции

Параметр | Описание
path | Путь к файлу.

См. также

  • CMain::GetCurDir

Примеры использования

<?
echo GetDirPath("/temp1/data/file.php");
// выводит строку "/temp1/data/"
?>


DeleteDirFiles

string
GetPagePath(
 string page = false
);

Возвращает путь к странице относительно корня.

В функцию может поступить URL относительно корня с параметрами, в этом случае функция вернет путь к странице без параметров.

Если в функцию поступает путь без указания файла, например: /ru/about/, то функция попытается самостоятельно определить индексный файл каталога и если определит его например, как index.php, то в результате вернет значение /ru/about/index.php.

Алгоритм определения индексного файла представлен в описании функции GetDirIndex.

Параметры функции

Параметр | Описание
page | Страница, путь к которой необходимо вернуть. Если параметр равен "false", то возвращается путь к текущей странице. Необязательный параметр, по умолчанию равен "false".

См. также

  • CMain::GetCurPage
  • CMain::GetCurPageParam
  • CMain::GetCurUri
  • GetDirIndex


RewriteFile

bool
RewriteFile(
 string abs_path,
 string content
);

Записывает в файл новое содержимое. Возвращает "true" в случае удачной записи в файл, иначе - "false".

Параметры функции

Параметр | Описание
abs_path | Абсолютный путь к файлу, который необходимо перезаписать.
content | Новое содержимое файла.

См. также

  • CFile::SaveFile
  • CMain::SaveFileContent

Примеры использования

<?
// перезапишем файл /ru/index.php
$content = '
    <?
    require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
    $APPLICATION->SetTitle("Заголовок страницы");
    ?>
    <?
    require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
    ?>
';
RewriteFile($_SERVER["DOCUMENT_ROOT"]."/ru/index.php", $content);
?>


Обзор функций

Функции для работы с элементами HTML:

Метод | Описание
InputType | Возвращает HTML код тегов <input type="checkbox"> (переключатель с множественным варинтом выбора ответа), либо <input type="radio"> (переключатель с единственным вариантом выбора ответа).
SelectBox | Возвращает HTML код тега <select> (выпадающий список с единственным вариантом выбора ответа) на основании данных из объекта класса CDBResult.
SelectBoxM | Возвращает HTML код тега <select multiple> (выпадающий список с множественными варинтами выбора ответа) на основании данных из объекта класса CDBResult.
SelectBoxFromArray | Возвращает HTML код тега <select> (выпадающий список с единственным вариантом выбора ответа) на основании данных из массива.
SelectBoxMFromArray | Возвращает HTML код тега <select multiple> (выпадающий список с множественными варинтами выбора ответа) на основании данных из массива.


InputType

string
InputType(
 string type,
 string name,
 string value,
 mixed checked,
 bool print_value = false,
 string title = "",
 string add_to_tag = ""
);

Возвращает HTML код тегов <input type="checkbox"> (переключатель с множественным вариантом выбора ответа), либо <input type="radio"> (переключатель с единственным вариантом выбора ответа).

Параметры функции

Параметр Описание
type Тип тэга:
<input type="type" ... >

Возможные значения:
  • checkbox - переключатель с множественным вариантом выбора ответа
  • radio - переключатель с единственным вариантом выбора ответа
name Имя тэга:
<input name="name" ... >
value Значение тэга:
<input value="value" ... >
checked Значение данного параметра будет сравниваться со значением параметра value, в случае совпадения - переключатель будет "отмечен" (checked):
<input checked ... >
print_value Если в данном параметре задано значение "true", то справа от тэга будет выведено значение параметра value.
Необязательный параметр. По умолчанию - "false".
title Если параметр print_value не равен "true" и в параметре title задано значение, то оно будет выведено справа от тэга.
Необязательный параметр. По умолчанию - "".
add_to_tag Произвольный HTML который будет добавлен в тэг:
<input add_to_tag ... >
Необязательный параметр. По умолчанию - "".

Примеры использования

<?
// Множественный выбор

echo "Результат выбора:<pre>"; print_r($check); echo "</pre>";
echo "Отметьте нужные варианты:<br>";
?>
<form action="" method="GET">
<?
echo "1:".InputType("checkbox", "check[]", "1", $check)."<br>";
echo "2:".InputType("checkbox", "check[]", "2", $check)."<br>";
echo "3:".InputType("checkbox", "check[]", "3", $check)."<br>";
?>
<br><input type="submit" value="OK">
</form>
<?
// Единичный выбор

echo "Результат выбора: ".$radio."<br><br>";
echo "Выберете один из следующих вариантов:<br>";
?>
<form action="" method="GET">
<?
echo "1: ".InputType("radio", "radio", "1", $radio)."<br>";
echo "2: ".InputType("radio", "radio", "2", $radio)."<br>";
echo "3: ".InputType("radio", "radio", "3", $radio)."<br>";
echo "4: ".InputType("radio", "radio", "4", $radio)."<br>";
?>
<br><input type="submit" value="OK">
</form>


SelectBox

string
SelectBox(
 string name,
 CDBResult values,
 string default = "",
 string selected = "",
 string add_to_tag = "class=\"typeselect\""
);

Возвращает HTML код тега <select> (выпадающий список с единственным вариантом выбора ответа) на основании данных из объекта класса CDBResult.

Параметры функции

Параметр | Описание
name | Имя тэга: <select name="name" ... >
values | Элементы списка. Объект типа CDBResult, содержащий набор записей, каждая из которых должна иметь по два: "REFERENCE_ID" (значение элемента списка) и "REFERENCE" (заголовок элемента списка).
default | Заголовок элемента списка выбираемого по умолчанию. Значение этого элемента - "NOT_REF". Необязательный параметр. По умолчанию - "" (не добавлять подобный элемент).
selected | Выбранный элемент. Значение данного параметра будет сравниваться с полями "REFERENCE_ID" набора записей передаваемого в параметре values, в случае совпадения элемент будет "выбран" (selected). Необязательный параметр. По умолчанию - "".
add_to_tag | Произвольный HTML который будет добавлен в тэг: <select add_to_tag ... > Необязательный параметр. По умолчанию - "class=\"typeselect\"".

См. также

  • SelectBoxFromArray

Пример использования

<?
// сформируем выборку из таблицы групп
$strSql = "
    SELECT
        G.ID as REFERENCE_ID,
        G.NAME as REFERENCE
    FROM
        b_group G
    ";
$rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

// выведем выпадающий список групп
echo SelectBox("GROUP", $rs, "< выберите группу >", $GROUP, "class =\"inputselect\"");
?>


SelectBoxFromArray

string
SelectBoxFromArray(
 string name,
 array values,
 string selected = "",
 string default = "",
 string add_to_tag = "class=\"typeselect\"",
 bool submit_form = false,
 string form_name = "form1"
);

Возвращает HTML код тега <select> (выпадающий список с единственным вариантом выбора ответа) на основании данных из массива.

Параметры функции

Параметр Описание
name Имя тэга:
<select name="name" ... >
values Элементы списка. Массив имеющий следующую структуру:
array(
    "REFERENCE" =>
        array(
            "Заголовок элемента 1",
            "Заголовок элемента 2",
            ...
            ),
    "REFERENCE_ID" =>
        array(
            "Значение элемента 1",
            "Значение элемента 2",
            ...
            )
    )
selected Выбранный элемент. Значение данного параметра будет искаться в массиве передаваемом в ключе "REFERENCE_ID" массива values, в случае совпадения элемент будет "выбран" (selected).
Необязательный параметр. По умолчанию - "".
default Заголовок элемента списка выбираемого по умолчанию. Значение этого элемента - "NOT_REF".
Необязательный параметр. По умолчанию - "" (не добавлять подобный элемент).
add_to_tag Произвольный HTML который будет добавлен в тэг:
<select add_to_tag ... >
Необязательный параметр. По умолчанию - "class=\"typeselect\"".
submit_form Если в данном параметре указать "true", то в момент выбора какого либо значения из выпадающего списка, произойдет submit формы, имя которой указано в параметре form_name.
Необязательный параметр. По умолчанию - "false" (не submit'ить форму).
form_name Если параметр submit_form = true, то здесь вам необходимо указать имя формы в которой будет расположен тэг <select>.
Необязательный параметр. По умолчанию - "form1".

См. также

  • SelectBox

Пример использования

<form name="form2" action="" method="GET">
<?
$arr = array(
    "REFERENCE" => // массив заголовков элементов
        array("Вариант 1", "Вариант 2", "Вариант 3"),
    "REFERENCE_ID" => // массив значений элементов
        array(1, 2, 3)
    );
echo SelectBoxFromArray("CHOICE", $arr, $CHOICE, "", "", true, "form2")
?>
</form>


SelectBoxM

string
SelectBoxM(
 string name,
 CDBResult values,
 array selected,
 string top_element = "",
 bool select_top_element = false,
 int size = 5,
 string add_to_tag = "class=\"typeselect\""
);

Возвращает HTML код тега <select multiple> (выпадающий список с множественными вариантами выбора ответа) на основании данных из объекта класса CDBResult.

Параметры функции

Параметр | Описание
name | Имя тэга: <select name="name" ... >
values | Элементы списка. Объект типа CDBResult, содержащий набор записей, каждая из которых должна иметь по два: "REFERENCE_ID" (значение элемента списка) и "REFERENCE" (заголовок элемента списка).
selected | Выбранные элементы. Массив, элементы которого будут сравниваться с полями "REFERENCE_ID" набора записей передаваемого в параметре values, в случае совпадения элемент будет "выбран" (selected).
top_element | Заголовок специального элемента который всегда помещается первым в списке и он может быть всегда выбран (контролируется параметром select_top_element). Значение этого элемента - "NOT_REF". Необязательный параметр. По умолчанию - "" (не добавлять подобный элемент).
select_top_element | Если значение "true", то элемент top_element будет всегда выбран (selected). Необязательный параметр. По умолчанию - "false" (не выбирать).
size | Поле size тэга select: <select size="size" ... > В данном параметре передается количество видимых строк в списке множественного выбора. Параметр необязательный. Значение по умолчанию - 5.
add_to_tag | Произвольный HTML который будет добавлен в тэг: <select add_to_tag ... > Необязательный параметр. По умолчанию - "class=\"typeselect\"".

См. также

  • SelectBoxMFromArray

Пример использования

<?
// сформируем выборку из таблицы групп
$strSql = "
    SELECT
        G.ID as REFERENCE_ID,
        G.NAME as REFERENCE
    FROM
        b_group G
    WHERE
        G.ID<>2 -- группа everybody которой все принадлежат по умолчанию
    ";
$rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

// выведем список групп с множественным выбором
echo SelectBoxM("arrGROUP[]", $rs, $arrGROUP, "< группа everybody >", true, 20,
"class =\"inputselect\"");
?>


SelectBoxMFromArray

string
SelectBoxMFromArray(
 string name,
 array values,
 array selected,
 string top_element = "",
 bool select_top_element = false,
 int size = 5,
 string add_to_tag = "class=\"typeselect\""
);

Возвращает HTML код тега <select multiple> (выпадающий список с множественными вариантами выбора ответа) на основании данных из массива.

Параметры функции

Параметр Описание
name Имя тэга:
<select name="name" ... >
values Элементы списка. Массив имеющий следующую структуру:
array(
    "REFERENCE" =>
        array(
            "Заголовок элемента 1",
            "Заголовок элемента 2",
            ...
            ),
    "REFERENCE_ID" =>
        array(
            "Значение элемента 1",
            "Значение элемента 2",
            ...
            )
    )
selected Выбранные элементы. Массив, значения которого будут искаться в массиве передаваемом в ключе "REFERENCE_ID" массива values, в случае совпадения элемент будет "выбран" (selected).
Необязательный параметр. По умолчанию - "".
top_element Заголовок специального элемента который всегда помещается первым в списке и он может быть всегда выбран (контролируется параметром select_top_element). Значение этого элемента - "NOT_REF".
Необязательный параметр. По умолчанию - "" (не добавлять подобный элемент).
select_top_element Если значение "true", то элемент top_element будет всегда выбран (selected).
Необязательный параметр. По умолчанию - "false" (не выбирать).
size Поле size тэга select:
<select size="size" ... >
В данном параметре передается количество видимых строк в списке множественного выбора. Параметр необязательный. Значение по умолчанию - 5.
add_to_tag Произвольный HTML который будет добавлен в тэг:
<select add_to_tag ... >
Необязательный параметр. По умолчанию - "class=\"typeselect\"".

См. также

  • SelectBoxM

Пример использования

<?
$arr = array(
    "REFERENCE" => // массив заголовков элементов
        array("Вариант 1", "Вариант 2", "Вариант 3"),
    "REFERENCE_ID" => // массив значений элементов
        array(1, 2, 3)
    );
echo SelectBoxMFromArray("arrSEL[]", $arr, $arrSEL, "", false, 4,
"class =\"inputselect\"");
?>


Обзор функций

Функции для построения и работы с фильтрами и сортировками

Метод | Описание
InitFilterEx | Инициализация фильтра.
DelFilterEx | Удаление фильтра.
GetFilterHiddens | Позволяет создать набор HTML тэгов типа hidden из набора переменных имена которых передаются в массиве, либо указан префикс имен этих переменных.
GetFilterParams | Создание строки состоящей из параметров для URL'а из входящего массива переменных, либо переменных имена которых начинаются с указанного префикса.
CheckFilterDates | Проверяет две даты введенные в фильтре на корректность.
InitSorting | Инициализация сортировки.
SortingEx | Генерация "стрелок" сортировки.


CheckFilterDates

CheckFilterDates(
 string date1,
 string date2,
 string &is_date1_wrong,
 string &is_date2_wrong,
 string &is_date2_less_date1
);

Проверяет две даты на корректность и сравнивает их между собой. Как правило функция используется в фильтрах для проверки корректности введенного периода времени.

Параметры функции

Параметр | Описание
date1 | Первая дата интервала ("c").
date2 | Вторая дата интервала ("по").
is_date1_wrong | Данный параметр является ссылкой на исходную переменную. Если в нем будет возвращено "Y", то дата заданная в параметре date1 некорректна для формата даты текущего сайта (языка).
is_date2_wrong | Данный параметр является ссылкой на исходную переменную. Если в нем будет возвращено "Y", то дата заданная в параметре date2 некорректна для формата даты текущего сайта (языка).
is_date2_less_date1 | Данный параметр является ссылкой на исходную переменную. Если в нем будет возвращено "Y", то дата заданная в параметре date1 больше даты заданной в параметре date2, что неправильно если задается период времени.

См. также

  • CDataBase::IsDate
  • CDataBase::CompareDates

Примеры использования

<?
CheckFilterDates("10.01.2003", "15.02.2004", $date1_wrong, $date2_wrong, $date2_less);
if ($date1_wrong=="Y") echo "Неверный формат первой даты!";
if ($date2_wrong=="Y") echo "Неверный формат второй даты!";
if ($date2_less=="Y") echo "Первая дата больше второй!";
?>


DelFilterEx

DelFilterEx(
 array vars,
 string id,
 bool session = true
);

Очищает переменные, содержащие значения фильтра, и очищает соответствующие сессионные переменные.

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

Параметры функции

Параметр | Описание
vars | Массив имен переменных фильтра.
id | Идентификатор фильтра. Строка идентифицирующая данный фильтр в сессионном массиве: $_SESSION["SESS_ADMIN"][id]
session | Использовать ли сессию. Если значение данного параметра равно "true", то значения фильтра будут также очищены из сессионного массива $_SESSION["SESS_ADMIN"][id].

См. также

  • InitFilterEx

Примеры использования

<?
$FilterArr = Array(
    "find_id",
    "find_id_exact_match",
    );

// если нажата кнопка "Установить фильтр" то
if (strlen($set_filter)>0)
{
    // запоминаем значения фильтра в сессии
    InitFilterEx($FilterArr,"ADV_BANNER_LIST","set");
}
else
{
    // инициализируем значения фильтра из сессии
    InitFilterEx($FilterArr,"ADV_BANNER_LIST","get");
}

// если была нажата кнопка "Сбросить фильтр"
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"ADV_BANNER_LIST");

$arFilter = Array(
    "ID"                    => $find_id,
    "ID_EXACT_MATCH"        => $find_id_exact_match,
    );
$rsBanners = CAdvBanner::GetList($by, $order, $arFilter, $is_filtered);
?>


GetFilterHiddens

string
GetFilterHiddens(
 mixed var,
 array extra_vars = array("filter"=>"Y","set_filter"=>"Y")
);

Возвращает набор HTML тэгов типа hidden из набора переменных, имена которых передаются в массиве, либо указан префикс имен этих переменных.

Параметры функции

Параметр | Описание
var | Имена переменных. В данном параметре можно передать либо массив, либо префикс имен этих переменных.
extra_vars В данном параметре можно передать массив, представляющий из себя имя и значение произвольных переменных, которые будут добавлены в результат. Структура данного массива:
array("ИМЯ_ПЕРЕМЕННОЙ" => "ЗНАЧЕНИЕ_ПЕРЕМЕННОЙ")
Как правило данный параметр используют для передачи имени и значения кнопки "Установить фильтр".
Параметр необязательный. По умолчанию - array("filter" => "Y", "set_filter" => "Y").

См. также

  • GetFilterParams

Примеры использования

<form method="GET">
    <?
    // добавим набор тэгов hidden имена которых будут начинаться с префикса "filter_"
    // и значениями равными значениям соответствующих переменных
    echo GetFilterHiddens("filter_");
    ?>
    <input type="hidden" name="lang" value="<?echo LANGUAGE_ID?>">
    <input type="submit" name="Add" value="Добавить новую запись&gt;">
</form>


GetFilterParams

string
GetFilterParams(
 mixed var,
 bool safe_for_html = true,
 array extra_vars = array("filter"=>"Y","set_filter"=>"Y")
);

Возвращает строку состоящюю из параметров для URL'а из входящего массива переменных, либо переменных имена которых начинаются с указанного префикса.

Параметры функции

Параметр | Описание
var | Имена переменных. В данном параметре можно передать либо массив, либо префикс имен этих переменных.
safe_for_html | Если значение равно "true", то результат будет приведен в HTML-безопасный вид.
extra_vars В данном параметре можно передать массив, представляющий из себя имя и значение произвольных переменных, которые будут добавлены в результат. Структура данного массива:
array("ИМЯ_ПЕРЕМЕННОЙ" => "ЗНАЧЕНИЕ_ПЕРЕМЕННОЙ")
Как правило данный параметр используют для передачи имени и значения кнопки "Установить фильтр".
Параметр необязательный. По умолчанию - array("filter" => "Y", "set_filter" => "Y").

См. также

  • GetFilterHiddens

Примеры использования

<?
// Данный код строит ссылку, при переходе по которой пользователь
// попадет на страницу adv.php с теми же переменными,
// имена которых имеют префикс - "filter_",
// с какими он попал на текущую страницу
?>
<a href="adv.php?id=<?echo $f_ID?>&<?echo GetFilterParams("filter_");?>">Изменить</a>


InitFilterEx

InitFilterEx(
 array vars,
 string id,
 string action = "set",
 bool session = true
);

Инициализирует, либо запоминает переменные фильтра в сессии.

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

Параметры функции

Параметр | Описание
vars | Массив имен переменных фильтра.
id | Идентификатор фильтра. Строка идентифицирующая данный фильтр в сессионном массиве: $_SESSION["SESS_ADMIN"][id]
action | Что необходимо сделать: запомнить значения или получить значения фильтра. Если значение равно "set", то значения переменных имена которых были переданы в параметре vars будут запомнены в сессионном массиве $_SESSION["SESS_ADMIN"][id]. В противном случае эти переменный будут инициализированы значениями хранящимися в сессионном массиве $_SESSION["SESS_ADMIN"][id]. Параметр необязательный. По умолчанию - "set".
session | Использовать ли сессию. Если значение данного параметра равно "true", то значения фильтра будут запоминаться в сессионном массиве $_SESSION["SESS_ADMIN"][id].

См. также

  • DelFilterEx

Примеры использования

<?
$FilterArr = Array(
    "find_id",
    "find_id_exact_match",
    );

// если нажата кнопка "Установить фильтр" то
if (strlen($set_filter)>0)
{
    // запоминаем значения фильтра в сессии
    InitFilterEx($FilterArr,"ADV_BANNER_LIST","set");
}
else
{
    // инициализируем значения фильтра из сессии
    InitFilterEx($FilterArr,"ADV_BANNER_LIST","get");
}

// если была нажата кнопка "Сбросить фильтр"
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"ADV_BANNER_LIST");

$arFilter = Array(
    "ID"                    => $find_id,
    "ID_EXACT_MATCH"        => $find_id_exact_match,
    );
$rsBanners = CAdvBanner::GetList($by, $order, $arFilter, $is_filtered);
?>


InitSorting

InitSorting(
 mixed page = false,
 string by_var = "by",
 string order_var = "order"
);

Инициализирует параметры сортировки хранимые в сессии, если сортировка не была явно задана. Если сортировка задана явно, то функция запоминает параметры сортировки в сессии.

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

Параметры функции

Параметр | Описание
page | Для какой страницы инициализировать сортировку. Значение "false" означает, что необходимо инициализировать сортировку для текущей страницы. Необязательный параметр, по умолчанию равен "false".
by_var | Имя переменной в которой передается идентфикатор поля для сортировки. Необязательный, по умолчанию равен "by".
order_var | Имя переменной, которая содержит направление сортировки: "asc" (по возрастания) или desc (по убыванию). Необязательный параметр, по умолчанию равен "order".

См. также

  • SortingEx

Примеры использования

<?
// если переменные $by и $order явно заданы, то их значения запоминаются в сессии
// иначе они инициализируется значениями хранимыми в сессии
InitSorting();
$rsUsers = CUser::GetList($by, $order);
?>
<table>
    <tr>
        <td>ID<br><?=SortingEx("s_id")?></td>
        <td>Логин<br><?=SortingEx("s_name")?></td>
    </tr>
    ...
</table>


SortingEx

string
SortingEx(
 string by,
 mixed page = false,
 string by_var = "by",
 string order_var = "order",
 string anchor = "nav_start"
);

Возвращает HTML, представляющий из себя "стрелки" сортировки. Функция как правило используется в шапке таблиц.

Параметры функции

Параметр | Описание
by | Значение которое будет передано в переменную by_var. Как правило в данном параметре указывается идентификатор поля для сортировки.
page | URL страницы вместе со всеми параметрами для которой будет сформирована ссылка на "стрелке". Необязательный параметр, равный по умолчанию - "false" (текущая страница).
by_var | Имя переменной в которую будет передано значение параметра by. Необязательный, по умолчанию равен "by".
order_var | Имя переменной, которая содержит направление сортировки: "asc" (по возрастания) или desc (по убыванию). Необязательный параметр, по умолчанию равен "order".
anchor | Якорь, до которого страница будет прокручена в браузере после установки сортировки. Необязательный параметр, по умолчанию равен "nav_start".

См. также

  • InitSorting

Примеры использования

<table>
    <tr>
        <td>ID<br><?=SortingEx("s_id")?></td>
        <td>Заголовок<br><?=SortingEx("s_name")?></td>
    </tr>
    <tr>
        <td>1</td>
        <td>Заголовок элемента</td>
    </tr>
</table>


Обзор функций

Функции для работы с модулями.

Метод | Описание
AddEventHandler | Регистрирует произвольный обработчик событий модуля.
CheckVersion | Сравнение версий модулей.
ExecuteModuleEvent | Выполнение обработчика события.
GetModuleEvents | Запрос списка обработчиков событий.
GetModuleID | Возвращает идентификатор модуля, которому принадлежит файл.
IsModuleInstalled | Проверяет установлен ли модуль.
RegisterModule | Регистрация модуля в системе.
RegisterModuleDependences | Регистрация нового обработчика события.
UnRegisterModule | Удаляет регистрационную запись модуля.
UnRegisterModuleDependences | Удаляет регистрационную запись обработчика события.

См. также

  • Описание концепции модулей
  • Класс CModule


AddEventHandler

AddEventHandler(
 string from_module_id,
 string event_id,
 mixed callback,
 int sort = 100,
 mixed full_path = false
);

Регистрирует произвольный обработчик callback события event_id модуля from_module_id. Если указан полный путь к файлу с обработчиком full_path, то он будет автоматически подключен перед вызовом обработчика.

Параметры функции

Параметр | Описание
from_module_id | Идентификатор модуля который будет инициировать событие.
event_id | Идентификатор события.
callback | Название функции обработчика. Если это метод класса, то массив вида Array(класс(объект), название метода).
sort | Очередность (порядок), в котором выполняется данный обработчик (обработчиков данного события может быть больше одного). Необязательный параметр, по умолчанию равен 100.
full_path | Полный путь к файлу для подключения при возникновении события перед вызовом callback.

См. также

  • Связи и взаимодействие модулей
  • RegisterModuleDependences

Примеры использования

<?
// скрипт в файле /bitrix/php_interface/init.php
AddEventHandler("main", "OnBeforeUserLogin", Array("MyClass", "BeforeLogin"));
class MyClass
{
  function BeforeLogin(&$arFields)
  {
        if(strtolower($arFields["LOGIN"])=="guest")
        {
            global $APPLICATION;
            $APPLICATION->throwException("Пользователь с именем входа Guest не может быть авторизован.");
            return false;
        }
  }
}
?>


CheckVersion

bool
CheckVersion(
 string version1,
 string version2
);

Сравнивает версии в форматах XX.XX.XX. Возвращает true, если первая версия, переданная в параметре version1, больше или равна второй версии, переданной в параметре version2, иначе - false.

Параметры функции

Параметр | Описание
version1 | Первая версия в формате "XX.XX.XX"
version2 | Вторая версия в формате "XX.XX.XX"

Примеры использования

<?
$ver1 = "3.0.15";
$ver2 = "4.0.0";

$res = CheckVersion($ver1, $ver2);

echo ($res) ? $ver1." >= ".$ver2 : $ver1." < ".$ver2;

// результат: 3.0.15 < 4.0.0
?>


ExecuteModuleEvent

mixed
ExecuteModuleEvent(
 array event,
 mixed param1 = NULL,
 mixed param2 = NULL,
 mixed param3 = NULL,
 mixed param4 = NULL,
 mixed param5 = NULL,
 mixed param6 = NULL,
 mixed param7 = NULL,
 mixed param8 = NULL,
 mixed param9 = NULL,
 mixed param10 = NULL
);

Запускает обработчик события на выполнение. Возвращает то значение, которое возвращает конкретный обработчик события.

Параметры функции

Параметр Описание
event Массив описывающий одну регистрационную запись хранящую связь между событием и обработчиком этого события (подобные записи хранятсяв таблице b_module_to_module). Ключи данного массива:
  • ID - ID записи
  • TIMESTAMP_X - время изменения записи
  • SORT - сортировка
  • FROM_MODULE_ID - какой модуль инициализирует событие
  • MESSAGE_ID - идентификатор события
  • TO_MODULE_ID - какой модуль содержит обработчик события
  • TO_CLASS - какой класс содержит обработчик события
  • TO_METHOD - метод класса являющийся по сути обработчиком события
param1,
param2,
... ,
param10 		Произвольный набор значений, которые передаются в качестве параметров в обработчик события.

См. также

  • GetModuleEvents

Примеры использования

<?
// проверка возможности удаления форума

// флаг запрещающий или разрешающий удалять форум
$bCanDelete = true;

// получим данные по всем обработчикам события "OnBeforeForumDelete"
// принадлежащего модулю с идентификатором "forum"
$rsEvents = GetModuleEvents("forum", "OnBeforeForumDelete");
while ($arEvent = $rsEvents->Fetch())
{
    // запустим на выполнение очередной обработчик события "OnBeforeForumDelete"
    // если функция-обработчик возвращает false, то
    if (ExecuteModuleEvent($arEvent, $del_id)===false)
    {
        // запрещаем удалять форум
        $bCanDelete = false;
        break;
    }
}
?>


GetModuleEvents

CDBResult
GetModuleEvents(
 string module_id,
 string event_id
);

Возвращает список обработчиков события event_id модуля module_id в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.
event_id | Идентификатор события.

См. также

  • ExecuteModuleEvent

Примеры использования

<?
// проверка возможности удаления форума

// флаг запрещающий или разрешающий удалять форум
$bCanDelete = true;

// получим данные по всем обработчикам события "OnBeforeForumDelete"
// принадлежащего модулю с идентификатором "forum"
$rsEvents = GetModuleEvents("forum", "OnBeforeForumDelete");
while ($arEvent = $rsEvents->Fetch())
{
    // запустим на выполнение очередной обработчик события "OnBeforeForumDelete"
    // если функция-обработчик возвращает false, то
    if (ExecuteModuleEvent($arEvent, $del_id)===false)
    {
        // запрещаем удалять форум
        $bCanDelete = false;
        break;
    }
}
?>


GetModuleID

string
GetModuleID(
 string path
);

Возвращает идентификатор модуля, которому принадлежит файл.

Параметры функции

Параметр | Описание
path | Путь к файлу лежащему в каталоге /bitrix/modules/.

Примеры использования

<?
echo GetModuleID("/bitrix/modules/main/include.php"); // main
?>


IsModuleInstalled

bool
IsModuleInstalled(
 string module_id
);

Проверяет установлен ли модуль. Возвращает "true", если модуль установлен. Иначе - "false".

Для использования функций и классов того или иного модуля, его необходимо предварительно подключить с помощью функции CModule::IncludeModule.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.

См. также

  • CModule::IsInstalled
  • CModule::IncludeModule

Примеры использования

<?
if (IsModuleInstalled("iblock")):

    echo "Модуль информационных блоков установлен";

endif;
?>


RegisterModule

RegisterModule(
 string mоdule_id
);

Регистрация модуля в системе. Как правило регистрация модуля является неотъемлемой частью процесса инсталляции модуля.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.

См. также

  • UnRegisterModule
  • CModule::DoInstall

Примеры использования

<?
// файл /bitrix/modules/statistic/install/step2.php
RegisterModule("statistic");
?>


RegisterModuleDependences

RegisterModuleDependences(
 string from_module_id,
 string event_id,
 string to_module_id,
 string to_class = "",
 string to_method = "",
 int sort = 100
);

Регистрирует обработчик события.

Параметры функции

Параметр | Описание
from_module_id | Идентификатор модуля, который будет инициировать событие.
event_id | Идентификатор события.
to_module_id | Идентификатор модуля, содержащий функцию-обработчик события.
to_class | Класс принадлежащий модулю module, метод которого является функцией-обработчиком события. Необязательный параметр. По умолчанию - "" (будет просто подключен файл /bitrix/modules/to_module_id/include.php).
to_method | Метод класса to_class являющийся функцией-обработчиком события. Необязательный параметр. По умолчанию - "" (будет просто подключен файл /bitrix/modules/to_module_id/include.php).
sort | Очередность (порядок), в котором выполняется данный обработчик (обработчиков данного события может быть больше одного). Необязательный параметр, по умолчанию равен 100.

См. также

  • Связи и взаимодействие модулей
  • UnRegisterModuleDependences

Примеры использования

<?
// Для того, чтобы при удалении пользователя сайта
// производилась соответствующая очистка данных форума,
// при установке форума выполняется регистрация нового
// обработчика события "OnUserDelete" модуля main.
// Этим обработчиком является метод OnUserDelete класса CForum модуля forum.

RegisterModuleDependences("main", "OnUserDelete", "forum", "CForum", "OnUserDelete");
?>


UnRegisterModule

UnRegisterModule(
 string module_id
);

Удаляет регистрационную запись, а также все настройки модуля из базы данных. Как правило удаление регистрационной записи модуля является неотъемлемой частью процесса деинсталляции модуля.

Параметры функции

Параметр | Описание
module_id | Идентификатор модуля.

См. также

  • RegisterModule
  • CModule::DoUninstall

Примеры использования

<?
// файл /bitrix/modules/statistic/install/unstep2.php
UnRegisterModule("statistic");
?>


UnRegisterModuleDependences

UnRegisterModuleDependences(
 string from_module_id,
 string event_id,
 string to_module_id,
 string to_class = "",
 string to_method = ""
);

Удаляет регистрационную запись обработчика события.

Параметры функции

Параметр | Описание
from_module_id | Идентификатор модуля который инициирует событие.
event_id | Идентификатор события.
to_module_id | Идентификатор модуля содержащий функцию-обработчик события.
to_class | Класс принадлежащий модулю module, метод которого является функцией-обработчиком события. Необязательный параметр. По умолчанию - "".
to_method | Метод класса to_class являющийся функцией-обработчиком события. Необязательный параметр. По умолчанию - "".

См. также

  • Связи и взаимодействие модулей
  • RegisterModuleDependences

Примеры использования

<?
UnRegisterModuleDependences("main", "OnUserDelete", "forum", "CForum", "OnUserDelete");
?>


Обзор функций

Функции для работы с языковыми файлами:

Метод | Описание
GetMessage | Возвращает по коду соответствующее сообщение на текущем языке.
IncludeModuleLangFile | Подключает языковой файл для скрипта модуля.
IncludeTemplateLangFile | Подключает языковой файл для компонента.

См. также

  • Языки


GetMessage

string
GetMessage(
 string message_id
);

Возвращает по коду соответствующее сообщение на текущем языке. Массивы соответствий кодов и сообщений задаются в языковых файлах. Перед использованием этой функции необходимо подключить соответствующий языковой файл.

Параметры функции

Параметр | Описание
message_id | Код сообщения.

См. также

  • IncludeModuleLangFile
  • IncludeTemplateLangFile

Примеры использования

<?
IncludeTemplateLangFile(__FILE__);
echo GetMessage("SOME_MESSAGE_CODE");
?>


IncludeModuleLangFile

IncludeModuleLangFile(
 string abs_path,
 string lang = false
);

Подключает языковой файл для скрипта, полный путь к которому передается в параметре path. Как правило данная функция используется для подключения языковых файлов модулей.

Подключаемый языковой файл должен иметь то же имя, что и подключающий файл, и быть расположен на диске в каталоге:
/bitrix/modules/ID модуля/lang/ID языка/путь к файлу относительно корня модуля

Параметры функции

Параметр | Описание
abs_path | Абсолютный путь к файлу, для которого необходимо подключить языковые сообщения.
lang | Идентификатор языка. Необязательный параметр, по умолчанию равен "false" (текущий язык).

См. также

  • Что такое "языковые файлы"
  • Языковые файлы модулей
  • IncludeTemplateLangFile

Примеры использования

<?
// Подключим языковой файл для текущего скрипта
IncludeModuleLangFile(__FILE__);
?>


IncludeTemplateLangFile

IncludeTemplateLangFile(
 string abs_path,
 string lang = false
);

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

Алгоритм поиска языкового файла:

  1. Сначала языковой файл будет искаться в каталоге

    /bitrix/templates/ID текущего шаблона сайта/lang/ID языка/относительный путь к скрипту

  2. Если файл не найден, он будет искаться в каталоге

    /bitrix/templates/.default/lang/ID языка/относительный путь к скрипту

  3. Затем если файл не найден, он будет искаться дистрибутиве модуля, т.е. в каталоге

    /bitrix/modules/ID модуля/install/templates/lang/ID языка/относительный путь к скрипту

В общем случае, под "относительный путь к скрипту", понимается путь к файлу относительно каталога /bitrix/templates/ID текущего шаблона сайта/.

В частном случае, при подключении компонент, под "относительный путь к скрипту", понимается путь для подключения компонента передаваемый в функцию CMain::IncludeFile в качестве первого параметра.

Параметры функции

Параметр | Описание
abs_path | Абсолютный путь к файлу, для которого необходимо подключить языковые сообщения.
lang | Идентификатор языка. Необязательный параметр, по умолчанию равен "false" (текущий язык).

См. также

  • Что такое "языковые файлы"
  • Языковые файлы компонент
  • IncludeModuleLangFile

Примеры использования

<?
// Подключим языковой файл для текущего компонента
// Предполагаем, что языковой файл расположен стандартным образом
IncludeTemplateLangFile(__FILE__);
?>


Обзор функций

Функции для отладки:

Метод | Описание
AddMessage2Log | Добавляет новую запись в log-файл.
SendError | Отсылает по E-Mail сообщение об ошибке.
mydump | Возвращает визуальное представление значения (дамп) переменной или объекта класса.

См. также

Специальные переменные включающие отладку


AddMessage2Log

AddMessage2Log(
 string text,
 string module_id = ""
);

Функция добавляет новую запись в log-файл.

Для работы функции необходимо, чтобы до ее вызова была определена константа LOG_FILENAME, содержащая абсолютный путь к log-файлу. Если эта константа не определена, то функция не выполняет никаких действий. Константа LOG_FILENAME при необходимости определяется в начале текущей страницы или в одном из файлов:

  • /bitrix/php_interface/dbconn.php
  • /bitrix/php_interface/ID сайта/init.php

Данная функция вызывается в случае ошибки в следующих функциях:

  • CDataBase::Query
  • CDataBase::QueryBind
  • CDataBase::QueryBindSelect

Log-файл накапливает все добавленные в него сообщения. Для очистки log-файла его можно просто удалить с диска.

Существует возможность записывать в отдельный отладочный файл все запросы к базе данных и время их выполнения, для этого необходимо инициализировать переменную $DBDebugToFile, значением "true" в файле /bitrix/php_interface/dbconn.php.

Параметры функции

Параметр | Описание
text | Текст сообщения.
module_id | Идентификатор модуля, который сохраняет сообщение. Необязательный параметр, по умолчанию - "".

См. также

Специальные переменные включающие отладку

Примеры использования

<?
// файл /bitrix/php_interface/dbconn.php

// определим константу LOG_FILENAME, в которой зададим путь к лог-файлу
define("LOG_FILENAME", $_SERVER["DOCUMENT_ROOT"]."/log.txt");
?>
<?
// Сохраним в лог сообщение
AddMessage2Log("Произвольный текст сообщения", "my_module_id");
?>
<?
// выполним преднамеренно некорректный SQL-запрос
$DB->Query("SELECT");
// работа скрипта будет прекращена и в лог-файл будет добавлено сообщение об ошибке
?>


mydump

string
mydump(
 mixed var,
 int max_depth = -1,
 int depth = 0
);

Возвращает визуальное представление значения (дамп) переменной или объекта класса.

Параметры функции

Параметр | Описание
var | Переменная для дампа.
max_depth | Максимальное количество рекурсивных вызовов данной функции в момент создания дампов сложных массивов или объектов класса с большой вложенностью. Необязательный параметр, по умолчанию - -1 (не ограничено).
depth | Счетчик рекурсивных вызовов данной функции в момент создания дампов сложных массивов или объектов класса с большой вложенностью. Необязательный параметр, по умолчанию - 0 (начальное значение).

Пример вызова функции

<?
// создадим дамп стандартного объекта класса CUser
echo "<pre>";
echo mydump($USER);
echo "</pre>";
?>

Пример результата

<?
 object(cuser) =>
  method(0) => Array[0]
  method(1) => Array[1]
  method(2) => Array[2]
  method(3) => Array[3]
  method(4) => Array[4]
  method(5) => Array[5]
  method(6) => Array[6]
  method(7) => Array[7]
  method(8) => Array[8]
  method(9) => Array[9]
  method(10) => Array[10]
  method(11) => Array[11]
  method(12) => Array[12]
  method(13) => Array[13]
  method(14) => Array[14]
  method(15) => Array[15]
  method(16) => Array[16]
  method(17) => Array[17]
  method(18) => Array[18]
  method(19) => Array[19]
  method(20) => Array[20]
  method(21) => Array[21]
  method(22) => Array[22]
  method(23) => Array[23]
  method(24) => Array[24]
  method(25) => Array[25]
  method(26) => Array[26]
  method(27) => Array[27]
  method(28) => Array[28]
  method(29) => Array[29]
  method(30) => Array[30]
  method(31) => Array[31]
  method(32) => Array[32]
  method(33) => Array[33]
  method(34) => Array[34]
  method(35) => Array[35]
  method(36) => Array[36]
  method(37) => Array[37]
  method(38) => Array[38]
  method(39) => Array[39]
  method(40) => Array[40]
  method(41) => Array[41]
  method(42) => Array[42]
  method(43) => Array[43]
  method(44) => Array[44]
  method(45) => Array[45]
  method(46) => Array[46]
  method(47) => Array[47]
  method(48) => Array[48]
  method(49) => Array[49]
  method(50) => Array[50]
  method(51) => Array[51]
  method(52) => Array[52]
  method(53) => Array[53]
  method(54) => Array[54]
  method(55) => Array[55]
  default => result =>
         NULL()  default => arResult =>
         NULL()  default => bNavStart =>
         boolean(true)  default => bShowAll =>
         boolean(true)  default => NavNum =>
         NULL()  default => NavPageCount =>
         NULL()  default => NavPageNomer =>
         NULL()  default => NavPageSize =>
         NULL()  default => NavShowAll =>
         NULL()  default => NavRecordCount =>
         NULL()  default => bFirstPrintNav =>
         boolean(true)  default => PAGEN =>
         NULL()  default => SIZEN =>
         NULL()  default => bFromArray =>
         boolean(true)  default => bFromLimited =>
         boolean(true)  default => sSessInitAdd =>
         string(0) =>
        ""
  default => nPageWindow =>
         integer(11)  default => nSelectedCount =>
         boolean(true)  default => SESS_AUTH =>
         NULL()  default => LAST_ERROR =>
         string(0) =>
        ""
  result =>
         NULL()  arResult =>
         NULL()  bNavStart =>
         boolean(true)  bShowAll =>
         boolean(true)  NavNum =>
         NULL()  NavPageCount =>
         NULL()  NavPageNomer =>
         NULL()  NavPageSize =>
         NULL()  NavShowAll =>
         NULL()  NavRecordCount =>
         NULL()  bFirstPrintNav =>
         boolean(true)  PAGEN =>
         NULL()  SIZEN =>
         NULL()  bFromArray =>
         boolean(true)  bFromLimited =>
         boolean(true)  sSessInitAdd =>
         string(0) =>
        ""
  nPageWindow =>
         integer(11)  nSelectedCount =>
         boolean(true)  SESS_AUTH =>
         array(10) =>
         [AUTHORIZED] =>
             string(1) =>
            "Y"
         [USER_ID] =>
             string(1) =>
            "2"
         [LOGIN] =>
             string(5) =>
            "nessy"
         [EMAIL] =>
             string(15) =>
            "mail@server.com"
         [PASSWORD_HASH] =>
             string(32) =>
            "fc0b9bd428702e477fb6a6fbc3da211c"
         [NAME] =>
             string(14) =>
            "Vitaly Kaplich"
         [FIRST_NAME] =>
             string(6) =>
            "Vitaliy"
         [LAST_NAME] =>
             string(7) =>
            "Kaplich"
         [GROUPS] =>
             array(3) =>
             [0] =>
                 integer(2)             [1] =>
                 integer(1)             [2] =>
                 integer(3)         [ADMIN] =>
             boolean(true)  LAST_ERROR =>
         string(0) =>
        ""
?>


SendError

SendError(
 string text,
 string module_id = ""
);

Отсылает по E-Mail сообщение об ошибке.

Для работы функции необходимо, чтобы до ее вызова была определена константа ERROR_EMAIL, содержащая E-Mail адрес на который будут отправляться сообщения об ошибках. Если эта константа не определена, то функция не выполняет никаких действий. Константа ERROR_EMAIL при необходимости определяется в начале текущей страницы или в одном из файлов:

  • /bitrix/php_interface/dbconn.php
  • /bitrix/php_interface/ID сайта/init.php

Помимо текста ошибки, в письмо будут включены:

  • HTTP_GET_VARS - массив переменных пришедших на страницу в HTTP запросе типа GET
  • HTTP_POST_VARS - массив переменных пришедших на страницу в HTTP запросе типа POST
  • HTTP_COOKIE_VARS - массив переменных хранящихся у посетителя на локальной машине (cookie)
  • HTTP_SERVER_VARS - массив стандартных серверных переменных

Данная функция вызывается в случае ошибки в следующих функциях:

  • CDataBase::Connect
  • CDataBase::Query
  • CDataBase::QueryBind
  • CDataBase::QueryBindSelect
  • CDBResult::Fetch (только для Oracle версии)

Параметры функции

Параметр | Описание
text | Текст сообщения.
module_id | Идентификатор модуля, который сохраняет сообщение. Необязательный параметр, по умолчанию - "".

Примеры использования

<?
// файл /bitrix/php_interface/dbconn.php

// определим константу ERROR_EMAIL, в которой зададим E-Mail администратора
define("ERROR_EMAIL", "admin@site.ru");
?>
<?
SendError("Произвольное текстовое сообщение");
?>


Обзор функций

Метод | Описание
check_email | Проверяет E-Mail адрес на синтаксическую корректность.
FindUserID | Выводит ряд HTML элементов позволяющих задать ID пользователя и рядом с этим полем ввода получить данные пользователя. Также выводиться кнопка ведущая на страницу поиска пользователя.
LocalRedirect | Выполняет перенаправление браузера на указанную страницу.
QueryGetData | Запрашивает web-адрес по протоколу HTTP.
GetWhoisLink | Возвращает ссылку на один из сайтов службы Whois для получения данных по заданному IP адресу.
DeleteParam | На основе стандартного массива $HTTP_GET_VARS формирует строку параметров, удаляя из нее указанные параметры.
InitURLParam | Инициализирует необходимые переменные из параметров заданного URL'а.
IsIE | Проверяет, является ли текущий браузер посетителя браузером "MS Internet Explorer".
Rel2Abs | Формирует путь относительно заданного каталога.
BXClearCache | Удаляет файлы кеша по указанному пути.
GetCountryByID | Возвращает название страны на заданном языке.
GetCountryArray | Возвращает отсортированный массив стран с названиями на заданном языке.
ShowError | Вывод сообщений об ошибках.
ShowNote | Вывод нотификаций.
ShowMessage | Вывод сообщений об ошибках и прочих сообщений.


BXClearCache

bool
BXClearCache(
 bool delete_all = false,
 string dir = ""
);

Удаляет все (либо только устаревшие) файлы кеша по указанному пути. Возвращает "true" в случае успешного завершения. В противном случае возвращает "false".

Параметры функции

Параметр | Описание
delete_all | Если значение равно "true", то будут удалены все файлы кеша, если значение равно "false", то будут удалены только устаревшие файлы кеша.
dir | Каталог, начиная с которого производить обработку. Применяется для частичной обработки кеша. Задается относительно корневой папки кеша - /bitrix/cache/.

Примеры использования

<?
// удалим весь кэш для каталога /forum/
BXClearCache(true, "/forum/");
?>


check_email

bool
check_email(
  string email
);

Проверяет E-Mail адрес на синтаксическую корректность. Возвращает "true", если адрес синтаксически корректен, в противном случае - "false".

Параметры функции

Параметр | Описание
email | Проверяемый E-Mail адрес.

Примеры использования

<?
echo (check_email("Bitrix <admin@bitrix.ru>")) ? "OK!" : "Error!"; // OK
echo (check_email("mail@server.com")) ? "OK!" : "Error!"; // OK
echo (check_email("admin@bi$trix.ru")) ? "OK!" : "Error!"; // ERROR
?>


DeleteParam

string
DeleteParam(
 array remove_params
);

На основе стандартного массива $HTTP_GET_VARS формирует строку параметров, удаляя из нее те параметры, имена которых указаны в remove_params.

Параметры функции

Параметр | Описание
remove_params | Массив имен параметров, которые необходимо удалить из результирующей строки.

Примеры использования

<?
// Сформируем ссылку на произвольную страницу
// со всеми текущими GET параметрами,
// при этом заменив (или добавив если их не было)
// параметры "page" и "order"
?>
<a href="page.php?page=1&order=asc&<?=DeleteParam(array("page","order"))?>">ссылка</a>


FindUserID

bool
FindUserID(
 string tag_name,
 string tag_value
 string user_name = "",
 string form_name = "form1",
 string tag_size = "3",
 string tag_maxlength = "",
 string button_title = "...",
 string tag_class = "typeinput",
 string button_class = "tablebodybutton",
 string search_page = "/bitrix/admin/user_search.php"
);

Выводит ряд HTML элементов, позволяющих задать ID пользователя и рядом с этим полем ввода получить данные пользователя. Также выводится кнопка, ведущая на страницу поиска пользователя.

Параметры функции

Параметр | Описание
tag_name | Имя поля для ввода ID пользователя: <input type="text" name="tag_name" ...>
tag_value | Значение поля для ввода ID пользователя: <input type="text" value="tag_value" ...>
user_name | ID, логин, имя и фамилия пользователя, выводимые рядом с полем для ввода ID пользователя, сразу же после загрузки страницы. Необязательный параметр. По умолчанию - "".
form_name | Имя формы, в которой находится поле для ввода ID пользователя. Необязательный параметр. По умолчанию - "form1".
tag_size | Ширина поля для ввода ID пользователя. <input type="text" size="tag_size" ...> Необязательный параметр. По умолчанию - "3".
tag_maxlength | Максимальное количество символов в поле для ввода ID пользователя: <input type="text" maxlength="tag_maxlength" ...> Необязательный параметр. По умолчанию - "" (не ограничено).
button_title | Подпись на кнопке ведущей на страницу поиска пользователя: <input type="button" value="button_title" ...> Необязательный параметр. По умолчанию - "...".
tag_class | CSS класс для поля ввода ID пользователя: <input type="input" class="tag_class" ...> Необязательный параметр. По умолчанию - "typeinput".
button_class | CSS класс для кнопки ведущей на страницу поиска пользователя: <input type="button" class="button_class" ...> Необязательный параметр. По умолчанию - "tablebodybutton".
search_page | Путь относительно корня на страницу поиска пользователя. Необязательный параметр. По умолчанию - "/bitrix/admin/user_search.php" (административная страница).

Примеры использования

<form name="form1">
<?
$name = "[<a href=\"/bitrix/admin/user_edit.php?lang=".language_id."&id=".
$USER_ID."\">".$USER_ID."</a>] (".$LOGIN.") ".$NAME;

echo FindUserID("USER_ID", $USER_ID, $name,
"form1", "3", "", "...", "inputtext", "inputbodybutton");
?>
</form>


GetCountryArray

array
GetCountryArray(
 string language_id = LANGUAGE_ID
)

Возвращает массив стран с названиями на заданном языке. Формат возвращаемого массива позволяет его использовать в функциях SelectBoxFromArray, SelectBoxMFromArray без предварительной подготовки.

Массив стран задается в файлах /bitrix/modules/main/lang/language_id/tools.php.

Параметры функции

Параметр | Описание
language_id | Идентификатор языка в котором необходимо вернуть названия стран. Необязательный параметр. По умолчанию - LANGUAGE_ID (текущий язык).

Пример возвращаемого массива:

Array
(
    [reference_id] => Array
        (
            [0] => 16
            [1] => 17
            [2] => 2
            [3] => 18
            ...
        ),
    [reference] => Array
        (
            [0] => Австралия
            [1] => Австрия
            [2] => Азербайджан
            [3] => Албания
            ...
        )
)

Пример использования:

<?
// выведем выпадающий список стран
echo SelectBoxFromArray(
    "COUNTRY_ID",
    <b>GetCountryArray</b>(),
    $COUNTRY_ID,
    "< выберите страну >"
    );
?>


GetCountryByID

string
GetCountryByID(
 int country_id,
 string language_id = LANGUAGE_ID
)

Возвращает название страны на заданном языке по ее коду.

Цифровые коды стран вы можете посмотреть в файле /bitrix/modules/main/lang/language_id/tools.php.

Параметры функции

Параметр | Описание
country_id | Цифровой код страны.
language_id | Идентификатор языка в котором необходимо вернуть название страны. Необязательный параметр. По умолчанию - LANGUAGE_ID (текущий язык).

Примеры использования

<?
echo GetCountryByID(34, "ru"); // Бразилия
?>


GetWhoisLink

string
GetWhoisLink(
  string ip,
  string link_class = "tablebodylink"
);

Возвращает ссылку на один из сайтов службы Whois для получения данных по заданному IP адресу.

Формат возвращаемой ссылки:
<a href="http://www.whois.sc/ip" class="link_class">ip</a>

Параметры функции

Параметр | Описание
ip | IP адрес в формате XXX.XXX.XXX.XXX для которого необходимо сформировать ссылку.
link_class | CSS класс ссылки.

Примеры использования

<?
echo GetWhoisLink("210.49.16.111");
?>


InitURLParam

string
InitURLParam(
 mixed url = false
);

Инициализирует переменные и массивы $_GET, $HTTP_GET_VARS, $_REQUEST, $GLOBALS параметрами переданными в url.

Как правило, данная функция используется с обработчике 404 ошибки, когда необходимо получить переменные переданные в URL'е. Подобные обработчики используются для организации сервисов на базе 404 ошибки. Подобные сервисы позволяют создавать более дружелюбные для поисковиков адреса.

Параметры функции

Параметр | Описание
url | URL, параметры которого необходимо инициализировать. Необязательный параметр. По умолчанию - "false" (текущая страница).

Примеры использования

<?
InitURLParam("/ru/index.php?ID=2&A=123");
// будут инициализированы переменные $ID=2 и $A=123
// а также соответствующие ключи массивов $_GET, $HTTP_GET_VARS, $_REQUEST, $GLOBALS
?>


IsIE

bool
IsIE()

Возвращает "true", если текущий браузер посетителя является браузером "MS Internet Explorer", в противном случае - "false".

Параметры функции

Без параметров.

Примеры использования

<?
if (IsIE()) echo "Вы пользуетесь MS Internet Explorer";
?>


LocalRedirect

LocalRedirect(
 string url
);

Выполняет перенаправление браузера на указанную страницу.

Для административной части перенаправление браузера можно использовать только до вывода какого-либо контента (т.е. до подключения файла prolog_admin_after.php или prolog_admin.php). В публичной части - никаких ограничений не накладывается.

Параметры функции

Параметр | Описание
url | URL на который будет перенаправлен браузер. Допустимо использование как относительных адресов, так и адресов ведущих на другие сайты и начинающихся со следующих протоколов: "http://", "https://", "ftp://".

Примеры использования

<?
// полный URL на другой сайт
LocalRedirect("http://www.bitrixsoft.ru/");

// относительный путь от корня текущего сайта
LocalRedirect("/ru/index.php");

// относительный путь к файлу в текущем каталоге текущего сайта
LocalRedirect("index.php");
?>


QueryGetData

string
QueryGetData(
  string site,
  int port,
  string page,
  string query,
  int &error_number,
  string &error_text,
  string http_method = "GET",
  string site_prefix = ""
);

Функция запрашивает указанный в параметрах web-адрес по протоколу HTTP. Возвращает тело (без заголовка) ответа, полученного от сервера. В случае ошибки возвращается пустая строка и устанавливаются параметры error_number и error_text.

Параметры функции

Параметр | Описание
site | Адрес сайта, страница которого запрашивается.
port | Номер порта. Как правило - 80.
page | Путь к запрашиваемой странице.
query | Строка параметров запроса в стандартном формате.
error_number | Данный параметр является ссылкой на исходную переменную. В нее будет возвращен номер ошибки в случае ее возникновения.
error_text | Данный параметр является ссылкой на исходную переменную. В нее будет возвращен текст ошибки в случае ее возникновения.
http_method Метод отправки запроса удаленному серверу. Допустимые значения:
  • "GET"
  • "POST"
Необязательный параметр, по умолчанию равен GET.
site_prefix Префикс адреса сайта для работы с SSL и TLS. Допустимые значения:
  • ""
  • "ssl://"
  • "tls://"
Необязательный параметр, по умолчанию равен "" (пустой строке) - стандартное соединение.

Ваш хостинг может не поддерживать соединения, отличные от стандартного.

Примеры использования

<?
// Запросим с сайта центрального банка РФ курсы валют за 18 января 2005 г
$strQueryText = QueryGetData(
    "www.cbr.ru",
    80,
    "/scripts/XML_daily.asp",
    "date_req=18.01.2005",
    $error_number,
    $error_text
    );
if (strlen($strQueryText)<=0)
{
   echo "Ошибка запроса курсов валют";
   if (intval($error_number)>0 || strlen($error_text)>0)
      echo ": (".$error_number.") ".$error_text;
   echo ". ";
}
else
{
   echo htmlspecialchars($strQueryText);
}
?>


Rel2Abs

string
Rel2Abs(
 string cur_dir,
 string rel_path
);

Возвращает путь относительно заданного каталога cur_dir.

Параметры функции

Параметр | Описание
cur_dir | Каталог, относительно которого задается путь rel_path.
rel_path | Относительный путь.

Примеры использования

<?
echo Rel2Abs("/site/", "/temp/index.php");		// /temp/index.php
echo Rel2Abs("/site/", "temp/index.php");		// /site/temp/index.php
echo Rel2Abs("/site/temp/", "../index.php");		// /site/index.php
echo Rel2Abs("/site/temp/", "../../index.php");	// /index.php
?>


ShowError

ShowError(
 string message,
 string css_class = "errortext"
);

Выводит сообщение об ошибке.

Параметры функции

Параметр | Описание
message | Строка сообщения.
css_class | Название CSS класса для оформления сообщения. Необязательный параметр, по умолчанию равен "errortext" (как правило красного цвета).

Примеры использования

<?
ShowError("Ошибка!");
?>


ShowMessage

ShowMessage(
  mixed message
);

Выводит ошибки и прочие сообщения.

Параметры функции

Параметр Описание
message Текст сообщения об ошибке или массив со следующими ключами:
  • TYPE - тип сообщения, допустимы следующие значения:
    • OK - обычное сообщения, для вывода будет использоваться CSS класс "notetext"
    • ERROR - сообщение об ошибке, для вывода будет использоваться CSS класс "errortext"
  • MESSAGE - текст сообщения.

Примеры использования

<?
// выведем обычное сообщение
ShowMessage(Array("TYPE"=>"OK", "MESSAGE"=>"Данные сохранены."));
?>
<?
// выведем сообщение об ошибке
ShowMessage("Ошибка! Вы забыли заполнить обязательные поля!");
?>


ShowNote

ShowNote(
 string message,
 string css_class = "notetext"
);

Выводит заданное сообщение.

Параметры функции

Параметр | Описание
message | Сообщение.
css_class | Название CSS класса для оформления сообщения. Необязательный параметр, по умолчанию равен "notetext" (как правило зеленого цвета).

Примеры использования

<?
ShowNote("Все в порядке!");
?>


Список событий

Ниже представлен список событий главного модуля. Для регистрации обработчика укажите в качестве идентификатора модуля - "main".

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

    См. также

    • Обработка событий
    • Связи и взаимодействие модулей

    События вызывающиеся в процессе выполнения страницы

    Событие | Описание
OnPageStart | Вызывается в начале выполняемой части пролога сайта, после подключения всех библиотек и отработки агентов.
OnBeforeProlog | Вызывается в конце выполняемой части пролога сайта (после события OnPageStart).
OnProlog | Вызывается в начале визуальной части пролога сайта.
OnEpilog | Вызывается в конце визуальной части эпилога сайта.
OnAfterEpilog | Вызывается в конце выполняемой части эпилога сайта (после события OnEpilog).

    См. также

    • Этапы выполнения страницы

    События при работе с пользователями и авторизация

    Событие | Описание
OnBeforeUserRegister | Вызывается до попытки зарегистрировать нового пользователя методом CUser::Register.
OnAfterUserRegister | Вызывается после попытки регистрации нового пользователя методом CUser::Register.
OnBeforeUserSimpleRegister | Вызывается до попытки упрощённой регистрации нового пользователя методом CUser::SimpleRegister.
OnAfterUserSimpleRegister | Вызывается после попытки упрощённой регистрации нового пользователя методом CUser::SimpleRegister
OnBeforeUserLogin | Вызывается до попытки авторизации пользователя методом CUser::Login.
OnUserLoginExternal | Вызывается перед попыткой авторизации пользователя методом CUser::Login, предназначен для проверки внешней авторизации.
OnAfterUserLogin | Вызывается после попытки авторизации пользователя методом CUser::Login.
OnBeforeUserLoginByHash | Вызывается перед попыткой авторизации пользователя методом CUser::LoginByHash.
OnAfterUserLoginByHash | Вызывается после попытки авторизации пользователя методом CUser::LoginByHash.
OnAfterUserAuthorize | Вызывается после авторизации пользователя.
OnBeforeUserLogout | Вызывается перед завершением сеанса авторизации пользователя методом CUser::Logout.
OnAfterUserLogout | Вызывается после завершения сеанса авторизации пользователя методом CUser::Logout.
OnBeforeUserAdd | Вызывается перед добавлением нового пользователя.
OnAfterUserAdd | Вызывается после добавления нового пользователя.
OnBeforeUserUpdate | Вызывается перед изменением параметров пользователя.
OnAfterUserUpdate | Вызывается после изменения параметров пользователя.
OnBeforeUserDelete | Вызывается перед удалением пользователя.
OnUserDelete | Вызывается во время удаления пользователя.
OnExternalAuthList | Вызывается для получения списка источников внешней авторизации.

    См. также

    • Внешняя авторизация

    События при работе с группами пользователей

    Событие | Описание
OnBeforeGroupDelete | Вызывается перед удалением группы пользователей.
OnGroupDelete | Вызывается после удаления группы пользователей.

    События при работе с файлами и правами

    Событие | Описание
OnChangeFile | Вызывается на изменение файла сразу после его сохранения.
OnChangePermissions | Вызывается при изменении прав доступа к файлу или папке.

    События при работе с шаблонами почтовых сообщений

    Событие | Описание
OnBeforeEventMessageDelete | Вызывается перед удалением почтового шаблона.
OnEventMessageDelete | Вызывается во время удаления почтового шаблона.

    События при работе с сайтами

    Событие | Описание
OnBeforeSiteDelete | Вызывается перед удалением сайта.
OnSiteDelete | Вызывается в момент удаления сайта.

    События при работе с языками

    Событие | Описание
OnBeforeLanguageDelete | Вызывается перед удалением языка.
OnLanguageDelete | Вызывается в момент удаления языка.

    События при работе с панелью управления

    Событие | Описание
OnPanelCreate | Вызывается в момент сбора данных для построения панели управления в публичной части сайта.

    См. также

    • Обработка событий
    • Связи и взаимодействие модулей


OnAfterEpilog

функция-обработчик();

Событие "OnAfterEpilog" возникает в конце выполняемой части эпилога сайта (после события OnEpilog).

Параметры функции-обработчика

Без параметров.

См. также

  • Событие "OnEpilog"
  • Этапы выполнения страницы и доступные на каждом этапе переменные и константы
  • Обработка событий

Пример регистрации функции-обработчика:

<?
RegisterModuleDependences("main",
                          "OnAfterEpilog",
                          "compression",
                          "CCompress",
                          "OnAfterEpilog");
?>


OnAfterUserAdd

функция-обработчик(
 array &arFields
);
Событие "OnAfterUserAdd" вызывается после попытки добавления нового пользователя методом CUser::Add.

Параметры

Параметр | Описание
arFields | Массив полей нового пользователя. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CUser::Add и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeUserAdd"
  • CUser::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnAfterUserAdd", Array("MyClass", "OnAfterUserAddHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterUserAdd"
    function OnAfterUserAddHandler(&$arFields)
    {
        if($arFields["ID"]>0)
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." добавлена.");
        else
            AddMessage2Log("Ошибка добавления записи (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterUserAuthorize

функция-обработчик(
 array user_fields
)
Обработчик события будет вызван из метода CUser::Authorize после авторизации пользователя, передавая в параметре user_fields массив всех полей авторизованного пользователя.

Параметры

Параметр | Описание
user_fields | Массив всех полей пользователя.

См. также

  • CUser::Authorize
  • Обработка событий
  • Внешняя авторизация

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnAfterUserAuthorize", Array("MyClass", "OnAfterUserAuthorizeHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterUserAuthorize"
    function OnAfterUserAuthorizeHandler($arUser)
    {
         // выполняем все действия связанные с авторизацией

    }
}
?>


OnAfterUserLogin

функция-обработчик(
 array &arParams
);

Событие "OnBeforeUserLogin" вызывается в методе CUser::Login после попытки авторизовать пользователя, проверив имя входа arParams['LOGIN'] и пароль arParams['PASSWORD'].

Параметры

Параметр Описание
arParams Массив полей проверки имени входа и пароля:
  • USER_ID - в случае если авторизация прошла успешно содержит код пользователя
  • RESULT_MESSAGE - массив с информационным текстом, описывающий результат проверки пользователя, в дальнейшем используется функцией ShowMessage для вывода сообщения.
  • LOGIN - Логин пользователя
  • PASSWORD - Пароль. Если параметр PASSWORD_ORIGINAL равен"Y", то в данном параметре был передан оригинальный пароль, в противном случае был передан хеш (md5) от оригинального пароля.
  • REMEMBER - Если значение равно "Y", то авторизация пользователя должна быть сохранена в куках.
  • PASSWORD_ORIGINAL - Если значение равно "Y", то это означает что PASSWORD не был сконвертирован в MD5 (т.е. в параметре PASSWORD был передан реальный пароль вводимый пользователем с клавиатуры), если значение равно "N", то это означает что PASSWORD уже сконвертирован в MD5.

Примечание
Все параметры данного обработчика являются ссылками на исходные переменные. Поэтому, если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.
Это позволяет, например, изменить RESULT_MESSAGE, что приведет к смене сообщения возвращаемого функцией CUser::Login.

См. также

  • Событие "OnBeforeUserLogin"
  • CUser::Login
  • Обработка событий
  • Внешняя авторизация

Пример функции-обработчика:

<?
AddEventHandler("main", "OnAfterUserLogin", Array("MyClass", "OnAfterUserLoginHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterUserLogin"
    function OnAfterUserLoginHandler(&$fields)
    {
        // если логин не успешен то
        if($fields['USER_ID']<=0)
        {
            // счетчик неудавшихся попыток логина
            $_SESSION["AUTHORIZE_FAILURE_COUNTER"]++;

            // если количество неудачных попыток авторизации превышает 10, то
            if ($_SESSION["AUTHORIZE_FAILURE_COUNTER"]>10)
            {
                // ищем пользователя по логину
                $rsUser = CUser::GetByLogin($fields['LOGIN']);
                // и если нашли, то
                if ($arUser = $rsUser->Fetch())
                {
                    // блокируем бюджет пользователя
                    $user = new CUser;
                    $user->Update($arUser["ID"],array("ACTIVE" => "N"));

                    // задаем сообщение
                    $fields['RESULT_MESSAGE'] = array("TYPE" => "ERROR", "MESSAGE" => "Ваш бюджет блокирован.");
                }
            }
        }
    }
}
?>


OnAfterUserLoginByHash

функция-обработчик(
 array &arParams
);
Событие "OnAfterUserLoginByHash" вызывается в методе CUser::LoginByHash() после проверки имени входа arParams['LOGIN'] и хеша от пароля arParams['HASH'] и попытки авторизовать пользователя. В параметре arParams['USER_ID'] будет передан код пользователя которого удалось авторизовать, а также массив с сообщением об ошибке arParams['RESULT_MESSAGE'].

Параметры

Параметр Описание
arParams Массив полей проверки имени входа и пароля:
  • USER_ID - в случае, если авторизация прошла успешно, содержит код пользователя
  • RESULT_MESSAGE - массив с информационным текстом, описывающий результат проверки пользователя, в дальнейшем используется функцией ShowMessage для вывода сообщения.
  • LOGIN - Логин пользователя
  • HASH - Пароль. Специальный хеш от пароля пользователя. Данный хеш как правило хранится в куках пользователя.

Некоторые параметры данного обработчика являются ссылками на исходные переменные. Поэтому если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.
Это позволяет, например, изменить RESULT_MESSAGE, что приведет к смене сообщения возвращаемого функцией CUser::LoginByHash.

См. также

  • Событие "OnBeforeUserLoginByHash"
  • CUser::LoginByHash
  • Обработка событий
  • Внешняя авторизация

Пример функции-обработчика:

// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnAfterUserLoginByHash", Array("MyClass", "OnAfterUserLoginByHashHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterUserLoginByHash"
    function OnAfterUserLoginByHashHandler(&$arParams)
    {
        if($arParams['USER_ID']<=0)
        {
            //переопределим сообщение об ошибке.
            $arParams['RESULT_MESSAGE'] = Array("MESSAGE" => "New error.", "TYPE" => "ERROR");
        }
    }
}
?>


OnAfterUserLogout

функция-обработчик(
 array &arParams
);
Событие "OnAfterUserLogout" вызывается после завершения авторизации пользователя.

Параметры

Параметр Описание
arParams Массив параметров:
  • ID - код пользователя
  • SUCCESS - результат операции: true, если авторизация завершена, false - в случае ошибки или отмены завершения авторзации обработчиком события OnBeforeUserLogout.

См. также

  • Событие "OnBeforeUserLogout"
  • CUser::Logout
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnAfterUserLogout"
    function OnAfterUserLogoutHandler($arParams)
    {
        // здесь выполняем все что касается завершения авторизации
        ...
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnAfterUserLogout"
RegisterModuleDependences("main", "OnAfterUserLogout",
"my_module_id", "MyClass", "OnAfterUserLogoutHandler");?>


OnAfterUserRegister

функция-обработчик(
 array &arFields
);
Событие "OnAfterUserRegister" вызывается после попытки регистрации нового пользователя методом CUser::Register.

Параметры

Параметр Описание
arFields Массив полей регистрации нового пользователя:
  • USER_ID - в случае если регистрация прошла успешно содержит код нового пользователя
  • RESULT_MESSAGE - массив с информационным текстом, описывающий результат регистрации пользователя, в дальнейшем используется функцией ShowMessage для вывода сообщения.
  • LOGIN - имя входа пользователя
  • NAME - имя пользователя
  • LAST_NAME - фамилия пользователя
  • PASSWORD - пароль
  • CONFIRM_PASSWORD - подтверждение пароля
  • CHECKWORD - новое контрольное слово для смены пароля
  • EMAIL - EMail пользователя
  • ACTIVE - флаг активности [Y|N]
  • SITE_ID - ID сайта по умолчанию для уведомлений
  • GROUP_ID - массив ID групп пользователя
  • USER_IP - IP адрес пользователя
  • USER_HOST - хост пользователя

Все параметры данного обработчика являются ссылками на исходные переменные. Поэтому если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.
Это позволяет, например, изменить RESULT_MESSAGE, что приведет к смене сообщения возвращаемого функцией CUser::Register.

См.также:

  • Событие "OnBeforeUserRegister"
  • Обработка событий
  • CUser::Register

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnAfterUserRegister"
    function OnAfterUserRegisterHandler(&$arFields)
    {
        // если регистрация успешна то
        if($arFields["USER_ID"]>0)
        {
            // если текущий сайт - r1, то
            if(SITE_ID=="r1")
            {
                // зададим сообщение об успешной регистрации на сайте r1
                $arFields["RESULT_MESSAGE"]["MESSAGE"] = "Вы успешно зарегистрировались на сайте \"Мой любимый сайт 1\"";
            }
            elseif(SITE_ID=="r2")
            {
                // зададим сообщение об успешной регистрации на сайте r2
                $arFields["RESULT_MESSAGE"]["MESSAGE"] = "Вы успешно зарегистрировались на сайте \"Мой любимый сайт 2\"";
            }
        }
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnAfterUserRegister"
RegisterModuleDependences("main", "OnAfterUserRegister", "my_module_id", "MyClass", "OnAfterUserRegisterHandler");
?>


OnAfterUserSimpleRegister

функция-обработчик(
 array &arFields,
);
Событие "OnAfterUserSimpleRegister" вызывается после попытки упрощённой регистрации нового пользователя методом CUser::SimpleRegister.

Параметры

Параметр Описание
arFields Массив полей регистрации нового пользователя:
  • USER_ID - в случае если регистрация прошла успешно содержит код нового пользователя
  • RESULT_MESSAGE - массив с информационным текстом, описывающий результат регистрации пользователя, в дальнейшем используется функцией ShowMessage для вывода сообщения.
  • PASSWORD - пароль
  • CONFIRM_PASSWORD - подтверждение пароля
  • CHECKWORD - контрольное слово для смены пароля
  • EMAIL - EMail пользователя
  • ACTIVE - флаг активности [Y|N]
  • SITE_ID - ID сайта по умолчанию для уведомлений
  • GROUP_ID - массив ID групп пользователя
  • USER_IP - IP адрес пользователя
  • USER_HOST - хост пользователя

Все параметры данного обработчика являются ссылками на исходные переменные. Поэтому если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.
Это позволяет, например, изменить RESULT_MESSAGE, что приведет к смене сообщения возвращаемого функцией CUser::SimpleRegister.

См.также:

  • Событие "OnBeforeUserSimpleRegister"
  • Обработка событий
  • CUser::Register

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnAfterUserSimpleRegister"
RegisterModuleDependences("main", "OnAfterUserSimpleRegister", "my_module_id", "MyClass", "OnAfterUserSimpleRegisterHandler");
?>

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnAfterUserSimpleRegister"
    function OnAfterUserSimpleRegisterHandler(&$fields)
    {
        // если регистрация успешна то
        if($fields["USER_ID"]>0)
        {
            // зададим сообщение об успешной регистрации
            $fields["RESULT_MESSAGE"]["MESSAGE"] = "Вы успешно зарегистрировались на сайте. Ваш логин - ".$fields["LOGIN"];
        }
    }
}
?>


OnAfterUserUpdate

функция-обработчик(
 array &arFields
);
Событие "OnAfterUserUpdate" вызывается после попытки изменения свойств пользователя методом CUser::Update.

Параметры

Параметр | Описание
arFields | Массив полей изменяемого пользователя. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CUser::Update и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeUserUpdate"
  • CUser::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnAfterUserUpdate", Array("MyClass", "OnAfterUserUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterUserUpdate"
    function OnAfterUserUpdateHandler(&$arFields)
    {
        if($arFields["RESULT"])
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." изменена.");
        else
            AddMessage2Log("Ошибка изменения записи ".$arFields["ID"]." (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnBeforeEventMessageDelete

bool
функция-обработчик(
 int template_id
);
Событие "OnBeforeEventMessageDelete" вызывается перед удалением почтового шаблона. Как правило задачи обработчика данного события - разрешить или запретить удаление почтового шаблона.

Параметры

Параметр | Описание
template_id | ID удаляемого почтового шаблона.

Возвращаемое значение

Для отмены удаления пользователя и прекращении выполнения метода CEventMessage::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnEventMessageDelete"
  • CEventMessage::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnBeforeEventMessageDelete"
    function OnBeforeEventMessageDeleteHandler($template_id)
    {
        // проверим есть ли связанные с удаляемым шаблоном записи
        $strSql = "SELECT * FROM my_table WHERE EMAIL_TEMPLATE_ID=".intval($template_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

        // если связанные записи есть то
        if ($ar = $rs->Fetch())
        {
            // запретим удаление почтового шаблона
            global $APPLICATION;
            $APPLICATION->throwException("В моей таблице есть связанные записи.");
            return false;
        }
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnBeforeEventMessageDelete"
RegisterModuleDependences("main", "OnBeforeEventMessageDelete",
             "my_module_id", "MyClass", "OnBeforeEventMessageDeleteHandler");
?>


OnBeforeGroupDelete

bool
функция-обработчик(
 int group_id
);
Событие "OnBeforeGroupDelete" вызывается перед удалением группы пользователей. Как правило задачи обработчика данного события - разрешить или запретить удаление группы пользователей.

Параметры

Параметр | Описание
group_id | ID удаляемой группы пользователей.

Возвращаемое значение

Для отмены удаления пользователя и прекращении выполнения метода CGroup::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnGroupDelete"
  • CGroup::Delete
  • Обработка событий

Пример:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeGroupDelete", Array("MyClass", "OnBeforeGroupDeleteHandler"));
class MyClass
{
    // создаем обработчик события "OnBeforeGroupDelete"
    function OnBeforeGroupDeleteHandler($group_id)
    {
        // проверим есть ли связанные с удаляемой группой пользователей записи
        $strSql = "SELECT * FROM my_table WHERE GROUP_ID=".intval($group_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

        // если связанные записи есть то
        if ($ar = $rs->Fetch())
        {
            // запретим удаление группы пользователей
            global $APPLICATION;
            $APPLICATION->throwException("В моей таблице есть связанные записи.");
            return false;
        }
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnBeforeGroupDelete" для модуля my_module_id
RegisterModuleDependences("main", "OnBeforeGroupDelete",
     "my_module_id", "MyClass", "OnBeforeGroupDeleteHandler");
?>


OnBeforeLanguageDelete

bool
функция-обработчик(
 string language_id
);
Событие "OnBeforeLanguageDelete" вызывается перед удалением языка. Как правило задачи обработчика данного события - разрешить или запретить удаление языка.

Параметры

Параметр | Описание
language_id | ID удаляемого языка.

Возвращаемое значение

Для отмены удаления языка и прекращении выполнения метода CLanguage::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnLanguageDelete"
  • CLanguage::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnBeforeLanguageDelete"
    function OnBeforeLanguageDeleteHandler($language_id)
    {
        // проверим есть ли связанные с удаляемым языком записи
        $strSql = "SELECT * FROM my_table WHERE LANGUAGE_ID=".$DB->ForSql($language_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

        // если связанные записи есть то
        if ($ar = $rs->Fetch())
        {
            // запретим удаление языка
            global $APPLICATION;
            $APPLICATION->throwException("В моей таблице есть связанные записи.");
            return false;
        }
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnBeforeLanguageDelete"
RegisterModuleDependences("main", "OnBeforeLanguageDelete",
         "my_module_id", "MyClass", "OnBeforeLanguageDeleteHandler");
?>


OnBeforeProlog

функция-обработчик();
Событие "OnBeforeProlog" вызывается в выполняемой части пролога сайта (после события OnPageStart).

Параметры функции-обработчика

Без параметров.

См. также

  • Событие "OnPageStart"
  • Этапы выполнения страницы и доступные на каждом этапе переменные и константы
  • Обработка событий

Пример:

<?
// файл /bitrix/php_interface/init.php
AddEventHandler("main", "OnBeforeProlog", "MyOnBeforePrologHandler", 50);

function MyOnBeforePrologHandler()
{
   global $USER;
   if(SITE_TEMPLATE_ID=='mynewtemplate' && $_SERVER['REMOTE_ADDR']!='127.0.0.1' && !$USER->IsAdmin())
      die('This template temporary unavailable.');
}
?>


OnBeforeSiteDelete

bool
функция-обработчик(
 string site_id
);
Событие "OnBeforeSiteDelete" вызывается перед удалением сайта. Как правило задачи обработчика данного события - разрешить или запретить удаление сайта.

Параметры

Параметр | Описание
site_id | ID удаляемого сайта.

Возвращаемое значение

Для отмены удаления сайта и прекращении выполнения метода CSite::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnSiteDelete"
  • CSite::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnBeforeSiteDelete"
    function OnBeforeSiteDeleteHandler($site_id)
    {
        // проверим есть ли связанные с удаляемым сайтом записи
        $strSql = "SELECT * FROM my_table WHERE SITE_ID=".$DB->ForSql($site_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

        // если связанные записи есть то
        if ($ar = $rs->Fetch())
        {
            // запретим удаление сайта
            global $APPLICATION;
            $APPLICATION->throwException("В моей таблице есть связанные записи.");
            return false;
        }
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnBeforeSiteDelete"
RegisterModuleDependences("main", "OnBeforeSiteDelete",
      "my_module_id", "MyClass", "OnBeforeSiteDeleteHandler");
?>


OnBeforeUserAdd

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CUser::Add до вставки нового пользователя, и может быть использовано для отмены вставки или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей нового пользователя.

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

Возвращаемое значение

Для отмены добавления и прекращении выполнения метода CUser::Add необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterUserAdd"
  • CUser::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeUserAdd", Array("MyClass", "OnBeforeUserAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeUserAdd"
    function OnBeforeUserAddHandler(&$arFields)
    {
        if(strlen($arFields["LAST_NAME"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Пожалуйста, введите фамилию.");
            return false;
        }
    }
}
?>


OnBeforeUserDelete

bool
функция-обработчик(
 int user_id
);
Событие "OnBeforeUserDelete" вызывается перед удалением пользователя. Как правило задачи обработчика данного события - разрешить или запретить удаление пользователя.

Параметры

Параметр | Описание
user_id | ID удаляемого пользователя.

Возвращаемое значение

Для отмены удаления пользователя и прекращении выполнения метода CUser::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnUserDelete"
  • CUser::Delete
  • Обработка событий

Пример:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeUserDelete", Array("MyClass", "OnBeforeUserDeleteHandler"));
class MyClass
{
    // создаем обработчик события "OnBeforeUserDelete"
    function OnBeforeUserDeleteHandler($user_id)
    {
        // проверим есть ли связанные с удаляемым пользователем записи
        $strSql = "SELECT * FROM my_table WHERE USER_ID=".intval($user_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);

        // если связанные записи есть то
        if ($ar = $rs->Fetch())
        {
            // запретим удаление пользователя
            global $APPLICATION;
            $APPLICATION->throwException("В моей таблице есть связанные записи.");
            return false;
        }
    }
}
?>


OnBeforeUserLogin

bool
функция-обработчик(
 array &arParams
);
Событие "OnBeforeUserLogin" вызывается в методе CUser::Login до проверки имени входа arParams['LOGIN'] и пароля arParams['PASSWORD'] и попытки авторизовать пользователя, и может быть использовано для прекращения процесса проверки или переопределения некоторых полей.

Параметры

Параметр Описание
arParams Массив полей для проверки имени входа и пароля:
  • LOGIN - Логин пользователя
  • PASSWORD - Пароль. Если параметр PASSWORD_ORIGINAL равен"Y", то в данном параметре был передан оригинальный пароль, в противном случае был передан хеш (md5) от оригинального пароля.
  • REMEMBER - Если значение равно "Y", то авторизация пользователя должна быть сохранена в куках.
  • PASSWORD_ORIGINAL - Если значение равно "Y", то это означает что PASSWORD не был сконвертирован в MD5 (т.е. в параметре PASSWORD был передан реальный пароль вводимый пользователем с клавиатуры), если значение равно "N", то это означает что PASSWORD уже сконвертирован в MD5.

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

Возвращаемое значение

Для отмены авторизации пользователя и прекращении выполнения метода CUser::Login необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterUserLogin"
  • CUser::Login
  • Обработка событий
  • Внешняя авторизация

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeUserLogin", Array("MyClass", "OnBeforeUserLoginHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeUserLogin"
    function OnBeforeUserLoginHandler(&$arFields)
    {
        // здесь выполняем любые действия связанные
        if(strtolower($arFields["LOGIN"])=="guest")
        {
            global $APPLICATION;
            $APPLICATION->throwException("Пользователь с именем входа Guest не может быть авторизован.");
            return false;
        }
    }
}
?>


OnBeforeUserLoginByHash

bool
функция-обработчик(
 array &arParams
)

Событие "OnBeforeUserLoginByHash" вызывается в методе CUser::LoginByHash() до проверки имени входа arParams['LOGIN'], хеша от пароля arParams['HASH'] и попытки авторизовать пользователя.

Параметры

Параметр Описание
arParams Массив полей для проверки имени входа и пароля:
  • LOGIN - Имя входа пользователя.
  • HASH - Специальный хеш от пароля пользователя. Данный хеш как правило хранится в куках пользователя.

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

Возвращаемое значение

Для отмены авторизации пользователя и прекращении выполнения метода CUser::LoginByHash необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterUserLoginByHash"
  • CUser::LoginByHash
  • Обработка событий
  • Внешняя авторизация

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeUserLoginByHash", Array("MyClass", "OnBeforeUserLoginByHashHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeUserLoginByHash"
    function OnBeforeUserLoginByHashHandler(&$arParams)
    {
        // здесь выполняем любые действия связанные
        if(strtolower($arParams['LOGIN'])=="guest")
        {
            global $APPLICATION;
            $APPLICATION->throwException("Пользователь с именем входа Guest не может авторизоваться по хешу.");
            return false;
        }
    }
}
?>


OnBeforeUserLogout

bool
функция-обработчик(
 array &arParams
);

Вызывается перед завершением сеанса авторизации пользователя методом CUser::Logout и может быть использовано для отмены завершения сеанса.

Параметры

Параметр Описание
arParams Массив параметров:
  • ID - код пользователя

См. также

  • Событие "OnAfterUserLogout"
  • CUser::Logout
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeUserLogout", Array("MyClass", "OnBeforeUserLogoutHandler"));
class MyClass
{
    function OnBeforeUserLogoutHandler($arParams)
    {
        if($arParams['ID']==10)
            return false;
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnBeforeUserLogout"
RegisterModuleDependences("main", "OnBeforeUserLogout",
"my_module_id", "MyClass", "OnBeforeUserLogoutHandler");?>


OnBeforeUserRegister

bool
функция-обработчик(
 array &arArgs
);
Событие "OnBeforeUserRegister" вызывается до попытки регистрации нового пользователя методом CUser::Register и может быть использовано для прекращения процесса регистрации или переопределения некоторых полей.

Параметры

Параметр Описание
arArgs Массив полей регистрации нового пользователя:
  • LOGIN - имя входа пользователя
  • NAME - имя пользователя
  • LAST_NAME - фамилия пользователя
  • PASSWORD - пароль
  • CONFIRM_PASSWORD - подтверждение пароля
  • CHECKWORD - новое контрольное слово для смены пароля
  • EMAIL - EMail пользователя
  • ACTIVE - флаг активности [Y|N]
  • SITE_ID - ID сайта по умолчанию для уведомлений
  • GROUP_ID - массив ID групп пользователя
  • USER_IP - IP адресс пользователя
  • USER_HOST - хост пользователя
На основании массива полей происходит добавление пользователя и отсылка почтового события NEW_USER.

Массив значений данного обработчика является ссылкой на исходные переменные. Поэтому при изменении значения параметра или добавлении нового поля в массив внутри обработчика приведет к смене значения исходной переменной поступившей на вход функции-обработчика.
Это позволяет, например, добавить в массив arArgs дополнительные регистрационные поля нового пользователя или поля для почтового события NEW_USER.

Возвращаемое значение

Для отмены авторизации пользователя и прекращении выполнения метода CUser::Register необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterUserRegister"
  • Обработка событий
  • CUser::Register

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnBeforeUserRegister"
    function OnBeforeUserRegisterHandler(&$arFields)
    {
        // если пользователь пришел по рекламной кампании #34, то
        if ($_SESSION["SESS_LAST_ADV_ID"]==34)
        {
            // добавляем его в группу #3
            $arFields["GROUP_ID"][] = 3;

            // добавим административный комментарий
            if (intval($_SESSION["SESS_ADV_ID"])>0)
                $arFields["ADMIN_NOTES"] = "Рекламная кампания #34 - прямой заход";
            else
                $arFields["ADMIN_NOTES"] = "Рекламная кампания #34 - возврат";

            $arFields["SITE_ID"] = "ru";
        }
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnBeforeUserRegister"
RegisterModuleDependences("main", "OnBeforeUserRegister", "my_module_id", "MyClass", "OnBeforeUserRegisterHandler");
?>


OnBeforeUserSimpleRegister

bool
функция-обработчик(
 array &arFields,
);
Событие "OnBeforeUserSimpleRegister" вызывается до попытки упрощённой регистрации нового пользователя методом CUser::SimpleRegister и может быть использовано для прекращения процесса регистрации или переопределения некоторых полей.

Параметры

Параметр Описание
arFields Массив полей упрощённой регистрации нового пользователя:
  • PASSWORD - пароль
  • CONFIRM_PASSWORD - подтверждение пароля
  • CHECKWORD - контрольное слово для смены пароля
  • EMAIL - EMail пользователя
  • ACTIVE - флаг активности [Y|N]
  • SITE_ID - ID сайта по умолчанию для уведомлений
  • GROUP_ID - массив ID групп пользователя
  • USER_IP - IP адрес пользователя
  • USER_HOST - хост пользователя
На основании массива полей происходит добавление пользователя и отсылка почтового события NEW_USER.

Все параметры данного обработчика являются ссылками на исходные переменные. Поэтому если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.
Это позволяет, например, добавить в массив fields дополнительные регистрационные поля или, например, определить поле LOGIN - имя входа пользователя (в противном случае после регистрации пользователя логин будет заменен user< ID нового пользователя>") .

Возвращаемое значение

Для отмены авторизации пользователя и прекращении выполнения метода CUser::SimpleRegister необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterUserSimpleRegister"
  • Обработка событий
  • CUser::Register

Пример:

<?
// файл /bitrix/php_interface/init.php
AddEventHandler(
    "main",
    "OnBeforeUserSimpleRegister",
    Array("MyClass", "OnBeforeUserSimpleRegisterHandler"),
    100,
    $_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/scripts/onbeforeusersimplereg.php"
);
?>
<?
// файл /bitrix/php_interface/scripts/onbeforeusersimplereg.php
class MyClass
{
    // создаем обработчик события "OnBeforeUserSimpleRegister"
    function OnBeforeUserSimpleRegisterHandler(&$arFields)
    {
        if (strpos($arFields["EMAIL"], "@mysite.com")===false)
        {
            global $APPLICATION;
            $APPLICATION->ThrowException("Регистрация возможно только для EMail адресов домена mysite.com");
            return false;
        }
    }
}
?>


OnBeforeUserUpdate

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CUser::Update до изменения параметров пользователя, и может быть использовано для отмены изменения или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей изменяемого пользователя.

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

Возвращаемое значение

Для отмены изменения и прекращении выполнения метода CUser::Update необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterUserUpdate"
  • CUser::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnBeforeUserUpdate", Array("MyClass", "OnBeforeUserUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeUserUpdate"
    function OnBeforeUserUpdateHandler(&$arFields)
    {
        if(is_set($arFields, "LAST_NAME") && strlen($arFields["LAST_NAME"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Пожалуйста, введите фамилию. (ID:".$arFields["ID"].")");
            return false;
        }
    }
}
?>


OnChangeFile

функция-обработчик(
 string path,
 string site_id
);

Событие "OnChangeFile" вызывается на изменение файла методом $APPLICATION->SaveFileContent, сразу после его сохранения.

Параметры

Параметр | Описание
path | Пусть к файлу относительно корня.
site_id | Идентификатор сайта на котором изменился файл.

См. также

  • Событие "OnChangePermissions"
  • CMain::SaveFileContent
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
AddEventHandler("main", "OnChangeFile", Array("MyClass", "OnChangeFileHandler"));
class MyClass
{
    // создаем обработчик события "OnChangeFile"
    function OnChangeFileHandler($path, $site)
    {
        // получим DOCUMENT_ROOT к указанному сайту
        $DOC_ROOT = CSite::GetSiteDocRoot($site);

        // получим содержимое файла по абсолютному пути
        $filesrc = $APPLICATION->GetFileContent($DOC_ROOT.$path);

        // парсинг содержимого файла
        $arContent = ParseFileContent($filesrc);
        $TITLE = $arContent["TITLE"];
        $BODY = $arContent["CONTENT"];

        // вставим в таблицу запись об изменении файла
        $arFields = array(
            "MODIFIED_BY" => $USER->GetID(), // кто изменил
            "TITLE"       => $TITLE,         // загововок файла
            "FILENAME"    => $path,          // путь к файлу относительно корня
            "SITE_ID"     => $site,          // идентификатор сайта
            "BODY"        => $BODY,          // содержимое файла
            );
        $arInsert = $DB->PrepareInsert("b_workflow_log", $arFields, "workflow");
        $strSql = "INSERT INTO b_workflow_log (TIMESTAMP_X,  ".$arInsert[0].") VALUES(now(), ".$arInsert[1].")";
        $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
    }
}
?>


OnChangePermissions

функция-обработчик(
 array site_path,
 array permissions
);
Событие "OnChangePermissions" вызывается при изменении прав доступа к файлу или папке методом $APPLICATION->SetFileAccessPermission.

Параметры

Параметр | Описание
site_path | Массив вида: array("идентификатор сайта", "путь к файлу относительно корня этого сайта").
permissions | Массив прав доступа.

См. также

  • Событие "OnChangeFile"
  • CMain::SetFileAccessPermission
  • Права доступа
  • Обработка событий

Пример:

<?
// файл /bitrix/modules/search/classes/mysql/search.php
class CSearch extends CAllSearch
{
    // создаем обработчик события "OnChangePermissions"
    function OnChangeFilePermissions($path, $permission)
    {
        CMain::InitPathVars($site, $path);
        $DOC_ROOT = CSite::GetSiteDocRoot($site);

        while(strlen($path)>0 && $path[strlen($path)-1]=="/") //отрежем / в конце, если есть
            $path=substr($path, 0, strlen($path)-1);

        global $APPLICATION, $DB;
        if(file_exists($DOC_ROOT.$path))
        {
            @set_time_limit(300);
            $arGroups = CSearch::GetGroupCached();
            if(is_dir($DOC_ROOT.$path))
            {
                $handle  = @opendir($DOC_ROOT.$path);
                while($file = @readdir($handle))
                {
                    if($file == "." || $file == "..") continue;
                    if(is_dir($DOC_ROOT.$path."/".$file))
                    {
                        if($path."/".$file=="/bitrix")
                            continue;
                    }
                    CSearch::OnChangeFilePermissions(Array($site, $path."/".$file), Array());
                }
            }
            else //if(is_dir($DOCUMENT_ROOT.$path))
            {
                $strGPerm = "0";
                for($i=0; $i<count($arGroups); $i++)
                {
                    if($arGroups[$i]>1)
                    {
                        $p = $APPLICATION->GetFileAccessPermission(Array($site, $path), Array($arGroups[$i]));
                        if($p>="R")
                        {
                            $strGPerm .= ",".$arGroups[$i];
                            if($arGroups[$i]==2) break;
                        }
                    }
                }

                $r = $DB->Query("SELECT ID FROM b_search_content WHERE MODULE_ID='main' AND ITEM_ID='".$site."|".$path."'");
                while($arR = $r->Fetch())
                    $DB->Query("DELETE FROM b_search_content_group WHERE SEARCH_CONTENT_ID=".$arR["ID"]);

                $strSql =
                    "INSERT INTO b_search_content_group(SEARCH_CONTENT_ID, GROUP_ID) ".
                    "SELECT S.ID, G.ID ".
                    "FROM b_search_content S, b_group G ".
                    "WHERE MODULE_ID='main' ".
                    "    AND ITEM_ID='".$site."|".$path."' ".
                    "    AND G.ID IN (".$strGPerm.") ";

                $DB->Query($strSql);
            } //if(is_dir($DOCUMENT_ROOT.$path))
        }//if(file_exists($DOCUMENT_ROOT.$path))
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnChangePermissions"
RegisterModuleDependences("main", "OnChangePermissions", "search", "CSearch", "OnChangeFilePermissions");
?>


OnEpilog

функция-обработчик();
Событие "OnEpilog" вызывается в конце визуальной части эпилога сайта.

Параметры функции-обработчика

Без параметров.

См. также

  • Событие "OnAfterEpilog"
  • Этапы выполнения страницы и доступные на каждом этапе переменные и константы
  • Обработка событий

Пример регистрации функции-обработчика:

<?
RegisterModuleDependences("main", "OnEpilog", "statistic", "CStatistic", "Set404", "100");
?>


OnEventMessageDelete

функция-обработчик(
 int template_id
);
Событие "OnEventMessageDelete" вызывается во время удаления почтового шаблона. Как правило задачи обработчика данного события - очистить базу данных от записей связанных с удаляемым почтовым шаблоном.

Параметры

Параметр | Описание
template_id | ID удаляемого почтового шаблона.

См. также

  • Событие "OnBeforeEventMessageDelete"
  • CEventMessage::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnEventMessageDelete"
    function OnEventMessageDeleteHandler($template_id)
    {
        // удалим связанные записи
        $strSql = "DELETE FROM my_table WHERE TEMPLATE_ID=".intval($template_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnEventMessageDelete"
RegisterModuleDependences("main", "OnEventMessageDelete",
          "my_module_id", "MyClass", "OnEventMessageDeleteHandler");
?>


OnExternalAuthList

array
функция-обработчик();
Событие "OnExternalAuthList" вызывается для получения списка источников внешней авторизации при вызове метода CUser::GetExternalAuthList.

Параметры

Без параметров.

Возвращаемое значение

Массив вида Array(Array("ID"=>"Код источника 1", "NAME"=>"Название источника 1"), ...) .

См. также

  • Обработка событий
  • CUser::GetExternalAuthList
  • Внешняя авторизация

Пример функции-обработчика:

<?
AddEventHandler("main", "OnExternalAuthList", Array("__IPBAuth", "OnExternalAuthList"));
class __IPBAuth
{
  function OnExternalAuthList()
  {
     return Array(
      Array("ID"=>"IPB", "NAME"=>"Invision Power Board")
      );
 }
}
?>


OnGroupDelete

функция-обработчик(
 int group_id
);
Событие "OnGroupDelete" вызывается в момент удаления группы пользователей. Как правило задачи обработчика данного события - очистить базу данных от записей связанных с удаляемой группой пользователей.

Параметры

Параметр | Описание
group_id | ID удаляемой группы пользователей.

См. также

  • Событие "OnBeforeGroupDelete"
  • CGroup::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
AddEventHandler("main", "OnGroupDelete", Array("MyClass", "OnGroupDeleteHandler"));
class MyClass
{
    // создаем обработчик события "OnGroupDelete"
    function OnGroupDeleteHandler($group_id)
    {
        // удалим связанные записи
        $strSql = "DELETE FROM my_table WHERE GROUP_ID=".intval($group_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
    }
}
?>


OnLanguageDelete

функция-обработчик(
 int language_id
);
Событие "OnLanguageDelete" вызывается во время удаления языка. Как правило задачи обработчика данного события - очистить базу данных от записей связанных с удаляемым языком.

Параметры

Параметр | Описание
language_id | ID удаляемого языка.

См. также

  • Событие "OnBeforeLanguageDelete"
  • CLanguage::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnLanguageDelete"
    function OnLanguageDeleteHandler($language_id)
    {
        // удалим связанные записи
        $strSql = "DELETE FROM my_table WHERE LANGUAGE_ID=".$DB->ForSql($language_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnLanguageDelete"
RegisterModuleDependences("main", "OnLanguageDelete",
            "my_module_id", "MyClass", "OnLanguageDeleteHandler");
?>


OnPageStart

функция-обработчик();
Событие "OnPageStart" вызывается в начале выполняемой части пролога сайта, после подключения всех библиотек и отработки агентов.

Параметры функции-обработчика

Без параметров.

См. также

  • Событие "OnBeforeProlog"
  • Этапы выполнения страницы и доступные на каждом этапе переменные и константы
  • Обработка событий

Пример регистрации функции-обработчика:

<?
RegisterModuleDependences("main", "OnPageStart", "statistic", "CStatistic", "Stoplist", "100");
?>


OnPanelCreate

функция-обработчик();
Событие "OnPanelCreate" вызывается в момент сбора данных для построения панели управления в публичной части сайта. Как правило задачи обработчика данного события - добавлять свои кнопки в панель управления сайтом.

Параметры

Без параметров.

См. также

  • Панель управления
  • CMain::AddPanelButton
  • CMain::ShowPanel
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("main", "OnPanelCreate", Array("MyClass", "OnPanelCreateHandler"));
class MyClass
{
    // добавим кнопку в панель управления
    function OnPanelCreateHandler()
    {
        global $APPLICATION;
        $APPLICATION->AddPanelButton(array(
            "HREF"      => "/bitrix/admin/my_page.php", // ссылка на кнопке
            "SRC"       => "/bitrix/images/my_module_id/button_image.gif", // картинка на кнопке
            "ALT"       => "Текст всплывающей подсказки на кнопке",
            "MAIN_SORT" => 300,
            "SORT"      => 10
            ));
    }
    /*
    Теперь при выводе панели управления в публичной части сайта
    будет также всегда выводиться наша кнопка
    */
}
?>


OnProlog

функция-обработчик();
Событие "OnProlog" вызывается в начале визуальной части пролога сайта.

Параметры функции-обработчика

Без параметров.

См. также

  • Событие "OnBeforeProlog"
  • Этапы выполнения страницы и доступные на каждом этапе переменные и константы
  • Обработка событий

Пример регистрации функции-обработчика:

<?
    RegisterModuleDependences("main",
                              "OnProlog",
                              "statistic",
                              "CStatistic",
                              "StartBuffer", "100");
?>


OnSendUserInfo

функция-обработчик(
  array &arParams
);
Событие "OnSendUserInfo" вызывается в методе CUser::SendUserInfo и предназначено для возможности переопределения параметров для отправки почтового события USER_INFO.

Параметры

Параметр Описание
arParams Массив полей для проверки имени входа и пароля:
  • FIELDS - Массив, содержащий набор полей вида Array("поле 1"=>"значение 1", ...). При отправке все поля передаются в обработку шаблона USER_INFO. Содержит по умолчанию след. поля:
    • "USER_ID" - код пользователя,
    • "STATUS" - текст статуса активности,
    • "MESSAGE" - текст сообщения,
    • "LOGIN" - имя входа,
    • "CHECKWORD" - контрольная строка,
    • "NAME" - имя пользователя,
    • "LAST_NAME" - фамилия,
    • "EMAIL" - E-Mail адрес
  • USER_FIELDS - Все поля пользователя, информация о котором будет высылаться.
  • SITE_ID - код сайта, используется для определения шаблона почтового события USER_INFO.

Параметр данного обработчика и элементы массива arParams являются ссылками на исходные переменные. Поэтому если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.

См. также

  • CUser::SendUserInfo
  • Почтовые события
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
AddEventHandler("main", "OnSendUserInfo", "MyOnSendUserInfoHandler");
function MyOnSendUserInfoHandler(&$arParams)
{
    if(strlen($arParams['USER_FIELDS']['LAST_NAME'])<=0)
        $arParams['CUSTOM_NAME'] = $arParams['USER_FIELDS']['LAST_NAME'];
    else
        $arParams['CUSTOM_NAME'] = $arParams['USER_FIELDS']['LOGIN'];
    // теперь в шаблоне USER_INFO можно использовать макрос #CUSTOM_NAME#
}
?>


OnSiteDelete

функция-обработчик(
 int site_id
);
Событие "OnSiteDelete" вызывается во время удаления сайта. Как правило задачи обработчика данного события - очистить базу данных от записей связанных с удаляемым сайтом.

Параметры

Параметр | Описание
site_id | ID удаляемого сайта.

См. также

  • Событие "OnBeforeSiteDelete"
  • CSite::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnSiteDelete"
    function OnSiteDeleteHandler($site_id)
    {
        // удалим связанные записи
        $strSql = "DELETE FROM my_table WHERE SITE_ID=".$DB->ForSql($site_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnSiteDelete"
RegisterModuleDependences("main", "OnSiteDelete",
       "my_module_id", "MyClass", "OnSiteDeleteHandler");
?>


OnUserDelete

функция-обработчик(
 int user_id
)
Событие "OnUserDelete" вызывается в момент удаления пользователя. Как правило задачи обработчика данного события - очистить базу данных от записей связанных с удаляемым пользователем.

Параметры

Параметр | Описание
user_id | ID удаляемого пользователя.

См. также

  • Событие "OnBeforeUserDelete"
  • CUser::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/modules/my_module_id/include.php
class MyClass
{
    // создаем обработчик события "OnUserDelete"
    function OnUserDeleteHandler($user_id)
    {
        // удалим связанные записи
        $strSql = "DELETE FROM my_table WHERE USER_ID=".intval($user_id);
        $rs = $DB->Query($strSql, false, "FILE: ".__FILE__."<br>LINE: ".__LINE__);
    }
}
?>

Пример регистрации функции-обработчика:

<?
// регистрируем обработчик события "OnUserDelete"
RegisterModuleDependences("main", "OnUserDelete",
        "my_module_id", "MyClass", "OnUserDeleteHandler");
?>


OnUserLoginExternal

mixed
функция-обработчик(
  array &arParams
);

Событие OnUserLoginExternal предназначено для возможности проверки имени входа и пароля во внешнем источнике. Обработчики этого события вызываются в методе CUser::Login, если ни один обработчик события OnBegoreUserLogin не вернул false, перед стандартной проверкой имени входа arParams['LOGIN'], пароля arParams['PASSWORD'] и попытки авторизовать пользователя.

Параметры

Параметр Описание
arParams Массив полей для проверки имени входа и пароля:
  • LOGIN - Логин пользователя
  • PASSWORD - Пароль. Если параметр PASSWORD_ORIGINAL равен"Y", то в данном параметре был передан оригинальный пароль, в противном случае был передан хеш (md5) от оригинального пароля.
  • REMEMBER - Если значение равно "Y", то авторизация пользователя должна быть сохранена в куках.
  • PASSWORD_ORIGINAL - Если значение равно "Y", то это означает что PASSWORD не был сконвертирован в MD5 (т.е. в параметре PASSWORD был передан реальный пароль вводимый пользователем с клавиатуры), если значение равно "N", то это означает что PASSWORD уже сконвертирован в MD5.

Параметр данного обработчика и элементы массива arParams являются ссылками на исходные переменные. Поэтому если вы измените значение параметра внутри обработчика, это приведет к смене значения исходной переменной поступившей на вход функции-обработчика.

Возвращаемое значение

Если необходимо авторизовать пользователя, то обработчик события должен вернуть идентификатор этого пользователя.

См. также

  • Событие "OnBeforeUserLogin"
  • Событие "OnAfterUserLogin"
  • CUser::Login
  • Обработка событий
  • Внешняя авторизация

Пример функции-обработчика:

<?
// пример авторизации пользователя из таблиц форума Innovision Power Board

// файл /bitrix/php_interface/init.php
AddEventHandler("main", "OnUserLoginExternal", Array("__IPBAuth", "OnUserLoginExternal"));
AddEventHandler("main", "OnExternalAuthList", Array("__IPBAuth", "OnExternalAuthList"));

define("IPB_TABLE_PREFIX", "ibf_");
define("IPB_VERSION", "2");

class __IPBAuth
{
    function OnUserLoginExternal(&$arArgs)
    {
        $groups_map = Array(
            /*'IPB Group ID' => 'Local Group ID',*/
            '4' => '1'
            );
        $table_user = IPB_TABLE_PREFIX."members";
        $table_converge = IPB_TABLE_PREFIX."members_converge";

        global $DB, $USER, $APPLICATION;
     extract($arArgs);

        if(IPB_VERSION == '1')
        {
            $strSql = "SELECT * FROM ".$table_user." WHERE name='".
                      $DB->ForSql($LOGIN)."' AND password='".md5($PASSWORD)."'";
        }
        else
        {
            $strSql =
                "SELECT t1.* ".
                "FROM ".$table_user." t1, ".$table_converge." t2 ".
                "WHERE t1.name='".$DB->ForSql($LOGIN)."' ".
                "    AND t1.email = t2.converge_email ".
                "    AND t2.converge_pass_hash = MD5(CONCAT(MD5(t2.converge_pass_salt), '".md5($PASSWORD)."'))";
        }

        $dbAuthRes = $DB->Query($strSql);
        if($arAuthRes = $dbAuthRes->Fetch())
        {
            $arFields = Array(
                "LOGIN" => $LOGIN,
                "NAME" => $arAuthRes['title'],
                "PASSWORD" => $PASSWORD,
                "EMAIL" => $arAuthRes['email'],
                "ACTIVE" => "Y",
                "EXTERNAL_AUTH_ID"=>"IPB",
                "LID" => SITE_ID
                );

            $oUser = new CUser;
            $res = CUser::GetList($O, $B, Array("LOGIN_EQUAL_EXACT"=>$LOGIN, "EXTERNAL_AUTH_ID"=>"IPB"));
            if(!($ar_res = $res->Fetch()))
                $ID = $oUser->Add($arFields);
            else
            {
                $ID = $ar_res["ID"];
                $oUser->Update($ID, $arFields);
            }

            if($ID>0)
            {
                $USER->SetParam("IPB_USER_ID", $arAuthRes['id']);

                $user_group = $arAuthRes['mgroup'];
                $arUserGroups = CUser::GetUserGroup($ID);
                foreach($groups_map as $ext_group_id => $group_id)
                {
                    if($ext_group_id==$user_group)
                        $arUserGroups[] = $group_id;
                    else
                    {
                        $arUserGroupsTmp = Array();
                        foreach($arUserGroups as $grid)
                            if($grid != $group_id)
                                $arUserGroupsTmp[] = $grid;
                        $arUserGroups = $arUserGroupsTmp;
                    }
                }
                CUser::SetUserGroup($ID, $arUserGroups);
                $arParams["STORE_PASSWORD"] = "N";

                return $ID;
            }
        }
    }

    function OnExternalAuthList()
    {
        return Array(
            Array("ID"=>"IPB", "NAME"=>"Invision Power Board")
            );
    }
}?>


Структура таблиц модуля блогов

Блоги

  • Классы
  • События
  • Информация для разработчиков
  • Константы модуля блогов
  • Структура таблиц модуля блогов


Информация для разработчиков

Перед использованием модуля необходимо проверить, установлен ли он и подключить его при помощи конструкции:

<?
if (CModule::IncludeModule("blog"))
{
   //здесь можно использовать функции модуля
}
?>


Константы модуля блогов

Ниже приведены все константы, которые используются в модуле блогов. В описании констант используется понятие "объект", которым может быть блог, сообщение, комментарий и т.д.

Константа | Значение | Описание
BLOG_PERMS_DENY | D | Доступ запрещён ко всем объектам блога.
BLOG_PERMS_READ | I | Чтение всех объектов.
BLOG_PERMS_WRITE | P | Чтение всех объектов и запись своих объектов.
BLOG_PERMS_FULL | W | Чтение всех объектов, запись всех объектов.
BLOG_PERMS_POST | P | Сообщения
BLOG_PERMS_COMMENT | C | Комментарии
BLOG_PUBLISH_STATUS_DRAFT | D | Статус "Черновик". Видит только автор или пользователь с правами BLOG_PERMS_FULL.
BLOG_PUBLISH_STATUS_PUBLISH | P | Статус "Опубликовано". Видят все, у кого есть права BLOG_PERMS_READ.
BLOG_BY_USER_ID | 1 | Используется при поиске по идентификатору пользователя сайта.
BLOG_BY_BLOG_USER_ID | 2 | Используется при поиске по идентификатору пользователя блога.
BLOG_ADD | 1 | Действие - добавление.
BLOG_CHANGE | 2 | Действие - изменение.
BLOG_RESET | 3 | Действие - сброс.


Структура таблиц модуля блогов

Блог

Поле | Описание
ID | Идентификатор блога.
NAME | Название блога.
DESCRIPTION | Описание блога.
DATE_CREATE | Дата создания блога.
DATE_UPDATE | Дата последнего изменения блога.
ACTIVE | Флаг активности блога.
OWNER_ID | Идентификатор пользователя - владельца блога.
URL | Адрес блога.
GROUP_ID | Идентификатор группы блога.
ENABLE_COMMENTS | Флаг - разрешены ли комментарии в блоге.
ENABLE_IMG_VERIF | Флаг - использовать ли CAPTCHA для анонимных комментариев.
ENABLE_RSS | Флаг - разрешен ли экспорт в RSS блога.
LAST_POST_ID | Идентификатор последнего сообщения в блоге.
LAST_POST_DATE | Дата последнего сообщения в блоге.
AUTO_GROUPS | Открытые группы.
EMAIL_NOTIFY | Флаг - отправлять ли письма на Email с новыми комментариями, сообщениями.

Сообщения блога

Поле | Описание
ID | Идентификатор сообщения.
TITLE | Заголовок сообщения.
BLOG_ID | Идентификатор блога сообщения.
AUTHOR_ID | Идентификатор автора сообщения - пользователя сайта.
DETAIL_TEXT | Текст сообщения.
DATE_CREATE | Дата создания сообщения.
DATE_PUBLISH | Дата публикации сообщения.
KEYWORDS | Ключевые слова сообщения.
PUBLISH_STATUS | Статус сообщения.
CATEGORY_ID | Идентификатор категории сообщения.
ATRIBUTE | Атрибуты сообщения.
ENABLE_TRACKBACK | Флаг - разрешены ли Trackback'и для этого сообщения.
ENABLE_COMMENTS | Флаг - разрешены ли комментарии для этого сообщения.
NUM_COMMENTS | Количество комментариев к сообщению.
NUM_TRACKBACKS | Количество Trackback'ов к сообщению.

Комментарии к сообщениям блога

Поле | Описание
ID | Идентификатор комментария.
BLOG_ID | Идентификатор блога.
POST_ID | Идентификатор сообщения.
PARENT_ID | Идентификатор родителя комментария.
AUTHOR_ID | Идентификатор пользователя - автора комментария.
ICON_ID | Идентификатор иконки комментария.
AUTHOR_NAME | Имя анонимного автора комментария.
AUTHOR_EMAIL | Email анонимного автора комментария.
AUTHOR_IP | IP автора комментария.
AUTHOR_IP1 | IP автора комментария.
DATE_CREATE | Дата создания комментария.
TITLE | Заголовок комментария.
POST_TEXT | Текст комментария.

Группы блогов

Поле | Описание
ID | Идентификатор группы.
NAME | Название группы.
SITE_ID | Идентификатор сайта группы.

Trackback'и к сообщениям блога

Поле | Описание
ID | Идентификатор Trackback'a.
TITLE | Заголовок Trackback'а.
URL | Адрес Trackback'а.
PREVIEW_TEXT | Текст Trackback'а.
BLOG_NAME | Название блога.
BLOG_ID | Идентификатор блога.
POST_DATE | Дата создания сообщения.
POST_ID | Идентификатор сообщения.

Пользователи блога

Поле | Описание
ID | Идентификатор пользователя блога.
USER_ID | Идентификатор пользователя сайта.
ALIAS | Псевдоним пользователя блога.
DESCRIPTION | Описание пользователя блога.
AVATAR | Аватар пользователя блога.
INTERESTS | Интересы пользователя блога.
LAST_VISIT | Дата последнего посещения.
DATE_REG | Дата регистрации пользователя блога.
ALLOW_POST | Флаг. Определяет, разрешено ли пользователю создавать сообщения в блогах.

Группы пользователей блога

Поле | Описание
ID | Идентификатор группы пользователей блога.
NAME | Название группы пользователей блога.
BLOG_ID | Идентификатор блога группы пользователей.


Классы модуля блогов

Следующие PHP классы используются в модуле блогов.

Классы

Класс | Описание
CBlog | Класс для работы с блогами.
CBlogCandidate | Класс для работы с желающими стать друзьями.
CBlogCategory | Класс для работы с категориями сообщений блога.
CBlogComment | Класс для работы с комментариями к сообщениям.
CBlogGroup | Класс для работы с группами блогов.
CBlogPost | Класс для работы с сообщениями блогов.
CBlogSitePath | Класс для работы с путями к публичной части блогов.
CBlogTrackBack | Класс для работы с TrackBack'ами к сообщениям.
CBlogUser | Класс для работы с пользователями блогов.
CBlogUserGroup | Класс для работы с группами пользователей блогов.
blogTextParser | Класс для форматирования сообщений.


Класс blogTextParser

blogTextParser - класс, предназначенный для форматирования сообщений и комментариев блогов. Осуществляет замену спецсимволов и заказных тегов на реальные HTML-теги, обработку ссылок, отображение смайлов и изображений.

Методы класса

Метод | Описание
convert | Функция форматирования сообщения.


convert

string
convert(
 string text,
 bool   bPreview = true,
 array  arImages = array(),
 array  arAllow = array("HTML" =>   "N",
                        "ANCHOR" => "Y",
                        "BIU" =>    "Y",
                        "IMG" =>    "Y",
                        "QUOTE" =>  "Y",
                        "CODE" =>   "Y",
                        "FONT" =>   "Y",
                        "LIST" =>   "Y",
                        "SMILES" => "Y",
                        "NL2BR" =>  "N")
);

Метод форматирует текст text в соответствии с параметрами bPreview, arImages, arAllow.

Параметры функции

Параметр | Описание
text | Исходный текст сообщения.
bPreview Флаг - обрезать ли текст для просмотра (по тегу [CUT]).
Необязательный. По умолчанию true - текст будет обрезан до тега [CUT].
arImages Массив вида array(array(IMAGE_ID, FILE_ID)[, ...]).
  • IMAGE_ID - идентификтор изображения в сообщении;
  • FILE_ID - идентификатор файла этого изображения.
Необязательный. По умолчания теги изображений не будут заменяться.
arAllow Массив параметров форматирования сообщения. Допустимы следующие параметры:
  • HTML - в тексте могут содержаться любые HTML теги
  • ANCHOR - разрешен тег <a>;
  • BIU - разрешены теги <b>, <i>, <u>;
  • IMG - разрешен тег <img>;
  • QUOTE - разрешен тег цитирования <quote>;
  • CODE - разрешен тег показа кода <code>;
  • FONT - разрешен тег <font>;
  • LIST - разрешены теги <ul>, <li>;
  • SMILES - показ смайликов в виде картинок;
  • NL2BR - заменять переводы каретки на тег <br> при разрешении принимать любые HTML теги.
Параметры могут принимать значения Y и N.

Возвращаемое значение

Метод возвращает отформатированное сообщение.

Примеры использования

<?
$arPost = CBlogPost::GetByID(3);
$p = new blogTextParser();

$res = CBlogImage::GetList(array("ID"=>"ASC"),
                           array("POST_ID"=>$arPost['ID'],
                           "BLOG_ID"=>$arPost['BLOG_ID']));
while ($arImage = $res->Fetch())
    $arImages[$arImage['ID']] = $arImage['FILE_ID'];

$text = $p->convert($arPost["DETAIL_TEXT"], false, $arImages);
?>


Класс CBlog

CBlog - класс для работы с блогами.

Метод | Описание
Add | Добавляет новый блог.
BuildRSS | Возвращает RSS сообщений блога.
CanUserCreateBlog | Проверяет - может ли пользователь создать блог.
CanUserManageBlog | Проверяет - может ли пользователь управлять блогом.
Delete | Удаляет блог.
GetBlogUserCommentPerms | Возвращает доступ к комментариям.
GetBlogUserPostPerms | Возвращает доступ к сообщениям.
GetByID | Возвращает блог по его идентификатору.
GetByOwnerID | Возвращает блог по идентификатору его владельца.
GetList | Возвращает список блогов по фильтру.
IsBlogOwner | Проверяет является ли пользователь владельцем блога.
IsFriend | Проверяет является ли пользователь другом блога.
PreparePath | Возвращает путь к блогу.
Update | Изменяет блог.


Add

CBlog::Add

int
CBlog::Add(
 array arFields
);

Метод добавляет новый блог.

Параметры функции

Параметр | Описание
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей блога. Также можно задать уровень доступа на сообщения и комментарии. Для этого необходимо задать массив вида array("PERMS_POST" => array("userGroupID" => "Permission"[, ...]), "PERMS_COMMENT" => array("userGroupID" => "Permission"[, ...])), где userGroupID - группа пользователей блога, Permission - уровень доступа.

Возвращаемое значение

Метод возвращает идентификатор добавленного блога, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlog::Update
  • Поля блога
  • Уровни доступа

Примеры использования

<?
$arFields = array(
    "NAME" => 'Блог администратора сайта',
    "DESCRIPTION" => 'В блоге описаны все изменения, происходящие на сайте',
    "GROUP_ID" => '1',
    "ENABLE_IMG_VERIF" => 'Y',
    "EMAIL_NOTIFY" => 'Y',
    "ENABLE_RSS" => "Y",
    "URL" => "admin-blog",
    "ACTIVE" => "Y",
    "OWNER_ID" => $USER->GetID()
);

$newID = CBlog::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новый блог [".$newID."] создан.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


BuildRSS

CBlog::BuildRSS

array
CBlog::BuildRSS(
 int    ID,
 string type = "RSS .92",
 int    numPosts = 10,
);

Метод возвращает сгенерированный RSS в формате type блога ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
type | Формат возвращаемого RSS. Может принимать значения: RSS .92 RSS 2.0 ATOM .03 Необязательный. По умолчанию RSS генерируется в формате RSS .92.
numPosts | Количество сообщений для экспорта. Необязательный. По умолчанию возвращется 10 последних сообщений.

Возвращаемое значение

Возвращается сгенерированный RSS сообщений блога.

Примеры использования

<?
echo CBlog::BuildRSS("2", "RSS 2.0", 25);
?>


CanUserCreateBlog

CBlog::CanUserCreateBlog

bool
CBlog::CanUserCreateBlog(
 int userID = 0
);

Метод проверяет имеет ли право пользователь userID создать и вести блог.

Параметры функции

Параметр | Описание
userID | Идентификатор пользователя. Необязательный. По умолчанию проверка осуществляется для текущего пользователя.

Возвращаемое значение

Метод возвращает true в случае если пользователь имеет право создать блог, в противном случае возвращает false.

См. также

  • CBlog::CanUserManageBlog

Примеры использования

<?
if(CBlog::CanUserCreateBlog($USER->GetID())
    echo "Вы можете создать и вести блог.";
else
    echo "Вы не можете создать и вести блог.";
?>


CanUserManageBlog

CBlog::CanUserManageBlog

bool
CBlog::CanUserManageBlog(
 int ID,
 int userID
);

Метод проверяет может ли пользователь userID управлять блогом ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает true в случае если пользователь может управлять блогом, в противном случае возвращает false.

См. также

  • CBlog::CanUserCreateBlog

Примеры использования

<?
if(CBlog::CanUserManageBlog(1, $USER->GetID())
    echo "Вы можете управлять блогом.";
else
    echo "Вы не можете управлять блогом.";
?>


Delete

CBlog::Delete

bool
CBlog::Delete(
 int ID
);

Метод удаляет блог ID и все связанные с ним объекты.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.

Возвращаемое значение

Метод возвращает true в случае успешного удаления блога и всех связанных с ним объектов, в противном случае возвращает false.

Примеры использования

<?
$DB->StartTransaction();
if(!CBlog::Delete($ID))
{
    echo 'Ошибка удаления блога '.$ID;
    $DB->Rollback();
}
else
    $DB->Commit();
?>


GetBlogUserCommentPerms

CBlog::GetBlogUserCommentPerms

string
CBlog::GetBlogUserCommentPerms(
 int ID,
 int userID
);

Метод возвращает право пользователя userID на комментарии блога ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает право пользователя на комментарии блога.

См. также

  • Уровни доступа к комментариям
  • CBlog::GetBlogUserPostPerms()

Примеры использования

<?
$perms = CBlog::GetBlogUserCommentPerms(1, $USER->GetID());
echo "Вы имеете следующее право на комментарии блога: ".$perms;
?>


GetBlogUserPostPerms

CBlog::GetBlogUserPostPerms

string
CBlog::GetBlogUserPostPerms(
 int ID,
 int userID
);

Метод возвращает право пользователя userID на сообщения блога ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает право пользователя на сообщения блога.

См. также

  • Уровни доступа к сообщениям блога
  • CBlog::GetBlogUserCommentPerms()

Примеры использования

<?
$perms = CBlog::GetBlogUserPostPerms(1, $USER->GetID());
echo "Вы имеете следующее право на сообщения блога: ".$perms;
?>


GetByID

CBlog::GetByID

array
CBlog::GetByID(
 int ID
);

Метод возвращает параметры блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.

Возвращаемое значение

Возвращается массив с полями блога.

Примечание

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

См. также

  • Поля блога
  • CBlog::GetList()
  • CBlog::GetByOwnerID()

Примеры использования

<?
$ID = 1;
$arBlog = CBlog::GetByID($ID);
if(is_array($arBlog))
    print_r($arBlog);
else
    echo "Блог не найден";
?>


GetByOwnerID

CBlog::GetByOwnerID

array
CBlog::GetByOwnerID(
 int userID
);

Метод возвращает блог пользователя с идентификатором userID.

Параметры функции

Параметр | Описание
userID | Идентификатор пользователя.

Возвращаемое значение

Возвращается массив с полями блога.

Примечание

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

См. также

  • Поля блога
  • CBlog::GetList()

Примеры использования

<?
$arBlog = CBlog::GetByOwnerID($ID);
if(is_array($arBlog))
    print_r($arBlog);
else
    echo "Блог не найден";
?>


GetList

CBlog::GetList

CDBResult
CBlog::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список блогов по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор блога;
  • NAME - название блога;
  • DATE_CREATE - дата создания блога;
  • DATE_UPDATE - дата изменения блога;
  • ACTIVE - активность блога;
  • OWNER_ID - идентификатор владельца блога;
  • URL - адрес блога;
  • GROUP_ID - идентификатор группы блога;
  • GROUP_NAME - название группы блога;
  • GROUP_SITE_ID - идентификатор сайта группы блога;
  • LAST_POST_ID - идентификатор последнего сообщения в блоге;
  • LAST_POST_DATE - дата последнего сообщения в блоге;
  • OWNER_LOGIN - логин владельца блога;
  • OWNER_NAME - имя владельца блога;
  • OWNER_LAST_NAME - фамилия владельца блога;
  • OWNER_EMAIL - электронный адрес владельца блога;
  • BLOG_USER_ALIAS - псевдоним владельца блога;
Необязательный. По умолчанию фильтруется по убыванию идентификатора блога.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор блога;
  • NAME - название блога;
  • DATE_CREATE - дата создания блога;
  • DATE_UPDATE - дата изменения блога;
  • ACTIVE - активность блога;
  • OWNER_ID - идентификатор владельца блога;
  • URL - адрес блога;
  • GROUP_ID - идентификатор группы блога;
  • GROUP_NAME - название группы блога;
  • GROUP_SITE_ID - идентификатор сайта группы блога;
  • ENABLE_COMMENTS - включены ли комментарии в блоге;
  • ENABLE_IMG_VERIF - включена ли CAPTCHA для комментариев в блоге;
  • EMAIL_NOTIFY - включено ли уведомление по Email в блоге;
  • ENABLE_RSS - включен ли экспорт в RSS блога;
  • LAST_POST_ID - идентификатор последнего сообщения в блоге;
  • LAST_POST_DATE - дата последнего сообщения в блоге;
  • OWNER_LOGIN - логин владельца блога;
  • OWNER_NAME - имя владельца блога;
  • OWNER_LAST_NAME - фамилия владельца блога;
  • OWNER_EMAIL - электронный адрес владельца блога;
  • BLOG_USER_ALIAS - псевдоним владельца блога;
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля блога

Примеры использования

<?
// выберем все активные блоги, привязанные к текущему сайту.
// результат будет отсортирован сначала по дате создания, затем по названию блога
// выберутся только необходимые нам поля: Идентификатор блога, Название блога, Адрес блога,
// Идентификатор владельца блога и Дату создания блога
$SORT = Array("DATE_CREATE" => "DESC", "NAME" => "ASC");
$arFilter = Array(
        "ACTIVE" => "Y",
        "GROUP_SITE_ID" => SITE_ID
    );
$arSelectedFields = array("ID", "NAME", "DESCRIPTION", "URL", "OWNER_ID", "DATE_CREATE");

$dbBlogs = CBlog::GetList(
        $SORT,
        $arFilter,
        false,
        false,
        $arSelectedFields
    );

while ($arBlog = $dbBlogs->Fetch())
{
    print_r($arBlog);
}
?>


IsBlogOwner

CBlog::IsBlogOwner

bool
CBlog::IsBlogOwner(
 int ID,
 int userID
);

Метод проверяет является ли пользователь userID владельцем блога ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает true в случае если пользователь является владельцем блога, в противном случае возвращает false.

Примеры использования

<?
if(CBlog::IsBlogOwner(1, $USER->GetID()))
    echo "Вы являетесь владельцем блога.";
else
    echo "Вы не являетесь владельцем блога.";
?>


IsFriend

CBlog::IsFriend

bool
CBlog::IsFriend(
 int ID,
 int userID
);

Метод проверяет, является ли пользователь userID другом блога ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
userID | Идентификатор пользователя.

Возвращаемое значение

Возвращается true если пользователь является другом блога, в противном случае возвращается false.

Примеры использования

<?
$ID = 1;
if(CBlog::IsFriend($ID, $USER->GetID))
    echo "Вы являетесь другом блога с ID=".$ID;
else
    echo "Вы можете падать заявку на вступление в друзья блога с ID=".$ID;
?>


PreparePath

CBlog::PreparePath

string
CBlog::PreparePath(
 string blogUrl,
 string siteID = false,
 bool   is404 = true,
);

Метод возвращает путь к блогу с адресом blogUrl относительно корня сайта siteID с учётом варианта публичной части (с обработчиком 404 ошибки или без).

Параметры функции

Параметр | Описание
blogUrl | Адрес блога.
siteID | Сайт. Необязательный. По умолчанию false - берется текущий сайт.
is404 | Используется ли обработчик 404 ошибки в публичной части. Необязательный. По умолчанию true - публичная часть блогов работает на базе обработчика 404 ошибки.

Возвращаемое значение

Возвращается путь к блогу относительно корня сайта.

Примеры использования

<?
echo '<a href="'.CBlog::PreparePath("admin-blog").'">Блог администратора</a>';
?>


SetBlogPerms

CBlog::SetBlogPerms

void
CBlog::SetBlogPerms(
 int    ID,
 array  arPerms,
 string permsType = BLOG_PERMS_POST
);

Метод устанавливает уровень доступа к сообщениям и комментариям блога ID.

Параметры функции

Параметр | Описание
ID | Идентификатор блога.
arPerms | Массив вида: array("BlogUserGroupID" => "Permissions"[, ...]), где BlogUserGroupID - идентификатор группы пользователей текущего блога, Permissions - уровень доступа.
permsType | Тип уровня доступа, который необходимо установить. Возможные значения: BLOG_PERMS_POST - на сообщения блога; BLOG_PERMS_COMMENT - на комментарии блога. Необязательный. По умолчанию равен BLOG_PERMS_POST - будет изменен уровень доступа к сообщениям блога.

См. также

  • Уровни доступа к сообщениям блога
  • Уровни доступа к комментариям блога

Примеры использования

<?
$ID = 1;
$arPerms = Array(
        "1" => BLOG_PERMS_READ,
        "2" => BLOG_PERMS_WRITE
    );
CBlog::SetBlogPerms($ID, $arPerms, BLOG_PERMS_COMMENT);
?>


Update

CBlog::Update

int
CBlog::Update(
 int   ID
 array arFields
);

Метод изменяет параметры блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого блога.
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей блога. Также можно задать уровень доступа на сообщения и комментарии. Для этого необходимо задать массив вида array("PERMS_POST" => array("userGroupID" => "Permission"[, ...]), "PERMS_COMMENT" => array("userGroupID" => "Permission"[, ...])), где userGroupID - группа пользователей блога, Permission - уровень доступа.

Возвращаемое значение

Метод возвращает идентификатор измененного блога, если изменение параметров прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • Поля блога
  • CBlog::Add
  • Уровни доступа

Примеры использования

<?
$ID = 1;
$arFields = array(
    "NAME" => 'Блог администратора сайта',
    "DESCRIPTION" => 'В блоге описаны все изменения, происходящие на сайте',
    "=DATE_UPDATE" => $DB->CurrentTimeFunction(),
    "GROUP_ID" => '1',
    "ENABLE_IMG_VERIF" => 'N',
    "EMAIL_NOTIFY" => 'Y',
    "ENABLE_RSS" => "N",
    "URL" => "admin-blog",
    "ACTIVE" => "Y",
    "OWNER_ID" => $USER->GetID()
);

$updateID = CBlog::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Блог [".$updateID."] изменен.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogCandidate

CBlogCandidate - класс для работы со списком пользователей, желающих вступить в друзья блога.

Метод | Описание
Add | Добавляет пользователя в список желающих вступить в друзья блога.
Delete | Удаляет желающего вступить в друзья блога.
GetByID | Возвращает информацию о пользователе, желающем вступить в друзья блога, по его идентификатору.
GetList | Возвращает список пользователей, желающих вступить в друзья блога.


Add

CBlogCandidate::Add

int
CBlogCandidate::Add(
 array arFields
);

Метод добавляет пользователя в список желающих вступить в друзья блога.

Параметры функции

Параметр | Описание
arFields | Массив вида array("BLOG_ID"=>"значение", "USER_ID"=>"значение").

Возвращаемое значение

Метод возвращает идентификатор добавленной записи, если добавление прошло успешно. При возникновении ошибки метод вернет false.

См. также

Примеры использования

<?
//добавим текущего пользователя в список желающих вступить в друзья блога
// с идентификатором 1
$arFields = array(
        "BLOG_ID" => 1,
        "USER_ID" => $USER->GetID()
    );

$newID = CBlogCandidate::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Вы добавлены в список желающих вступить в друзья блога";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Delete

CBlogCandidate::Delete

bool
CBlogCandidate::Delete(
 int ID
);

Метод удаляет запись с идентификатором ID из списка желающих вступить в друзья блога.

Параметры функции

Параметр | Описание
ID | Идентификатор записи.

Возвращаемое значение

Метод возвращает true в случае успешного удаления записи, в противном случае возвращает false.

Примеры использования

<?

if(!CBlogCandidate::Delete($ID))
{
    echo 'Ошибка удаления записи!';
}
else
{
    echo 'Пользователь удален из списка желающих вступить в сообщество.';
}
?>


GetByID

CBlogCandidate::GetByID

array
CBlogCandidate::GetByID(
 int ID
);

Метод возвращает параметры записи с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор записи.

Возвращаемое значение

Возвращается массив вида:
Array(
    "ID"=>"ID записи",
    "BLOG_ID"=>"ID блога",
    "USER_ID"=>"ID пользователя"
)

Примечание

Функция использует встроенное кэширование. Таким образом, запрос к базе данных при многократном использовании функции на странице будет производиться только один раз.

См. также

  • CBlogCandidate::GetList()

Примеры использования

<?
$ID = 1;
$arCandidate = CBlogCandidate::GetByID($ID);
if(is_array($arCandidate))
    print_r($arCandidate);
else
    echo "Запись не найдена";
?>


GetList

CBlogCandidate::GetList

CDBResult
CBlogCandidate::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список пользователей, желающих вступить в друзья блога, по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...])
Поле для сортировки может принимать значения:
  • ID - идентификатор записи;
  • BLOG_ID - идентификатор блога;
  • USER_ID - идентификатор пользователя;
  • BLOG_USER_ID - идентификатор пользователя блога;
  • BLOG_USER_ALIAS - псевдоним пользователя блога;
  • USER_LOGIN - логин пользователя;
  • USER_NAME - имя пользователя;
  • USER_LAST_NAME - фамилия пользователя;
  • USER_EMAIL - Email пользователя.
Необязательный. По умолчанию фильтруется по убыванию идентификатора записи.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]).
Фильтруемое поле может принимать значения:
  • ID - идентификатор записи;
  • BLOG_ID - идентификатор блога;
  • USER_ID - идентификатор пользователя;
  • BLOG_USER_ID - идентификатор пользователя блога;
  • BLOG_USER_ALIAS - псевдоним пользователя блога;
  • USER_LOGIN - логин пользователя;
  • USER_NAME - имя пользователя;
  • USER_LAST_NAME - фамилия пользователя;
  • USER_EMAIL - Email пользователя.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно
"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.
Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult

Примеры использования

<?
// выберем список желающих вступить в друзья блога
//c идентификатором 1
$dbUsers = CBlogCandidate::GetList(
    array("USER_LAST_NAME" => "ASC", "USER_NAME" => "ASC"),
    array("BLOG_ID" => 1),
    false,
    false,
    array("ID", "USER_ID", "BLOG_USER_ALIAS", "USER_LOGIN", "USER_NAME", "USER_LAST_NAME")
);
while ($arUsers = $dbUsers->Fetch())
{
    print_r($arUsers);
}
?>


Класс CBlogCategory

CBlogCategory - класс для работы с категориями сообщений блога.

Метод | Описание
Add | Добавляет новый категорию.
Delete | Удаляет категорию.
GetByID | Возвращает категорию по ее идентификатору.
GetList | Возвращает список категорий по фильтру.
Update | Изменяет категорию.


Add

CBlogCategory::Add

int
CBlogCategory::Add(
 array arFields
);

Метод добавляет новую категорию.

Параметры функции

Параметр | Описание
arFields | Массив вида array("BLOG_ID"=>"значение", "NAME"=>"значение").

Возвращаемое значение

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

См. также

  • CBlogCategory::Update

Примеры использования

<?
$arFields = array(
    "BLOG_ID" => 1,
    "NAME" => "Общая категория"
);

$newID = CBlogCategory::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новая категория [".$newID."] добавлена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Delete

CBlogCategory::Delete

bool
CBlogCategory::Delete(
 int ID
);

Метод удаляет категорию с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор категории.

Возвращаемое значение

Метод возвращает true в случае успешного удаления категории, в противном случае возвращает false.

Примеры использования

<?
if(!CBlogCategory::Delete($ID))
{
    echo 'Ошибка удаления категории '.$ID;
}
else
    echo 'Категория удалена.';
?>


GetByID

CBlogCategory::GetByID

array
CBlogCategory::GetByID(
 int ID
);

Метод возвращает параметры категории с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор категории.

Возвращаемое значение

Возвращается массив вида:
Array(
    "ID" => "ID категории",
    "BLOG_ID" => "ID блога",
    "NAME" => "Название категории"
)
Если категория не найдена метод вернет false.

Примечание

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

См. также

  • CBlogCategory::GetList()

Примеры использования

<?
$ID = 1;
$arCategory = CBlogCategory::GetByID($ID);
if(is_array($arCategory))
    print_r($arCategory);
else
    echo "Категория не найдена.";
?>


GetList

CBlogCategory::GetList

CDBResult
CBlogCategory::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список категорий по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор категории;
  • BLOG_ID - идентификатор блога;
  • NAME - название категории.
Необязательный. По умолчанию фильтруется по убыванию идентификатора категории.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор категории;
  • BLOG_ID - идентификатор блога;
  • NAME - название категории.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.
Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult

Примеры использования

<?
// выберем все категории блога с идентификатором 1
$arOrder = Array(
        "NAME" => "ASC",
        "ID" => "ASC"
    );
$arFilter = Array(
        "BLOG_ID"=>'1'
    );
$arSelectedFields = Array("ID", "BLOG_ID", "NAME");

$dbCategory = CBlogCategory::GetList($arOrder, $arFilter, false, false, $arSelectedFields);
while ($arCategory = $dbCategory->Fetch())
{
    print_r($arCategory);
}
?>


Update

CBlogCategory::Update

int
CBlogCategory::Update(
 int   ID
 array arFields
);

Метод изменяет параметры категории с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемой категории.
arFields | Массив вида array("BLOG_ID"=>"ID блога", "NAME"=>"название категории").

Возвращаемое значение

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

См. также

  • CBlogCategory::Add

Примеры использования

<?
$ID = 1;
$arFields = array(
    "BLOG_ID" => 1,
    "NAME" => 'Личное'
);

$updateID = CBlogCategory::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Категория [".$updateID."] изменена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogComment

CBlogComment - класс для работы с комментариями к сообщениям блогов.

Метод | Описание
Add | Добавляет новый комментарий к сообщению.
Delete | Удаляет комментарий к сообщению.
GetByID | Возвращает комментарий к блогу по его идентификатору.
GetList | Возвращает список комментариев по фильтру.
Update | Изменяет комментарий к сообщению.


Add

CBlogComment::Add

int
CBlogComment::Add(
 array arFields
);

Метод добавляет новый комментарий к сообщению.

Параметры функции

Параметр | Описание
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей комментария.

Возвращаемое значение

Метод возвращает идентификатор добавленного комментария, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogComment::Update
  • Поля комментария к сообщению

Примеры использования

<?
$UserIP = CBlogUser::GetUserIP();
$arFields = array(
    "TITLE" => 'Мое первое сообщение в блоге',
    "POST_TEXT" => 'Текст моего первого сообщения в блоге',
    "BLOG_ID" => 1,
    "POST_ID" => 2,
    "PARENT_ID" => 0, //комментарий привязан к сообщению
    "AUTHOR_ID" => $USER->GetID(), //добавляем неанонимный комментарий,
    //в противном случае необходимо задать AUTHOR_NAME, AUTHOR_EMAIL
    "DATE_CREATE" => ConvertTimeStamp(false, "FULL"),
    "AUTHOR_IP" => $UserIP[0],
    "AUTHOR_IP1" => $UserIP[1]
);

$newID = CBlogComment::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новый комментарий [".$newID."] добавлен.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Delete

CBlogComment::Delete

bool
CBlogComment::Delete(
 int ID
);

Метод удаляет комментарий с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор комментария.

Возвращаемое значение

Метод возвращает true в случае успешного удаления комментария, в противном случае возвращает false.

Примечание

При удалении комментария, у которого PARENT_ID не равен нулю, все его комментарии будут привязаны на уровень выше.

Примеры использования

<?
$DB->StartTransaction();
if(!CBlogComment::Delete($ID))
{
    echo 'Ошибка удаления комментария '.$ID;
    $DB->Rollback();
}
else
    $DB->Commit();
?>


GetByID

CBlogComment::GetByID

array
CBlogComment::GetByID(
 int ID
);

Метод возвращает параметры комментария с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор комментария.

Возвращаемое значение

Возвращается массив с полями комментария.

Примечание

Функция использует встроенное кэширование. Таким образом, запрос к базе данных при многократном использовании функции на странице будет производиться только один раз.

См. также

  • CBlogComment::GetList()
  • Поля комментария к сообщению

Примеры использования

<?
$ID = 1;
$arComment = CBlogComment::GetByID($ID);
if(is_array($arComment))
    print_r($arComment);
else
    echo "Комментарий не найден.";
?>


GetList

CBlogComment::GetList

CDBResult
CBlogComment::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список комментариев по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор комментария;
  • POST_ID - идентификатор сообщения;
  • BLOG_ID - идентификатор блога;
  • AUTHOR_ID - идентификатор автора комментария;
  • TITLE - заголовок комментария;
  • POST_TEXT - текст комментария;
  • DATE_CREATE - дата создания комментария;
  • PARENT_ID - идентификатор родителя комментария;
  • AUTHOR_NAME - имя автора анонимного комментария;
  • AUTHOR_EMAIL - Email автора анонимного комментария;
  • AUTHOR_IP - IP-адрес автора комментария;
  • AUTHOR_IP1 - IP-адрес автора комментария;
  • USER_LOGIN - логин автора неанонимного комментария;
  • USER_NAME - имя автора неанонимного комментария;
  • USER_LAST_NAME - фамилия автора неанонимного комментария;
  • USER_EMAIL - Email автора неанонимного комментария.
Необязательный. По умолчанию фильтруется по убыванию идентификатора комментария.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор комментария;
  • POST_ID - идентификатор сообщения;
  • BLOG_ID - идентификатор блога;
  • AUTHOR_ID - идентификатор автора комментария;
  • TITLE - заголовок комментария;
  • POST_TEXT - текст комментария;
  • DATE_CREATE - дата создания комментария;
  • PARENT_ID - идентификатор родителя комментария;
  • AUTHOR_NAME - имя автора анонимного комментария;
  • AUTHOR_EMAIL - Email автора анонимного комментария;
  • AUTHOR_IP - IP-адрес автора комментария;
  • AUTHOR_IP1 - IP-адрес автора комментария;
  • USER_LOGIN - логин автора неанонимного комментария;
  • USER_NAME - имя автора неанонимного комментария;
  • USER_LAST_NAME - фамилия автора неанонимного комментария;
  • USER_EMAIL - Email автора неанонимного комментария.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.
Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля комментария к сообщению

Примеры использования

<?
// выберем все комментарии к сообщению с идентификатором 1
$arOrder = Array(
        "ID" => "ASC",
        "DATE_CREATE" => "ASC"
    );
$arFilter = Array(
        "POST_ID"=>'1'
    );
$arSelectedFields = Array("ID", "BLOG_ID", "POST_ID", "PARENT_ID", "AUTHOR_ID", "AUTHOR_NAME", "AUTHOR_EMAIL", "AUTHOR_IP", "AUTHOR_IP1", "TITLE", "POST_TEXT", "DATE_CREATE");

$dbComment = CBlogComment::GetList($arOrder, $arFilter, false, false, $arSelectedFields);
while ($arComment = $dbComment->Fetch())
{
    print_r($arComment);
}
?>


Update

CBlogComment::Update

int
CBlogComment::Update(
 int   ID
 array arFields
);

Метод изменяет параметры комментария с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого комментария к сообщению.
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей комментария к сообщению.

Возвращаемое значение

Метод возвращает идентификатор измененного комментария к сообщению, если изменение параметров прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogComment::Add
  • Поля комментария к сообщению

Примеры использования

<?
$ID = 1;
$arFields = array(
    "TITLE" => 'Мое первый измененный комментарий',
    "DETAIL_TEXT" => 'Текст моего первого измененного комментария',
    "BLOG_ID" => 1,
    "POST_ID" => 2
);

$updateID = CBlogComment::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Комментарий [".$updateID."] изменен.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogGroup

CBlogGroup - класс для работы с группами блогов.

Метод | Описание
Add | Добавляет новую группу.
Delete | Удаляет группу.
GetByID | Возвращает группу по ее идентификатору.
GetList | Возвращает список групп по фильтру.
Update | Изменяет группу.


Add

CBlogGroup::Add

int
CBlogGroup::Add(
 array arFields
);

Метод добавляет новую группу.

Параметры функции

Параметр | Описание
arFields | Массив вида array("SITE_ID"=>"значение", "NAME"=>"значение").

Возвращаемое значение

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

См. также

  • CBlogGroup::Update

Примеры использования

<?
$arFields = array(
    "SITE_ID" => "ru",
    "NAME" => "Общая группа"
);

$newID = CBlogGroup::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новая группа [".$newID."] добавлена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Delete

CBlogGroup::Delete

bool
CBlogGroup::Delete(
 int ID
);

Метод удаляет группу с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор группы.

Возвращаемое значение

Метод возвращает true в случае успешного удаления группы, в противном случае возвращает false.

Примеры использования

<?
if(!CBlogGroup::Delete($ID))
{
    echo 'Ошибка удаления группы '.$ID;
}
else
    echo 'Группа удалена.';
?>


GetByID

CBlogGroup::GetByID

array
CBlogGroup::GetByID(
 int ID
);

Метод возвращает параметры группы с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор группы.

Возвращаемое значение

Возвращается массив вида:
Array(
    "ID" => "ID группы",
    "SITE_ID" => "ID сайта",
    "NAME" => "Название группы"
)
Если группа не найдена метод вернет false.

Примечание

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

См. также

  • CBlogGroup::GetList()

Примеры использования

<?
$ID = 1;
$arGroup = CBlogGroup::GetByID($ID);
if(is_array($arGroup))
    print_r($arGroup);
else
    echo "Группа не найдена.";
?>


GetList

CBlogGroup::GetList

CDBResult
CBlogGroup::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список групп по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор категории;
  • SITE_ID - идентификатор сайта;
  • NAME - название категории.
Необязательный. По умолчанию фильтруется по убыванию идентификатора категории.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор категории;
  • SITE_ID - идентификатор сайта;
  • NAME - название категории.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.
Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult

Примеры использования

<?
// выберем все группы сайта с идентификатором "ru"
$arOrder = Array(
        "NAME" => "ASC",
        "ID" => "ASC"
    );
$arFilter = Array(
        "SITE_ID"=>'ru'
    );
$arSelectedFields = Array("ID", "SITE_ID", "NAME");

$dbGroup = CBlogGroup::GetList($arOrder, $arFilter, false, false, $arSelectedFields);
while ($arGroup = $dbGroup->Fetch())
{
    print_r($arGroup);
}
?>


Update

CBlogGroup::Update

int
CBlogGroup::Update(
 int   ID
 array arFields
);

Метод изменяет параметры группы с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемой группы.
arFields | Массив вида array("SITE_ID"=>"ID сайта", "NAME"=>"название категории").

Возвращаемое значение

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

См. также

  • CBlogGroup::Add

Примеры использования

<?
$ID = 1;
$arFields = array(
    "SITE_ID" => "ru",
    "NAME" => "Веселые блоги"
);

$updateID = CBlogGroup::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Группа [".$updateID."] изменена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogPost

CBlogPost - класс для работы с сообщениями блогов.

Метод | Описание
Add | Добавляет новое сообщение в блог.
CanUserDeletePost | Проверяет - может ли пользователь удалить сообщение.
CanUserEditPost | Проверяет - может ли пользователь изменять сообщение.
Delete | Удаляет сообщение блога.
GetBlogUserCommentPerms | Возвращает доступ к комментариям сообщения.
GetBlogUserPostPerms | Возвращает доступ к сообщению.
GetByID | Возвращает сообщение блога по его идентификатору.
GetList | Возвращает список сообщений по фильтру.
GetListCalendar | Возвращает список дней в которые были сообщения для календаря.
PreparePath | Возвращает путь к сообщению.
SetPostPerms | Устанавливает уровень доступа на сообщение и комментарии.
Update | Изменяет сообщение.


Add

CBlogPost::Add

int
CBlogPost::Add(
 array arFields
);

Метод добавляет новое сообщение в блог.

Параметры функции

Параметр Описание
arFields Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей сообщения блога.

Также, можно задать отдельный уровень доступа на сообщение и комментарии. Для этого необходимо задать массив вида
array("PERMS_POST" =>    array("userGroupID" => "Permission"[, ...]),
      "PERMS_COMMENT" => array("userGroupID" => "Permission"[, ...]))
где userGroupID - группа пользователей блога, Permission - уровень доступа.

Возвращаемое значение

Метод возвращает идентификатор добавленного сообщения, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogPost::Update
  • Поля сообщения
  • Уровни доступа

Примеры использования

<?
$CATEGORY_ID = CBlogCategory::Add(array("BLOG_ID" => 1,"NAME" => 'Категория 1'));
$arFields = array(
    "TITLE" => 'Мое первое сообщение в блоге',
    "DETAIL_TEXT" => 'Текст моего первого сообщения в блоге',
    "BLOG_ID" => 1,
    "AUTHOR_ID" => $USER->GetID,
    "=DATE_CREATE" => $DB->GetNowFunction(),
    "DATE_PUBLISH" => '15.08.2007 9:40',
    "PUBLISH_STATUS" => BLOG_PUBLISH_STATUS_PUBLISH,
    "ENABLE_TRACKBACK" => 'N',
    "ENABLE_COMMENTS" => 'Y'
    "CATEGORY_ID" => $CATEGORY_ID,
    "PERMS_P" => Array("1" => BLOG_PERMS_READ, "2" => BLOG_PERMS_READ),
    "PERMS_C" => Array("1" => BLOG_PERMS_READ, "2" => BLOG_PERMS_WRITE)
);

$newID = CBlogPost::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новое сообщение [".$newID."] добавлено.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


CanUserDeletePost

CBlogPost::CanUserDeletePost

bool
CBlogPost::CanUserDeletePost(
 int ID,
 int userID
);

Метод проверяет может ли пользователь userID удалить сообщение ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщения.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает true в случае если пользователь может удалить сообщение, в противном случае возвращает false.

См. также

  • CBlogPost::CanUserEditPost

Примеры использования

<?
if(CBlogPost::CanUserDeletePost(1, $USER->GetID()))
    echo "Вы можете удалить сообщение.";
else
    echo "Вы не можете удалить сообщение.";
?>


CanUserEditPost

CBlogPost::CanUserEditPost

bool
CBlogPost::CanUserEditPost(
 int ID,
 int userID
);

Метод проверяет может ли пользователь userID изменить сообщение ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщения.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает true в случае если пользователь может изменить сообщение, в противном случае возвращает false.

См. также

  • CBlogPost::CanUserDeletePost

Примеры использования

<?
if(CBlogPost::CanUserEditPost(1, $USER->GetID()))
    echo "Вы можете изменить сообщение.";
else
    echo "Вы не можете изменить сообщение.";
?>


Delete

CBlogPost::Delete

bool
CBlogPost::Delete(
 int ID
);

Метод удаляет сообщение ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщение.

Возвращаемое значение

Метод возвращает true в случае успешного удаления сообщения, в противном случае возвращает false.

Примеры использования

<?
$DB->StartTransaction();
if(!CBlogPost::Delete($ID))
{
    echo 'Ошибка удаления сообщения '.$ID;
    $DB->Rollback();
}
else
    $DB->Commit();
?>


GetBlogUserCommentPerms

CBlogPost::GetBlogUserCommentPerms

string
CBlogPost::GetBlogUserCommentPerms(
 int ID,
 int userID
);

Метод возвращает право пользователя userID на комментарии к сообщению ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщения.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает право пользователя на комментарии к сообщению.

См. также

  • Уровни доступа к комментариям
  • CBlogPost::GetBlogUserPostPerms()

Примеры использования

<?
$perms = CBlogPost::GetBlogUserCommentPerms(1, $USER->GetID());
echo "Вы имеете следующее право на комментарии к сообщению: ".$perms;
?>


GetBlogUserPostPerms

CBlogPost::GetBlogUserPostPerms

string
CBlogPost::GetBlogUserPostPerms(
 int ID,
 int userID
);

Метод возвращает право пользователя userID на сообщение ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщения.
userID | Идентификатор пользователя.

Возвращаемое значение

Метод возвращает право пользователя на сообщение.

См. также

  • Уровни доступа к сообщениям
  • CBlogPost::GetBlogUserCommentPerms()

Примеры использования

<?
$perms = CBlogPost::GetBlogUserPostPerms(1, $USER->GetID());
echo "Вы имеете следующее право на сообщение: ".$perms;
?>


GetByID

CBlogPost::GetByID

array
CBlogPost::GetByID(
 int ID
);

Метод возвращает параметры сообщения с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщения.

Возвращаемое значение

Возвращается массив с полями сообщения.

Примечание

Функция использует встроенное кэширование. Таким образом, запрос к базе данных при многократном использовании функции на странице будет производиться только один раз.

См. также

  • Поля блога
  • CBlogPost::GetList()

Примеры использования

<?
$ID = 1;
$arPost = CBlogPost::GetByID($ID);
if(is_array($arPost))
    print_r($arPost);
else
    echo "Сообщение не найдено";
?>


GetList

CBlogPost::GetList

CDBResult
CBlogPost::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список сообщений по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор сообщения;
  • TITLE - заголовок сообщения;
  • BLOG_ID - идентификатор блога;
  • AUTHOR_ID - идентификатор автора сообщения;
  • DETAIL_TEXT - текст сообщения;
  • DATE_CREATE - дата создания сообщения;
  • DATE_PUBLISH - дата публичкации сообщения;
  • DATE_PUBLISH_DAY - день публикации сообщения;
  • DATE_PUBLISH_MONTH - месяц публикации сообщения;
  • DATE_PUBLISH_YEAR - год публикации сообщения;
  • KEYWORDS - ключевые слова сообщения;
  • PUBLISH_STATUS - статус публикации сообщения;
  • CATEGORY_ID - идентификатор категории сообщения;
  • CATEGORY_NAME - название категории сообщения;
  • ATRIBUTE - атрибуты сообщения;
  • ENABLE_TRACKBACK - разрешены ли trackback'и к сообщению;
  • ENABLE_COMMENTS - разрешены ли комментарии к сообщению;
  • NUM_COMMENTS - количество комментариев;
  • NUM_TRACKBACKS - количество trackback'ов;
  • AUTHOR_LOGIN - логин автора сообщения;
  • AUTHOR_NAME - имя автора сообщения;
  • AUTHOR_LAST_NAME - фамилия автора сообщения;
  • AUTHOR_EMAIL - Email автора сообщения;
Необязательный. По умолчанию фильтруется по убыванию идентификатора сообщения.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор сообщения;
  • TITLE - заголовок сообщения;
  • BLOG_ID - идентификатор блога;
  • AUTHOR_ID - идентификатор автора сообщения;
  • DETAIL_TEXT - текст сообщения;
  • DATE_CREATE - дата создания сообщения;
  • DATE_PUBLISH - дата публичкации сообщения;
  • DATE_PUBLISH_DAY - день публикации сообщения;
  • DATE_PUBLISH_MONTH - месяц публикации сообщения;
  • DATE_PUBLISH_YEAR - год публикации сообщения;
  • KEYWORDS - ключевые слова сообщения;
  • PUBLISH_STATUS - статус публикации сообщения;
  • CATEGORY_ID - идентификатор категории сообщения;
  • CATEGORY_NAME - название категории сообщения;
  • ATRIBUTE - атрибуты сообщения;
  • ENABLE_TRACKBACK - разрешены ли trackback'и к сообщению;
  • ENABLE_COMMENTS - разрешены ли комментарии к сообщению;
  • NUM_COMMENTS - количество комментариев;
  • NUM_TRACKBACKS - количество trackback'ов;
  • AUTHOR_LOGIN - логин автора сообщения;
  • AUTHOR_NAME - имя автора сообщения;
  • AUTHOR_LAST_NAME - фамилия автора сообщения;
  • AUTHOR_EMAIL - Email автора сообщения;
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля сообщения

Примеры использования

<?
// выберем все опубликованные сообщения всех блогов за апрель 2007 года
// у которых больше двух комментариев

$SORT = Array("DATE_PUBLISH" => "DESC", "NAME" => "ASC");
$arFilter = Array(
    "PUBLISH_STATUS" => BLOG_PUBLISH_STATUS_PUBLISH,
    "DATE_PUBLISH_MONTH" => '04',
    "DATE_PUBLISH_YEAR" => '2007',
    ">NUM_COMMENTS" => 2
    );

$dbPosts = CBlogPost::GetList(
        $SORT,
        $arFilter
    );

while ($arPost = $dbPosts->Fetch())
{
    print_r($arPost);
}
?>


GetListCalendar

CBlogPost::GetListCalendar

Array
CBlogPost::GetListCalendar(
 int blogID,
 int year = false,
 int month = false,
 int day = false
);

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

Параметры функции

Параметр | Описание
blogID | Идентификатор блога.
year | Год. Год за который необходимо найти дни, в которые были написаны сообщения. Принимает как значение года двухзначным числом, тогда это считается 20хх год, так и значения года четырехзначным числом. Необязательный. По умолчанию записи не фильтруются.
month | Месяц. Месяц за который необходимо найти дни, в которые были написаны сообщения. Для фильтрации по месяцу обязательно задать параметр year. Необязательный. По умолчанию записи не фильтруются.
day | День. Позваляет проверить были ли сообщения в этот день. Для фильтрации по дню обязательно задать параметры year и month. Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается массив вида:
Array(
 [0] => Array
        (
            [YEAR] => 2007
            [MONTH] => 07
            [DAY] => 17
            [DATE] => 17.07.2007
        )[,
 ...]
)

См. также

  • CBlogPost::GetList()

Примеры использования

<?
// выберем данные для календаря за апрель 2007 года для блога
// с идентификатором 1

$arDates = CBlogPost::GetListCalendar(
        1,
        '06',
        '4'
    );

print_r($arDates);
?>


PreparePath

CBlogPost::PreparePath

string
CBlogPost::PreparePath(
 string blogUrl,
 int    postID = 0,
 string siteID = false,
 bool   is404 = true,
);

Метод возвращает путь к сообщению postID блога с адресом blogUrl относительно корня сайта siteID с учётом варианта публичной части (с обработчиком 404 ошибки или без).

Параметры функции

Параметр | Описание
blogUrl | Адрес блога.
postID | Идентификатор сообщения. Необязательный. По умолчанию 0 - будет возвращен путь к блогу.
siteID | Сайт. Необязательный. По умолчанию false - берется текущий сайт.
is404 | Используется ли обработчик 404 ошибки в публичной части. Необязательный. По умолчанию true - публичная часть блогов работает на базе обработчика 404 ошибки.

Возвращаемое значение

Возвращается путь к сообщению блога относительно корня сайта.

Примеры использования

<?
echo '<a href="'.CBlogPost::PreparePath("admin-blog", 1).'">Первое сообщение в блоге "Блог администратора"</a>';
?>


SetPostPerms

CBlogPost::SetPostPerms

void
CBlogPost::SetPostPerms(
 int    ID,
 array  arPerms,
 string permsType = BLOG_PERMS_POST
);

Метод устанавливает уровень доступа к сообщению и комментариям сообщения ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сообщения.
arPerms Массив вида: array("BlogUserGroupID" => "Permissions"[, ...]), где
BlogUserGroupID - идентификатор группы пользователей текущего блога,
Permissions - уровень доступа.
permsType Тип уровня доступа, который необходимо установить. Возможные значения:
  • BLOG_PERMS_POST - на сообщение;
  • BLOG_PERMS_COMMENT - на комментарии к сообщению.
Необязательный. По умолчанию равен BLOG_PERMS_POST - будет изменен уровень доступа к сообщению.

См. также

  • Уровни доступа к сообщениям блога
  • Уровни доступа к комментариям блога

Примеры использования

<?
$ID = 1;
$arPerms = Array(
        "1" => BLOG_PERMS_READ,
        "2" => BLOG_PERMS_WRITE
    );
CBlogPost::SetPostPerms($ID, $arPerms, BLOG_PERMS_COMMENT);
?>


Update

CBlogPost::Update

int
CBlogPost::Update(
 int   ID
 array arFields
);

Метод изменяет параметры сообщения с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого сообщения блога.
arFields Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей соообщения блога.
Также можно задать отдельный уровень доступа на сообщение и комментарии. Для этого необходимо задать массив вида:
array("PERMS_POST" =>    array("userGroupID" => "Permission"[, ...]),
      "PERMS_COMMENT" => array("userGroupID" => "Permission"[, ...]))
где userGroupID - группа пользователей блога, Permission - уровень доступа.

Возвращаемое значение

Метод возвращает идентификатор измененного сообщения блога, если изменение параметров прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • Поля сообщения
  • CBlogPost::Add

Примеры использования

<?
$ID = 1;
$arFields = array(
    "TITLE" => 'Мое первое измененное сообщение в блоге',
    "DETAIL_TEXT" => 'Текст моего первого измененного сообщения в блоге',
    "BLOG_ID" => 1,
    "AUTHOR_ID" => $USER->GetID,
    "DATE_PUBLISH" => '25.08.2007 9:40',
    "PUBLISH_STATUS" => BLOG_PUBLISH_STATUS_PUBLISH,
    "ENABLE_TRACKBACK" => 'N',
    "ENABLE_COMMENTS" => 'Y'
    "PERMS_P" => Array("1" => BLOG_PERMS_DENY, "2" => BLOG_PERMS_DENY),
    "PERMS_C" => Array("1" => BLOG_PERMS_READ, "2" => BLOG_PERMS_WRITE)
);

$updateID = CBlogPost::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Сообщение [".$updateID."] изменено.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogSitePath

CBlogSitePath - класс для работы с путями к публичной части блогов.

Метод | Описание
Add | Добавляет новый путь.
Delete | Удаляет путь.
GetByID | Возвращает путь по его идентификатору.
GetBySiteID | Возвращает путь по идентификатору сайта.
GetList | Возвращает список путей по фильтру.
Update | Изменяет путь.


Add

CBlogSitePath::Add

int
CBlogSitePath::Add(
 array arFields
);

Метод добавляет новый путь.

Параметры функции

Параметр | Описание
arFields | Массив вида array("SITE_ID"=>"значение", "PATH"=>"значение").

Возвращаемое значение

Метод возвращает идентификатор добавленного пути, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogSitePath::Update

Примеры использования

<?
$arFields = array(
    "SITE_ID" => "ru",
    "PATH" => "/blog/"
);

$newID = CBlogSitePath::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новый путь [".$newID."] добавлен.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Delete

CBlogSitePath::Delete

bool
CBlogSitePath::Delete(
 int ID
);

Метод удаляет путь с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор пути.

Возвращаемое значение

Метод возвращает true в случае успешного удаления пути, в противном случае возвращает false.

Примеры использования

<?
$ID = 1;
if(!CBlogSitePath::Delete($ID))
{
    echo 'Ошибка удаления пути '.$ID;
}
else
    echo 'Путь удален.';
?>


GetByID

CBlogSitePath::GetByID

array
CBlogSitePath::GetByID(
 int ID
);

Метод возвращает параметры пути с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор пути.

Возвращаемое значение

Возвращается массив вида:
Array(
    "ID" => "ID пути",
    "SITE_ID" => "ID сайта",
    "PATH" => "Путь"
)
Если путь не найден метод вернет false.

Примечание

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

См. также

  • CBlogSitePath::GetList()
  • CBlogSitePath::GetBySiteID()

Примеры использования

<?
$ID = 1;
$arSitePath = CBlogSitePath::GetByID($ID);
if(is_array($arSitePath))
    print_r($arSitePath);
else
    echo "Путь не найден.";
?>


GetBySiteID

CBlogSitePath::GetBySiteID

array
CBlogSitePath::GetBySiteID(
 string siteID
);

Метод возвращает параметры пути сайта siteID.

Параметры функции

Параметр | Описание
siteID | Идентификатор сайта.

Возвращаемое значение

Возвращается массив вида:

Array(
    "ID" => "ID пути",
    "SITE_ID" => "ID сайта",
    "PATH" => "Путь"
)
Если путь не найден метод вернет false.

Примечание

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

См. также

  • CBlogSitePath::GetList()
  • CBlogSitePath::GetByID()

Примеры использования

<?
$SiteID = "ru";
$arSitePath = CBlogSitePath::GetBySiteID($SiteID);
if(is_array($arSitePath))
    print_r($arSitePath);
else
    echo "Путь не найден.";
?>


GetList

CBlogSitePath::GetList

CDBResult
CBlogSitePath::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список путей по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор пути;
  • SITE_ID - идентификатор сайта;
  • PATH - путь.
Необязательный. По умолчанию фильтруется по убыванию идентификатора категории.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор пути;
  • SITE_ID - идентификатор сайта;
  • PATH - путь.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.
Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult

Примеры использования

<?
// выберем все пути сайта с идентификатором "ru"
$arOrder = Array(
        "PATH" => "ASC",
        "ID" => "ASC"
    );
$arFilter = Array(
        "SITE_ID"=>'ru'
    );
$arSelectedFields = Array("ID", "SITE_ID", "PATH");

$dbSitePath = CBlogSitePath::GetList($arOrder, $arFilter, false, false, $arSelectedFields);
while ($arSitePath = $dbSitePath->Fetch())
{
    print_r($arSitePath);
}
?>


Update

CBlogSitePath::Update

int
CBlogSitePath::Update(
 int   ID
 array arFields
);

Метод изменяет параметры пути с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого пути.
arFields | Массив вида array("SITE_ID"=>"ID сайта", "PATH"=>"путь").

Возвращаемое значение

Метод возвращает идентификатор измененного пути, если изменение параметров прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogSitePath::Add

Примеры использования

<?
$ID = 1;
$arFields = array(
    "SITE_ID" => "ru",
    "PATH" => "/ru/blog/"
);

$updateID = CBlogSitePath::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Путь [".$updateID."] изменен.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogTrackback

CBlogTrackback - класс для работы с Trackback к сообщениям.

GetPing | Принимает Trackback-запросы.
SendPing | Отправляет Trackback-запрос по заданным адресам.


GetPing

CBlogTrackback::GetPing

void
CBlogTrackback::GetPing(
 string blogUrl,
 int    postID,
 array  arParams
);

Метод принимает и сохраняет Trackback-запрос arParams к сообщению postID блога с адресом blogUrl.

Параметры функции

Параметр | Описание
blogUrl | Адрес блога.
postID | Идентификатор сообщения.
arParams Массив параметров Trackback-запроса:
  • title - обязательный, заголовок Trackback'а;
  • url - обязательный, адрес Trackback'a;
  • excerpt - текст Trackback'а;
  • blog_name - название блога.

Примеры использования

<?
if (CModule::IncludeModule("blog"))
{
    $postID = IntVal($postID);
    $blogUrl = Trim($blogUrl);

    if (strtoupper($_SERVER["REQUEST_METHOD"]) != "POST")
    {
        LocalRedirect(CBlogPost::PreparePath($blogUrl, $postID));
        die();
    }

    $arParams = array();
    if (isset($_REQUEST))
    {
        if (isset($_REQUEST["title"]))
            $arParams["title"] = $_REQUEST["title"];
        if (isset($_REQUEST["url"]))
            $arParams["url"] = $_REQUEST["url"];
        if (isset($_REQUEST["excerpt"]))
            $arParams["excerpt"] = $_REQUEST["excerpt"];
        if (isset($_REQUEST["blog_name"]))
            $arParams["blog_name"] = $_REQUEST["blog_name"];
    }

    CBlogTrackback::GetPing($blogUrl, $postID, $arParams);
}
?>


SendPing

CBlogTrackback::SendPing

void
CBlogTrackback::SendPing(
 int   postID,
 array arPingUrls
);

Метод отправляет Trackback-запрос о сообщении postID по заданным адресам arPingUrls.

Параметры функции

Параметр | Описание
postID | Идентификатор сообщения.
arPingUrls | Массив адресов, по которым необходимо отправить Trackback-запрос.

Примеры использования

<?
$ID = 2;
$arPingUrls = array(
        "/blog/trackback.php/admin-blog/1.php",
        "http://www.bitrixsoft.ru/blog/blogman/trackback.php/admin-blog/1.php"
    );
CBlogTrackback::SendPing($ID, $arPingUrls);
?>


Класс CBlogUser

CBlogUser - класс для работы с пользователями блогов.

Add | Добавляет пользователя блогов.
Delete | Удаляет пользователя блогов.
GetByID | Возвращает пользователя блога по его идентификатору.
GetList | Возвращает список пользователя блога по фильтру.
Update | Изменяет параметры пользователя блога.
GetUserFriendsList | Возвращает список сообщений друзей блога.
CanUserUpdateUser | Проверяет - может ли пользователь блога изменить информацию о себе.
DeleteFromUserGroup | Удаляет пользователя блога из группы пользователей блога.
AddToUserGroup | Добавляет пользователя блога в группу пользователей блога.
SetLastVisit | Регистрирует посещение пользователя блога в его профайле.
GetUserFriends | Возвращет список друзей пользователя блога или список пользователей блогов в друзьях у которых находится пользователь.
GetUserGroups | Возвращает список групп блога, в которых находится пользователь блога.
GetUserPerms | Возвращает уровень прав пользователя блога.
GetUserName | Вовзращает имя пользователя для отображения в публичной части.
PreparePath | Возвращает путь к профайлу пользователя блога.
GetUserIP | Возвращает IP-адреса пользователя.


Add

CBlogUser::Add

int
CBlogUser::Add(
 array arFields
);

Метод добавляет нового пользователя блогов.

Параметры функции

Параметр | Описание
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей пользователя.

Возвращаемое значение

Метод возвращает идентификатор добавленного пользователя, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogUser::Update
  • Поля пользователя блога

Примеры использования

<?
//создадим профайл пользователя блога для текущего пользователя
$arFields = array(
    "USER_ID" => $USER->GetID(),
    "=LAST_VISIT" => $DB->GetNowFunction(),
    "=DATE_REG" => $DB->GetNowFunction(),
    "ALLOW_POST" => "Y",
    "ALIAS" => "Псевдоним пользователя",
    "DESCRIPTION" => "Обычный пользователь сайта с блогом",
    "INTERESTS" => "программирование, PHP, MySQL, Bitrix, Битрикс"
);

$newID = CBlogUser::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новый пользователь блога [".$newID."] добавлен.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


AddToUserGroup

CBlogUser::AddToUserGroup

bool
CBlogUser::AddToUserGroup(
 int    ID,
 int    blogID,
 array  arGroups = array(),
 string joinStatus = "Y",
 int    selectType = BLOG_BY_BLOG_USER_ID,
 int    action = BLOG_CHANGE
);

Метод добавляет пользователя с идентификатором ID в группы пользователей arGroups блога blogID.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя.
blogID | Идентификатор блога.
arGroups | Массив идентификаторов групп пользователей блога, к которым необходимо привязать пользователя.
joinStatus | Необязательный. Параметр временно не используется.
selectType По какому идентификатору искать пользователя. Возможные значения:
  • BLOG_BY_USER_ID - по идентификатору пользователя сайта;
  • BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.
Необязательный. По умолчанию BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.
action Совершаемое действие. Возможные значения:
  • BLOG_ADD - добавление пользователя в группы;
  • BLOG_CHANGE - изменение уже существующих привязок.
Необязательный. По умолчанию BLOG_CHANGE - изменение уже существующих привязок.

Возвращаемое значение

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

Примеры использования

<?
// добавим текущего пользователя в группы с ID = 1, 2, 3 пользователей блога с ID = 1
$ID = $USER->GetID();
if(!CBlogUser::AddToUserGroup($ID, 1, array(1,2,3), "", BLOG_BY_USER_ID, BLOG_ADD))
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
else
{
    echo 'Пользователь ['.$ID.'] добавлен в группы пользователей блога';
}
?>


CanUserUpdateUser

CBlogUser::CanUserUpdateUser

bool
CBlogUser::CanUserUpdateUser(
 int ID,
 int userID,
 int selectType = BLOG_BY_BLOG_USER_ID
);

Метод проверяет может ли пользователь сайта userID изменять профайл пользователя ID блога.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя.
userID | Идентификатор пользователя сайта.
selectType По какому идентификатору искать пользователя. Возможные значения:
  • BLOG_BY_USER_ID - по идентификатору пользователя сайта;
  • BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.
Необязательный. По умолчанию BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.

Возвращаемое значение

Метод возвращает true в случае если пользователь изменить профайл, в противном случае возвращает false.

Примеры использования

<?
if(CBlogUser::CanUserUpdateUser(1, $USER->GetID(), BLOG_BY_USER_ID)
    echo "Вы можете изменить этот профайл.";
else
    echo "Вы не можете изменить этот профайл.";
?>


Delete

CBlogUser::Delete

bool
CBlogUser::Delete(
 int ID
);

Метод удаляет профайл пользователя блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя сайта.

Возвращаемое значение

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

Примечание

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

Примеры использования

<?
$ID = $USER->GetID();
if(!CBlogUser::Delete($ID))
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
else
{
    echo 'Профайл блога пользователя ['.$ID.'] удален';
}
?>


DeleteFromUserGroup

CBlogUser::DeleteFromUserGroup

bool
CBlogUser::DeleteFromUserGroup(
 int ID,
 int blogID,
 int selectType = BLOG_BY_BLOG_USER_ID,
);

Метод удаляет пользователя с идентификатором ID из всех групп пользователей блога blogID.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя.
blogID | Идентификатор блога.
selectType По какому идентификатору искать пользователя. Возможные значения:
  • BLOG_BY_USER_ID - по идентификатору пользователя сайта;
  • BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.
Необязательный. По умолчанию BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.

Возвращаемое значение

Метод возвращает true в случае успешного удаления пользователя из групп, в противном случае возвращает false, а в исключениях будут содержаться ошибки.

Примеры использования

<?
// удалим текущего пользователя из всех групп пользователей блога с ID = 1
$ID = $USER->GetID();
if(!CBlogUser::DeleteFromUserGroup($ID, 1, BLOG_BY_USER_ID))
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
else
{
    echo 'Пользователь ['.$ID.'] удален из групп пользователей блога';
}
?>


GetByID

CBlogUser::GetByID

array
CBlogUser::GetByID(
 int ID,
 int selectType = BLOG_BY_BLOG_USER_ID
);

Метод возвращает параметры пользователя блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя.
selectType Тип выборки. Может принимать следующие значения:
  • BLOG_BY_BLOG_USER_ID - найти пользователя по идентификатору пользователя блога;
  • BLOG_BY_USER_ID - найти пользователя по идентификатору пользователя сайта.
Необязательный. По умолчанию равен BLOG_BY_BLOG_USER_ID.

Возвращаемое значение

Возвращается массив с полями пользователя блога.

Примечание

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

См. также

  • CBlogUser::GetList()
  • Поля пользователя блога

Примеры использования

<?
$ID = $USER->GetID();
$arUser = CBlogUser::GetByID($ID, BLOG_BY_USER_ID);
if(is_array($arUser))
    print_r($arUser);
else
    echo "Пользователь не найден.";
?>


GetList

CBlogUser::GetList

CDBResult
CBlogUser::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список пользователей блога по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор пользователя блога;
  • USER_ID - идентификатор пользователя сайта;
  • ALIAS - псевдоним пользователя;
  • AVATAR - идентификатор аватара пользователя блога;
  • INTERESTS - интересы пользователя блога;
  • LAST_VISIT - время последнего посещения блогов;
  • DATE_REG - дата регистрации пользователя блога;
  • ALLOW_POST - флаг - разрешено ли писать в блогах;
  • USER_LOGIN - логин пользователя сайта;
  • USER_NAME - имя пользователя сайта;
  • USER_LAST_NAME - фамилия пользователя сайта;
  • USER_EMAIL - Email пользователя сайта;
  • GROUP_GROUP_ID - идентификатор группы пользователей блога;
  • GROUP_BLOG_ID - идентификатор блога группы пользователей блога.
Необязательный. По умолчанию фильтруется по убыванию идентификатора пользователя блога.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор пользователя блога;
  • USER_ID - идентификатор пользователя сайта;
  • ALIAS - псевдоним пользователя;
  • AVATAR - идентификатор аватара пользователя блога;
  • INTERESTS - интересы пользователя блога;
  • LAST_VISIT - время последнего посещения блогов;
  • DATE_REG - дата регистрации пользователя блога;
  • ALLOW_POST - флаг - разрешено ли писать в блогах;
  • USER_LOGIN - логин пользователя сайта;
  • USER_NAME - имя пользователя сайта;
  • USER_LAST_NAME - фамилия пользователя сайта;
  • USER_EMAIL - Email пользователя сайта;
  • GROUP_GROUP_ID - идентификатор группы пользователей блога;
  • GROUP_BLOG_ID - идентификатор блога группы пользователей блога.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.
Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля пользователей блога

Примеры использования

<?
// выберем всех пользователей - друзей блога с идентификатором 1
$arOrder = Array(
        "USER_NAME" => "ASC",
        "ID" => "ASC"
    );
$arFilter = Array(
        "GROUP_BLOG_ID" => 1
    );
$arSelectedFields = Array("ID", "USER_ID", "ALIAS", "USER_LOGIN", "USER_NAME", "USER_LAST_NAME");

$dbUsers = CBlogUser::GetList(
    $arOrder,
    $arFilter,
    false,
    false
    $arSelectedFields
);
while ($arUsers = $dbUsers->Fetch())
{
    print_r($arUsers);
}
?>


GetUserFriends

CBlogUser::GetUserFriends

CDBResult
CBlogUser::GetUserFriends(
 int  ID,
 bool bFlag = true
);

В зависимости от флага bFlag возвращает или список блогов друзей пользователя ID или список блогов, в которых пользователь ID является другом.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя сайта.
bFlag | Флаг. Если значение true, то возвращается список блогов в которых пользователь является другом, в противном случае возвращается список блогов друзей пользователя. Необязательный. По умолчанию true - возвращается список блогов в которых пользователь является другом.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult

Примеры использования

<?
// выберем все блоги друзей пользователя
$dbFriends = CBlogUser::GetUserFriends($USER->GetID(), True);
while ($arFriends = $dbFriends->Fetch())
{
    ?><a href="<?= CBlog::PreparePath($arFriends["URL"], false, $is404) ?>"><?= htmlspecialchars($arFriends["NAME"]) ?></a><?
}

?>


GetUserFriendsList

CBlogUser::GetUserFriendsList

CDBResult
CBlogUser::GetUserFriendsList(
 int  ID,
 int  userID = false,
 bool bAuth = false,
 int  limit = 20
);

Возвращает список сообщений друзей пользователя ID.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя, сообщения друзей которого необходимо выбрать.
userID | Идентификатор пользователя сайта для которого будут проверяться права.
bAuth | Авторизован ли текущий пользователь, для которого будет происходить проверка прав.
limit | Количество выводимых сообщений.

Возвращаемое значение

Метод возвращает массив вида:
Array(
    [ID] => 20, //идетификатор сообщения
    [DATE_PUBLISH] => 2007-08-08 18:41:24, // дата публикации сообщения
    [BLOG_ID] => 1, // идентификатор блога
    [URL] => 'admin-blog' // адрес блога
)

Примеры использования

<?
// выберем 20 сообщений друзей пользователя с ID=2
$ID = 2;
$dbList = CBlogUser::GetUserFriendsList($ID, $USER->GetID(), $USER->IsAuthorized(), 20);
while($arList = $dbLis->Fetch())
{
    $arPost = CBlogPost::GetByID($arList["ID"]);
    print_r($arPost);
}
?>


GetUserGroups

CBlogUser::GetUserGroups

array
CBlogUser::GetUserGroups(
 int    ID,
 int    blogID,
 string joinStatus = "",
 int    selectType = BLOG_BY_BLOG_USER_ID
);

Метод возвращает массив групп пользователей блога blogID, к которым привязан пользователя с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор пользователя.
blogID | Идентификатор блога.
joinStatus | Флаг - уже привязан пользователь к группе или только ожидает привязки. Необязательный. По умолчанию статус не учитывается.
selectType По какому идентификатору искать пользователя. Возможные значения:
  • BLOG_BY_USER_ID - по идентификатору пользователя сайта;
  • BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.
Необязательный. По умолчанию BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.

Возвращаемое значение

Метод возвращает массив групп пользователей блога, в случае ошибки возвращает false.

Примечание

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

Примеры использования

<?
// получим группы пользователей блога с ID=1, к которым привязан текущий пользователь
$ID = $USER->GetID();
$arUserGroups = CBlogUser::GetUserGroups($ID, 1, "", BLOG_BY_USER_ID);
if(is_array($arUserGroups))
    print_r($arUserGroups);
?>


GetUserIP

CBlogUser::GetUserIP

string
CBlogUser::GetUserIP();

Метод возвращает IP-адреса текущего посетителя.

Возвращаемое значение

Возвращается массив с доступными IP.

Примеры использования

<?
    $userIP = CBlogUser::GetUserIP();
    print_r($userIP);
?>


GetUserName

CBlogUser::GetUserName

string
CBlogUser::GetUserName(
 string alias,
 string name,
 string lastName,
 string login
);

Метод возвращает имя пользователя в зависимости от наличия параметров и разрешения использовать псевдоним. Если разрешен псевдоним, то вернется псевдоним, если нет, но есть имя или фамилия, то вернется имя и фамилия, в противном случае просто логин пользователя сайта.

Параметры функции

Параметр | Описание
alias | Псевдоним пользователя блога.
name | Имя пользователя сайта.
lastName | Фамилия пользователя сайта.
login | Логин пользователя сайта.

Возвращаемое значение

Возвращается имя пользователя.

Примеры использования

<?
//выведем имя текущего пользователя для блогов
$dbUser = CUser::GetByID($USER->GetID());
$arUser = $dbUser->Fetch();
$BlogUser = CBlogUser::GetByID($arUser["ID"], BLOG_BY_USER_ID);
$AuthorName = CBlogUser::GetUserName($BlogUser["ALIAS"], $arUser["NAME"], $arUser["LAST_NAME"], $arUser["LOGIN"]);
echo $AuthorName;
?>


GetUserPerms

CBlogUser::GetUserPerms

string
CBlogUser::GetUserPerms(
 array arGroups,
 int   blogID,
 int   postID = 0,
 int   permsType = BLOG_PERMS_POST,
 int   selectType = BLOG_BY_BLOG_USER_ID,
);

Метод возвращает уровень доступа пользователя блога на permsType, привязанного к группам arGroups, на сообщение postID блога ID.

Параметры функции

Параметр | Описание
arGroups | Массив групп пользователей блога или идентификтор пользователя. Если указывается идентификатор пользователя, то функция самостоятельно получает группы пользователей блога.
blogID | Идентификатор блога.
postID Идентификатор сообщения.
Необязательный. По умолчанию 0 - будет возвращено уровень доступа по умолчанию.
permsType Тип доступа. Возможные значения:
  • BLOG_PERMS_POST - доступ на сообщения;
  • BLOG_PERMS_COMMENT - доступ на комментарии.
Необязательный. По умолчанию BLOG_PERMS_POST - уровень доступа на сообщения.
selectType По какому идентификатору искать пользователя. Используется только, если в качестве первого параметра передается идентификатор пользователя. Возможные значения:
  • BLOG_BY_USER_ID - по идентификатору пользователя сайта;
  • BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.
    Необязательный. По умолчанию BLOG_BY_BLOG_USER_ID - по идентификатору пользователя блога.

    • Возвращаемое значение

    Метод возвращает уровень доступа пользователя.

    См. также

    • Уровни доступа

    Примеры использования

    <?
// получим уровень доступа к сообщениям блога с идентификатором 2
$blogID = 2;
$arUserGroups = CBlogUser::GetUserGroups($userID, $blogID, "Y", BLOG_BY_USER_ID);
$perms = CBlogUser::GetUserPerms(arUserGroups, $blogID, 0, BLOG_PERMS_POST);
echo "Вы имеете следующее право на сообщения блога: ".$perms;
?>


PreparePath

CBlogUser::PreparePath

string
CBlogUser::PreparePath(
 int    userID,
 string siteID = false,
 bool   is404 = true,
);

Метод возвращает путь к профайлу пользователя userID относительно корня сайта siteID с учётом варианта публичной части (с обработчиком 404 ошибки или без).

Параметры функции

Параметр | Описание
userID | Идентификатор пользователя сайта.
siteID | Идентификатор сайта. Необязательный. По умолчанию false - берется текущий сайт.
is404 | Используется ли обработчик 404 ошибки в публичной части. Необязательный. По умолчанию true - публичная часть блогов работает на базе обработчика 404 ошибки.

Возвращаемое значение

Возвращается путь к профайлу пользователя относительно корня сайта.

Примеры использования

<?
echo '<a href="'.CBlogUser::PreparePath($USER->GetID()).'">Ваш профайл</a>';
?>


SetLastVisit

CBlogUser::SetLastVisit

bool
CBlogUser::SetLastVisit(
);

Метод регистрирует последнее посещение блога текущим пользователем.

Возвращаемое значение

Метод возвращает true в случае успешной регистрации посещения, в противном случае возвращает false.

Примеры использования

<?
if(!CBlogUser::SetLastVisit())
    echo 'Ошибка!';
?>


Update

CBlogUser::Update

int
CBlogUser::Update(
 int   ID
 array arFields
);

Метод изменяет параметры пользователя блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого пользователя блога.
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей пользователя блога.

Возвращаемое значение

Метод возвращает идентификатор измененного пользователя блога, если изменение параметров прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CBlogUser::Add
  • Поля пользователя блога

Примеры использования

<?
//изменим профайл пользователя блога для текущего пользователя
$arUser = CBlogUser::GetByID($USER->GetID(), BLOG_BY_USER_ID)
$arFields = array(
    "ALIAS" => "Псевдоним текущего пользователя",
    "DESCRIPTION" => "Обычный пользователь сайта с блогом",
    "INTERESTS" => "программирование, PHP, MySQL, Bitrix, Битрикс, Microsoft"
);

$updateID = CBlogUser::Update($arUser["ID"], $arFields);
if(IntVal($updateID)>0)
{
    echo "Информация о пользователе блогов [".$updateID."] изменена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Класс CBlogUserGroup

CBlogUserGroup - класс для работы с группами пользователей блогов.

Метод | Описание
Add | Добавляет новую группу пользователей блога.
Delete | Удаляет группу пользователей блога.
GetGroupPerms | Возвращает уровень доступа группы пользователей блога.
GetByID | Возвращает группу пользователей блога по ее идентификатору.
GetList | Возвращает список групп пользователей блога по фильтру.
Update | Изменяет группу пользователей блога.


Add

CBlogUserGroup::Add

int
CBlogUserGroup::Add(
 array arFields
);

Метод добавляет новую группу пользователей блога.

Параметры функции

Параметр | Описание
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей группы пользователей блога.

Возвращаемое значение

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

См. также

  • CBlogUserGroup::Update
  • Поля группы пользователей

Примеры использования

<?
$arFields = array(
    "NAME" => 'Друзья',
    "BLOG_ID" => 1
);

$newID = CBlogUserGroup::Add($arFields);
if(IntVal($newID)>0)
{
    echo "Новая группа [".$newID."] добавлена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


Delete

CBlogUserGroup::Delete

bool
CBlogUserGroup::Delete(
 int ID
);

Метод удаляет группу пользователей блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор группы пользователей блога.

Возвращаемое значение

Метод возвращает true в случае успешного удаления группы пользователей блога, в противном случае возвращает false.

Примеры использования

<?
if(!CBlogUserGroup::Delete($ID))
{
    echo 'Ошибка удаления группы '.$ID;
}
?>


GetByID

CBlogUserGroup::GetByID

array
CBlogUserGroup::GetByID(
 int ID
);

Метод возвращает параметры группы пользователей блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор группы пользователей блога.

Возвращаемое значение

Возвращается массив с полями группы пользователей блога.

Примечание

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

См. также

  • Поля группы пользователей блога
  • CBlogUserGroup::GetList()

Примеры использования

<?
$ID = 3;
$arUserGroup = CBlogUserGroup::GetByID($ID);
if(is_array($arUserGroup))
    print_r($arUserGroup);
else
    echo "Группа пользователей не найдена.";
?>


GetGroupPerms

CBlogUserGroup::GetGroupPerms

string
CBlogUserGroup::GetGroupPerms(
 int    ID,
 int    blogID,
 int    postID = 0,
 string permsType = BLOG_PERMS_POST
);

Метод возвращает уровень доступа группы ID.

Параметры функции

Параметр | Описание
ID | Идентификатор группы пользователей блога.
blogID | Идентификатор блога.
postID Идентификатор сообщения.
Необязательный. По умолчанию 0 - возвращается уровень доступа по умолчанию, который задается в настройках блога.
permsType Тип доступа. Возможные значения:
  • BLOG_PERMS_POST - доступ к сообщениям;
  • BLOG_PERMS_COMMENT - доступ к комментариям сообщения.
Необязательный. По умолчанию BLOG_PERMS_POST - возвращается уровень доступа для сообщений.

Возвращаемое значение

Метод возвращает уровень доступа группы пользователей блога на сообщение или комметарии.

См. также

  • Уровни доступа к сообщениям

Примеры использования

<?
$perms = CBlogUserGroup::GetGroupPerms(3, 1);
echo "Группа пользователей с ID=3 имеете следующее право на сообщения блога 1: ".$perms;
?>


GetList

CBlogUserGroup::GetList

CDBResult
CBlogUserGroup::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array(),
 bool  arGroupBy = false,
 bool  arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список групп пользователей блога по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]) Поле для сортировки может принимать значения:
  • ID - идентификатор группы пользователей;
  • NAME - название группы пользователей;
  • BLOG_ID - идентификатор блога;
  • USER2GROUP_ID - идентификатор привязки пользователя к группе пользователей;
  • USER2GROUP_USER_ID - идентификатор пользователя группы пользователей блога.
Необязательный. По умолчанию фильтруется по убыванию идентификатора группы пользователей.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор группы пользователей;
  • NAME - название группы пользователей;
  • BLOG_ID - идентификатор блога;
  • USER2GROUP_ID - идентификатор привязки пользователя к группе пользователей;
  • USER2GROUP_USER_ID - идентификатор пользователя группы пользователей блога.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Необязательный. По умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Необязательный. По умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Необязательный. По умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля группы пользователей

Примеры использования

<?
// выберем все группы пользователей блога с ID = 1

$SORT = Array("NAME" => "ASC", "ID" => "ASC");
$arFilter = Array(
    "BLOG_ID" => 1
    );

$dbUserGroup = CBlogUserGroup::GetList(
        $SORT,
        $arFilter
    );

while ($arUserGroup = $dbUserGroup->Fetch())
{
    print_r($arUserGroup);
}
?>


Update

CBlogUserGroup::Update

int
CBlogUserGroup::Update(
 int   ID
 array arFields
);

Метод изменяет параметры группы пользователей блога с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемой группы пользователей.
arFields | Массив вида array("поле"=>"значение"[, ...]), содержащий значения полей группы пользователей блога.

Возвращаемое значение

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

См. также

  • Поля группы пользователя блога
  • CBlogUserGroup::Add

Примеры использования

<?
$ID = 3;
$arFields = array(
    "NAME" => 'Близкие друзья',
    "BLOG_ID" => 1
);

$updateID = CBlogUserGroup::Update($ID, $arFields);
if(IntVal($updateID)>0)
{
    echo "Группа пользователей [".$updateID."] изменена.";
}
else
{
    if ($ex = $APPLICATION->GetException())
        echo $ex->GetString();
}
?>


События модуля блогов

Событие | Описание
OnBeforeBlogAdd | Вызывается перед добавлением блога.
OnBlogAdd | Вызывается при добавлении блога.
OnBeforeBlogUpdate | Вызывается перед изменением блога.
OnBlogUpdate | Вызывается при изменении блога.
OnBeforeBlogDelete | Вызывается перед удалением блога.
OnBlogDelete | Вызывается при удалении блога.


OnBeforeBlogAdd

bool
функция-обработчик(
 array &arParams
);

Событие вызывается в методе CBlog::Add до вставки блога, и может быть использовано для отмены вставки или переопределения некоторых полей.

Параметры функции

Параметр | Описание
arParams | Массив полей блога.

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

Возвращаемое значение

Для отмены добавления и прекращении выполнения метода CBlog::Add необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnBlogAdd"
  • CBlog::Add
  • Обработка событий

Примеры использования

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("blog",
                "OnBeforeBlogAdd",
                Array("MyClass", "OnBeforeBlogAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeBlogAdd"
    function OnBeforeBlogAddHandler(&$arFields)
    {
        if(strlen($arFields["DESCRIPTION"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите описание блога.");
            return false;
        }
    }
}
?>


OnBeforeBlogDelete

bool
функция-обработчик(
 int   ID
);

Событие вызывается в методе CBlog::Delete до удаления блога и может быть использовано для отмены удаления.

Параметры функции

Параметр | Описание
ID | Идентификатор удаляемого блога.

Возвращаемое значение

Для отмены удаления и прекращении выполнения метода CBlog::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnBlogDelete"
  • CBlog::Delete
  • Обработка событий

Примеры использования

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("blog",
                "OnBeforeBlogDelete",
                Array("MyClass", "OnBeforeBlogDeleteHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeBlogDelete"
    function OnBeforeBlogDeleteHandler($ID)
    {
        if(IntVal($ID) == 1)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Первый блог удалить нельзя.");
            return false;
        }
    }
}
?>


OnBeforeBlogUpdate

bool
функция-обработчик(
 int   ID,
 array &arParams
);

Событие вызывается в методе CBlog::Update до изменения блога и может быть использовано для отмены изменения или переопределения некоторых полей.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого блога.
arParams | Массив полей блога.

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

Возвращаемое значение

Для отмены изменения и прекращении выполнения метода CBlog::Update, необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnBlogUpdate"
  • CBlog::Update
  • Обработка событий

Примеры использования

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("blog",
                "OnBeforeBlogUpdate",
                Array("MyClass", "OnBeforeBlogUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeBlogUpdate"
    function OnBeforeBlogUpdateHandler($ID, &$arFields)
    {
        if(strlen($arFields["DESCRIPTION"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите описание блога.");
            return false;
        }
    }
}
?>


OnBlogAdd

bool
функция-обработчик(
 int   ID
 array &arParams
);

Событие вызывается в момент добавления блога.

Параметры функции

Параметр | Описание
ID | Идентификатор добавленного блога.
arParams | Массив полей блога.

См. также

  • Событие "OnBeforeBlogAdd"
  • CBlog::Add
  • Обработка событий

Примеры использования

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("blog",
                "OnBlogAdd",
                Array("MyClass", "OnBlogAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBlogAdd"
    function OnBlogAddHandler($ID, &$arFields)
    {
        ...
    }
}
?>


OnBlogDelete

bool
функция-обработчик(
 int   ID
);

Событие вызывается в момент удаления блога.

Параметры функции

Параметр | Описание
ID | Идентификатор удаляемого блога.

См. также

  • Событие "OnBeforeBlogDelete"
  • CBlog::Delete
  • Обработка событий

Примеры использования

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("blog",
                "OnBlogDelete",
                Array("MyClass", "OnBlogDeleteHandler"));

class MyClass
{
    // создаем обработчик события "OnBlogDelete"
    function OnBlogDeleteHandler($ID)
    {
        ...
    }
}
?>


OnBlogUpdate

bool
функция-обработчик(
 int   ID
 array &arParams
);

Событие вызывается в момент изменения блога.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого блога.
arParams | Массив полей блога.

См. также

  • Событие "OnBeforeBlogUpdate"
  • CBlog::Update
  • Обработка событий

Примеры использования

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("blog",
                "OnBlogUpdate",
                Array("MyClass", "OnBlogUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBlogUpdate"
    function OnBlogUpdateHandler($ID, &$arFields)
    {
        ...
    }
}
?>


OnBlogUpdate

Валюты

  • Классы
  • Функции


Классы

Следующие классы используются для работы с модулем валют.

Классы

Класс | Описание
CCurrency | Класс для управления валютами: добавление, удаление, перечисление.
CCurrencyLang | Класс для работы с языкозависимыми параметрами валют (название, формат и пр.)
CCurrencyRates | Класс для работы с курсами валют: сохранение, конвертация и пр.


Класс CCurrency

CCurrency - класс для управления валютами: добавление, удаление, перечисление.

Методы класса

Метод | Описание
Add | Функция добавляет новую валюту.
Delete | Функция удаляет валюту с кодом currency.
GetBaseCurrency | Функция возвращает код базовой валюты.
GetByID | Функция возвращает массив языконезависимых параметров валюты по ее коду currency.
GetCurrency | Функция возвращает массив языконезависимых параметров валюты по ее коду currency. Функция аналогична функции GetByID, за исключение того, что возвращаемый результат в функции GetCurrency кешируется.
GetList | Функция возвращает список валют, отсортированный по полю из параметра by в направлении order.
SelectBox | Функция для формирования готового кода выпадающего списка (select) валют.
Update | Функция изменяет параметры валюты currency на параметры, указанные в массиве arFields.


Add

CCurrency::Add

string
CCurrency::Add(
 array arFields
);

Функция добавляет новую валюту. После добавления новой валюты необходимо установить ее языкозависимые параметры в помощью метода CCurrencyLang::Add

Параметры функции

Параметр Описание
arFields

Ассоциативный массив параметров валюты, в котором ключами являются названия параметров, а значениями - значения параметров.

Допустимые названия параметров:
CURRENCY - трехсимвольный код валюты (должен быть обязательно установлен)
AMOUNT_CNT - количество единиц валюты по-умолчанию, которое учавствует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
AMOUNT - курс валюты по-умолчанию (одна из валют сайта должна иметь курс 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)
SORT - порядок сортировки
DATE_UPDATE - дата последнего изменения записи

Возвращаемые значения

Функция возвращает код добавленной валюты или False в случае ошибки

Пример использования

<?
// Добавим новую валюту "Исландские кроны"
$arFields = array(
   "CURRENCY" => "ISK",
   "AMOUNT" => 44.8378,
   "AMOUNT_CNT" => 100,
   "SORT" => 250
);
CCurrency::Add($arFields);
?>


Delete

CCurrency::Delete

bool
CCurrency::Delete(
 string currency
);

Функция удаляет валюту с кодом currency. Удаляются в том числе все введенные курсы для этой валюты, а так же языкозависимые свойства валюты.

Параметры функции

Параметр | Описание
currency | Код валюты.

Возвращаемые значения

Функция возвращает True в случае успешного удаления и False - в противном случае

Пример использования

<?
CCurrency::Delete("USD");
?>


GetBaseCurrency

CCurrency::GetBaseCurrency

string CCurrency::GetBaseCurrency();

Функция возвращает код базовой валюты.

Одна из валют сайта должна иметь курс "по-умолчанию" равный 1. Эта валюта называется базовой. Курс всех валют, кроме базовой, задается относительно базовой валюты.

Параметры функции

Функция не имеет параметров.


GetByID

CCurrency::GetByID

array
CCurrency::GetByID(
 string currency
);

Функция возвращает массив языконезависимых параметров валюты по ее коду currency.

Смотрите так же функцию CCurrency::GetCurrency

Параметры функции

Параметр | Описание
currency | Код валюты.

Возвращаемые значения

Ассоциативный массив с ключами

Ключ | Описание
CURRENCY | Код валюты (трехсимвольный)
AMOUNT_CNT | Количество единиц валюты по-умолчанию, которое учавствует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
AMOUNT | Курс валюты по-умолчанию (одна из валют сайта должна иметь курс 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)
SORT | Порядок сортировки.
DATE_UPDATE | Дата последнего изменения записи.

Пример использования

<?
if (!($ar_usd_cur = CCurrency::GetByID("USD")))
{
    echo "Валюта USD не найдена";
}
else
{
    echo "Валюта USD имеет параметры:<pre>";
    print_r($ar_usd_cur);
    echo "</pre>";
}
?>


GetCurrency

CCurrency::GetCurrency

array
CCurrency::GetCurrency(
 string currency
);

Функция возвращает массив языконезависимых параметров валюты по ее коду currency. Функция аналогична функции CCurrency::GetByID, за исключение того, что возвращаемый результат в функции CCurrency::GetCurrency кэшируется. Поэтому повторный вызов функции с тем же кодом валюты в рамках одной страницы не приводит к дополнительному запросу в базу данных.

Смотрите так же функцию CCurrency::GetByID

Параметры функции

Параметр | Описание
currency | Код валюты.

Возвращаемые значения

Ассоциативный массив с ключами

Ключ | Описание
CURRENCY | Код валюты (трехсимвольный)
AMOUNT_CNT | Количество единиц валюты по-умолчанию, которое учавствует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
AMOUNT | Курс валюты по-умолчанию (одна из валют сайта должна иметь курс 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)
SORT | Порядок сортировки.
DATE_UPDATE | Дата последнего изменения записи.


GetList

CCurrency::GetList

CDBResult
CCurrency::GetList(
 string &by,
 string &order,
 string lang = LANGUAGE_ID
);

Функция возвращает список валют, отсортированный по полю из параметра by в направлении order. Языкозависимые параметры валют берутся для языка, указанного в параметре lang (по умолчанию равен текущему языку).

Параметры функции

Параметр | Описание
by | Переменная, содержащая порядок сортировки валют. Допустимые значения переменной: currency - код валюты name - название валюты на языке lang sort - индекс сортировки (по-умолчанию)
order | Переменная, содержащая направление сортировки. Допустимые значения: asc - по возрастанию значений (по-умолчанию) desc - по убыванию значений.
lang | Код языка, для которого выбираются языкозависимые параметры валют.

Возвращаемые значения

Возвращается объект класса CDBResult, каждая запись в котором представляет собой массив с ключами

Ключ | Описание
CURRENCY | Код валюты (трехсимвольный)
AMOUNT_CNT | Количество единиц валюты по-умолчанию, которое учавствует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
AMOUNT | Курс валюты по-умолчанию (одна из валют сайта должна иметь курс 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)
SORT | Порядок сортировки.
DATE_UPDATE | Дата последнего изменения записи.
LID | Код языка.
FORMAT_STRING | Строка формата для показа сумм в этой валюте.
FULL_NAME | Полное название валюты.
DEC_POINT | Символ, который используется при показе сумм в этой валюте для отображения десятичной точки.
THOUSANDS_SEP | Символ, который используется при показе сумм в этой валюте для отображения разделителя тысяч.
DECIMALS | Количество знаков после запятой при показе.

Пример использования

<?
// Выведем список валют на текущем языке, отсортированный по названию
// Кроме того выведем сумму 11.95 в формате этой валюты на текущем языке
$lcur = CCurrency::GetList(($b="name"), ($order1="asc"), LANGUAGE_ID);
while($lcur_res = $lcur->Fetch())
{
    echo "[".$lcur_res["CURRENCY"]."] ".$lcur_res["FULL_NAME"].": ";
    echo CurrencyFormat(11.95, $lcur_res["CURRENCY"])."<br>";
}
?>


SelectBox

CCurrency::SelectBox

string
CCurrency::SelectBox(
 string sFieldName,
 string sValue,
 string sDefaultValue = "",
 bool bFullName = True,
 string JavaFunc = "",
 string sAdditionalParams = ""
);

Функция для формирования готового кода выпадающего списка (select) валют. Список валют при построении списка кэшируется. Поэтому вывод дополнительных выпадающих списков в рамках одной страницы не приводит к дополнительным запросам к базе данных.

Параметры функции

Параметр | Описание
sFieldName | Название выпадающего списка.
sValue | Код валюты, которую нужно установить в списке выбранной.
sDefaultValue | Особое значение в списке, которое не соответствует ни одной валюте. Например, значение "Все" или "Не установлено". В этом случае код валюты в списке будет пустым. Если параметр пуст, то особое значение не отображается.
bFullName | Выводить ли полное имя валюты. Если параметр равен False, то в списке выводятся только коды валют.
JavaFunc | Название JavaScript функции, которая вызывается на событие OnChange списка. Если значение пустое, то функция не вызывается.
sAdditionalParams | Строка произвольных дополнительных атрибутов тега <select>

Возвращаемые значения

Строка, содержащая код для формирования выпадающего списка валют

Пример использования

<?
// Выведем выпадающий список валют
// с именем CURRENCY_DEFAULT, выбранной по умолчанию,
// валютой RUR, без особого значения

echo CCurrency::SelectBox("CURRENCY_DEFAULT",
                          "RUR",
                          "",
                          True,
                          "",
                          "class='typeselect'");
?>


Update

CCurrency::Update

bool
CCurrency::Update(
 string currency,
 array arFields
);

Функция изменяет параметры валюты currency на параметры, указанные в массиве arFields

Параметры функции

Параметр | Описание
currency | Код валюты, параметры которой нужно изменить.
arFields | Массив новых параметров валюты. Значение $arFields["CURRENCY"] должно совпадать с кодом currency изменяемой валюты.

Возвращаемые значения

Код валюты, параметры которой изменили, или False в случае ошибки


Класс CCurrencyLang

CCurrencyLang - класс для работы с языкозависимыми параметрами валют (название, формат и пр.)

Методы класса

Метод | Описание
Add | Функция добавляет новые языкозависимые параметры валюты.
Delete | Функция удаляет языкозависимые свойства валюты для указываемого языка.
GetByID | Функция возвращает массив языкозависимых параметров валюты для указываемого языка.
GetCurrencyFormat | Функция возвращает массив языкозависимых параметров валюты для указываемого языка.
Update | Функция обновляет языкозависимые параметры валюты для указываемого языка.


Add

CCurrencyLang::Add

bool
CCurrencyLang::Add(
 array arFields
);

Функция добавляет новые языкозависимые параметры валюты

Параметры функции

Параметр Описание
arFields

Ассоциативный массив параметров валюты, ключами которого являются названия параметров, а значениями - значения параметров.

Допустимые ключи:
CURRENCY - код валюты, для которой добавляются языкозависимые параметры (обязательно должен присутствовать)
LID - код языка (обязательный)
FORMAT_STRING - строка формата, в соответствии с которой выводится суммы в этой валюте на этом языке (обязательный)
FULL_NAME - полное название валюты
DEC_POINT - символ, являющийся десятичной точкой при выводе сумм (обязательный)
THOUSANDS_SEP - разделитель тысяч при выводе
DECIMALS - количество знаков после запятой при выводе (обязательный)

Возвращаемые значения

Возвращает значение True в случае успешного добавления и False - в противном случае

Пример использования

<?
$arFields = array(
    "FORMAT_STRING" => "# руб", // символ # будет заменен
                                // реальной суммой при выводе
    "FULL_NAME" => "Рубль",
    "DEC_POINT" => ".",
    "THOUSANDS_SEP" => "\xA0",  // неразрывный пробел
    "DECIMALS" => 2,
    "CURRENCY" => "RUR",
    "LID" => "ru"
);

// Если запись существует, обновляем,
// иначе добавляем новую
$db_result_lang = CCurrencyLang::GetByID("RUR", "ru");
if ($db_result_lang)
    CCurrencyLang::Update("RUR", "ru", $arFields);
else
    CCurrencyLang::Add($arFields);
?>


Delete

CCurrencyLang::Delete

bool
CCurrencyLang::Delete(
 string currency,
 string lang
);

Функция удаляет языкозависимые свойства валюты currency для языка lang

Параметры функции

Параметр | Описание
currency | Код валюты для удаления.
lang | Код языка.

Возвращаемые значения

Функция возвращает True в случае успешного удаления и False - в противном случае.


GetByID

CCurrencyLang::GetByID

array
CCurrencyLang::GetByID(
 string currency,
 string lang
);

Функция возвращает массив языкозависимых параметров валюты currency для языка lang

Параметры функции

Параметр | Описание
currency | Код валюты, языкозависимые параметры которой нужны.
lang | Код языка.

Возвращаемые значения

Ассоциативный массив с ключами

Ключ | Описание
CURRENCY | Код валюты (трехсимвольный)
LID | Код языка.
FORMAT_STRING | Строка формата, в соответствии с которой выводится суммы в этой валюте на этом языке.
FULL_NAME | Полное название валюты.
DEC_POINT | Символ, являющийся десятичной точкой при выводе сумм.
THOUSANDS_SEP | Разделитель тысяч при выводе.
DECIMALS | Количество знаков после запятой при выводе.

Пример использования

<?
$arFields = array(
    "FORMAT_STRING" => "# руб", // символ # будет заменен
                                // реальной суммой при выводе
    "FULL_NAME" => "Рубль",
    "DEC_POINT" => ".",
    "THOUSANDS_SEP" => "\xA0",  // неразрывный пробел
    "DECIMALS" => 2,
    "CURRENCY" => "RUR",
    "LID" => "ru"
);

// Если запись существует, то обновляем, иначе добавляем новую
$db_result_lang = CCurrencyLang::GetByID("RUR", "ru");
if ($db_result_lang)
    CCurrencyLang::Update("RUR", "ru", $arFields);
else
    CCurrencyLang::Add($arFields);
?>


GetCurrencyFormat

CCurrencyLang::GetCurrencyFormat

array
CCurrencyLang::GetCurrencyFormat(
 string currency,
 string lang = LANGUAGE_ID
);

Функция возвращает массив языкозависимых параметров валюты currency для языка lang.

Функция аналогична функции CCurrencyLang::GetByID, за исключение того, что возвращаемый результат в функции CCurrencyLang::GetCurrencyFormat кешируется. Поэтому повторный вызов функции с теми же кодами валюты и языка в рамках одной страницы не приводит к дополнительному запросу к базе данных.

Параметры функции

Параметр | Описание
currency | Код валюты, языкозависимые параметры которой нужны.
lang | Код языка.

Возвращаемые значения

Ассоциативный массив с ключами

Ключ | Описание
CURRENCY | Код валюты (трехсимвольный)
LID | Код языка.
FORMAT_STRING | Строка формата, в соответствии с которой выводится суммы в этой валюте на этом языке.
FULL_NAME | Полное название валюты.
DEC_POINT | Символ, являющийся десятичной точкой при выводе сумм.
THOUSANDS_SEP | Разделитель тысяч при выводе.
DECIMALS | Количество знаков после запятой при выводе.

Пример использования

<?
function MyFormatCurrency($fSum, $strCurrency)
{
    if (!isset($fSum) || strlen($fSum)<=0)
        return "";

    $arCurFormat = CCurrencyLang::GetCurrencyFormat($strCurrency);

    if (!isset($arCurFormat["DECIMALS"]))
        $arCurFormat["DECIMALS"] = 2;

    $arCurFormat["DECIMALS"] = IntVal($arCurFormat["DECIMALS"]);

    if (!isset($arCurFormat["DEC_POINT"]))
        $arCurFormat["DEC_POINT"] = ".";

    if (!isset($arCurFormat["THOUSANDS_SEP"]))
        $arCurFormat["THOUSANDS_SEP"] = "\\"."xA0";

    $tmpTHOUSANDS_SEP = $arCurFormat["THOUSANDS_SEP"];
    eval("\$tmpTHOUSANDS_SEP = \"$tmpTHOUSANDS_SEP\";");
    $arCurFormat["THOUSANDS_SEP"] = $tmpTHOUSANDS_SEP;

    if (!isset($arCurFormat["FORMAT_STRING"]))
        $arCurFormat["FORMAT_STRING"] = "#";

    $num = number_format($fSum,
                         $arCurFormat["DECIMALS"],
                         $arCurFormat["DEC_POINT"],
                         $arCurFormat["THOUSANDS_SEP"]);

    return str_replace("#",
                       $num,
                       $arCurFormat["FORMAT_STRING"]);
}

echo "Сумма 11800.95 руб на текущем языке будет выглядеть так: ";
echo MyFormatCurrency(11800.95, "RUR");
?>


Update

CCurrencyLang::Update

bool
CCurrencyLang::Update(
 string currency,
 string lang,
 array arFields
);

Функция обновляет языкозависимые параметры валюты currency для языка lang

Параметры функции

Параметр | Описание
currency | Код валюты, языкозависимые параметры которой нужно обновить.
lang | Код языка, для которого языкозависимые параметры валюты нужно обновить.
arFields

Ассоциативный массив новых параметров валюты, ключами которого являются названия параметров, а значениями - значения параметров.

Допустимые ключи:
CURRENCY - код валюты
LID - код языка
FORMAT_STRING - строка формата, в соответствии с которой выводится суммы в этой валюте на этом языке
FULL_NAME - полное название валюты
DEC_POINT - символ, являющийся десятичной точкой при выводе сумм
THOUSANDS_SEP - разделитель тысяч при выводе
DECIMALS - количество знаков после запятой при выводе

Возвращаемые значения

Возвращает значение True в случае успешного добавления и False - в противном случае

Пример использования

<?
$arFields = array(
    "FORMAT_STRING" => "# руб", // символ # будет заменен
                                // реальной суммой при выводе
    "FULL_NAME" => "Рубль",
    "DEC_POINT" => ".",
    "THOUSANDS_SEP" => "\xA0",  // неразрывный пробел
    "DECIMALS" => 2,
    "CURRENCY" => "RUR",
    "LID" => "ru"
);

// Если запись существует, то обновляем, иначе добавляем новую
$db_result_lang = CCurrencyLang::GetByID("RUR", "ru");
if ($db_result_lang)
    CCurrencyLang::Update("RUR", "ru", $arFields);
else
    CCurrencyLang::Add($arFields);
?>


Класс CCurrencyRates

CCurrencyRates - класс для работы с курсами валют: сохранение, конвертация и пр.

Методы класса

Метод | Описание
Add | Функция добавляет новую запись в таблицу курсов валют.
ConvertCurrency | Функция переводит сумму из одной валюты в другую по курсу, установленному на конкретную дату.
Delete | Удаляет запись из таблицы курсов валют.
GetByID | Возвращает параметры курса валют.
GetConvertFactor | Функция возвращает коэффициент для перевода сумм на конкретную дату.
GetList | Функция возвращает отсортированный список курсов валют, удовлетворяющих фильтру.
Update | Функция изменяет параметры записи в таблице курсов валют на значения из передаваемого массива.


Add

CCurrencyRates::Add

bool
CCurrencyRates::Add(
 array arFields
);

Функция добавляет новую запись в таблицу курсов валют

Параметры функции

Параметр Описание
arFields

Ассоциативный массив параметров курса валюты, ключами которого являются названия параметров, а значениями - значения параметров.

Допустимые ключи:
CURRENCY - код валюты, для которой добавляется курс (обязательно должен присутствовать)
DATE_RATE - дата, за которую устанавливается курс (обязательный)
RATE_CNT - количество единиц валюты, которое участвует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц) (обязательный)
RATE - курс валюты (одна из валют сайта должна иметь курс "по-умолчанию" 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)

Возвращаемые значения

Возвращает значение True в случае успешного добавления и False - в противном случае

Пример использования

<?
// Считаем, что RUR - базовая валюта
// Курс ирландских крон (ISK) на 21.02.2005:  10 ISK = 48.1756 RUR

$arFields = array(
    "RATE" => 48.1756,
    "RATE_CNT" => 10,
    "CURRENCY" => "ISK",
    "DATE_RATE" => "21.02.2005"
    );

if (!CCurrencyRates::Add($arFields))
    echo "Ошибка добавления курса";
?>


ConvertCurrency

CCurrencyRates::ConvertCurrency

float
CCurrencyRates::ConvertCurrency(
 float valSum,
 string curFrom,
 string curTo,
 string valDate = ""
);

Функция переводит сумму valSum из валюты curFrom в валюту curTo по курсу, установленному на дату valDate

Параметры функции

Параметр | Описание
valSum | Сумма в валюте curFrom, которую нужно перевести в валюту curTo
curFrom | Исходная валюта.
curTo | Конечная валюта.
valDate | Дата, по курсу на которую нужно осуществить перевод. Если дата пуста, то перевод идет по текущему курсу.

Возвращаемые значения

Сумма в новой валюте

Пример использования

<?
// предполагаем, что валюты USD и EUR существуют в базе
$val = 11.95; // сумма в USD
$newval = CCurrencyRates::ConvertCurrency($val, "USD", "EUR");
echo $val." USD = ".$newval." EUR";
?>


Delete

CCurrencyRates::Delete

bool
CCurrencyRates::Delete(
 int ID
);

Удаляет запись с кодом ID из таблицы курсов валют

Параметры функции

Параметр | Описание
ID | Код записи для удаления.

Возвращаемые значения

Возвращает значение True в случае успешного добавления и False - в противном случае


GetByID

CCurrencyRates::GetByID

array
CCurrencyRates::GetByID(
 int ID
);

Возвращает параметры курса валют с кодом ID

Параметры функции

Параметр | Описание
ID | Код курса.

Возвращаемые значения

Ассоциативный массив с ключами

Ключ | Описание
ID | Код курса.
CURRENCY | Код валюты.
DATE_RATE | Дата, за которую установлен курс.
RATE_CNT | количество единиц валюты, которое участвует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
RATE | курс валюты (одна из валют сайта должна иметь курс "по-умолчанию" 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)


GetConvertFactor

CCurrencyRates::GetConvertFactor

float
CCurrencyRates::GetConvertFactor(
 string curFrom,
 string curTo,
 string valDate = ""
);

Функция возвращает коэффициент для перевода сумм из валюты curFrom в валюту curTo по курсу, установленному на дату valDate

Параметры функции

Параметр | Описание
curFrom | Исходная валюта.
curTo | Валюта назначения.
valDate | Дата, по курсу на которую нужно осуществить перевод. Если дата пуста, то перевод идет по текущему курсу.

Возвращаемые значения

Коэффициент для перевода.

Пример использования

<?
$arVals = array(11.95, 18.27, 5.01);
$rate_cost = CCurrencyRates::GetConvertFactor("RUR", "USD");
for ($i = 0; $i < count($arVals); $i++)
{
    echo $arVals[$i]." RUR = ".Round($rate_cost*$arVals[$i], 2)." USD";
}
?>


Update

CCurrencyRates::Update

bool
CCurrencyRates::Update(
 int ID,
 array arFields
);

Функция изменяет параметры записи в таблице курсов валют на значения из массива arFields

Параметры функции

Параметр | Описание
ID | Код записи.
arFields

Ассоциативный массив новых параметров курса валюты, ключами которого являются названия параметров, а значениями - значения параметров.

Допустимые ключи:
CURRENCY - код валюты
DATE_RATE - дата, за которую устанавливается курс
RATE_CNT - количество единиц валюты, которое участвует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
RATE - курс валюты (одна из валют сайта должна иметь курс "по-умолчанию" 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)

Возвращаемые значения

Возвращает значение True в случае успешного добавления и False - в противном случае.


GetList

CCurrencyRates::GetList

CDBResult
CCurrencyRates::GetList(
 string &by,
 string &order,
 array arFilter = Array()
);

Функция возвращает список курсов валют, удовлетворяющих фильтру arFilter, отсортированный по полю by в направлении order

Параметры функции

Параметр Описание
by Переменная , содержащая название поля для сортировки. Доступные названия:
date - дата курса (по умолчанию)
curr - валюта
rate - курс.
order Переменная, содержащая направление сортировки. Допустимы значения:
asc - по возрастанию (по умолчанию)
desc - по убыванию.
arFilter

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

Допустимые поля для фильтра:
CURRENCY - код валюты
DATE_RATE - дата курса (выбираются записи с датами больше или равными указанной)
!DATE_RATE - дата курса (выбираются записи с датами меньше указанной)

Возвращаемые значения

Объект класса CDBResult, содержащий записи с ключами

Ключ | Описание
ID | Код курса.
CURRENCY | Код валюты.
DATE_RATE | Дата, за которую установлен курс.
RATE_CNT | количество единиц валюты, которое участвует в задании курса валюты (например, если 10 Датских крон стоят 48.7 рублей, то 10 - это количество единиц)
RATE | курс валюты (одна из валют сайта должна иметь курс "по-умолчанию" 1, она называется базовой, остальные валюты имеют курс относительно базовой валюты)

Пример использования

<?
// Выведем все курсы USD, отсортированные по дате
$arFilter = array(
    "CURRENCY" => "USD"
    );
$by = "date";
$order = "desc";

$db_rate = CCurrencyRates::GetList($by, $order, $arFilter);
while($ar_rate = $db_rate->Fetch())
{
    echo $ar_rate["RATE"]."<br>";
}
?>


CurrencyFormat

Функции

  • CurrencyFormat


CurrencyFormat

string
CurrencyFormat(
 float fSum,
 string strCurrency
);

Функция форматирует сумму fSum в соответствии с правилами форматирования для валюты strCurrency на текущем языке

Параметры функции

Параметр | Описание
fSum | Денежная сумма, которую нужно сформатировать.
strCurrency | Валюта, по правилам которой нужно производить форматирование.

Возвращаемые значения

Возвращает сформатированую строку

Пример использования

<?
echo CurrencyFormat(11800.95, "USD");
?>


Веб-сервисы

  • Классы


Классы модуля Web Service

Следующие PHP классы используются для реализации веб-сервисов в компонентах.

Классы

Класс | Описание
CWebServiceDesc | Структура описывающая методы и типы веб-сервиса.
IWebService | Интерфейс веб-сервиса для регистрации в CWebService.
CWebService | Менеджер веб-сервисов.

Следующие PHP классы реализуют SOAP протокол, WSDL, генерацию XML в модуле webservice.

Реализованные классы

Класс | Описание
CXMLCreator | Класс для генерации XML
CSOAPFault | Класс для обработки ошибок SOAP сервера и клиента.
CSOAPRequest | Класс формирует SOAP запрос/конверт.
CSOAPServerResponser | Интерфейс для реализации пользовательского обработчика SOAP запросов.
CSOAPServer | Класс SOAP сервер.
CSOAPClient | Класс SOAP клиент.
CWSDLCreator | Класс для автоматической генерации WSDL для веб-сервиса. Document/literal binding only.
CSOAPCodec | Класс трансформирует данные в XML согласно описанию веб-сервиса.
CSOAPResponse | Класс формирует/обрабатывает SOAP ответы.
CWSSOAPResponser | Класс реализующий обработку запросов к веб-сервисам через SOAP. Наследует CSOAPServerResponser.

Абстрактные классы

Класс | Описание
CSOAPHeader | Абстрактный класс для обработки SOAP пакета.
CSOAPBody | Абстрактный класс для обработки SOAP пакета.
CSOAPEnvelope | Абстрактный класс для обработки SOAP пакета.


CSOAPClient

Методы класса

Метод | Описание
CSOAPClient | Конструктор класса. Настраивает SOAP клиент на конкретный сервер ($server), точку доступа soap сервера ($path='/'), порт web сервера ($port).
send | Функция отсылает SOAP запрос сформированный CSOAPRequest.
setTimeout | Функция устанавливает время ожидания ответа SOAP сервера.
getRawRequest | Функция возвращает строку - запрос ушедший SOAP серверу.
getRawResponse | Функция возвращает строку - ответ SOAP сервера.
setLogin | Функция устанавливает логин для авторизации через HTTP Basic для SOAP запроса.
setPassword | Функция устанавливает пароль для авторизации через HTTP Basic для SOAP запроса.
login | Функция возвращает установленный логин.
password | Функция возвращает установленный пароль.

Пример использования номер 1 (внутренний тест)

function TestComponent()
{
    global $APPLICATION;
    $client = new CSOAPClient( "bitrix.soap", $APPLICATION->GetCurPage() );
    $request = new CSOAPRequest( "wsTestStartOut1", "http://bitrix.soap/" );
    $request->addParameter("str1", "qwe");
    $request->addParameter("str2", "fjdfhgfdh");
    $request->addParameter("int3", "123");
    $response = $client->send( $request );
    echo "Call wsTestStartOut1";
    if ( $response->isFault() )
    {
        print( "SOAP fault: " . $response->faultCode(). " - " . $response->faultString() . "" );
    }
    else
        echo "[OK]: ".mydump($response->Value);
}

Пример использования номер 2 (внешний тест)

function TestComponent()
{
    $client = new CSOAPClient("ws.strikeiron.com", "/relauto/iplookup/DNS");
    $request = new CSOAPRequest( "DNSLookup", "http://tempuri.org/");
    $request->addSOAPHeader( "LicenseInfo xmlns=\"http://ws.strikeiron.com\"",
            array("UnregisteredUser" => array( "EmailAddress" => "qwerty@mail.ru" ))
        );
    $request->addParameter("server", "www.yandex.ru");
    $response = $client->send( $request );

    echo "SOAPRequest: ".htmlspecialchars($client->getRawRequest());
    echo "SOAPResponse: ".htmlspecialchars($client->getRawResponse());
}


CSOAPFault

Члены класса

Параметр | Описание
$FaultCode | Параметр, содержащий код ошибки SOAP.
$FaultString | Параметр, содержащий строку, описывающую суть ошибки SOAP в доступном пользователю виде.

Конструктор класса CSOAPFault

CSOAPFault::CSOAPFault(
    string faultCode = "",
    string faultString = ""
)

Особенность использования

Обычно экземпляр этого класса передается в метод ShowResponse SOAP сервера, а тот передает CSOAPFault в SOAPResponse::payload, который различает тип ответа Value: ошибка ли это (экземпляр класса CSOAPFault), или же это обычный тип данных.

Таким образом, ошибки SOAP сервера, представленные классом CSOAPFault, компилируются в ответ отдельным способом. Все остальные типы проходят либо строгое кодирование согласно описанным типам веб-сервиса, либо легкое - с помощью CXMLCreator::encodeValueLight.

Пример использования

// Часть кода обработчика веб-сервисов SOAP сервера
$this->ShowResponse( $cserver, $functionName, $namespaceURI,
    new CSOAPFault(
        'Server Error',
        'Method not found'
    ) );


CSOAPRequest

Методы класса

Метод | Описание
CSOAPRequest | Конструктор класса.
addSOAPHeader | Функция добавляет в SOAP запрос часть заголовка.
addBodyAttribute | Функция добавляет атрибут к тегу body SOAP запроса.
addParameter | Функция добавляет данные для передачи в SOAP запросе. Для веб-сервиса - параметры вызываемого метода.
payload | Функция возвращает сформированный SOAP запрос в виде строки.

Пример использования

// Формируем запрос к веб-сервису ws.strikeiron.com/relauto/iplookup/DNS

$request = new CSOAPRequest( "DNSLookup", "http://tempuri.org/");
    $request->addSOAPHeader( "LicenseInfo xmlns=\"http://ws.strikeiron.com\"",
            array("UnregisteredUser" => array( "EmailAddress" => "qwerty@mail.ru" ))
        );
    $request->addParameter("server", "www.yandex.ru");


Конструктоа CSOAPRequest

CSOAPRequest::Конструктоа CSOAPRequest

CSOAPRequest::CSOAPRequest(
    string name = "",
    string namespace = "",
    array  parameters = array()
);

Конструктор класса.

Параметры конструктора

Параметр | Описание
name | Название сообщения в запросе.
namespace | Пространство имён сообщения запроса.
parameters | Параметры запроса в формате array("Название Параметра" => "Значение"). Значение может отдаваться в виде аналогичном тому, что принимает метод addParameter в качестве Value.

Пример использования

// Вызов DNSLookup метода веб-сервиса
$request = new CSOAPRequest( "DNSLookup", "http://tempuri.org/");


addParameter

CSOAPRequest::addParameter

void
CSOAPRequest::addParameter(
    string name,
        ЛюбойТипДанных value
)

Метод добавляет данные для передачи в SOAP запрос. Для веб-сервиса - параметры вызываемого метода.

Параметры метода

Параметр | Описание
name | Название параметра.
value | Обычно - ассоциативный массив описывающий содержание сообщения в заголовке запроса. См. CXMLCreator::encodeValueLight.

Пример использования

// Пример создания запроса для вызова веб-сервиса из файла webservice.wsdl.phpt
$request = new CSOAPRequest( "wsTestStart4", "http://bitrix.soap/" );
$request->addParameter("str1", "qwe");
$request->addParameter("str2", array(
    "1:ArrayOfsGenTestXEl" => array(
        "id" => "123",
        "name" => "qwe",
        "testa" => array(
                "1:ArrayOfsGenLiteEl" => array("id" => "56", "name" => "asd"),
                "2:ArrayOfsGenLiteEl" => array("id" => "13", "name" => "fjhg")
                )
    ),
    "2:ArrayOfsGenTestXEl" => array(
        "id" => "7653",
        "name" => "dfgsdf DASD",
        "testa" => array(
                "1:ArrayOfsGenLiteEl" => array("id" => "78", "name" => "ty"),
                "2:ArrayOfsGenLiteEl" => array("id" => "99", "name" => "3425rte")
            )
    )
));


addSOAPHeader

CSOAPRequest::addSOAPHeader

void
CSOAPRequest::addSOAPHeader(
    string name,
    ЛюбойТипДанных value
)

Метод добавляет в SOAP запрос часть заголовка.

Параметры метода

Параметр | Описание
name | Название сообщения в заголовке soap запроса.
value | Обычно - ассоциативный массив описывающий содержание сообщения в заголовке запроса. См. CXMLCreator::encodeValueLight.

Пример использования

$request->addSOAPHeader(
    "LicenseInfo xmlns=\"http://ws.strikeiron.com\"",
    array(
        "UnregisteredUser" => array( "EmailAddress" => "qwerty@mail.ru" ))
    );


addBodyAttribute

CSOAPRequest::addBodyAttribute

void
CSOAPRequest::addBodyAttribute(
    string name,
    string value
)

Метод добавляет атрибут к тегу body SOAP запроса.

Параметры метода

Параметр | Описание
name | Название атрибута.
value | Значение атрибута.


CSOAPServer

Методы класса

Метод | Описание
GetRequestData | Функция возвращает принятый запрос SOAP пакета.
GetResponseData | Функция возвращает ушедший в ответ SOAP пакет. GetResponseData можно вызвать только после ProcessRequest.
boolean AddServerResponser( CSOAPServerResponser &respobject ) | Функция регистрирует обработчик SOAP запроса. Обработчики, наследующие, интерфейс CSOAPServerResponser, должны быть зарегистрированы заранее, до вызова метода ProcessRequest.
ShowRawResponse | Функция формирует и отсылает SOAP Response пакет вместе с данными в виде CXMLCreator.
ShowResponse | Функция формирует и отсылает SOAP Response пакет, после преобразования данных.
ShowSOAPFault | Функция формирует и отсылает SOAP Response пакет с ошибкой.
ProcessRequest | Функция запускает обработку SOAP запроса. К этому моменту обработчики CSOAPServerResponser должны быть зарегистрированы методом AddServerResponser. Возвращает true если обработка успешна, иначе false.
stripHTTPHeader | Функция отрезает HTTP заголовок в том месте, где начинается XML-документ.

Пример использования

В этом примере в $arParams["SOAPSERVER_RESPONSER"] содержаться объекты обработчики SOAP.

Обычно SOAP-обработчик создаётся в компоненте, сохраняется в массив в $arParams["SOAPSERVER_RESPONSER"] и далее, когда включается компонент webservice.server, выполняется следующий код.

// В компоненте обработчика

// Создаем экземпляр обработчика
$research =& new CMSSOAPResearch();

// Конфигурируем обработчик
$research->provider_id = '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}';
$research->service_id = '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}';
$research->add_tittle = "";
$research->query_path = "http://{$_SERVER[HTTP_HOST]}/ws/wscauth.php";
$research->registration_path = "http://{$_SERVER[HTTP_HOST]}/ws/wscauth.php";

// Сохраняем для передачи в webservice.server
$arParams["SOAPSERVER_RESPONSER"] = array( &$research );

.........

// В компоненте webservice.server
$server = new CSOAPServer();

for ($i = 0; $i<count($arParams["SOAPSERVER_RESPONSER"]); $i++)
{
    $server->AddServerResponser($arParams["SOAPSERVER_RESPONSER"][$i]);
}

$result = $server->ProcessRequest();


CSOAPServerResponser

Методы интерфейса

Метод | Описание
void OnBeforeRequest( CSOAPServer &cserver ) | Метод вызывается для всех обработчиков CSOAPServerResponser зарегистрированных в обрабатывающем SOAP сервере при наступлении события, когда получен запрос к серверу, но ещё не началось его раскодирование.
void OnAfterResponse( CSOAPServer &cserver ) | Метод вызывается для всех обработчиков CSOAPServerResponser зарегистрированных в обрабатывающем SOAP сервере при наступлении события, когда завершилась обработка запроса и ответ уже отослан (ProcessRequestBody вернула true).
boolean ProcessRequestBody( CSOAPServer &cserver, CDataXMLNode body ) | Метод обработчик запроса SOAP сервера. Если метод обработал запрос и ответил вызовом ShowResponse, то возвращается true. Иначе возвращается false и вызовы ProcessRequestBody обработчиков продолжаются по цепочке пока не будет найден обработчик запроса, либо пока список обработчиков не иссякнет.

Параметры метода

Параметр | Описание
cserver | Ссылка на объект CSOAPServer, обрабатывающего soap запрос.
body | Часть XML запроса от элемента, следующего за тегом body в виде CDataXMLNode.

Пример использования

class CMSSOAPResearch extends CSOAPServerResponser
{
    var $provider_id;
    var $service_id;
    var $add_tittle;
    var $query_path;
    var $registration_path;

    function OnBeforeRequest(&$cserver)
    {
        AddMessage2Log(mydump($cserver->GetRequestData()));
    }

    function ProcessRequestBody(&$cserver, $body)
    {
        $functionName = $body->name();
        $namespaceURI = $body->namespaceURI();
        $requestNode = $body;

        if ($functionName == "Registration")
        {
            $root = new CXMLCreator("RegistrationResponse");
            $root->setAttribute("xmlns", "urn:Microsoft.Search");

            $regres = new CXMLCreator("RegistrationResult");
            $root->addChild($regres);

            $prup = new CXMLCreator("ProviderUpdate");
            $prup->setAttribute("xmlns", "urn:Microsoft.Search.Registration.Response");
            $prup->setAttribute("revision", "1");
            $prup->setAttribute("build", "1");
            $regres->addChild($prup);

            $stat = new CXMLCreator("Status");
            $stat->setData("SUCCESS");
            $prup->addChild($stat);

            $providers = array(

                "Provider" => array (
                    "Message" => "Тестовая служба.",
                    "Id" => "{$this->provider_id}",
                    "Name" => "Тестовая служба. {$this->add_tittle}",
                    "QueryPath" => $this->query_path,
                    "RegistrationPath" => $this->registration_path,
                    "AboutPath" => "http://www.bitrix.ru/",
                    "Type" => "SOAP",
                    "Revision" => "1",
                    "Services" => array(
                        "Service" => array(
                            "Id" => "{$this->service_id}",
                            "Name" => "Тестовая служба. {$this->add_tittle}",
                            "Description" => "Тестовая служба для тестирования soap сервера.",
                            "Copyright" => "(c) Bitrix.",
                            "Display" => "On",
                            "Category" => "ECOMMERCE_GENERAL",
                            "Parental" => "Unsupported",
                        )
                    )
                )

            );

            $providersEncoded = CSOAPRequest::encodeValueLight("Providers", $providers);
            $prup->addChild($providersEncoded);

            $cserver->ShowRawResponse($root, true);

            AddMessage2Log($cserver->GetResponseData());

            return true;
        }

        return false;
    }
}


CWebService

Методы класса

Метод | Описание
SetComponentContext | Функция запоминает контекст конфигурации компонента ($arParams) для передачи его в контекст вызова метода веб-сервиса.
GetComponentContext | Функция возвращает контекст конфигурации компонента ($arParams), который предоставляет веб-сервис. Может вызываться из методов веб-сервиса: CWebService::GetComponentContext.
SOAPServerProcessRequest | Функция вызывает обработчик SOAP сервера для обработки входящего запроса по методу POST. Обработчик вызывается для экземпляра веб-сервиса указанного в параметрах функции.
RegisterWebService | Функция регистрирует веб-сервис.
GetSOAPServerRequest | Функция возвращает SOAP запрос (string), который принял SOAP Сервер.
GetSOAPServerResponse | Функция возвращает ответ (string) SOAP Сервера.
MethodRequireHTTPAuth | Функция проверяет, пройдена ли HTTP Basic авторизация. Используется для методов веб-сервисов, которые требует авторизацию.
TestComponent | Функция вызывает IWebService::TestComponent запрашиваемого зарегистрированного веб-сервиса.
GetWSDL | Функция возвращает автоматически сгенирированный WSDL код (если CWebServiceDesc->wsdlauto равно true).
GetDefaultEndpoint | Функция возвращает точку доступа (например, http://site.ru/ws.php) для веб-сервиса по умолчанию.
GetDefaultTargetNS | Функция возвращает пространство имён для веб-сервиса по умолчанию.
GetWebServiceDeclaration | Функция возвращает экземпляр класса CWebServiceDesc через интерфейс IWebService веб-сервиса.
GetInterface | Функция возвращает экземпляр класса веб-сервиса, реализующий IWebService.


RegisterWebService

CWebService::RegisterWebService

boolean
CWebService::RegisterWebService(string className);

Метод регистрирует веб-сервис. Если операция проведена успешно, возвращается true, иначе false.

Если веб-сервис реализован через систему компонентов, то RegisterWebService вызывается автоматически в компоненте webservice.server. В этом случае className = $arParams["WEBSERVICE_NAME"].

Параметры функции

Параметр | Описание
className | Название класса веб-сервиса. реализующего интерфейс IWebService.

Пример использования

// В компоненте webservice.server
CWebService::RegisterWebService($arParams["WEBSERVICE_CLASS"]);

// В компоненте веб-сервиса
$arParams["WEBSERVICE_NAME"] = "bitrix.webservice.checkauth";
// Следующий параметр прямо передается в SOAPServerProcessRequest
$arParams["WEBSERVICE_CLASS"] = "CCheckAuthWS";
$arParams["WEBSERVICE_MODULE"] = "";
$APPLICATION->IncludeComponent(
    "bitrix:webservice.server",
    "",
    $arParams
    );


CWebServiceDesc

Веб-сервис

IWebService. wsdlauto boolean Параметр указывает, нужно ли генерировать WSDL-код автоматически. wstargetns string Пространство имён, например, http://bitrix.ru/ wsendpoint string Конечная точка (точка доступа) веб-сервиса - например, http://bitrix.ru/ws/testws.php classes array Описатель методов веб-сервиса. structTypes array Описатель сложных типов данных веб-сервиса (структуры). classTypes array Описатель сложных типов данных, десериализуемых из XML в экземпляры классов.

Класс CWebServiceDesc (описатель веб-сервиса) должен быть полностью инициализирован. Этот класс возвращается методом IWebService::GetWebServiceDesc. После регистрации описателя веб-сервиса, в его экземпляре автоматически создаётся экземпляр SOAP сервера и экземпляр WSDL генератора.

Методы веб-сервиса

Методы веб-сервисов всегда:

  • принадлежат классу, реализующему веб-сервис;
  • полностью описывают свои исходящие и входящие параметры;
  • строго соблюдают типы входящих\исходящих данных согласно их описанию.

Типы данных

Типы данных используемые методами веб-сервиса могут быть двух типов:

  • Простые типы - string, bool, boolean, int, integer, double, float, number;
  • Сложные типы - массивы, структуры (сериализуются в ассоциативные массивы), классы (сериализуются в экземпляры классов); Описываются с помощью structTypes, classTypes.

Типы данных описываются в трёх местах в описателе веб-сервиса CWebServiceDesc:

  • classes - массивы как параметры методов (см. описание классов);
  • structTypes - структуры;
  • classTypes - классы;

Описание веб-сервиса

Если автоматически генерируется WSDL, то генерируется Document/Literal binding. SOAP сервер поддерживает также исключительное Document/Literal binding. Для всех типов и параметров генерируется XSD схема.

Параметр Описание
classes Этот член класса обязательно должен быть инициализирован. Описывает методы веб-сервиса через его класс, входящие и исходящие параметры. Может оперировать массивами (как сложными типами данных) если указывается атрибут arrType и varType. При этом для массива автоматически создаётся свой тип данных в XSD схеме.

Ассоциативный массив:
$wsdesc->classes = array(
    "Имя класса содержащего метод веб-сервиса" => array(
        "Название метода веб-сервиса" => array(
            // означает что метод публичный
            "type"        => "public",
            "name"        => "Название метода веб-сервиса",
            // описание принимаемых методом параметров
            // "strict" => "no" - значит, что параметр не обязательный.
            //                    Его можно не передавать в soap запросе.
            "input"        => array(
                // "ТипДанных" - название сложного или простого типа данных
                "ИмяПараметра" =>array("varType" => "ТипДанных"[, "strict" => "no"]),
                // Так описываются параметры - массивы
                // varType - название массива (как типа данных, для xsd схемы)
                // arrType - тип элементов массива
                "ИмяПараметра" =>array("varType" => "ArrayOf"."ТипДанных",
                                        "arrType" => "ТипДанных"),
                // Пример передачи сложных типов данных.
                // Сложные типы должны быть описаны в structTypes, classTypes
                "ИмяПараметра" =>array("varType" => "sGenTest"),
                // Пример передачи массива сложного типа (структуры)
                "ИмяПараметра" =>array("varType" => "ArrayOfSGenTest",
                                        "arrType" => "sGenTest")
            ...
            // описание исходящих параметров
            "output"    => array(
                // Здесь может быть описан только один исходящий параметр
                "user" => array("varType" => "ТипДанных")
            ),
            // требуется ли для вызова метода пройти HTTP Basic авторизацию.
            "httpauth" => "Y или N"
        ), ...
    ), ...
);
structTypes Описывает структурные типы данных. В PHP они представлены ассоциативными массивами. В VisualStudio они представлены структурами (или классами).

SOAP сервер десериализует эти типы в ассоциативные массивы. Имена этих типов данных могут быть использованы в описателе параметров методов веб-сервиса в classes. Для этих типов данных автоматически создаётся ComplexType в xsd схеме.

Ассоциативный массив:
$wsdesc->structTypes["ИмяСтруктуры"] =
    array(
        "ИмяПоля" => array("varType" => "ТипДанных"),
        ...
    );
classTypes Описывает классы как типы данных. В PHP, VisualStudio они представленны классами.

SOAP сервер десериализует эти типы в экземпляры описанных классов. На момент десериализации класс должен быть определён (например, в компоненте, реализующем веб-сервис). Имена этих типов данных могут быть использованы в описателе параметров методов веб-сервиса в classes. Для этих типов данных автоматически создается ComplexType в xsd схеме.

Ассоциативный массив:
$wsdesc->classTypes["ИмяКласса"] =
    array(
        "ИмяПоля" => array("varType" => "ТипДанных"),
        ...
    );

Пример использования

В качестве хорошего примера использования CWebServiceDesc, вы можете исследовать вот этот файл: \bitrix\modules\webservice\classes\general\webservice.wsdl.php:

class CCheckAuthWS extends IWebService
{
    ...

    function GetWebServiceDesc()
    {
        $wsdesc = new CWebServiceDesc();
        $wsdesc->wsname = "bitrix.webservice.checkauth";
        $wsdesc->wsclassname = "CCheckAuthWS";
        $wsdesc->wsdlauto = true;
        $wsdesc->wsendpoint = CWebService::GetDefaultEndpoint();
        $wsdesc->wstargetns = CWebService::GetDefaultTargetNS();

        $wsdesc->classTypes = array();
        $wsdesc->structTypes["CUser"] =
        array(
            "ID" => array("varType" => "integer"),
            "NAME" => array("varType" => "string"),
            "TIMESTAMP_X" => array("varType" => "string"),
            "LOGIN" => array("varType" => "string"),
            "PASSWORD" => array("varType" => "string"),
            "CHECKWORD" => array("varType" => "string"),
            "ACTIVE" => array("varType" => "string"),
            "LAST_NAME" => array("varType" => "string"),
            "EMAIL" => array("varType" => "string")
        );

        $wsdesc->classes = array(
            "CCheckAuthWS" => array(
                "CheckAuthorization" => array(
                    "type"        => "public",
                    "name"        => "CheckAuthorization",
                    "input"        => array(
                        "user" =>array("varType" => "string"),
                        "password" =>array("varType" => "string")),
                    "output"    => array(
                        "user" => array("varType" => "CUser")
                        )
                ),
            "GetHTTPUserInfo" => array(
                    "type"        => "public",
                    "name"        => "GetHTTPUserInfo",
                    "input"        => array(),
                    "output"    => array(
                        "user" => array("varType" => "CUser")
                        ),
                    "httpauth" => "Y"
                )
            )
        );

        return $wsdesc;
    }

    ...
}


CXMLCreator

Класс представляет собой тег XML-документа, состоящий из атрибутов, дочерних элементов, текстового содержимого и CDATA контента.

Методы класса

Метод | Описание
CXMLCreator( string tag, boolean cdata ) | Конструктор класса. Принимает в качестве параметра название тега.
static CXMLCreator createTagAttributed( string heavyTag ) | Функция создаёт тег CXMLCreator из названия тега heavyTag, записанного в особенном формате.
static CXMLCreator encodeValueLight( string name, AnyType Value ) | Функция создаёт дерево XML документа с именем Name и строением Value. Name - название тега в формате heavyTag метода createTagAttributed. Value может быть любым типом данных, например, последовательностью вложенных ассоциативных массивов. Смотрите пример использования ниже.
setCDATA | Функция устанавливает CDATA-контент тега.
setAttribute | Функция устанавливает атрибут тега.
setData | Функция устанавливает текстовое содержимое тега.
setName | Функция устанавливает название тега.
addChild | Функция добавляет элемент XML документа в список своих детей.
getChildrenCount | Функция возвращает количество подчинённых элементов XML документа.
getXML | Функция возвращает XML документ в виде строки.
getXMLHeader | Функция возвращает заголовок XML документа.

Пример применения в обработчике SOAP запросов SOAP сервера

class CMSSOAPResearch extends CSOAPServerResponser
{
    ...

    function ProcessRequestBody(&$cserver, $body)
    {
        $functionName = $body->name();
        $namespaceURI = $body->namespaceURI();
        $requestNode = $body;

        if ($functionName == "Registration")
        {
            $root = new CXMLCreator("RegistrationResponse");
            $root->setAttribute("xmlns", "urn:Microsoft.Search");

            $regres = new CXMLCreator("RegistrationResult");
            $root->addChild($regres);

            $prup = new CXMLCreator("ProviderUpdate");
            $prup->setAttribute("xmlns", "urn:Microsoft.Search.Registration.Response");
            $prup->setAttribute("revision", "1");
            $prup->setAttribute("build", "1");
            $regres->addChild($prup);

            $stat = new CXMLCreator("Status");
            $stat->setData("SUCCESS");
            $prup->addChild($stat);

            $providers = array(

                "Provider" => array (
                    "Message" => "Тестовая служба.",
                    "Id" => "{$this->provider_id}",
                    "Name" => "Тестовая служба. {$this->add_tittle}",
                    "QueryPath" => $this->query_path,
                    "RegistrationPath" => $this->registration_path,
                    "AboutPath" => "http://www.bitrix.ru/",
                    "Type" => "SOAP",
                    "Revision" => "1",
                    "Services" => array(
                        "Service" => array(
                            "Id" => "{$this->service_id}",
                            "Name" => "Тестовая служба. {$this->add_tittle}",
                            "Description" => "Тестовая служба для тестирования soap сервера.",
                            "Copyright" => "(c) Bitrix.",
                            "Display" => "On",
                            "Category" => "ECOMMERCE_GENERAL",
                            "Parental" => "Unsupported",
                        )
                    )
                )

            );

            $providersEncoded = CSOAPRequest::encodeValueLight("Providers", $providers);
            $prup->addChild($providersEncoded);

            ...

            return true;
        }

        return false;
    }
}


createTagAttributed

CXMLCreator::createTagAttributed

static
CXMLCreator
CXMLCreator::createTagAttributed(string heavyTag);

Статический метод возвращает созданный тэг CXMLCreator из названия heavyTag, записанного в особенном формате. Если формат heavyTag неверен, возвращается true.

Параметры функции

Параметр | Описание
heavyTag | Строка названия тэга в формате: [Индекс:]НазваниеТэга [Атрибут="Значение атрибута" ...] Индекс - число, помогающее поместить в ассоциативном массиве сразу несколько тегов с одинаковым названием. Атрибут может быть записан в виде: симв:симв = "Значение"

Пример использования

CXMLCreator::createTagAttributed( "LicenseInfo xmlns=\"http://ws.strikeiron.com\"");

// Или
CXMLCreator::encodeValueLight( "LicenseInfo xmlns=\"http://ws.strikeiron.com\"",
array(
    "1:ArrayOfStringEl" => "Строка1",
    "2:ArrayOfStringEl" => "Строка2"
    )
);


IWebService

Методы интерфейса IWebService

Метод | Описание
GetWebServiceDesc | Возвращает класс, полностью описывающий веб-сервис (методы, типы данных, ...).
TestComponent | Метод внутреннего авто-тестирования веб-сервиса.

IWebService - интерфейс через который регистрируется веб-сервис в CWebService. Класс, реализующий веб-сервис, должен наследовать этот интерфейс.


GetWebServiceDesc

CWebServiceDesc
IWebService::GetWebServiceDesc();

Метод возвращает экземпляр класса CWebServiceDesc - описателя веб-сервиса.


TestComponent

void
IWebService::TestComponent();

Метод запускает внутреннее тестирование веб-сервиса с использованием SOAP клиента. Этот метод вызывается из публичной части веб-сервиса.

class CCheckAuthWS extends IWebService
{
    ...

    function TestComponent()
    {
        global $APPLICATION;
        $client = new CSOAPClient("bitrix.soap", $APPLICATION->GetCurPage());

        // HTTP Authorization required by GetHTTPUserInfo method
        $client->setLogin("admin");
        $client->setPassword("123456");
        $request = new CSOAPRequest("GetHTTPUserInfo", CWebService::GetDefaultTargetNS());

        //$request->addParameter("stub", 0);
        $response = $client->send( $request );
        if ($response->FaultString)
            echo $response->FaultString;
        else
            echo "Call GetHTTPUserInfo():
".mydump($response->Value)."
";

    }

    ...
}


Введение

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

Модуль "Веб-формы" обеспечивает:

  • Наглядный интерфейс создания веб-форм, включающий в себя:
    • формирование списка вопросов и ответов на них;
    • формирование списка дополнительных полей;
    • формирование списка статусов результатов веб-формы;
    • распределение прав доступа на веб-форму и каждый статус в отдельности.
  • Вывод веб-формы для заполнения.
  • Сохранение значений ответов на вопросы веб-формы в виде результатов.
  • Выполнение ряда вспомогательных действий в момент сохранения результата:
    • проверка введенных данных на корректность;
    • отсылка данных результата посредством электронной почты;
    • создание события в модуле "Статистика".
  • Вывод результатов в виде списка, а также возможность выполнения следующих действий:
    • редактирование и обновление результата;
    • смена статуса результата;
    • удаление результата;
    • фильтрация результатов по настраиваемому набору вопросов и полей.


Имена HTML полей веб-форм

Вопросы веб-формы

При выводе веб-формы все ответы на вопросы представляются в виде HTML полей, заполняя которые, пользователи отвечают на тот или иной вопрос. Ниже представлена таблица зависимости имен HTML-полей от типов ответов.

Тип ответа | Описание | Имя HTML поля | Значение ответа
text | Однострочное текстовое поле. | form_text_answer_id | Текст, введенный с клавиатуры.
textarea | Многострочное текстовое поле. | form_textarea_answer_id | Текст, введенный с клавиатуры.
password | Однострочное текстовое поле для ввода пароля. | form_password_answer_id | Текст, введенный с клавиатуры.
date | Однострочное текстовое поле для ввода даты. | form_date_answer_id | Текст, введенный с клавиатуры.
radio | Переключатель одиночного выбора. | form_radio_question_sid | ID выбранного ответа.
dropdown | Выпадающий список одиночного выбора. | form_dropdown_question_sid | ID выбранного ответа.
checkbox | Флаг множественного выбора. | form_checkbox_question_sid[] | Массив ID выбранных ответов.
multiselect | Список множественного выбора. | form_multiselect_question_sid[] | Массив ID выбранных ответов.
file | Поле для ввода произвольного файла. | form_file_answer_id | Массив, описывающий загруженный файл.
image | Поле для ввода изображения. | form_image_answer_id | Массив, описывающий загруженный файл.
Принятые обозначения
  • answer_id - ID ответа;
  • question_sid - символьный идентификатор вопроса.

Поля веб-формы

Помимо ответов на вопросы веб-формы, необходимо выводить и редактировать значения полей веб-формы. Ниже представлена таблица зависимости имен HTML полей от типов поля веб-формы.

Тип поля | Описание | Имя HTML поля | Значение
text | Текст | form_textarea_ADDITIONAL_field_id | Текст, введенный с клавиатуры.
integer | Число | form_text_ADDITIONAL_field_id | Текст, введенный с клавиатуры.
date | Дата | form_date_ADDITIONAL_field_id | Текст, введенный с клавиатуры.
Принятые обозначения
  • field_id - ID поля веб-формы.

См. также

  • CForm::GetTextField
  • CForm::GetTextAreaField
  • CForm::GetPasswordField
  • CForm::GetDateField
  • CForm::GetRadioField
  • CForm::GetCheckBoxField
  • CForm::GetDropDownField
  • CForm::GetMultiSelectField
  • CForm::GetFileField
  • CFormResult::GetDataByIDForHTML


Права модуля веб-форм

В этом разделе

  • Права на модуль
  • Права на веб-форму
  • Права на результат (статус)
    •

    Права на модуль

    Права на модуль "Веб-формы" задаются для групп пользователей и регулируют доступ к административной части модуля. Права могут быть следующих видов (в порядке возрастания уровня доступа):

    • [D] доступ закрыт - доступ к административной части модуля закрыт;
    • [R] доступ открыт - доступ к административной части модуля открыт;
    • [W] полный доступ - полный административный доступ на весь модуль и на все веб-формы модуля.
    Каждый пользователь может обладать только одним из вышеперечисленных прав доступа, которое является для него максимальным.

    Права на веб-форму

    Права на каждую веб-форму позволяют разграничить доступ пользователей к той или иной веб-форме и ее результатам. Права могут быть следующих видов (в порядке возрастания уровня доступа):

    • 1 - доступ закрыт (форма и ее результаты полностью недоступны);
    • 10 - заполнение формы (посетитель может только заполнить и сохранить форму);
    • 15 - редактирование своего результата (посетитель получает возможность видеть список своих результатов, который он может фильтровать и сортировать; также посетитель может просмотреть, изменить и удалить свой результат);
    • 20 - просмотр всех результатов (посетитель получает возможность просмотра всех активных результатов);
    • 25 - редактирование всех результатов и просмотр настроек формы (посетитель получает возможность просмотра и редактирования всех результатов в зависимости от их статусов; также, если у него открыт доступ к административной части модуля, у него есть доступ на просмотр настроек формы);
    • 30 - полный доступ (включает в себя все вышеописанные права, а также право на изменение настроек формы).
    Каждый пользователь может обладать только одним из вышеперечисленных прав доступа, которое является для него максимальным.

    Права на результат (статус)

    Права на результат определяются статусом, в котором находится тот или иной результат. Соответственно, данные права задаются в настройках того или иного статуса и могут быть следующих видов:

    • VIEW - право на просмотр результатов в данном статусе;
    • MOVE - право на перевод результатов в данный статус;
    • EDIT - право на редактирование результатов в данном статусе;
    • DELETE - право на удаление результатов в данном статусе.
    Один пользователь может обладать одним и более из вышеперечисленных прав доступа.


Обработчики статусов

Оглавление

  • Введение
  • Файлы-обработчики
  • Доступные переменные

Введение

Каждый результат в обязательном порядке должен обладать тем или иным статусом. При создании результата новый статус назначается в соответствии с флагом Присваивать данный статус всем новым документам по умолчанию (данный флаг может быть установлен только у одного статуса). В процессе работы статус у результата может меняться.

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

  • создавать почтовые события, предназначенные для отправки e-mail сообщений;
  • производить привязку пользователя, изменившего статус, к другой группе пользователей (например, для того, чтобы открыть доступ к определённым частям сайта);
  • другие действия.

Файлы-обработчики

Файлы-обработчики представляют собой PHP-скрипты, которые подключаются в момент смены статуса. Они могут располагаться в любом каталоге относительно корня сайта; например, в каталоге /bitrix/php_interface/include/form/handlers/.

Для того, чтобы задать файл-обработчик, необходимо перейти на страницу редактирования параметров того или иного статуса. На данной странице будут доступны следующие параметры:

  • Файл-обработчик смены данного статуса на какой либо другой (либо удаление результата) - данный параметр может содержать путь относительно корня к файлу-обработчику, который будет подключен при смене у какого-либо результата данного статуса на иной статус; также он будет подключен при удалении результата, находящегося в данном статусе;
  • Файл-обработчик смены какого либо статуса на данный (либо добавление нового результата) - данный параметр может содержать путь относительно корня к файлу-обработчику, который будет подключен при смене у результата произвольного статуса на данный; также он будет подключен при создании нового результата и установки у него данного статуса.

Доступные переменные

Для обработчика, указанного в параметре "Файл-обработчик смены данного статуса на какой либо другой (либо удаление результата)", будут доступны следующие переменные.

Переменная | Описание
$CURRENT_STATUS_ID | ID текущего статуса результата (до его смены).
$NEW_STATUS_ID | ID нового статуса, на который будет произведена смена.
$RESULT_ID | ID результата, над которым происходит действие по смене статуса.
$arResult | Массив, описывающий поля этого результата.
$ACTION Символьный код действия, производимого над результатом. Допустимы следующие значения:
  • UPDATE - результат был обновлен (модифицирован);
  • SET_STATUS - у результата напрямую сменили статус (например, из списка результатов);
  • DELETE - результат был удален.

Для обработчика, указанного в параметре "Файл-обработчик смены какого либо статуса на данный (либо добавление нового результата)", будут доступны следующие переменные.

Переменная | Описание
$CURRENT_STATUS_ID | ID текущего статуса.
$PREV_STATUS_ID | ID предыдущего статуса.
$RESULT_ID | ID результата, над которым происходит действие по смене статуса.
$arResult | Массив, описывающий поля этого результата.
$ACTION Символьный код действия, производимого над результатом. Допустимы следующие значения:
  • UPDATE - результат был обновлен (модифицирован);
  • SET_STATUS - у результата напрямую сменили статус (например, из списка результатов);
  • ADD - был добавлен новый результат.


Список терминов

Иерархическая схема сущностей модуля

Веб-форма
Синонимами (реализациями) данного термина можно считать такие сущности, как "анкета" и "опросный лист". Веб-форма представляет из себя совокупность:
  • списка вопросов;
  • списка ответов на вопросы;
  • списка дополнительных полей веб-формы;
  • списка возможных статусов для результатов веб-формы.

Веб-форма может быть выведена на экран, заполнена и сохранена в виде результата.

На веб-форму можно установить различные права доступа для групп пользователей:

  • 1 - доступ закрыт (форма и ее результаты полностью недоступны);
  • 10 - заполнение формы (посетитель может только заполнить и сохранить форму);
  • 15 - редактирование своего результата (посетитель получает возможность видеть список своих результатов, который он может фильтровать и сортировать; также посетитель может просмотреть, изменить и удалить свой результат);
  • 20 - просмотр всех результатов (посетитель получает возможность просмотра всех активных результатов);
  • 25 - редактирование всех результатов и просмотр настроек формы (посетитель получает возможность просмотра и редактирования всех результатов в зависимости от их статусов, а также, если у него открыт доступ к административной части модуля - доступ на просмотр настроек формы);
  • 30 - полный доступ (включает в себя все вышеописанные права, а также право на изменение настроек формы).
Один пользователь может обладать только одним из вышеприведенных прав доступа (которое является для него максимальным).

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

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

Вопрос
Представляет из себя совокупность:
  • непосредственно текста вопроса;
  • типа текста вопроса [text|html];
  • изображение вопроса;
  • списка ответов;
  • настроек, связанных с отображением вопроса в списке результатов;
  • настроек, связанных с отображением полей для фильтрации результатов по значениям ответов на данный вопрос.

Ответ
Каждый вопрос веб-формы подразумевает набор HTML-полей предназначенных для ввода ответа на данный вопрос. Каждое такое HTML-поле является ответом. Таким образом, ответ (в терминологии данного модуля) подразумевает совокупность таких понятий как:
  • параметр ANSWER_TEXT (выводится рядом с HTML полей в качестве подписи к этому полю);
  • параметр ANSWER_VALUE (используется для внутренних служебных целей, например, при расчёте значений полей веб-формы);
  • тип, который может принимать следующие значения:
    • text - однострочное текстовое поле;
    • textarea - многострочное текстовое поле;
    • radio - переключатель одиночного выбора (radio-кнопка);
    • checkbox - флаг множественного выбора (checkbox);
    • dropdown - элемент выпадающего списка одиночного выбора;
    • multiselect - элемент списка множественного выбора;
    • date - поле для ввода даты;
    • image - поле для загрузки изображения;
    • file - поле для загрузки произвольного файла;
    • password - поле для ввода пароля.
  • ширина;
  • высота;
  • дополнительные параметры.
Результат
После того, как пользователь заполнит веб-форму и нажмет Сохранить, все значения ответов будут сохранены в базу данных в виде результата. Если разработчик предусмотрит использование полей, то предварительно рассчитанные значения этих полей могут быть также записаны в результат. Каждый результат в обязательном порядке должен обладать тем или иным статусом, регулирующим права доступа к данному результату. Таким образом, результат - это совокупность:
  • значений ответов на вопросы веб-формы;
  • значений полей веб-формы;
  • значения статуса.
Статус
Основная задача статуса - разграничение прав доступа на результат для каждой из грапп пользователей.

Права доступа для статуса могут быть следующих видов:

  • VIEW - право на просмотр результатов в данном статусе;
  • MOVE - право на перевод результатов в данный статус;
  • EDIT - право на редактирование результатов в данном статусе;
  • DELETE - право на удаление результатов в данном статусе.

Один пользователь может обладать одним и более из вышеперечисленных прав доступа.

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

Валидатор

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

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

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


Создание собственных валидаторов полей веб-форм

В этом разделе

  • Структура валидатора
  • Описание валидатора
  • Параметры валидатора
  • Обработка параметров
  • Валидатор
    •
  • Интеграция валидатора
  • Пример
    •

    Структура валидатора

    Валидатор представляет собой класс или набор функций следующей структуры:

    Метод | Описание
Описание валидатора | Функция, передающая обработчику валидаторов описание валидатора, названия методов и пр.
Настройки валидатора | Функция, возвращающая массив настроек валидатора.
Обработка настроек | Набор функций, отвечающий за подготовку настроек к занесению в БД и обратное преобразование.
Функция валидации | Собственно, валидатор.

    Поскольку работать с набором отдельных функций неудобно, рекомендуется объединить их в класс (пространство имен). Исходя из этой рекомендации будет идти дальнейшее описание, а также, реализован приводимый пример. В примере валидатор "Число в промежутке" реализован в виде класса CFormCustomValidatorNumberEx.

    Описание валидатора

    Описание валидатора представляет собой метод, возвращающий ассоциативный массив следующей структуры:

    Параметр | Описание
NAME | Уникальный строковой идентифкатор валидатора.
DESCRIPTION | Название валидатора.
TYPES | Массив типов полей, к которым применим валидатор.
SETTINGS | Название метода, возвращающего массив настроек валидатора. Не обязателен. В случае реализации валидатора в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
CONVERT_TO_DB | Название метода, отвечающего за проверку параметров валидатора и преобразование массива настроек в строку для сохранения. Не обязателен, если валидатор не имеет настроек. В случае реализации валидатора в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
CONVERT_FROM_DB | Название метода, отвечающего за обратное преобразование строки параметров валидатора в массив. Не обязателен, если валидатор не имеет настроек. В случае реализации валидатора в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
HANDLER | Название основного метода, отвечающего собственно за валидацию значения поля. В случае реализации валидатора в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").

    Пример:

function GetDescription()
{
  return array(
    "NAME"            => "custom_number_ex",                                   // идентификатор
    "DESCRIPTION"     => "Число в промежутке",                                 // наименование
    "TYPES"           => array("text", "textarea"),                            // типы полей
    "SETTINGS"        => array("CFormCustomValidatorNumberEx", "GetSettings"), // метод, возвращающий массив настроек
    "CONVERT_TO_DB"   => array("CFormCustomValidatorNumberEx", "ToDB"),        // метод, конвертирующий массив настроек в строку
    "CONVERT_FROM_DB" => array("CFormCustomValidatorNumberEx", "FromDB"),      // метод, конвертирующий строку настроек в массив
    "HANDLER"         => array("CFormCustomValidatorNumberEx", "DoValidate")   // валидатор
  );
}
    Параметры валидатора

    Метод, заданный элементом SETTINGS, должен возвращать массив элементов вида:

    "имя_параметра" => array(
    "TITLE"   => "название_параметра",
    "TYPE"    => "тип_параметра",
    "DEFAULT" => "значение_по_умолчанию",
    "VALUES"  => array(
        "значение1" => "наименование_значения1",
        "значение2" => "наименование_значения2",
        "значение3" => "наименование_значения3"
    )
)
    Параметр | Описание
    имя_параметра | Ключом массива является уникальное в рамках данного валидатора строковое наименование параметра.
    TITLE | Наименование параметра
    TYPE Тип поля для ввода значения параметра. Может принимать следющие значения:
    • TEXT - обычное текстовое поле;
    • CHECKBOX - галочка. Результатом будет значение {Y|N};
    • DROPDOWN - выпадающий список;
    • DATE - поле для ввода даты.
    DEFAULT | Значение параметра по умолчанию.
    VALUES | Массив элементов вида "значение" => "наименование значения" для параметров типа DROPDOWN

    Пример:

function GetSettings()
{
  return array(
    "NUMBER_FROM" => array(
      "TITLE"   => "Нижний порог числа",
      "TYPE"    => "TEXT",
      "DEFAULT" => "0",
    ),

    "NUMBER_TO" => array(
      "TITLE"   => "Верхний порог числа",
      "TYPE"    => "TEXT",
      "DEFAULT" => "100",
    ),

    "NUMBER_FLOAT" => array(
      "TITLE"   => "Не только целое",
      "TYPE"    => "CHECKBOX",
      "DEFAULT" => "Y",
    ),
  );
}
    Обработка параметров

    Обработка параметров валидатора требует двух методов, задаваемых в описании параметрами CONVERT_TO_DB и CONVERT_FROM_DB. Первый из них получает на вход массив значений параметров и должен вернуть их строковое представление. Второй - совершить обратное преобразование. Оба метода могут также совершать произвольные манипуляции со значениями параметров.

    Пример:

function ToDB($arParams)
{
  // проверка переданных параметров
  $arParams["NUMBER_FLOAT"] = $arParams["NUMBER_FLOAT"] == "Y" ? "Y" : "N";
  $arParams["NUMBER_FROM"]  = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_FROM"]) : intval($arParams["NUMBER_FROM"]);
  $arParams["NUMBER_TO"]    = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_TO"]) : intval($arParams["NUMBER_TO"]);

  // перестановка значений порогов, если требуется
  if ($arParams["NUMBER_FROM"] > $arParams["NUMBER_TO"])
  {
    $tmp                     = $arParams["NUMBER_FROM"];
    $arParams["NUMBER_FROM"] = $arParams["NUMBER_TO"];
    $arParams["NUMBER_TO"]   = $tmp;
  }

  // возвращаем сериализованную строку
  return serialize($arParams);
}

function FromDB($strParams)
{
  // никаких преобразований не требуется, просто вернем десериализованный массив
  return unserialize($strParams);
}
    Валидатор

    Основной метод получает на вход 4 параметра: массив параметров валидатора, массив параметров вопроса, массив ответов вопроса и массив значений ответов. Он должен вернуть true в случае успешной валидации значения и false в случае ошибки. Текст ошибки возвращается посредством CMain::ThrowException(). В тексте ошибки можно использовать шаблон #FIELD_NAME# для получения названия поля, в котором произошла ошибка.

    Пример:

function DoValidate($arParams, $arQuestion, $arAnswers, $arValues)
{
  global $APPLICATION;

  foreach ($arValues as $value)
  {
    // пустые значения пропускаем
    if (strlen($value) <= 0) continue;

    // приведем значение к числу
    $value = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($value) : intval($value);

    // проверим нижний порог числа
    if (strlen($arParams["NUMBER_FROM"]) > 0 && $value < intval($arParams["NUMBER_FROM"]))
    {
      // вернем ошибку
      $APPLICATION->ThrowException("#FIELD_NAME#: слишком маленькое значение");
      return false;
    }

    // проверим верхний порог числа
    if (strlen($arParams["NUMBER_TO"]) > 0 && $value > intval($arParams["NUMBER_TO"]))
    {
      // вернем ошибку
      $APPLICATION->ThrowException("#FIELD_NAME#: слишком большое значение");
      return false;
    }
  }

  // все значения прошли валидацию, вернем true
  return true;
}

    Обратите внимание: при обработке значений полей перечислимых типов (dropdown, multiselect, radio, checkbox) валидатор получит на вход массив ID выбранных ответов.

    Интеграция валидатора

    Класс валидатора должен подключаться в любом месте, в котором он будет доступен из административной панели и в публичной части (подробнее см. порядок выполнения страниц), например, в /bitrix/php_interface/init.php. Непосредственно, файл валидатора может находиться где угодно, например, в /bitrix/php_interface/include/form/validators/. Подключение валидатора производится установкой описательной функции валидатора в качестве обработчика события onFormValidatorBuildList.

    Пример

    Подытожив все вышесказанное, сформируем валидатор. Класс валидатора расположим в файле /bitrix/php_interface/include/form/validators/val_num_ex.php

<?
// Листинг файла /bitrix/php_interface/include/form/validators/val_num_ex.php

// подключим модуль
CModule::IncludeModule("form");

class CFormCustomValidatorNumberEx
{
  function GetDescription()
  {
    return array(
      "NAME"            => "custom_number_ex",                                   // идентификатор
      "DESCRIPTION"     => "Число в промежутке",                                 // наименование
      "TYPES"           => array("text", "textarea"),                            // типы полей
      "SETTINGS"        => array("CFormCustomValidatorNumberEx", "GetSettings"), // метод, возвращающий массив настроек
      "CONVERT_TO_DB"   => array("CFormCustomValidatorNumberEx", "ToDB"),        // метод, конвертирующий массив настроек в строку
      "CONVERT_FROM_DB" => array("CFormCustomValidatorNumberEx", "FromDB"),      // метод, конвертирующий строку настроек в массив
      "HANDLER"         => array("CFormCustomValidatorNumberEx", "DoValidate")   // валидатор
    );
  }

  function GetSettings()
  {
    return array(
      "NUMBER_FROM" => array(
        "TITLE"   => "Нижний порог числа",
        "TYPE"    => "TEXT",
        "DEFAULT" => "0",
      ),

      "NUMBER_TO" => array(
        "TITLE"   => "Верхний порог числа",
        "TYPE"    => "TEXT",
        "DEFAULT" => "100",
      ),

      "NUMBER_FLOAT" => array(
        "TITLE"   => "Не только целое",
        "TYPE"    => "CHECKBOX",
        "DEFAULT" => "Y",
      ),
    );
  }

  function ToDB($arParams)
  {
    // проверка переданных параметров
    $arParams["NUMBER_FLOAT"] = $arParams["NUMBER_FLOAT"] == "Y" ? "Y" : "N";
    $arParams["NUMBER_FROM"]  = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_FROM"]) : intval($arParams["NUMBER_FROM"]);
    $arParams["NUMBER_TO"]    = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($arParams["NUMBER_TO"]) : intval($arParams["NUMBER_TO"]);

    // перестановка значений порогов, если требуется
    if ($arParams["NUMBER_FROM"] > $arParams["NUMBER_TO"])
    {
      $tmp                     = $arParams["NUMBER_FROM"];
      $arParams["NUMBER_FROM"] = $arParams["NUMBER_TO"];
      $arParams["NUMBER_TO"]   = $tmp;
    }

    // возвращаем сериализованную строку
    return serialize($arParams);
  }

  function FromDB($strParams)
  {
    // никаких преобразований не требуется, просто вернем десериализованный массив
    return unserialize($strParams);
  }

  function DoValidate($arParams, $arQuestion, $arAnswers, $arValues)
  {
    global $APPLICATION;

    foreach ($arValues as $value)
    {
      // пустые значения пропускаем
      if (strlen($value) <= 0) continue;

      // приведем значение к числу
      $value = $arParams["NUMBER_FLOAT"] == "Y" ? floatval($value) : intval($value);

      // проверим нижний порог числа
      if (strlen($arParams["NUMBER_FROM"]) > 0 && $value < intval($arParams["NUMBER_FROM"]))
      {
        // вернем ошибку
        $APPLICATION->ThrowException("#FIELD_NAME#: слишком маленькое значение");
        return false;
      }

      // проверим верхний порог числа
      if (strlen($arParams["NUMBER_TO"]) > 0 && $value > intval($arParams["NUMBER_TO"]))
      {
        // вернем ошибку
        $APPLICATION->ThrowException("#FIELD_NAME#: слишком большое значение");
        return false;
      }
    }

    // все значения прошли валидацию, вернем true
    return true;
  }
}

// установим метод CFormCustomValidatorNumberEx в качестве обработчика события
AddEventHandler("form", "onFormValidatorBuildList", array("CFormCustomValidatorNumberEx", "GetDescription"));
?>

    После этого остается только вставить в /bitrix/php_interface/init.php строку

    include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/include/form/validators/val_num_ex.php");

    См. также

  • Класс CFormValidator
  • События
  • AddEventHandler
    •


Создание собственных валидаторов полей веб-форм

Классы

  • CForm
  • CFormAnswer
  • CFormField
  • CFormOutput
  • CFormResult
  • CFormStatus
  • CFormValidator


Класс CForm

CForm - класс для работы с веб-формами.

Поля

Поле | Тип | Описание
ID | int | Идентификатор веб-формы.
SID | varchar(50) | Символьный идентификатор веб-формы.
TIMESTAMP_X | datetime | Время последнего изменения веб-формы.
NAME | varchar(255) | Заголовок веб-формы.
BUTTON | varchar(255) | Подпись на кнопки при заполнении веб-формы или редактировании результата.
C_SORT | int | Индекс сортировки.
IMAGE_ID | int | ID изображения веб-формы.
DESCRIPTION | varchar(2000) | Описание веб-формы.
DESCRIPTION_TYPE | varchar(4) | Тип описания веб-формы ("text" или "html").
MAIL_EVENT_TYPE | varchar(50) | Идентификатор типа почтового события.
FILTER_RESULT_TEMPLATE | varchar(2000) | Путь к скрипту, отображающему фильтр по результатам веб-форм в административной части модуля.
TABLE_RESULT_TEMPLATE | varchar(2000) | Путь к скрипту, отображающему таблицу результатов веб-форм в административной части модуля.
STAT_EVENT1 | varchar(255) | Идентификатор EVENT1 типа события для модуля "Статистика".
STAT_EVENT2 | varchar(255) | Идентификатор EVENT2 типа события для модуля "Статистика".
STAT_EVENT3 | varchar(255) | Дополнительный параметр события для модуля "Статистика".

Методы для работы с веб-формой

Метод | Описание
Set | Добавляет новую веб-форму, либо обновляет параметры существующей.
SetMailTemplate | Создает тип почтового события и почтовые шаблоны для веб-формы.
GetList | Возвращает список веб-форм.
GetByID | Возвращает параметры веб-формы по ее цифровому идентификатору.
GetBySID | Возвращает параметры веб-формы по ее символьному идентификатору.
GetDataByID | Возвращает массивы, описывающие вопросы и поля веб-формы.
GetResultAnswerArray | Возвращает массивы, описывающие вопросы и поля веб-формы, а также ответы и их значения.
GetPermission | Возвращает право пользователя на веб-форму.
Copy | Копирует веб-форму.
Reset | Удаляет все результаты веб-формы.
Delete | Удаляет веб-форму и все ее результаты.
Check | Проверяет введенные значения на обязательность, правильность формата даты и правильность типа файла.

Методы, возвращающие HTML код полей фильтра

Метод | Описание
GetTextFilter | Однострочное текстовое поле для фильтрации текстовых значений.
GetDateFilter | Два поля для ввода интервала дат.
GetDropDownFilter | Выпадающий список одиночного выбора.
GetNumberFilter | Два поля для ввода числового интервала.
GetExistFlagFilter | Флаг, используемый для фильтрации по факту существования ответа на вопрос.

Методы, возвращающие HTML код полей для ввода ответов на вопросы веб-формы

Метод | Описание
GetTextField | Однострочное текстовое поле для ввода текста.
GetTextAreaField | Многострочное текстовое поле для ввода текста.
GetPasswordField | Однострочное текстовое поле для ввода пароля.
GetDateField | Поле для ввода даты.
GetRadioField | Переключатель одиночного выбора.
GetCheckBoxField | Флаг множественного выбора.
GetDropDownField | Выпадающий список одиночного выбора.
GetMultiSelectField | Список множественного выбора.
GetFileField | Поле для ввода файла.

Методы получения текущего значения поля

Метод | Описание
GetTextValue | Возвращает текущее значение для однострочного текстового поля.
GetTextAreaValue | Возвращает текущее значение для многострочного текстового поля.
GetPasswordValue | Возвращает текущее значение для поля ввода пароля.
GetDateValue | Возвращает текущее значение для поля ввода даты.
GetRadioValue | Возвращает текущее значение для переключателя одиночного выбора.
GetCheckBoxValue | Возвращает текущее значение для флага множественного выбора.
GetDropDownValue | Возвращает текущее значение для выпадающего списка одиночного выбора.
GetMultiSelectValue | Возвращает текущее значение для списка множественного выбора.

Дополнительные методы

Метод | Описание
IsAdmin | Возвращает "true", если текущий пользователь имеет административные права на модуль Веб-формы, в противном случае - "false".


Check

CForm::Check

string
CForm::Check(
 int form_id,
 array values = false,
 int result_id = false,
 string check_rights = "Y",
 string return_array = "N"
)

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

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
values Массив значений введенных в веб-форме.
Параметр необязательный. По умолчанию - "false" (использовать стандартный массив $_REQUEST).

Пример:
Array
(
    [form_text_586] => Иванов Иван Иванович
    [form_date_587] => 10.03.1992
    [form_textarea_588] => г. Мурманск
    [form_radio_VS_MARRIED] => 589
    [form_checkbox_VS_INTEREST] => Array
        (
            [0] => 592
            [1] => 593
            [2] => 594
        )

    [form_dropdown_VS_AGE] => 597
    [form_multiselect_VS_EDUCATION] => Array
        (
            [0] => 603
            [1] => 604
        )

    [form_text_606] => 2345
    [form_image_607] => 1045
    [form_file_607] => 1049
)
result_id Если данная функция вызывается для проверки полей при редактировании результата, то в данном параметре необходимо указать его ID.
Параметр необязательный. По умолчанию - "false" (новый результат).
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для успешной проверки прав, производимой данной функцией, пользователь должен обладать как минимум правом [10] Заполнение формы на форму, указанную в параметре form_id.
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).
return_array Если данный параметр не установлен или равен "N", то функция возвращает отформатированный список ошибок.
Если же установлен в "Y", то функция возвращает массив, в котором сообщения об ошибках, связанные с конкретными полями, идут с ключом, равным строковому идентификатору поля, а остальные - с числовым ключом. Например,
array(
        0 => "Неверно введено слово с картинки",
        "test_fld" => "Не указано значение обязательных полей: Первое поле"
        )

См. также

  • CFormResult::Add
  • CFormResult::Update

Примеры использования

<?
// проверим корректность введенных параметров и
// права пользователя
$error = CForm::Check($FORM_ID, $_REQUEST, $RESULT_ID);

// если функция не вернула текст ошибки, то
if (strlen($error)<=0)
{
    // обновляем результат
    CFormResult::Update($RESULT_ID, $_REQUEST);
}
?>


Copy

CForm::Copy

mixed
CForm::Copy(
 int form_id,
 string check_rights = "Y"
)

Копирует веб-форму с ее вопросами, полями и статусами. Возвращает ID новой веб-формы в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр | Описание
form_id | ID формы.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для копирования веб-формы необходимо право [W] Полный доступ" на модуль "Веб-формы".
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CFormField::Copy
  • CFormAnswer::Copy
  • CFormStatus::Copy

Примеры использования

<?
$FORM_ID = 4;
// скопируем веб-форму
if ($NEW_FORM_ID=CForm::Copy($FORM_ID))
{
    echo "Веб-форма #4 успешно скопирована в новую веб-форму #".$NEW_FORM_ID;
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


Delete

CForm::Delete

bool
CForm::Delete(
 int form_id,
 string check_rights = "Y"
)

Удаляет веб-форму со всеми ее результатами. Возвращает "true" в случае положительного результата, и "false" - в противном случае.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для удаления веб-формы необходимо иметь право [W] Полный доступ на модуль "Веб-формы".
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CFormField::Delete
  • CFormAnswer::Delete
  • CFormStatus::Delete
  • CFormResult::Delete

Примеры использования

<?
$FORM_ID = 4;
// удалим веб-форму
if (CForm::Delete($FORM_ID))
{
    echo "Веб-форма #4 удалена.";
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


GetByID

CForm::GetByID

CDBResult
CForm::GetByID(
 int form_id
)

Возвращает параметры веб-формы в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.

См. также

  • Поля CForm
  • CForm::GetBySID
  • CForm::GetList

Примеры использования

<?
$FORM_ID = 2;
$rsForm = CForm::GetByID($FORM_ID);
$arForm = $rsForm->Fetch();
echo "<pre>"; print_r($arForm); echo "</pre";
?>


GetBySID

CForm::GetBySID

CDBResult
CForm::GetBySID(
 string form_sid
)

Возвращает параметры веб-формы в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
form_sid | Символьный идентификатор веб-формы.

См. также

  • Поля CForm
  • CForm::GetByID
  • CForm::GetList

Примеры использования

<?
$FORM_SID = "ANKETA";
$rsForm = CForm::GetBySID($FORM_SID);
$arForm = $rsForm->Fetch();
echo "<pre>"; print_r($arForm); echo "</pre";
?>


GetCheckBoxField

CForm::GetCheckBoxField

string
CForm::GetCheckBoxField(
 string question_sid,
 int answer_id,
 mixed value = "",
 string add_to_checkbox = "class=\"inputcheckbox\""
)

Возвращает HTML код флага множественного выбора (checkbox), предназначенного для выбора ответа типа "checkbox" на вопрос, символьный идентификатор которого передается в параметре question_sid.

Функция может использоваться как в форме содания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_checkbox_question_sid[]

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
answer_id | ID ответа.
value | Если в данном параметре будет передано значение, совпадающее с answer_id, то флаг множественного выбора будет отмечен (checked): <input type="checkbox" checked ...> Параметр необязательный. По умолчанию - "".
add_to_checkbox | Произвольный HTML, который будет добавлен в результирующий HTML тег флага множественного выбора: <input type="checkbox" add_to_checkbox ...> Необходимо учитывать, что если в данном параметре задать ключевое слово "checked", то данный переключатель будет выбран по умолчанию. Параметр необязательный. По умолчанию - "class=\"inputcheckbox\"".

См. также

  • CForm::GetCheckBoxValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Какие области знаний вас интересуют ?</td>
        <td><?

            /**********************************************************
                выводим два checkbox'а (математика/физика)
                как варианты ответа на вопрос
                "Какие области знаний вас интересуют ?"
            **********************************************************/

            $QUESTION_SID = "INTEREST"; // символьный идентификатор вопроса

            /***********************
              checkbox "математика"
            ***********************/

            // массив описывающий один checkbox
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 591,            // ID checkbox'а
                "FIELD_PARAM"   => "checked class=\"inputcheckbox\""   // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetCheckBoxValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем checkbox
            echo CForm::GetCheckBoxField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "математика<br>";

            /***********************
                checkbox "физика"
            ***********************/

            // массив описывающий один checkbox
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 593,       // ID checkbox'а
                "FIELD_PARAM"   => ""         // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetCheckBoxValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем checkbox
            echo CForm::GetCheckBoxField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "физика";
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetCheckBoxValue

CForm::GetCheckBoxValue

int
CForm::GetCheckBoxValue(
 string question_sid,
 array answer,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает ID ответа (answer["ID"]), в случае если он был выбран среди группы ответов типа "checkbox" на вопрос, символьный идентификатор которого указан в параметре question_sid.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет ID ответа (answer["ID"]), если он был установлен как ответ по умолчанию (ответом по умолчанию считаются те, у которых присутствует строка "checked" в answer["FIELD_PARAM"]).

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
answer Массив, описывающий параметры ответа, с обязательными ключами:
  • ID - ID ответа;
  • FIELD_PARAM - если значение этого ключа содержит слово "checked", то ID этого ответа будет возвращен данной функцией по умолчанию (т.е. при создании нового результата).
form_values Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML.

Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetCheckBoxField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Какие области знаний вас интересуют ?</td>
        <td><?

            /**********************************************************
                выводим два checkbox'а (математика/физика)
                как варианты ответа на вопрос
                "Какие области знаний вас интересуют ?"
            **********************************************************/

            $QUESTION_SID = "INTEREST"; // символьный идентификатор вопроса

            /***********************
              checkbox "математика"
            ***********************/

            // массив описывающий один checkbox
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 591,            // ID checkbox'а
                "FIELD_PARAM"   => "checked class=\"inputcheckbox\""   // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetCheckBoxValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем checkbox
            echo CForm::GetCheckBoxField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "математика<br>";

            /***********************
                checkbox "физика"
            ***********************/

            // массив описывающий один checkbox
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 593,       // ID checkbox'а
                "FIELD_PARAM"   => ""         // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetCheckBoxValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем checkbox
            echo CForm::GetCheckBoxField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "физика";
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetDataByID

CForm::GetDataByID

mixed
CForm::GetDataByID(
 int form_id,
 array &form,
 array &questions,
 array &answers,
 array &dropdown,
 array &multiselect,
 string get_fields = "Y"
)

Возвращает массивы, описывающие веб-форму, вопросы и поля для ответов. Сама функция возвращает ID веб-формы в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
form Массив, содержащий параметры формы. Ключи данного массива:
  • ID - ID веб-формы;
  • TIMESTAMP_X - дата изменения;
  • NAME - наименование;
  • SID - символьный идентификатор;
  • BUTTON - подпись к кнопке при редактировании результата или создании нового результата;
  • C_SORT - порядок сортировки;
  • IMAGE_ID - ID изображения;
  • DESCRIPTION - описание;
  • DESCRIPTION_TYPE - тип описания, допустимы следующие значения:
    • text - текст;
    • html - HTML код.
  • MAIL_EVENT_TYPE - идентификатор типа почтового события;
  • FILTER_RESULT_TEMPLATE - путь относительно корня к скрипту, отображающему фильтр по результатам веб-форм в административной части модуля;
  • TABLE_RESULT_TEMPLATE - путь относительно корня к скрипту, отображающему таблицу результатов веб-формы в административной части модуля;
  • STAT_EVENT1 - идентификатор event1 типа события для модуля "Статистика";
  • STAT_EVENT2 - идентификатор event2 типа события для модуля "Статистика";
  • STAT_EVENT3 - дополнительный параметр event3 события для модуля "Статистика";
  • QUESTIONS - количество вопросов формы;
  • C_FIELDS - количество полей формы;
  • STATUSES - количество статусов.
Пример:
Array
(
    [ID] => 4
    [TIMESTAMP_X] => 18.05.2005 12:17:05
    [NAME] => Анкета посетителя сайта
    [SID] => ANKETA
    [BUTTON] => Сохранить
    [C_SORT] => 300
    [IMAGE_ID] => 1053
    [DESCRIPTION] => Тестовая форма.
    [DESCRIPTION_TYPE] => text
    [MAIL_EVENT_TYPE] => FORM_FILLING_ANKETA
    [FILTER_RESULT_TEMPLATE] =>
    [TABLE_RESULT_TEMPLATE] =>
    [STAT_EVENT1] => form
    [STAT_EVENT2] => anketa
    [STAT_EVENT3] =>
    [C_FIELDS] => 1
    [QUESTIONS] => 6
    [STATUSES] => 4
)
questions Массив, содержащий вопросы и поля формы. Ключами данного массива являются идентификаторы вопросов/полей, а значениями - массивы, каждый из которых описывает один вопрос/поле.

Ключи массива, описывающего один вопрос/поле:
  • ID - ID вопроса/поля;
  • FORM_ID - ID формы;
  • TIMESTAMP_X - дата изменения вопроса/поля;
  • ACTIVE - флаг активности [Y|N];
  • TITLE - текст вопроса либо заголовок поля;
  • TITLE_TYPE - тип текста;
  • SID - символьный идентификатор вопроса/поля;
  • C_SORT - порядок сортировки;
  • ADDITIONAL - если Y - то данная запись является вопросом; если N - то полем формы;
  • REQUIRED - флаг обязательности ответа на вопрос [Y|N];
  • IN_FILTER - флаг, показывающий отражен ли вопрос/поле в фильтре формы результатов [Y|N];
  • IN_RESULTS_TABLE - флаг, показывающий отображается ли вопрос/поле в таблице результатов [Y|N];
  • IN_EXCEL_TABLE - флаг, показывающий отображается ли вопрос/поле в Excel-таблице результатов [Y|N];
  • FIELD_TYPE тип поля, возможны следующие значения:
    • text - текст;
    • integer - число;
    • date - дата.
  • IMAGE_ID - ID изображения в описании вопроса;
  • COMMENTS - служебный комментарий;
  • FILTER_TITLE - заголовок поля фильтра по данному вопросу/полю;
  • RESULTS_TABLE_TITLE - заголовок столбца таблицы результатов.
Пример:
Array
(
    [VS_NAME] => Array
        (
            [ID] => 140
            [FORM_ID] => 4
            [TIMESTAMP_X] => 28.08.2003 11:45:57
            [ACTIVE] => Y
            [TITLE] => Фамилия, имя, отчество
            [TITLE_TYPE] => html
            [SID] => VS_NAME
            [C_SORT] => 100
            [ADDITIONAL] => N
            [REQUIRED] => Y
            [IN_FILTER] => Y
            [IN_RESULTS_TABLE] => Y
            [IN_EXCEL_TABLE] => Y
            [FIELD_TYPE] =>
            [IMAGE_ID] =>
            [COMMENTS] =>
            [FILTER_TITLE] => ФИО
            [RESULTS_TABLE_TITLE] => ФИО
        )

    [VS_MARRIED] => Array
        (
            [ID] => 143
            [FORM_ID] => 4
            [TIMESTAMP_X] => 11.11.2004 18:13:21
            [ACTIVE] => Y
            [TITLE] => Вы женаты / замужем ?
            [TITLE_TYPE] => text
            [SID] => VS_MARRIED
            [C_SORT] => 400
            [ADDITIONAL] => N
            [REQUIRED] => Y
            [IN_FILTER] => Y
            [IN_RESULTS_TABLE] => Y
            [IN_EXCEL_TABLE] => Y
            [FIELD_TYPE] =>
            [IMAGE_ID] =>
            [COMMENTS] =>
            [FILTER_TITLE] => Семейный статус
            [RESULTS_TABLE_TITLE] => Семейный статус
        )
    ...
)
answers Массив, содержащие данные по полям для ответа на вопросы веб-формы. Ключами данного массива являются идентификаторы вопросов, а значениями - массивы, каждый из которых описывает набор полей для ответа на вопрос.

Структура массива, описывающего одно поле ответа:
  • ID - ID поля для ответа;
  • FIELD_ID - ID вопроса формы;
  • TIMESTAMP_X - дата изменения поля;
  • MESSAGE - текст [ANSWER_TEXT];
  • C_SORT - порядок сортировки;
  • ACTIVE - флаг активности [Y|N];
  • VALUE - значение [ANSWER_VALUE];
  • FIELD_TYPE - тип поля ответа, допустимы следующие значения:
    • text - однострочное текстовое поле;
    • textarea - многострочное текстовое поле;
    • radio - переключатель одиночного выбора;
    • checkbox - флаг множественного выбора;
    • dropdown - элемента выпадающего списка одиночного выбора;
    • multiselect - элемента списка множественного выбора;
    • date - поле для ввода дата в календарем;
    • image - поле для ввода изображения;
    • file - поле для ввода произвольного файла;
    • password - однострочное поле для ввода пароля.
  • FIELD_WIDTH - ширина поля ответа;
  • FIELD_HEIGHT - высота поля ответа;
  • FIELD_PARAM - параметры поля ответа.
Пример
Array
(
    [VS_NAME] => Array
        (
            [0] => Array
                (
                    [ID] => 586
                    [FIELD_ID] => 140
                    [TIMESTAMP_X] => 2003-08-28 11:45:57
                    [MESSAGE] =>
                    [C_SORT] => 100
                    [ACTIVE] => Y
                    [VALUE] =>
                    [FIELD_TYPE] => text
                    [FIELD_WIDTH] => 50
                    [FIELD_HEIGHT] => 0
                    [FIELD_PARAM] =>
                )

        )

    [VS_MARRIED] => Array
        (
            [0] => Array
                (
                    [ID] => 589
                    [FIELD_ID] => 143
                    [TIMESTAMP_X] => 2004-11-11 18:13:21
                    [MESSAGE] => да
                    [C_SORT] => 100
                    [ACTIVE] => Y
                    [VALUE] =>
                    [FIELD_TYPE] => radio
                    [FIELD_WIDTH] => 0
                    [FIELD_HEIGHT] => 0
                    [FIELD_PARAM] => SELECTED class="inputradio"
                )

            [1] => Array
                (
                    [ID] => 590
                    [FIELD_ID] => 143
                    [TIMESTAMP_X] => 2004-11-11 18:13:21
                    [MESSAGE] => нет
                    [C_SORT] => 200
                    [ACTIVE] => Y
                    [VALUE] =>
                    [FIELD_TYPE] => radio
                    [FIELD_WIDTH] => 0
                    [FIELD_HEIGHT] => 0
                    [FIELD_PARAM] =>
                )

        )
    ...
)
dropdown Массив, предназначенный для построения выпадающих списков одиночного выбора; содержит данные по всем полям ответа типа dropdown.

Пример:
Array
(
    [VS_AGE] => Array
        (
            [reference] => Array
                (
                    [0] => -
                    [1] => 10-19
                    [2] => 20-29
                    [3] => 30-39
                    [4] => 40-49
                    [5] => 50-59
                    [6] => 60 и старше
                )

            [reference_id] => Array
                (
                    [0] => 608
                    [1] => 596
                    [2] => 597
                    [3] => 598
                    [4] => 599
                    [5] => 600
                    [6] => 601
                )

            [param] => Array
                (
                    [0] => NOT_ANSWER
                    [1] =>
                    [2] => SELECTED
                    [3] =>
                    [4] =>
                    [5] =>
                    [6] =>
                )

        )
    ...
)
multiselect Массив, предназначенный для построения списков множественного выбора; содержит данные по всем полям для ответа типа multiselect.

Пример:
Array
(
    [VS_EDUCATION] => Array
        (
            [reference] => Array
                (
                    [0] => начальное
                    [1] => средне-специальное
                    [2] => высшее
                    [3] => ясли с отличием
                )

            [reference_id] => Array
                (
                    [0] => 602
                    [1] => 603
                    [2] => 604
                    [3] => 605
                )

            [param] => Array
                (
                    [0] =>
                    [1] =>
                    [2] => SELECTED
                    [3] =>
                )

        )
    ...
)
get_fields Если значение данного параметра равно "Y", то в массиве questionsбудут представлены только поля формы.
Если значение равно "" - вопросы и поля формы.
В остальных случаях - в массиве questionsбудут описаны только вопросы формы.

Параметр необязательный. По умолчанию - "N" (не добавлять в массив questionsданные о полях веб-формы).

См. также

  • CForm::GetResultAnswerArray

Примеры использования

<?
if (CForm::GetDataByID($FORM_ID,
    $form,
    $questions,
    $answers,
    $dropdown,
    $multiselect))
{
    echo "<pre>";
        print_r($form);
        print_r($questions);
        print_r($answers);
        print_r($dropdown);
        print_r($multiselect);
    echo "</pre>";
}
?>


GetDateField

CForm::GetDateField

string
CForm::GetDateField(
 int answer_id,
 string html_form_name,
 string value = "",
 mixed size = "",
 string add_to_text = "class=\"inputtext\""
)

Возвращает HTML код однострочного текстового поля. Данное поле предназначено для ввода ответа типа "date". В результирующий HTML код будет добавлена иконка, ведущая на страницу с календарем.

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля для ввода даты будет сформировано по следующей маске:
form_date_answer_id

Параметры функции

Параметр | Описание
answer_id | ID ответа.
html_form_name Имя HTML формы для создания нового результата или редактирования существующего.
<form name="html_form_name" ...>
Параметр необязательный. По умолчанию - "form1".
value Значение результирующего текстового поля:
<input type="text" value="value" ...>

Параметр необязательный. По умолчанию - "".
size Ширина результирующего текстового поля для ввода даты:
<input type="text" size="size" ...>

Параметр необязательный. По умолчанию - "".
add_to_text Произвольный HTML который будет добавлен в результирующий HTML тег текстового поля для ввода даты:
<input type="text" add_to_text ...>

Параметр необязательный. По умолчанию - "class=\"inputtext\"".

См. также

  • CForm::GetDateValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form name="ANKETA" action="" method="POST">
<table>
    <tr>
        <td>Дата рождения:</td>
        <td><?

            // массив описывающий поле для ввода даты
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 587,   // ID поля для ответа на вопрос "Дата рождения?"
                "VALUE"         => "",    // параметр ANSWER_VALUE (значение по умолчанию)
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetDateValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetDateField(
                $arAnswer["ID"],
                "ANKETA",
                $value,
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_PARAM"]
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetDateFilter

CForm::GetDateFilter

string
CForm::GetDateFilter(
 int filter_sid,
 string html_form_name = "form1",
 string show_dropdown = "Y",
 string add_to_dropdown = "class=\"inputselect\"",
 string add_to_text = "class=\"inputtext\""
)

Возвращает HTML код поля фильтра, предназначенного для фильтрации результатов по датам, введенным в качестве ответа на вопрос веб-формы, либо значений полей веб-формы типа "дата". Возвращаемый HTML код включает в себя два поля, предназначенных для ввода интервала дат, а также некоторые вспомогательные элементы (календарь, выпадающий список дней).

Примечание
Имена результирующих HTML полей будут сформированы по следующим маскам:
find_filter_sid_1 - первое поля интервала дат (с)
find_filter_sid_2 - второе поле интервала дат (по)

Параметры функции

Параметр Описание
filter_sid Идентификатор поля фильтра. Формируется по следующему шаблону:
FSID_QSID_USER_date,
где:
  • FSID - символьный идентификатор веб-формы;
  • QSID - символьный идентификатор вопроса/поля веб-формы.
Примеры:
  • ANKETA_USER_BIRTHDAY_USER_date
  • ANKETA_DATE_FIELD_USER_date
html_form_name Имя HTML формы, в которой выводится фильтр.
<form name="html_form_name" ...>

Параметр необязательный. По умолчанию - "form1".
show_dropdown Если значение "Y", то возвращаемый HTML код будет включать выпадающий список дней, предназначенный для облегчения выбора даты.

Параметр необязательный. По умолчанию - "Y" (вывести выпадающий список дней).
add_to_dropdown Если show_dropdown="Y", то в данном параметре можно указать произвольный HTML, который будет добавлен в тег выпадающего списка дней:
<select add_to_dropdown ...>

Параметр необязательный. По умолчанию - "class=\"inputselect\"".
add_to_text Произвольный HTML, который будет добавлен в теги однострочных текстовых полей, предназначенных для ввода даты:
<input type="text" add_to_text ...>

Параметр необязательный. По умолчанию - "class=\"inputtext\"".

См. также

  • CalendarPeriod
  • CForm::GetTextFilter
  • CForm::GetDropDownFilter
  • CForm::GetNumberFilter
  • CForm::GetExistFlagFilter

Примеры использования

<form name="form1" action="" method="POST">
<table>
    <tr>
        <td>Дата рождения:</td>
        <td><?
            echo CForm::GetDateFilter(
                "ANKETA_USER_BIRTHDAY_USER_date",
                "form1",
                "Y",
                "class=\"inputselect\"",
                "class=\"inputtext\""
                );
            ?></td>
    </tr>
</table>
<input type="submit" value="Фильтр">
</form>


GetDateValue

CForm::GetDateValue

string
CForm::GetDateValue(
 int answer_id,
 array answer,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает текущее значение ответа типа "date", ID которого передается в параметре answer_id.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет значение по умолчанию для данного ответа (т.е. то что задается в answer["VALUE"]).

Параметры функции

Параметр | Описание
answer_id | ID ответа.
answer | Массив, описывающий параметры ответа, обязательным элементом которого является элемент с ключом VALUE и значением, в котором содержится значение по умолчанию для ответа. Как правило, таким значением по умолчанию становится параметр ANSWER_VALUE ответа.
form_values | Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML. Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetDateField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form name="ANKETA" action="" method="POST">
<table>
    <tr>
        <td>Дата рождения:</td>
        <td><?

            // массив описывающий поле для ввода даты
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 587,   // ID поля для ответа на вопрос "Дата рождения?"
                "VALUE"         => "",    // параметр ANSWER_VALUE (значение по умолчанию)
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetDateValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetDateField(
                $arAnswer["ID"],
                "ANKETA",
                $value,
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_PARAM"]
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetDropDownField

CForm::GetDropDownField

string
CForm::GetDropDownField(
 string question_sid,
 array list,
 mixed value = "",
 string add_to_dropdown = "class=\"inputselect\""
)

Возвращает HTML код выпадающего списка одиночного выбора, предназначенного для выбора ответа из группы ответов типа "dropdown" на вопрос, символьный идентификатор которого передается в параметре question_sid.

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_dropdown_question_sid

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
list Массив ответов типа "dropdown" на вопрос question_sid. Минимально требуемая структура данного массива:
Array
(
    [reference] => Array
        (
            [0] => заголовок ответа 1
            [1] => заголовок ответа 2
            [2] => заголовок ответа 3
            ...
        )

    [reference_id] => Array
        (
            [0] => ID ответа 1
            [1] => ID ответа 2
            [2] => ID ответа 3
            ...
        )
)
В данном массиве под заголовком элемента понимается параметр ANSWER_TEXT ответа.
value Если в данном параметре будет передано значение совпадающее с ID ответа, то данный ответ будет выбран в результирующем выпадающем списке:
<option value="значение элемента" selected>заголовок ответа</option>

Параметр необязательный. По умолчанию - "".
add_to_dropdown Произвольный HTML который будет добавлен в результирующий HTML тег:
<select add_to_dropdown ...>

Параметр необязательный. По умолчанию - "class=\"inputselect\"".

См. также

  • CForm::GetDropDownValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>*Возраст:</td>
        <td><?

            // символьный идентификатор вопроса
            $QUESTION_SID = "AGE";

            // массив описывающий элементы выпадающего списка
            $arDropDown = array (

                "reference" => array (
                        "-",
                        "10-19",
                        "20-29",
                        "30-39",
                        "40-49",
                        "50-59",
                        "60 и старше"
                    ),

                "reference_id" => array (
                        608,
                        596,
                        597,
                        598,
                        599,
                        600,
                        601
                    ),

                "param" => array (
                        "not_answer class=\"inputselect\"", // не является ответом
                        "",
                        "checked", // значение по умолчанию
                        "",
                        "",
                        "",
                        ""
                    )
            );

            // получим текущее значение выпадающего списка
            $value = CForm::GetDropDownValue($QUESTION_SID, $arDropDown, $arrVALUES);

            // выведем выпадающий список
            echo CForm::GetDropDownField(
                $QUESTION_SID,           // символьный идентификатор вопроса
                $arDropDown,             // массив описывающий элементы списка
                $value,                  // значение выбранного элемента списка
                "class=\"inputselect\""  // стиль выпадающего списка
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetDropDownFilter

CForm::GetDropDownFilter

string
CForm::GetDropDownFilter(
 int field_id,
 string parameter_type,
 string filter_sid,
 string add_to_dropdown = "class=\"inputselect\""
)

Возвращает HTML код поля фильтра, представляющего из себя выпадающий список одиночного выбора. Данный выпадающий список может быть использован для фильтрации результатов по значению ответа на вопрос веб-формы. Значения этого выпадающего списка формируются из значений параметров ответов - ANSWER_TEXT или ANSWER_VALUE.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
find_filter_sid

Параметры функции

Параметр | Описание
field_id | ID вопроса/поля.
parameter_type Тип параметра ответа, допустимы следующие значения:
  • ANSWER_TEXT;
  • ANSWER_VALUE.
filter_sid Идентификатор поля фильтра. Формируется по следующему шаблону:
FSID_QSID_PTYPE_dropdown,
где:
  • FSID - символьный идентификатор веб-формы;
  • QSID - символьный идентификатор вопроса/поля веб-формы;
  • PTYPE - тип параметра ответа, задаваемый в parameter_type.
Примеры:
  • ANKETA_MARRIED_ANSWER_TEXT_dropdown;
  • ANKETA_CAR_ANSWER_VALUE_dropdown.
add_to_dropdown Произвольный HTML который будет добавлен в тег выпадающего списка:
<select add_to_dropdown ...>

Параметр необязательный. По умолчанию - "class=\"inputselect\"".

См. также

  • CForm::GetTextFilter
  • CForm::GetDateFilter
  • CForm::GetNumberFilter
  • CForm::GetExistFlagFilter

Примеры использования

<form name="form1" action="" method="POST">
<table>
    <tr>
        <td>Образование:</td>
        <td><?
            $FIELD_ID = 15; // ID вопроса "Ваше образование?"
            echo CForm::GetDropDownFilter(
                $FIELD_ID,
                "ANSWER_TEXT",
                "ANKETA_EDUCATION_ANSWER_TEXT_dropdown",
                "class=\"inputselect\""
                );
            ?></td>
    </tr>
</table>
<input type="submit" value="Фильтр">
</form>


GetDropDownValue

CForm::GetDropDownValue

int
CForm::GetDropDownValue(
 string question_sid,
 array answer_list,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает ID ответа, выбранного среди группы ответов типа "dropdown" на вопрос, символьный идентификатор которого указан в параметре question_sid.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет ID ответа выбранного по умолчанию. Поиск ответа по умолчанию осуществляется среди группы ответов, задаваемых в параметре answer_list, посредством поиска строки "checked" в answer_list["param"][i]; если такая строка будет найдена, то функция вернет ID данного ответа (хранимый в answer_list["reference_id"][i]).

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
answer_list Массив ответов типа "dropdown" на вопрос question_sid. Минимально требуемая структура данного массива:
Array
(
    [reference_id] => Array
        (
            [0] => ID ответа 1
            [1] => ID ответа 2
            [2] => ID ответа 3
            ...
        )

    [param] => Array
        (
            [0] => параметр ответа 1
            [1] => параметр ответа 2
            [2] => параметр ответа 3
            ...
        )
)
form_values Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML.

Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetDropDownField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>*Возраст:</td>
        <td><?

            // символьный идентификатор вопроса
            $QUESTION_SID = "AGE";

            // массив описывающий элементы выпадающего списка
            $arDropDown = array (

                "reference" => array (
                        "-",
                        "10-19",
                        "20-29",
                        "30-39",
                        "40-49",
                        "50-59",
                        "60 и старше"
                    ),

                "reference_id" => array (
                        608,
                        596,
                        597,
                        598,
                        599,
                        600,
                        601
                    ),

                "param" => array (
                        "not_answer class=\"inputselect\"", // не является ответом
                        "",
                        "checked", // значение по умолчанию
                        "",
                        "",
                        "",
                        ""
                    )
            );

            // получим текущее значение выпадающего списка
            $value = CForm::GetDropDownValue($QUESTION_SID, $arDropDown, $arrVALUES);

            // выведем выпадающий список
            echo CForm::GetDropDownField(
                $QUESTION_SID,           // символьный идентификатор вопроса
                $arDropDown,             // массив описывающий элементы списка
                $value,                  // значение выбранного элемента списка
                "class=\"inputselect\""  // стиль выпадающего списка
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetExistFlagFilter

CForm::GetExistFlagFilter

string
CForm::GetExistFlagFilter(
 int filter_sid,
 string add_to_checkbox = "class=\"inputcheckbox\""
)

Возвращает HTML код поля фильтра, предназначенного для фильтрации результатов по факту существования значения ответа на вопрос веб-формы или факту существования значения поля веб-формы. Возвращаемый HTML код включает в себя флаг множественного выбора (checkbox).

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
find_filter_sid

Параметры функции

Параметр Описание
filter_sid Идентификатор поля фильтра. Формируется по следующему шаблону:
FSID_QSID_PTYPE_exist,
где:
  • FSID - символьный идентификатор веб-формы;
  • QSID - символьный идентификатор вопроса/поля веб-формы;
  • PTYPE - тип параметра по которому будет фильтрация, возможны следующие значения:
    • ANSWER_TEXT - параметр ANSWER_TEXT вопроса веб-формы;
    • ANSWER_VALUE - параметр ANSWER_VALUE вопроса веб-формы;
    • USER - для вопроса веб-формы - вводимое с клавиатуры значение, для полей веб-формы - значение этого поля веб-формы.
Примеры:
  • ANKETA_USER_NAME_USER_text;
  • ANKETA_TEST_FIELD_USER_text.
add_to_checkbox Произвольный HTML который будет добавлен в тег флага выпадающего списка:
<input type="checkbox" add_to_checkbox ...>

Параметр необязательный. По умолчанию - "class=\"inputcheckbox\"".

См. также

  • CForm::GetDateFilter
  • CForm::GetDropDownFilter
  • CForm::GetNumberFilter
  • CForm::GetTextFilter

Примеры использования

<form action="" method="POST">
<table>
    <tr>
        <td>Есть фотография?</td>
        <td><?
            echo CForm::GetExistFlagFilter(
                "ANKETA_PHOTO_USER_exist",
                "class=\"inputcheckbox\""
                );
            ?></td>
    </tr>
</table>
<input type="submit" value="Фильтр">
</form>


GetFileField

CForm::GetFileField

string
CForm::GetFileField(
 int answer_id,
 mixed width = "",
 string file_type = "IMAGE",
 int max_file_size = 0,
 mixed file_id = "",
 string add_to_file = "class=\"inputfile\"",
 string add_to_checkbox = "class=\"inputcheckbox\"",
)

Возвращает HTML код поля для загрузки файла. Данное поле предназначено для ввода ответа типа "image" или "file".

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_file_type_answer_id

Параметры функции

Параметр | Описание
answer_id | ID ответа.
width Ширина результирующего поля для ввода файла:
<input type="file" size="width" ...>

Параметр необязательный. По умолчанию - "".
file_type Тип файла, допустимы следующие значения:
  • IMAGE - изображение;
  • FILE - произвольный файл.
Параметр необязательный. По умолчанию - "IMAGE" (изображение).
max_file_size Максимальный размер загружаемого файла (в байтах).

Параметр необязательный. По умолчанию - 0 (без ограничений).
file_id ID загруженного (редактируемого) файла.

Параметр необязательный. По умолчанию - "".
add_to_file Произвольный HTML, который будет добавлен в HTML тег поля для загрузки файла:
<input type="file" add_to_file ...>

Параметр необязательный. По умолчанию - "class=\"inputfile\"".
add_to_checkbox Произвольный HTML, который будет добавлен в HTML тег флага удаления редактируемого файла:
<input type="checkbox" add_to_checkbox ...>

Параметр необязательный. По умолчанию - "class=\"inputcheckbox\"".

См. также

  • CFormResult::GetFileByAnswerID
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Фотография:</td>
        <td><?

            /************************************************************
                                    Изображение
            ************************************************************/

            // массив описывающий поле ответа
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 607,   // ID поля для ответа на вопрос "Фотография"
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // попробуем получить параметры загруженного файла
            if ($arFile = CFormResult::GetFileByAnswerID($RESULT_ID, $arAnswer["ID"])):
                // если файл был получен то
                if (intval($arFile["USER_FILE_ID"])>0):
                    // если это изображение то
                    if ($arFile["USER_FILE_IS_IMAGE"]=="Y") :
                        // выведем изображение
                        echo CFile::ShowImage(
                            $arFile["USER_FILE_ID"],
                            0,
                            0,
                            "border=0",
                            "",
                            true);
                    endif;
                    echo "<br><br>";
                endif;
            endif;

            // выведем поле для ввода файла
            echo CForm::GetFileField(
                $arAnswer["ID"],
                $arAnswer["FIELD_WIDTH"],
                "IMAGE",
                0,  // максимальный размер файла не ограничен
                $arFile["USER_FILE_ID"],
                $arAnswer["FIELD_PARAM"]);

            ?></td>
    </tr>
    <tr>
        <td>Резюме:</td>
        <td><?

            /************************************************************
                                Произвольный файл
            ************************************************************/

            // массив описывающий поле ответа
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 610,   // ID поля для ответа на вопрос "Резюме"
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // попробуем получить параметры загруженного файла
            if ($arFile = CFormResult::GetFileByAnswerID($RESULT_ID, $arAnswer["ID"])):
                // если файл был получен то
                if (intval($arFile["USER_FILE_ID"])>0):

                    // выведем информацию о файле
                    ?>

                    <a title="Просмотр файла" target="_blank" class="tablebodylink" href="/bitrix/tools/form_show_file.php?rid=<?=$result_id?>&hash=<?echo $arFile["USER_FILE_HASH"]?>〈=<?=LANGUAGE_ID?>"><?=htmlspecialchars($arFile["USER_FILE_NAME"])?></a>
                    &nbsp;
                    (<?
                    $a = array("b", "Kb", "Mb", "Gb");
                    $pos = 0;
                    $size = $arFile["USER_FILE_SIZE"];
                    while($size>=1024) {$size /= 1024; $pos++;}
                    echo round($size,2)." ".$a[$pos];
                    ?>)
                    &nbsp;&nbsp;
                    [&nbsp;<a title="<?echo str_replace("#FILE_NAME#", $arFile["USER_FILE_NAME"], "Скачать")?>" class="tablebodylink" href="/bitrix/tools/form_show_file.php?rid=<?=$result_id?>&hash=<?echo $arFile["USER_FILE_HASH"]?>〈=<?=LANGUAGE_ID?>&action=download">Скачать</a>&nbsp;]
                    <br><br>

                    <?
                endif;
            endif;

            // выведем поле для ввода файла
            echo CForm::GetFileField(
                $arAnswer["ID"],
                $arAnswer["FIELD_WIDTH"],
                "FILE",
                0,  // максимальный размер файла не ограничен
                $arFile["USER_FILE_ID"],
                $arAnswer["FIELD_PARAM"]);

            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetList

CForm::GetList

CDBResult
CForm::GetList(
 string &by = "s_sort",
 string &order = "asc",
 array filter = array(),
 bool &is_filtered,
 int min_permission = 10
)

Возвращает список веб-форм в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
by Ссылка на переменную с полем для сортировки, может принимать значения:
  • s_id - ID веб-формы;
  • s_sort - индекс сортировки;
  • s_name - заголовок веб-формы;
  • s_sid - символьный идентификатор веб-формы.
оrder Ссылка на переменную с порядком сортировки, может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации. В массиве допустимы следующие ключи:
  • ID* - ID веб-формы (по умолчанию будет искаться точное совпадение);
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SID* - символьный идентификатор веб-формы (по умолчанию будет искаться точное совпадение);
  • SID_EXACT_MATCH - если значение равно "N", то при фильтрации по SID будет искаться вхождение;
  • NAME* - заголовок веб-формы (по умолчанию будет искаться вхождение);
  • NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по NAME будет искаться точное совпадение;
  • DESCRIPTION* - описание веб-формы (по умолчанию будет искаться вхождение);
  • DESCRIPTION_EXACT_MATCH - если значение равно "Y", то при фильтрации по DESCRIPTION будет искаться точное совпадение;
  • SITE* - идентификатор сайта или массив идентификаторов сайтов, к которым приписана веб-форма (по умолчанию будет искаться точное совпадение);
  • SITE_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE будет искаться вхождение.
* - допускается сложная логика
is_filtered | Ссылка на переменную, хранящую флаг отфильтрованности списка веб-форм. Если значение равно "true", то список был отфильтрован.
min_permission Минимальный уровень прав на веб-форму.

Параметр необязательный. По умолчанию - 10 (право на заполнение веб-формы и создание нового результата)

См. также

  • Поля CForm
  • Права на веб-форму
  • CForm::GetByID
  • CForm::GetBySID

Примеры использования

<?
// сформируем массив фильтра
$arFilter = Array(
 "ID"                      => "1 | 2",          // ID=1 либо ID=2
 "ID_EXACT_MATCH"          => "Y",              // точное совпадение по ID
 "NAME"                    => "Анкета",         // в заголовке веб-формы есть слово "Анкета"
 "NAME_EXACT_MATCH"        => "N",              // не точное совпадение по NAME
 "SID"                     => "ANKETA",         // символьный идентификатор равен ANEKTA
 "SID_EXACT_MATCH"         => "Y",              // точное совпадение по SID
 "DESCRIPTION"             => "заполните",      // в описании есть слово "заполните"
 "DESCRIPTION_EXACT_MATCH" => "N",              // не точное совпадение по DESCRIPTION
 "SITE"                    => array("r1", "e2") // веб-форма приписана и к сайтам r1, e2
);

// получим список всех форм у которых у текущего пользователя есть право на заполнение
$rsForms = CForm::GetList($by="s_id", $order="desc", $arFilter, $is_filtered);
while ($arForm = $rsForms->Fetch())
{
    echo "<pre>"; print_r($arForm); echo "</pre>";
}
?>


GetMultiSelectField

CForm::GetMultiSelectField

string
CForm::GetMultiSelectField(
 string question_sid,
 array list,
 array values = array(),
 mixed height = "",
 string add_to_multiselect = "class=\"inputselect\""
)

Возвращает HTML код списка множественного выбора, предназначенного для выбора ответов из группы ответов типа "multiselect" на вопрос, символьный идентификатор которого передается в параметре question_sid.

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_multiselect_question_sid[]

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
list Массив ответов типа "multiselect" на вопрос question_sid. Минимально требуемая структура данного массива:
Array
(
    [reference] => array
        (
            [0] => заголовок ответа 1
            [1] => заголовок ответа 2
            [2] => заголовок ответа 3
            ...
        )

    [reference_id] => array
        (
            [0] => ID ответа 1
            [1] => ID ответа 2
            [2] => ID ответа 3
            ...
        )
)
В данном массиве под заголовком ответа понимается параметр ANSWER_TEXT ответа.
values Если в данном параметре будет передан массив со значениями, совпадающими с ID ответов, данные ответы будут выбраны (выделены) в результирующем списке:
<option value="значение элемента" selected>заголовок элемента</option>

Параметр необязательный. По умолчанию - array() (пустой массив).
height Высота результирующего списка множественного выбора:
<select multiple size="height" ...>

Параметр необязательный. По умолчанию - "class=\"inputselect\"".
add_to_multiselect Произвольный HTML, который будет добавлен в результирующий HTML тег:
<select add_to_multiselect ...>

Параметр необязательный. По умолчанию - "class=\"inputselect\"".

См. также

  • CForm::GetMultiSelectValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
  // используем данные пришедшие с формы
  $arrVALUES = $_REQUEST;
}
else
{
  // сформируем этот массив из данных по результату
  $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
  <tr>
    <td>Ваше образование:</td>
    <td><?

      // символьный идентификатор вопроса
      $QUESTION_SID = "EDUCATION";

      // массив описывающий элементы списка множественного выбора
      $arMultiSelect = array (

        "reference" => array (
            "начальное",
            "средне-специальное",
            "высшее",
          ),

        "reference_id" => array (
            602,
            603,
            604,
          ),

        "param" => array (
            "",
            "",
            "checked", // значение по умолчанию
          )
      );

      // получим текущее значение выпадающего списка
      $arValues = CForm::GetMultiSelectValue($QUESTION_SID, $arMultiSelect, $arrVALUES);

      // выведем список множественного выбора
      echo CForm::GetMultiSelectField(
        $QUESTION_SID,           // символьный идентификатор вопроса
        $arMultiSelect,          // массив описывающий элементы списка
        $arValues,               // значения выбранных элементов списка
        10,                      // высота списка
        "class=\"inputselect\""  // стиль списка
        );
      ?></td>
  </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetMultiSelectValue

CForm::GetMultiSelectValue

array
CForm::GetMultiSelectValue(
 string question_sid,
 array answer_list,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает массив ID ответов, выбранных среди группы ответов типа "multiselect" на вопрос, символьный идентификатор которого указан в параметре question_sid.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет массив ID ответов, выбранных по умолчанию. Поиск ответа по умолчанию осуществляется среди группы ответов, задаваемых в параметре answer_list, посредством поиска строки "checked" в answer_list["param"][i]; если такая строка будет найдена, то функция добавит данный ID ответа (хранимый в answer_list["reference_id"][i]) в результирующий массив.

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
answer_list Массив ответов типа "multiselect" на вопрос question_sid. Минимально требуемая структура данного массива:
Array
(
    [reference_id] => Array
        (
            [0] => ID ответа 1
            [1] => ID ответа 2
            [2] => ID ответа 3
            ...
        )

    [param] => Array
        (
            [0] => параметр ответа 1
            [1] => параметр ответа 2
            [2] => параметр ответа 3
            ...
        )
)
form_values Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML.

Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetMultiSelectField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
  // используем данные пришедшие с формы
  $arrVALUES = $_REQUEST;
}
else
{
  // сформируем этот массив из данных по результату
  $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
  <tr>
    <td>Ваше образование:</td>
    <td><?

      // символьный идентификатор вопроса
      $QUESTION_SID = "EDUCATION";

      // массив описывающий элементы списка множественного выбора
      $arMultiSelect = array (

        "reference" => array (
            "начальное",
            "средне-специальное",
            "высшее",
          ),

        "reference_id" => array (
            602,
            603,
            604,
          ),

        "param" => array (
            "",
            "",
            "checked", // значение по умолчанию
          )
      );

      // получим текущее значение выпадающего списка
      $arValues = CForm::GetMultiSelectValue($QUESTION_SID, $arMultiSelect, $arrVALUES);

      // выведем список множественного выбора
      echo CForm::GetMultiSelectField(
        $QUESTION_SID,           // символьный идентификатор вопроса
        $arMultiSelect,          // массив описывающий элементы списка
        $arValues,               // значения выбранных элементов списка
        10,                      // высота списка
        "class=\"inputselect\""  // стиль списка
        );
      ?></td>
  </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetNumberFilter

CForm::GetNumberFilter

string
CForm::GetNumberFilter(
 int filter_sid,
 int size = "10",
 string add_to_text = "class=\"inputtext\""
)

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

Примечание
Имена результирующих HTML полей будут сформированы по следующим маскам:
find_filter_sid_1 - первое поля числового интервала (с)
find_filter_sid_2 - второе поле числового интервала (по)

Параметры функции

Параметр Описание
filter_sid Идентификатор поля фильтра. Формируется по следующему шаблону:
FSID_QSID_PTYPE_integer,
где:
  • FSID - символьный идентификатор веб-формы,
  • QSID - символьный идентификатор вопроса/поля веб-формы;
  • PTYPE - тип параметра, по которому будет фильтрация, возможны следующие значения:
    • ANSWER_TEXT - параметр ANSWER_TEXT вопроса веб-формы;
    • ANSWER_VALUE - параметр ANSWER_VALUE вопроса веб-формы;
    • USER - для вопроса веб-формы - вводимое с клавиатуры значение, для полей веб-формы - значение этого поля веб-формы.
Примеры:
  • ANKETA_AGE_USER_integer;
  • ANKETA_CAR_POWER_ANSWER_VALUE_integer.
size Ширина однострочного текстового поля:
<input type="text" size="size" ...>

Параметр необязательный. По умолчанию - "10".
add_to_text Произвольный HTML, который будет добавлен в теги однострочных текстовых полей, в которых вводится дата:
<input type="text" add_to_text ...>

Параметр необязательный. По умолчанию - "class=\"inputtext\"".

См. также

  • CalendarPeriod
  • CForm::GetTextFilter
  • CForm::GetDropDownFilter
  • CForm::GetDateFilter
  • CForm::GetExistFlagFilter

Примеры использования

<form name="form1" action="" method="POST">
<table>
    <tr>
        <td>Возраст:</td>
        <td><?
            echo CForm::GetNumberFilter(
                "ANKETA_AGE_USER_integer",
                "10",
                "class=\"inputtext\""
                );
            ?></td>
    </tr>
</table>
<input type="submit" value="Фильтр">
</form>


GetPasswordField

CForm::GetPasswordField

string
CForm::GetPasswordField(
 int answer_id,
 string value = "",
 mixed size = "",
 string add_to_text = "class=\"inputtext\""
)

Возвращает HTML код однострочного текстового поля. Данное поле предназначено для ввода ответа типа "password".

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_password_answer_id

Параметры функции

Параметр | Описание
answer_id | ID ответа.
value | Значение результирующего текстового поля: <input type="password" value="value" ...> Параметр необязательный. По умолчанию - "".
size | Ширина результирующего текстового поля: <input type="password" size="size" ...> Параметр необязательный. По умолчанию - "".
add_to_text | Произвольный HTML, который будет добавлен в результирующий HTML тег текстового поля: <input type="password" add_to_text ...> Параметр необязательный. По умолчанию - "class=\"inputtext\"".

См. также

  • CForm::GetPasswordValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Пароль:</td>
        <td><?

            // массив описывающий поле для ввода пароля
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 609,   // ID поля для ответа на вопрос "Пароль"
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetPasswordValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetPasswordField(
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_PARAM"]
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetPasswordValue

CForm::GetPasswordValue

string
CForm::GetPasswordValue(
 int answer_id,
 array answer,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает текущее значение ответа типа "password", ID которого передается в параметре answer_id.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет значение по умолчанию для данного ответа (т.е. то что задается в answer["VALUE"]).

Параметры функции

Параметр | Описание
answer_id | ID ответа.
answer | Массив, описывающий параметры ответа, обязательным элементом которого является элемент с ключом VALUE и значением, в котором содержится значение по умолчанию для ответа. Как правило, таким значением по умолчанию становится параметр ANSWER_VALUE ответа.
form_values | Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML. Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetPasswordField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Пароль:</td>
        <td><?

            // массив описывающий поле для ввода пароля
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 609,   // ID поля для ответа на вопрос "Пароль"
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetPasswordValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetPasswordField(
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_PARAM"]
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetPermission

CForm::GetPermission

int
CForm::GetPermission(
 int form_id,
 array groups = false,
 string from_db = ""
)

Возвращает право доступа к веб-форме:

  • 1 - доступ закрыт (форма и ее результаты полностью недоступны);
  • 10 - заполнение формы (посетитель может только заполнить и сохранить форму);
  • 15 - редактирование своего результата (посетитель получает возможность видеть список своих результатов, который он может фильтровать и сортировать; также посетитель может просмотреть, изменить и удалить свой результат);
  • 20 - просмотр всех результатов (посетитель получает возможность просмотра всех активных результатов);
  • 25 - редактирование всех результатов и просмотр настроек формы (посетитель получает возможность просмотра и редактирования всех результатов в зависимости от их статусов; также, если у него открыт доступ к административной части модуля, доступ на просмотр настроек формы);
  • 30 - полный доступ (включает в себя все вышеописанные права, а также право на изменение настроек формы).

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
groups | Массив ID групп пользователей, для которых нужно определить право доступа. Параметр необязательный. По умолчанию - "false" (группы текущего пользователя).
from_db | Если значение равно "Y", право доступа определяется без учета значения по умолчанию, устанавливаемого в настройках модуля Веб-формы.

См. также

  • Права на веб-форму
  • CFormStatus::GetPermissions
  • CFormStatus::GetPermissionList
  • CFormResult::GetPermissions

Примеры использования

<?
$FORM_ID = 4;
// получим права текущего пользователя
$permission = CForm::GetPermission($FORM_ID);
if ($permission==10) echo "У вас есть право на заполнение веб-формы";
?>


GetRadioField

CForm::GetRadioField

string
CForm::GetRadioField(
 string question_sid,
 int answer_id,
 mixed value = "",
 string add_to_radio = "class=\"inputradio\""
)

Возвращает HTML код переключателя одиночного выбора (radio-кнопка), предназначенного для выбора ответа типа "radio" на вопрос, символьный идентификатор которого передается в параметре question_sid.

Функция может использоваться как в форме содания нового результата, так и в форме редактирования существующего.

Имя результирующего HTML поля будет сформировано по следующей маске: form_radio_question_sid

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
answer_id | ID ответа.
value | Если в данном параметре будет передано значение совпадающее с answer_id, то переключатель одиночного выбора будет выбран (checked): <input type="radio" checked ...> Параметр необязательный. По умолчанию - "".
add_to_radio | Произвольный HTML который будет добавлен в результирующий HTML тег переключателя одиночного выбора: <input type="radio" add_to_radio ...> Необходимо учитывать что если в данном параметре задать ключевое слово "checked", то данный переключатель будет выбран по умолчанию. Параметр необязательный. По умолчанию - "class=\"inputradio\"".

См. также

  • CForm::GetRadioValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Вы курите?</td>
        <td><?

            /**********************************************************
                выводим две radio-кнопки (да/нет)
                как варианты ответа на вопрос "Вы курите?"
            **********************************************************/

            $QUESTION_SID = "SMOKE"; // символьный идентификатор вопроса

            /***********************
                radio-кнопка "да"
            ***********************/

            // массив описывающий одну radio-кнопку
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 589,    // ID radio-кнопки
                "FIELD_PARAM"   => "checked class=\"inputradio\""   // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetRadioValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем radio-кнопку
            echo CForm::GetRadioField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "да <br>";

            /***********************
                radio-кнопка "нет"
            ***********************/

            // массив описывающий одну radio-кнопку
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 590,    // ID radio-кнопки
                "FIELD_PARAM"   => ""      // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetRadioValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем radio-кнопку
            echo CForm::GetRadioField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "нет";
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetRadioValue

CForm::GetRadioValue

int
CForm::GetRadioValue(
 string question_sid,
 array answer,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает ID ответа, выбранного среди группы ответов типа "radio" на вопрос, символьный идентификатор которого указан в параметре question_sid.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет ID ответа (answer["ID"]), если он был установлен как ответ по умолчанию (ответами по умолчанию считаются те, у которых присутствует строка "checked" в answer["FIELD_PARAM"]).

Параметры функции

Параметр | Описание
question_sid | Символьный идентификатор вопроса.
answer Массив описывающий параметры ответа, с обязательными ключами:
  • ID - ID ответа;
  • FIELD_PARAM - если значение этого ключа содержит слово "checked", то ID этого ответа будет возвращен данной функцией по умолчанию (т.е. при создании нового результата).
form_values Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML.

Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetRadioField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Вы курите?</td>
        <td><?

            /**********************************************************
                выводим две radio-кнопки (да/нет)
                как варианты ответа на вопрос "Вы курите?"
            **********************************************************/

            $QUESTION_SID = "SMOKE"; // символьный идентификатор вопроса

            /***********************
                radio-кнопка "да"
            ***********************/

            // массив описывающий одну radio-кнопку
            $arAnswer = array(
                "ID"            => 589,    // ID radio-кнопки
                "FIELD_PARAM"   => "checked class=\"inputradio\""   // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetRadioValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем radio-кнопку
            echo CForm::GetRadioField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "да <br>";

            /***********************
                radio-кнопка "нет"
            ***********************/

            // массив описывающий одну radio-кнопку
            $arAnswer = array(
                "ID"            => 590,    // ID radio-кнопки
                "FIELD_PARAM"   => ""      // параметр ответа
                );

            // получим текущее значение
            $value = CForm::GetRadioValue($QUESTION_SID, $arAnswer, $arrVALUES);

            // выведем radio-кнопку
            echo CForm::GetRadioField(
                $QUESTION_SID,
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_PARAM"]
                );
            echo "нет";
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetResultAnswerArray

CForm::GetResultAnswerArray

CForm::GetResultAnswerArray(
 int form_id,
 array &columns,
 array &answers,
 array &answers2 = array(),
 array filter = array(),
)

Возвращает массивы, описывающие вопросы и поля веб-формы, а также ответы на вопросы.

Параметры функции

Параметр | Описание
form_id | ID формы.
columns Массив, описывающий те вопросы и поля формы, которые:
  1. активны;
  2. включены в таблицу результатов.
Ключами данного массива являются ID вопросов/полей, а значениями - массив, описывающий сам вопрос/поле, в свою очередь, имеющий следующие ключи:
  • ID - ID вопроса/поля;
  • FORM_ID - ID формы;
  • TIMESTAMP_X - дата изменения вопроса/поля;
  • ACTIVE - флаг активности [Y|N];
  • TITLE - текст вопроса, либо заголовок поля;
  • TITLE_TYPE - тип текста;
  • SID - символьный идентификатор вопроса/поля;
  • C_SORT - порядок сортировки;
  • ADDITIONAL - если Y - то данная запись является вопросом; если N - то полем формы;
  • REQUIRED - флаг обязательности ответа на вопрос [Y|N];
  • IN_FILTER - флаг показывающий отражен ли вопрос/поле в фильтре формы результатов [Y|N];
  • IN_RESULTS_TABLE - флаг показывающий отображается ли вопрос/поле в таблице результатов [Y|N];
  • IN_EXCEL_TABLE - флаг показывающий отображается ли вопрос/поле в Excel-таблице результатов [Y|N];
  • FIELD_TYPE тип поля, возможны следующие значения:
    • text - текст;
    • integer - число;
    • date - дата.
  • IMAGE_ID - ID изображения в описании вопроса;
  • COMMENTS - служебный комментарий;
  • FILTER_TITLE - заголовок поля фильтра по данному вопросу/полю;
  • RESULTS_TABLE_TITLE - заголовок столбца таблицы результатов.
Пример:
Array
(
    [140] => Array
        (
            [ID] => 140
            [FORM_ID] => 4
            [TIMESTAMP_X] => 19.05.2005 11:42:04
            [ACTIVE] => Y
            [TITLE] => Фамилия, имя, отчество
            [TITLE_TYPE] => html
            [SID] => VS_NAME
            [C_SORT] => 100
            [ADDITIONAL] => N
            [REQUIRED] => Y
            [IN_FILTER] => Y
            [IN_RESULTS_TABLE] => N
            [IN_EXCEL_TABLE] => N
            [FIELD_TYPE] =>
            [IMAGE_ID] =>
            [COMMENTS] =>
            [FILTER_TITLE] =>
            [RESULTS_TABLE_TITLE] =>
        )

    [144] => Array
        (
            [ID] => 144
            [FORM_ID] => 4
            [TIMESTAMP_X] => 11.11.2004 18:11:21
            [ACTIVE] => Y
            [TITLE] => Какие области знаний вас интересуют ?
            [TITLE_TYPE] => text
            [SID] => VS_INTEREST
            [C_SORT] => 500
            [ADDITIONAL] => N
            [REQUIRED] => N
            [IN_FILTER] => Y
            [IN_RESULTS_TABLE] => Y
            [IN_EXCEL_TABLE] => Y
            [FIELD_TYPE] =>
            [IMAGE_ID] =>
            [COMMENTS] =>
            [FILTER_TITLE] =>
            [RESULTS_TABLE_TITLE] =>
        )
    ...
)
answers Массив, содержащий ответы на вопросы формы, а также значения полей формы. Ключами данного массива являются:
  • RESULT_ID - ID результата;
  • FIELD_ID - ID вопроса/поля;
  • SID - символьный идентификатор вопроса/поля;
  • TITLE - текст вопроса или заголовок поля веб-формы;
  • TITLE_TYPE - тип текста вопроса, допустимы следующие значения:
    • text - текст;
    • html - HTML код.
  • FILTER_TITLE - подпись поля фильтра по данному вопросу/полю;
  • RESULTS_TABLE_TITLE - подпись столбца таблицы результатов;
  • ANSWER_ID - ID ответа;
  • ANSWER_TEXT - параметр ответа ANSWER_TEXT, записанный в таблицу результата;
  • MESSAGE - параметр ответа ANSWER_TEXT, хранящийся в таблице ответов (синоним ключа ANSWER_TEXT);
  • ANSWER_VALUE - параметр ответа ANSWER_VALUE, записанный в таблицу результата;
  • VALUE - параметр ответа ANSWER_VALUE, хранящийся в таблице ответов (синоним ключа ANSWER_VALUE);
  • USER_TEXT - текстовое значение, введенное пользователем;
  • USER_DATE - дата, введенная пользователем (данный ключ может содержать значение, только если FIELD_TYPE="date");
  • USER_FILE_ID - ID файла загруженного пользователем (данный ключ может содержать значение, только если FIELD_TYPE="image" или FIELD_TYPE="file");
  • USER_FILE_NAME - оригинальное имя загруженного файла (данный ключ может содержать значение, только если FIELD_TYPE="image" или FIELD_TYPE="file");
  • USER_FILE_IS_IMAGE - "Y" - если FIELD_TYPE="image", "N" - если FIELD_TYPE="file"
  • USER_FILE_HASH - уникальный хеш, используемый при показе файла (данный ключ может содержать значение, только если FIELD_TYPE="file");
  • USER_FILE_SUFFIX - суффикс к расширению загруженного файла (данный ключ может содержать значение, только если FIELD_TYPE="file");
  • USER_FILE_SIZE - размер файла в байтах (данный ключ может содержать значение, только если FIELD_TYPE="image" или FIELD_TYPE="file");
  • FIELD_TYPE - тип поля ответа, возможны следующие значения:
    • text - однострочное текстовое поле;
    • textarea - многострочное текстовое поле;
    • radio - переключатель одиночного выбора;
    • checkbox - флаг множественного выбора;
    • dropdown - элемента выпадающего списка одиночного выбора;
    • multiselect - элемента списка множественного выбора;
    • date - поле для ввода дата в календарем;
    • image - поле для ввода изображения;
    • file - поле для ввода произвольного файла;
    • password - однострочное поле для ввода пароля.
  • FIELD_WIDTH - ширина поля ответа;
  • FIELD_HEIGHT - высота поля ответа;
  • FIELD_PARAM - параметры поля ответа.
Пример:
Array
(
    [186] => Array
        (
            [140] => Array
                (
                    [586] => Array
                        (
                            [RESULT_ID] => 186
                            [FIELD_ID] => 140
                            [SID] => VS_NAME
                            [TITLE] => Фамилия, имя, отчество
                            [TITLE_TYPE] => html
                            [FILTER_TITLE] =>
                            [RESULTS_TABLE_TITLE] =>
                            [ANSWER_ID] => 586
                            [ANSWER_TEXT] =>
                            [MESSAGE] =>
                            [ANSWER_VALUE] =>
                            [VALUE] =>
                            [USER_TEXT] => Иванов Дмитрий Витальевич
                            [USER_DATE] =>
                            [USER_FILE_ID] =>
                            [USER_FILE_NAME] =>
                            [USER_FILE_IS_IMAGE] =>
                            [USER_FILE_HASH] =>
                            [USER_FILE_SUFFIX] =>
                            [USER_FILE_SIZE] =>
                            [FIELD_TYPE] => text
                            [FIELD_WIDTH] => 50
                            [FIELD_HEIGHT] => 0
                            [FIELD_PARAM] =>
                        )
                )

            [144] => Array
                (
                    [594] => Array
                        (
                            [RESULT_ID] => 186
                            [FIELD_ID] => 144
                            [SID] => VS_INTEREST
                            [TITLE] => Какие области знаний вас интересуют ?
                            [TITLE_TYPE] => text
                            [FILTER_TITLE] =>
                            [RESULTS_TABLE_TITLE] =>
                            [ANSWER_ID] => 594
                            [ANSWER_TEXT] => иностранные языки
                            [MESSAGE] => иностранные языки
                            [ANSWER_VALUE] => 4
                            [VALUE] => 4
                            [USER_TEXT] =>
                            [USER_DATE] =>
                            [USER_FILE_ID] =>
                            [USER_FILE_NAME] =>
                            [USER_FILE_IS_IMAGE] =>
                            [USER_FILE_HASH] =>
                            [USER_FILE_SUFFIX] =>
                            [USER_FILE_SIZE] =>
                            [FIELD_TYPE] => checkbox
                            [FIELD_WIDTH] => 0
                            [FIELD_HEIGHT] => 0
                            [FIELD_PARAM] =>
                        )

                    [595] => Array
                        (
                            [RESULT_ID] => 186
                            [FIELD_ID] => 144
                            [SID] => VS_INTEREST
                            [TITLE] => Какие области знаний вас интересуют ?
                            [TITLE_TYPE] => text
                            [FILTER_TITLE] =>
                            [RESULTS_TABLE_TITLE] =>
                            [ANSWER_ID] => 595
                            [ANSWER_TEXT] => програмирование
                            [MESSAGE] => програмирование
                            [ANSWER_VALUE] => 5
                            [VALUE] => 5
                            [USER_TEXT] =>
                            [USER_DATE] =>
                            [USER_FILE_ID] =>
                            [USER_FILE_NAME] =>
                            [USER_FILE_IS_IMAGE] =>
                            [USER_FILE_HASH] =>
                            [USER_FILE_SUFFIX] =>
                            [USER_FILE_SIZE] =>
                            [FIELD_TYPE] => checkbox
                            [FIELD_WIDTH] => 0
                            [FIELD_HEIGHT] => 0
                            [FIELD_PARAM] => SELECTED class=inputcheckbox
                        )
                )
            ...
        )
    ...
)
answers2 Массив, содержащий, по сути, те же данные, что и массив answers, но имеющий несколько другую структуру.

Пример:
Array
(
    [186] => Array
        (
            [VS_NAME] => Array
                (
                    [0] => Array
                        (
                            [RESULT_ID] => 186
                            [FIELD_ID] => 140
                            [SID] => VS_NAME
                            [TITLE] => Фамилия, имя, отчество
                            [TITLE_TYPE] => html
                            [FILTER_TITLE] =>
                            [RESULTS_TABLE_TITLE] =>
                            [ANSWER_ID] => 586
                            [ANSWER_TEXT] =>
                            [MESSAGE] =>
                            [ANSWER_VALUE] =>
                            [VALUE] =>
                            [USER_TEXT] => Иванов Дмитрий Витальевич
                            [USER_DATE] =>
                            [USER_FILE_ID] =>
                            [USER_FILE_NAME] =>
                            [USER_FILE_IS_IMAGE] =>
                            [USER_FILE_HASH] =>
                            [USER_FILE_SUFFIX] =>
                            [USER_FILE_SIZE] =>
                            [FIELD_TYPE] => text
                            [FIELD_WIDTH] => 50
                            [FIELD_HEIGHT] => 0
                            [FIELD_PARAM] =>
                        )

                )

           [VS_INTEREST] => Array
                (
                    [0] => Array
                        (
                            [RESULT_ID] => 186
                            [FIELD_ID] => 144
                            [SID] => VS_INTEREST
                            [TITLE] => Какие области знаний вас интересуют ?
                            [TITLE_TYPE] => text
                            [FILTER_TITLE] =>
                            [RESULTS_TABLE_TITLE] =>
                            [ANSWER_ID] => 594
                            [ANSWER_TEXT] => иностранные языки
                            [MESSAGE] => иностранные языки
                            [ANSWER_VALUE] => 4
                            [VALUE] => 4
                            [USER_TEXT] =>
                            [USER_DATE] =>
                            [USER_FILE_ID] =>
                            [USER_FILE_NAME] =>
                            [USER_FILE_IS_IMAGE] =>
                            [USER_FILE_HASH] =>
                            [USER_FILE_SUFFIX] =>
                            [USER_FILE_SIZE] =>
                            [FIELD_TYPE] => checkbox
                            [FIELD_WIDTH] => 0
                            [FIELD_HEIGHT] => 0
                            [FIELD_PARAM] =>
                        )

                    [1] => Array
                        (
                            [RESULT_ID] => 186
                            [FIELD_ID] => 144
                            [SID] => VS_INTEREST
                            [TITLE] => Какие области знаний вас интересуют ?
                            [TITLE_TYPE] => text
                            [FILTER_TITLE] =>
                            [RESULTS_TABLE_TITLE] =>
                            [ANSWER_ID] => 595
                            [ANSWER_TEXT] => програмирование
                            [MESSAGE] => програмирование
                            [ANSWER_VALUE] => 5
                            [VALUE] => 5
                            [USER_TEXT] =>
                            [USER_DATE] =>
                            [USER_FILE_ID] =>
                            [USER_FILE_NAME] =>
                            [USER_FILE_IS_IMAGE] =>
                            [USER_FILE_HASH] =>
                            [USER_FILE_SUFFIX] =>
                            [USER_FILE_SIZE] =>
                            [FIELD_TYPE] => checkbox
                            [FIELD_WIDTH] => 0
                            [FIELD_HEIGHT] => 0
                            [FIELD_PARAM] => SELECTED class=inputcheckbox
                        )
                )
            ...
        )
    ...
)
filter

 Массив для фильтрации выбираемых значений. В массиве допустимы следующие ключи:
  • RESULT_ID* - ID результата (по умолчанию будет искаться точное совпадение);
  • RESULT_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по RESULT_ID будет искаться вхождение;
  • FIELD_ID* - ID вопроса/поля (по умолчанию будет искаться точное совпадение);
  • FIELD_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по FIELD_ID будет искаться вхождение;
  • FIELD_SID* - символьный код вопроса/поля (по умолчанию будет искаться вхождение);
  • FIELD_SID_EXACT_MATCH - если значение равно "Y", то при фильтрации по FIELD_SID будет искаться точное совпадение;
  • IN_RESULTS_TABLE - если значение равно "Y", то ответы на вопрос (либо значения поля веб-формы) будет отображены в таблице результатов;
  • IN_EXCEL_TABLE - если значение равно "Y", то ответы на вопрос (либо значения поля веб-формы) будет отображены в Excel таблице результатов.
* - допускается сложная логика.

См. также

  • CFormResult::GetDataByID
  • CFormField::GetList
  • CFormAnswer::GetList

Примеры использования

// получим данные по результату ID=145
CForm::GetResultAnswerArray($FORM_ID,
    $arrColumns,
    $arrAnswers,
    $arrAnswersVarname,
    array("RESULT_ID" => "145"));

echo "<pre>";
echo "arrColumns:";
print_r($arrColumns);
echo "arrAnswers:";
print_r($arrAnswers);
echo "arrAnswersVarname:";
print_r($arrAnswersVarname);
echo "</pre>";


GetTextAreaField

CForm::GetTextAreaField

string
CForm::GetTextAreaField(
 int answer_id,
 int cols = "",
 int rows = "",
 string add_to_textarea = "class=\"inputtextarea\""
 string value = "",
)

Возвращает HTML код многострочного текстового поля. Данное поле предназначено для ввода ответа типа "textarea".

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_textarea_answer_id

Параметры функции

Параметр | Описание
answer_id | ID ответа.
cols | Ширина результирующего многострочного текстового поля: <textarea cols="cols" ...> Параметр необязательный. По умолчанию - "".
rows | Высота результирующего многострочного текстового поля: <textarea rows="rows" ...> Параметр необязательный. По умолчанию - "".
add_to_textarea | Произвольный HTML, который будет добавлен в результирующий тег многострочного текстового поля: <textarea add_to_textarea ...> Параметр необязательный. По умолчанию - "class=\"inputtextarea\"".
value | Значение результирующего многострочного текстового поля: <textarea ...>value</textarea> Параметр необязательный. По умолчанию - "".

См. также

  • CForm::GetTextAreaValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Адрес:</td>
        <td><?

            // массив описыващий многострочное текстовое поле
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 588,   // ID поля для ответа на вопрос "Ваш адрес?"
                "VALUE"         => "",    // параметр ANSWER_VALUE (значение по умолчанию)
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_HEIGHT"  => 5,     // высота поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetTextAreaValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetTextAreaField(
                $arAnswer["ID"],
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_HEIGHT"],
                $arAnswer["FIELD_PARAM"],
                $value
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetTextAreaValue

CForm::GetTextAreaValue

string
CForm::GetTextAreaValue(
 int answer_id,
 array answer,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает текущее значение ответа типа "textarea", ID которого передается в параметре answer_id.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет значение по умолчанию для данного ответа (т.е. то что задается в answer["VALUE"]).

Параметры функции

Параметр | Описание
answer_id | ID ответа.
answer | Массив, описывающий параметры ответа, обязательным элементом которого является элемент с ключом VALUE и значением, в котором содержится значение по умолчанию для ответа. Как правило, таким значением по умолчанию становится параметр ANSWER_VALUE ответа.
form_values | Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML. Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetTextAreaField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Адрес:</td>
        <td><?

            // массив описыващий многострочное текстовое поле
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 588,   // ID поля для ответа на вопрос "Ваш адрес?"
                "VALUE"         => "",    // параметр ANSWER_VALUE (значение по умолчанию)
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_HEIGHT"  => 5,     // высота поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetTextAreaValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetTextAreaField(
                $arAnswer["ID"],
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_HEIGHT"],
                $arAnswer["FIELD_PARAM"],
                $value
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetTextField

CForm::GetTextField

string
CForm::GetTextField(
 int answer_id,
 string value = "",
 mixed size = "",
 string add_to_text = "class=\"inputtext\""
)

Возвращает HTML код однострочного текстового поля. Данное поле предназначено для ввода ответа типа "text".

Функция может использоваться как в форме создания нового результата, так и в форме редактирования существующего.

Примечание
Имя результирующего HTML поля будет сформировано по следующей маске:
form_text_answer_id

Параметры функции

Параметр | Описание
answer_id | ID ответа.
value | Значение результирующего текстового поля: <input type="text" value="value" ...> Параметр необязательный. По умолчанию - "".
size | Ширина результирующего текстового поля: <input type="text" size="size" ...> Параметр необязательный. По умолчанию - "".
add_to_text | Произвольный HTML, который будет добавлен в результирующий HTML тег текстового поля: <input type="text" add_to_text ...> Параметр необязательный. По умолчанию - "class=\"inputtext\"".

См. также

  • CForm::GetTextValue
  • Имена HTML полей

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Фамилия:</td>
        <td><?

            // массив описывающий однострочное текстовое поле
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 586,   // ID поля для ответа на вопрос "Ваша фамилия?"
                "VALUE"         => "",    // параметр ANSWER_VALUE (значение по умолчанию)
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetTextValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetTextField(
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_PARAM"]
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


GetTextFilter

CForm::GetTextFilter

string
CForm::GetTextFilter(
 int filter_sid,
 int size = 45,
 string add_to_text = "class=\"inputtext\"",
 string add_to_checkbox = "class=\"inputcheckbox\""
)

Возвращает HTML код поля фильтра, предназначенного для фильтрации результатов по текстовым значениям ответов на вопросы веб-формы или текстовым значениям полей веб-формы. Возвращаемый HTML код включает в себя однострочное текстовое поле и флаг для установки точности фильтрации.

Примечание
Имена результирующих HTML полей будут сформированы по следующим маскам:
find_filter_sid - однострочное текстовое поля
find_filter_sid_exact_match - флаг для установки точности фильтрации

Параметры функции

Параметр Описание
filter_sid Идентификатор поля фильтра. Формируется по следующему шаблону:
FSID_QSID_PTYPE_text,
где:
  • FSID - символьный идентификатор веб-формы;
  • QSID - символьный идентификатор вопроса/поля веб-формы;
  • PTYPE - тип параметра по которому будет фильтрация, возможны следующие значения:
    • ANSWER_TEXT - параметр ANSWER_TEXT вопроса веб-формы;
    • ANSWER_VALUE - параметр ANSWER_VALUE вопроса веб-формы;
    • USER - для вопроса веб-формы - вводимое с клавиатуры значение, для полей веб-формы - значение этого поля веб-формы.
Примеры:
  • ANKETA_USER_NAME_USER_text;
  • ANKETA_TEST_FIELD_USER_text.
size Ширина однострочного текстового поля:
<input type="text" size="size" ...>

Параметр необязательный. По умолчанию - "45".
add_to_text Произвольный HTML, который будет добавлен в тег однострочного текстового поля:
<input type="text" add_to_text ...>

Параметр необязательный. По умолчанию - "class=\"inputtext\"".
add_to_checkbox Произвольный HTML, который будет добавлен в тег флага для установки точности фильтрации:
<input type="checkbox" add_to_checkbox ...>

Параметр необязательный. По умолчанию - "class=\"inputcheckbox\"".

См. также

  • CForm::GetDateFilter
  • CForm::GetDropDownFilter
  • CForm::GetNumberFilter
  • CForm::GetExistFlagFilter

Примеры использования

<form action="" method="POST">
<table>
    <tr>
        <td>Фамилия:</td>
        <td><?
            echo CForm::GetTextFilter(
                "ANKETA_USER_NAME_USER_text",
                45,
                "class=\"inputtext\"",
                "class=\"inputcheckbox\""
                );
            ?></td>
    </tr>
</table>
<input type="submit" value="Фильтр">
</form>


GetTextValue

CForm::GetTextValue

string
CForm::GetTextValue(
 int answer_id,
 array answer,
 mixed form_values = false
)

Если массив, переданный в параметре form_values, инициализирован (например, в момент редактирования результата), то функция возвращает текущее значение ответа типа "text", ID которого передается в параметре answer_id.

Если массив, переданный в параметре form_values, не инициализирован (например, в момент создания нового результата), то функция вернет значение по умолчанию для данного ответа (т.е. то что задается в answer["VALUE"]).

Параметры функции

Параметр | Описание
answer_id | ID ответа.
answer | Массив, описывающий параметры ответа, обязательным элементом которого является элемент с ключом VALUE и со значением в котором содержится значение по умолчанию для ответа. Как правило таким значением по умолчанию становится параметр ANSWER_VALUE ответа.
form_values | Ассоциированный массив значений, пришедших с веб-формы при создании нового или редактировании существующего результата (стандартный массив $_REQUEST). Данный массив может быть также получен с помощью функции CFormResult::GetDataByIDForHTML. Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::GetTextField

Примеры использования

<?
/*******************************************
       Редактирование результата
*******************************************/

$RESULT_ID = 12; // ID результата

// если была нажата кнопка "Сохранить" то
if (strlen($_REQUEST["save"])>0)
{
    // используем данные пришедшие с формы
    $arrVALUES = $_REQUEST;
}
else
{
    // сформируем этот массив из данных по результату
    $arrVALUES = CFormResult::GetDataByIDForHTML($RESULT_ID);
}
?>
<form action="" method="POST">
<table>
    <tr>
        <td>Фамилия:</td>
        <td><?

            // массив описывающий однострочное текстовое поле
            // содержит минимально-необходимые поля
            $arAnswer = array(
                "ID"            => 586,   // ID поля для ответа на вопрос "Ваша фамилия?"
                "VALUE"         => "",    // параметр ANSWER_VALUE (значение по умолчанию)
                "FIELD_WIDTH"   => 10,    // ширина поля
                "FIELD_PARAM"   => ""     // параметры поля
                );

            // получим текущее значение
            $value = CForm::GetTextValue($arAnswer["ID"], $arAnswer, $arrVALUES);

            // выведем поле
            echo CForm::GetTextField(
                $arAnswer["ID"],
                $value,
                $arAnswer["FIELD_WIDTH"],
                $arAnswer["FIELD_PARAM"]
                );
            ?></td>
    </tr>
</table>
<input type="submit" name="save" value="Сохранить">
</form>


IsAdmin

CForm::IsAdmin

bool
CForm::IsAdmin()

Возвращает "true", если текущий пользователь имеет административные права на модуль Веб-формы, в противном случае - "false".

Параметры функции

Без параметров.

См. также

  • Права на модуль

Примеры использования

<?
if (CForm::IsAdmin())
{
    echo "У вас административные права на модуль Веб-форм.";
}
?>


Reset

CForm::Reset

bool
CForm::Reset(
 int form_id,
 string check_rights = "Y"
)

Удаляет все результаты веб-формы. Возвращает "true" в случае положительного результата, и "false" - в противном случае.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для удаления всех результатов веб-формы необходимо иметь право [30] Полный доступ на форму, указанную в параметре form_id.

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CFormField::Reset
  • CFormResult::Reset

Примеры использования

<?
$FORM_ID = 4;
// удалим результаты веб-формы
if (CForm::Reset($FORM_ID))
{
    echo "Результаты веб-формы #4 удалены.";
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


Set

CForm::Set

mixed
CForm::Set(
 array fields,
 mixed form_id = false,
 string check_rights = "Y"
)

Добавляет новую веб-форму или обновляет заданную. Возвращает ID обновленной или добавленной веб-формы в случае положительного результата, в противном случае - "false".

Примечание
При обновлении существующей веб-формы (или при добавлении новой веб-формы), автоматически обновляется тип почтового события (либо создаётся новый тип).

Параметры функции

Параметр Описание
fields Массив значений полей; в качестве ключей массива допустимы:
  • NAME* - заголовок веб-формы;
  • SID* - символьный идентификатор веб-формы;
  • C_SORT - индекс сортировки;
  • BUTTON - подпись к кнопке при создании или редактировании результата;
  • DESCRIPTION - описание;
  • DESCRIPTION_TYPE - тип описания, допустимы следующие значения:
    • text - текст;
    • html - HTML код.
  • FILTER_RESULT_TEMPLATE - путь относительно корня к файлу, который будет использован для показа фильтра результатов в административной части модуля;
  • TABLE_RESULT_TEMPLATE - путь относительно корня к файлу, который будет использован для показа таблицы результатов в административной части модуля;
  • STAT_EVENT1 - идентификатор EVENT1 типа события для модуля "Статистика";
  • STAT_EVENT2 - идентификатор EVENT2 типа события для модуля "Статистика";
  • STAT_EVENT3 - дополнительный параметр события для модуля "Статистика";
  • arIMAGE - массив, описывающий изображение веб-формы, допустимы следующие ключи этого массива:
    • name - имя файла;
    • size - размер файла;
    • tmp_name - временный путь на сервере;
    • type - тип загружаемого файла;
    • del - если значение равно "Y", то изображение будет удалено;
    • MODULE_ID - идентификатор модуля "Веб-формы" ("form").
  • arSITE - массив идентификаторов сайтов, к которым будет привязана данная форма:
    array("ID_САЙТА_1", "ID_САЙТА_2", ...)
  • arMAIL_TEMPLATE - массив ID почтовых шаблонов, приписанных к данной форме:
    array("ID_ШАБЛОНА_1", "ID_ШАБЛОНА_2", ...)
  • arMENU - массив заголовков меню, отображаемого в административной части и ведущего на результаты данной формы:
    array("ID_ЯЗЫКА_1" => "МЕНЮ_1", "ID_ЯЗЫКА_2" => "МЕНЮ_2", ...)
  • arGROUP - массив, описывающий права групп пользователей на данную веб-форму:
    array("ID_ГРУППЫ_1" => "ПРАВО_1", "ID_ГРУППЫ_2" => "ПРАВО_2", ...)
* - обязательно к заполнению.
form_id ID обновляемой веб-формы.

Параметр необязательный. По умолчанию - "false" (добавление новой веб-формы).
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для обновления параметров веб-формы необходимо иметь право [30] Полный доступ на форму, указанную в параметре form_id. Для добавления новой веб-формы необходимо иметь право [W] Полный доступ на модуль Веб-формы.

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • Поля CForm
  • Права на веб-форму
  • CFile::MakeFileArray

Примеры использования

<?
/*************************************************
             Добавление веб-формы
*************************************************/

// создадим массив описывающий изображение
// находящееся в файле на сервере
$arIMAGE = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/web_form.gif");
$arIMAGE["MODULE_ID"] = "form";

$arFields = array(
    "NAME"              => "Анкета посетителя",
    "SID"               => "VISITOR_FORM",
    "C_SORT"            => 300,
    "BUTTON"            => "Сохранить",
    "DESCRIPTION"       => "Заполните пож-та анкету",
    "DESCRIPTION_TYPE"  => "text",
    "STAT_EVENT1"       => "form",
    "STAT_EVENT2"       => "visitor_form",
    "arSITE"            => array("r1"),
    "arMENU"            => array("ru" => "Анкета посетителя", "en" => "Visitor Form"),
    "arGROUP"           => array("2" => "15", "3" => "20"),
    "arIMAGE"           => $arIMAGE
    );

// добавим новую веб-форму
$NEW_ID = CForm::Set($arFields);
if ($NEW_ID>0) echo "Добавлена веб-форма с ID=".$NEW_ID;
else // ошибка
{
    // выводим текст ошибки
    global $strError;
    echo $strError;
}
?>

<?
// пример обновления веб-формы параметры которой были визуально
// отредактированы в административной части

$w = CGroup::GetList($v1, $v2, Array("ADMIN"=>"N"), $v3);
$arGroups = array();
while ($wr=$w->Fetch()) $arGroups[] = array("ID"=>$wr["ID"], "NAME"=>$wr["NAME"]);

$z = CLanguage::GetList($v1, $v2, array("ACTIVE" => "Y"));
$arFormMenuLang = array();
while ($zr=$z->Fetch()) $arFormMenuLang[] = array("LID"=>$zr["LID"], "NAME"=>$zr["NAME"]);

$rs = CSite::GetList(($by="sort"), ($order="asc"));
while ($ar = $rs->Fetch())
{
    if ($ar["DEF"]=="Y") $def_site_id = $ar["ID"];
    $arrSites[$ar["ID"]] = $ar;
}

if ((strlen($save)>0 || strlen($apply)>0) && $REQUEST_METHOD=="POST")
{
    $arIMAGE_ID = $HTTP_POST_FILES["IMAGE_ID"];
    $arIMAGE_ID["MODULE_ID"] = "form";
    $arIMAGE_ID["del"] = ${"IMAGE_ID_del"};
    $arFields = array(
        "NAME"                      => $NAME,
        "SID"                       => $SID,
        "C_SORT"                    => $C_SORT,
        "BUTTON"                    => $BUTTON,
        "DESCRIPTION"               => $DESCRIPTION,
        "DESCRIPTION_TYPE"          => $DESCRIPTION_TYPE,
        "FILTER_RESULT_TEMPLATE"    => $FILTER_RESULT_TEMPLATE,
        "TABLE_RESULT_TEMPLATE"     => $TABLE_RESULT_TEMPLATE,
        "STAT_EVENT1"               => $STAT_EVENT1,
        "STAT_EVENT2"               => $STAT_EVENT2,
        "STAT_EVENT3"               => $STAT_EVENT3,
        "arIMAGE"                   => $arIMAGE_ID,
        "arSITE"                    => $arSITE,
        "arMAIL_TEMPLATE"           => $arMAIL_TEMPLATE
        );

    // меню
    $arMENU = array();
    reset($arFormMenuLang);
    while (list(,$arrL)=each($arFormMenuLang))
    {
        $var = "MENU_".$arrL["LID"];
        global $$var;
        $arMENU[$arrL["LID"]] = $$var;
    }
    $arFields["arMENU"] = $arMENU;

    // права доступа
    $arGROUP = array();
    reset($arGroups);
    while (list(,$arrG)=each($arGroups))
    {
        $var = "PERMISSION_".$arrG["ID"];
        global $$var;
        $arGROUP[$arrG["ID"]] = $$var;
    }
    $arFields["arGROUP"] = $arGROUP;

    if ($ID = CForm::Set($arFields, $ID))
    {
        if (strlen($strError)<=0)
        {
            if (strlen($save)>0) LocalRedirect("form_list.php?lang=".LANGUAGE_ID);
            else LocalRedirect("form_edit.php?ID=".$ID."〈=".LANGUAGE_ID);
        }
    }
    $DB->PrepareFields("b_form");
}
?>


SetMailTemplate

CForm::SetMailTemplate

array
CForm::SetMailTemplate(
 int form_id,
 string add_template = "Y",
 string old_form_sid = ""
)

Создает или обновляет тип почтового события для веб-формы. При необходимости могут быть созданы почтовые шаблоны. Функция возвращает массив идентификаторов новых почтовых шаблонов, если они были созданы.

Примечание
При создании нового типа почтового события, символьный идентификатор этого типа задается в виде FORM_FILLING_символьный ID веб-формы.

Параметры функции

Параметр | Описание
form_id | ID веб-формы, для которой необходимо создать или обновить тип почтового события.
add_template | Если значение равно "Y", то будут созданы почтовые шаблоны для обновленного или вновь созданного типа почтового события. Параметр необязательный. По умолчанию - "Y" (создать почтовые шаблоны).
old_form_sid | Если в данном параметре будет задан символьный идентификатор веб-формы, то все почтовые шаблоны, принадлежащие этой веб-форме, будут приписаны к вновь созданному типу почтового события. Данный параметр используется, как правило, при редактировании веб-формы в момент смены символьного идентификатора. Параметр необязательный. По умолчанию - "" (не приписывать почтовые шаблоны к новому типу почтового события).

См. также

  • Почтовая система
  • CForm::Set

Примеры использования

<?
// добавляем для веб-формы новый типа почтового события
// при этом создаем почтовые шаблоны

$arTemplates = CForm::SetMailTemplate($FORM_ID);

// приписываем вновь созданные почтовые шаблоны данной веб-форме

CForm::Set(array("arMAIL_TEMPLATE" = $arTemplates), $FORM_ID);
?>


Класс CFormAnswer

CFormAnswer - класс для работы с ответами.

Поля

Поле | Тип | Описание
ID | int | Идентификатор ответа.
FIELD_ID | int | Идентификатор вопроса (синоним данного поля - QUESTION_ID).
TIMESTAMP_X | datetime | Время последнего изменения параметров ответа.
MESSAGE | varchar(2000) | Значение параметра ответа ANSWER_TEXT.
VALUE | varchar(255) | Значение параметра ответа ANSWER_VALUE.
FIELD_TYPE varchar(255) Тип поля ответа, допустимы следующие значения:
  • text - однострочное текстовое поле;
  • textarea - многострочное текстовое поле;
  • radio - переключатель одиночного выбора (radio-кнопка);
  • checkbox - флаг множественного выбора (checkbox);
  • dropdown - элемент выпадающего списка одиночного выбора;
  • multiselect - элемент списка множественного выбора;
  • date - поле для ввода даты;
  • image - поле для загрузки изображения;
  • file - поле для загрузки произвольного файла;
  • password - поле для ввода пароля.
FIELD_WIDTH | int | Ширина поля ответа.
FIELD_HEIGHT | int | Высота поля ответа.
FIELD_PARAM | varchar(2000) | Параметры поля ответа.
C_SORT | int | Индекс сортировки.
ACTIVE | char | Флаг активности (Y|N).

Методы

Метод | Описание
Set | Добавляет новый ответ, либо обновляет параметры существующего.
GetList | Возвращает список ответов по указанному вопросу.
GetByID | Возвращает параметры ответа.
Copy | Копирует ответ.
Delete | Удаляет ответ и все значения в результатах, связанные с данным ответом.


Copy

CFormAnswer::Copy

mixed
CFormAnswer::Copy(
 int answer_id,
 mixed question_id = false
)

Копирует ответ. Возвращает ID нового ответа в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр | Описание
answer_id | ID ответа который необходимо скопировать.
question_id | ID вопроса, в который необходимо скопировать ответ. Необязательный параметр. По умолчанию - "false" (текущий вопрос).

См. также

  • CForm::Copy
  • CFormField::Copy
  • CFormStatus::Copy

Примеры использования

<?
$answer_id = 589; // ID ответа "да" на вопрос "Вы женаты/замужем?"
// скопируем ответа
if ($NEW_ANSWER_ID = CFormAnswer::Copy($answer_id))
{
    echo "Ответ #589 успешно скопирован в новый ответ #".$NEW_ANSWER_ID;
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


Delete

CFormAnswer::Delete

bool
CFormAnswer::Delete(
 int answer_id,
 int question_id = false,
)

Удаляет ответ и все значения в результатах, связанные с ним. Возвращает "true" в случае положительного результата, и "false" - в противном случае.

Параметры функции

Параметр | Описание
answer_id | ID удаляемого ответа.
question_id | ID вопроса, к которому приписан удаляемый ответ. Указание данного параметра позволяет ускорить выполнение функции. Параметр необязательный. По умолчанию - "false".

См. также

  • CForm::Delete
  • CFormField::Delete
  • CFormStatus::Delete
  • CFormResult::Delete

Примеры использования

<?
$answer_id = 589; // ID ответа
// удалим ответ
if (CFormAnswer::Delete($answer_id))
{
    echo "Ответ #589 удален.";
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


GetByID

CFormAnswer::GetByID

CDBResult
CFormAnswer::GetByID(
 int answer_id
)

Возвращает параметры ответа в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
answer_id | ID ответа.

См. также

  • Поля CFormAnswer
  • CFormAnswer::GetList

Примеры использования

<?
$answer_id = 589; // ID ответа
$rsAnswer = CFormAnswer::GetByID($answer_id);
$arAnswer = $rsAnswer->Fetch();
echo "<pre>"; print_r($arAnswer); echo "</pre";
?>


GetList

CFormAnswer::GetList

CDBResult
CFormAnswer::GetList(
 int question_id,
 string &by = "s_sort",
 string &order = "asc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список ответов в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
question_id | ID вопроса.
by Ссылка на переменную с полем для сортировки результирующего списка. Может принимать значения:
  • s_id - ID ответа;
  • s_sort - индекс сортировки.
оrder Ссылка на переменную с порядком сортировки. Может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации. В массиве допустимы следующие ключи:
  • ID* - ID ответа (по умолчанию будет искаться точное совпадение);
  • ID_EXACT_MATCH - если значение равно "N", при фильтрации по ID будет искаться вхождение;
  • ACTIVE - флаг активности, допустимые следующие значения:
    • Y - ответ активен;
    • N - ответ не активен.
  • MESSAGE* - параметр ANSWER_TEXT (по умолчанию будет искаться вхождение);
  • MESSAGE_EXACT_MATCH - если значение равно "Y", при фильтрации по MESSAGE будет искаться точное совпадение;
  • VALUE* - параметр ANSWER_VALUE (по умолчанию будет искаться вхождение);
  • VALUE_EXACT_MATCH - если значение равно "Y", то при фильтрации по VALUE будет искаться точное совпадение;
  • FIELD_TYPE* - тип поля ответа (по умолчанию будет искаться вхождение);
  • FIELD_TYPE_EXACT_MATCH - если значение равно "Y", при фильтрации по FIELD_TYPE будет искаться точное совпадение;
  • FIELD_PARAM* - параметр поля ответа (по умолчанию будет искаться вхождение);
  • FIELD_PARAM_EXACT_MATCH - если значение равно "Y", то при фильтрации по FIELD_PARAM будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Ссылка на переменную хранящую флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

См. также

  • Поля CFormAnswer
  • CFormAnswer::GetByID

Примеры использования

<?
$QUESTION_ID = 143; // ID вопроса

// сформируем массив фильтра
$arFilter = Array(
    "ID"                      => "589 | 590", // ID ответа равен 589 или 590
    "ID_EXACT_MATCH"          => "Y",         // точное совпадение для ID
    "ACTIVE"                  => "Y",         // флаг активности
    "MESSAGE"                 => "да | нет",  // параметр ANSWER_TEXT равен "да" или "нет"
    "MESSAGE_EXACT_MATCH"     => "Y",         // точное совпадение для MESSAGE
    "FIELD_TYPE"              => "radio",     // тип поля ответа - radio-кнопка
    "FIELD_TYPE_EXACT_MATCH"  => "Y",         // точное совпадение для FIELD_TYPE
    "FIELD_PARAM"             => "checked",   // параметр включает в себя строку "checked"
    "FIELD_PARAM_EXACT_MATCH" => "N"          // вхождение для FIELD_PARAM
);

// получим список всех ответов вопроса #143
$rsAnswers = CFormAnswer::GetList(
    $QUESTION_ID,
    $by="s_id",
    $order="desc",
    $arFilter,
    $is_filtered
    );
while ($arAnswer = $rsAnswers->Fetch())
{
    echo "<pre>"; print_r($arAnswer); echo "</pre>";
}
?>


Set

CFormAnswer::Set

mixed
CFormAnswer::Set(
 array fields,
 mixed answer_id = false,
 mixed current_question_id = false
)

Добавляет новый ответ или обновляет существующий. Возвращает ID обновленного или добавленного ответа в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр Описание
fields Массив значений, в качестве ключей массива допустимы:
  • QUESTION_ID* - ID вопроса
  • MESSAGE* - значение параметра ответа ANSWER_TEXT;
  • VALUE - значение параметра ответа ANSWER_VALUE;
  • C_SORT - порядок сортировки;
  • ACTIVE - флаг активности, допустимы следующие значения:
    • Y - ответ активен;
    • N - ответ не активен (по умолчанию).
  • FIELD_TYPE - тип поля ответа, допустимы следующие значения:
    • text - однострочное текстовое поле;
    • textarea - многострочное текстовое поле;
    • radio - переключатель одиночного выбора (radio-кнопка);
    • checkbox - флаг множественного выбора (checkbox);
    • dropdown - элемент выпадающего списка одиночного выбора;
    • multiselect - элемент списка множественного выбора;
    • date - поле для ввода даты;
    • image - поле для загрузки изображения;
    • file - поле для загрузки произвольного файла;
    • password - поле для ввода пароля.
  • FIELD_WIDTH - ширина поля ответа;
  • FIELD_HEIGHT - высота поля ответа;
  • FIELD_PARAM - параметр поля ответа.
* - обязательные поля.
answer_id ID обновляемого ответа.
Параметр необязательный. По умолчанию - "false" (добавление нового ответа).
current_question_id ID вопроса, к которому приписан обновляемый ответ. Указание данного параметра позволяет ускорить выполнение функции.
Параметр необязательный. По умолчанию - "false".

См. также

  • Поля CFormAnswer

Примеры использования

<?
$QUESTION_ID = 140; // ID вопроса "Фамилия, имя, отчество"

$arFields = array(
    "QUESTION_ID"   => $QUESTION_ID,
    "MESSAGE"       => " ",
    "C_SORT"        => 100,
    "ACTIVE"        => "Y",
    "FIELD_TYPE"    => "text",
    "FIELD_WIDTH"   => "40"
    );

$NEW_ID = CFormAnswer::Set($arFields);
if ($NEW_ID>0) echo "Успешно добавлен ID=".$NEW_ID;
else // ошибка
{
    // выводим текст ошибки
    global $strError;
    echo $strError;
}
?>

<?
$QUESTION_ID = 143; // ID вопроса "Вы женаты/замужем?"

$arFields = array(
    "QUESTION_ID"      => $QUESTION_ID,
    "MESSAGE"       => "да",
    "C_SORT"        => 100,
    "ACTIVE"        => "Y",
    "FIELD_TYPE"    => "radio",
    "FIELD_PARAM"   => "checked"
    );
CFormAnswer::Set($arFields);

$arFields = array(
    "QUESTION_ID"      => $QUESTION_ID,
    "MESSAGE"       => "нет",
    "C_SORT"        => 200,
    "ACTIVE"        => "Y",
    "FIELD_TYPE"    => "radio"
    );
CFormAnswer::Set($arFields);
?>


Класс CFormField

CFormField - класс для работы с вопросами и полями.

Поля

Поле | Тип | Описание
ID | int | Идентификатор вопроса / поля.
SID | varchar(50) | Символьный идентификатор вопроса / поля.
FORM_ID | int | ID веб-формы, к которой приписан данный вопрос / поле.
TIMESTAMP_X | datetime | Время последнего изменения параметров вопроса / поля.
ACTIVE | char | Флаг активности (Y|N).
ADDITIONAL | char | Если в данном флаге хранится значение "Y", то данная запись является полем, иначе это вопрос веб-формы.
FIELD_TYPE varchar(50) Тип поля, допустимы следующие значения:
  • text - текст;
  • integer - число;
  • date - дата.
TITLE | varchar(2000) | Текст вопроса или заголовок поля.
TITLE_TYPE | varchar(4) | Тип текста вопроса ("text" или "html").
IMAGE_ID | int | Изображение вопроса.
C_SORT | int | Индекс сортировки.
REQUIRED | char | Флаг обязательности ответа на вопрос при создании нового или редактировании существующего результата (Y|N).
IN_FILTER | char | Означает, что данный вопрос / поле входят в фильтр по результатам.
FILTER_TITLE | varchar(2000) | Подпись к полю фильтра.
IN_RESULTS_TABLE | char | Если в данном флаге хранится значение "Y", значение данного вопроса / поля будет отображено в HTML таблице результатов.
IN_EXCEL_TABLE | char | Если в данном флаге хранится значение "Y", значение данного вопроса / поля будет отображено в Excel таблице результатов.
RESULTS_TABLE_TITLE | varchar(2000) | Заголовок столбца в таблице результатов.
COMMENTS | varchar(2000) | Служебный комментарий к вопросу / полю.

Методы

Метод | Описание
Set | Добавляет новый вопрос / поле, либо обновляет параметры существующего.
GetList | Возвращает список вопросов / полей.
GetByID | Возвращает параметры вопроса / поля по цифровому идентификатору.
GetBySID | Возвращает параметры вопроса / поля по символьному идентификатору.
Copy | Копирует вопрос / поле.
Reset | Удаляет все значения ответов на вопрос / поле из результатов.
Delete | Удаляет вопрос / поле, а также все значения ответов на него из результатов.


Copy

CFormField::Copy

mixed
CFormField::Copy(
 int field_id,
 string check_rights = "Y",
 mixed form_id = false
)

Копирует вопрос или поле веб-формы. Возвращает ID нового вопроса/поля в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр | Описание
field_id | ID вопроса/поля, который необходимо скопировать.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для копирования вопроса/поля необходимо обладать нижеследующими правами:
  1. [25] просмотр параметров веб-формы на веб-форму, из которой идет копирование;
  2. [30] полный доступ на веб-форму, в которую копируется
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).
form_id ID веб-формы, в которую необходимо скопировать вопрос/поле.

Необязательный параметр. По умолчанию - "false" (текущая веб-форма).

См. также

  • CForm::Copy
  • CFormAnswer::Copy
  • CFormStatus::Copy

Примеры использования

<?
$FIELD_ID = 140; // ID вопроса
// скопируем вопрос
if ($NEW_FIELD_ID=CFormField::Copy($FIELD_ID))
{
    echo "Вопрос #140 успешно скопирован в новый вопрос #".$NEW_FIELD_ID;
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


Delete

CFormField::Delete

bool
CFormField::Delete(
 int field_id,
 string check_rights = "Y"
)

Удаляет вопрос/поле и все ответы на него из результатов. Возвращает "true" в случае положительного результата, и "false" - в противном случае.

Параметры функции

Параметр | Описание
field_id | ID вопроса/поля.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для успешного выполнения данной операции необходимо иметь право [30] Полный доступ на веб-форму, к которой принадлежит field_id.

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CForm::Delete
  • CFormAnswer::Delete
  • CFormStatus::Delete
  • CFormResult::Delete

Примеры использования

<?
$FIELD_ID = 140;
// удалим вопрос #140
if (CFormField::Delete($FIELD_ID))
{
    echo "Вопрос #140 удален.";
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


GetByID

CFormField::GetByID

CDBResult
CFormField::GetByID(
 int field_id
)

Возвращает параметры вопроса/поля в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
field_id | ID вопроса/поля.

См. также

  • Поля CFormField
  • CFormField::GetBySID
  • CFormField::GetList

Примеры использования

<?
$FIELD_ID = 140; // ID вопроса или поля веб-формы
$rsField = CFormField::GetByID($FIELD_ID);
$arField = $rsField->Fetch();
echo "<pre>"; print_r($arField); echo "</pre";
?>


GetBySID

CFormField::GetBySID

CDBResult
CFormField::GetBySID(
 int field_sid
)

Возвращает параметры вопроса/поля в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
field_sid | Символьный идентификатор вопроса/поля.

См. также

  • Поля CFormField
  • CFormField::GetByID
  • CFormField::GetList

Примеры использования

<?
$FIELD_SID = "VS_INTEREST"; // символьный идентификатор вопроса или поля веб-формы
$rsField = CFormField::GetBySID($FIELD_SID);
$arField = $rsField->Fetch();
echo "<pre>"; print_r($arField); echo "</pre";
?>


GetList

CFormField::GetList

CDBResult
CFormField::GetList(
 int form_id,
 string get_only_fields,
 string &by = "s_sort",
 string &order = "asc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список вопросов/полей веб-формы в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
get_only_fields Может принимать следующие значения:
  • Y - возвращаемый список должен содержать только поля веб-формы;
  • N - возвращаемый список должен содержать только вопросы веб-формы;
  • ALL - возвращаемый список должен содержать и вопросы и поля веб-формы.
by Ссылка на переменную с полем для сортировки результирующего списка, может принимать значения:
  • s_id - ID;
  • s_active - флаг активности;
  • s_sid - символьный идентификатор;
  • s_sort - индекс сортировки;
  • s_title - текст вопроса или заголовок поля веб-формы;
  • s_comments - служебный комментарий;
  • s_required - флаг обязательности ответа на вопрос веб-формы;
  • s_in_results_table - флаг включения в HTML таблицу результатов;
  • s_in_excel_table - флаг включения в Excel таблицу результатов;
  • s_field_type - тип поля веб-формы.
оrder Ссылка на переменную с порядком сортировки, может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации. В массиве допустимы следующие ключи:
  • ID* - ID вопроса/поля (по умолчанию будет искаться точное совпадение);
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SID* - символьный идентификатор вопроса/поля (по умолчанию будет искаться точное совпадение);
  • SID_EXACT_MATCH - если значение равно "N", то при фильтрации по SID будет искаться вхождение;
  • TITLE* - текст вопрос или заголовок поля веб-формы (по умолчанию будет искаться вхождение);
  • TITLE_EXACT_MATCH - если значение равно "Y", то при фильтрации по TITLE будет искаться точное совпадение;
  • COMMENTS* - служебный комментарий (по умолчанию будет искаться вхождение);
  • COMMENTS_EXACT_MATCH - если значение равно "Y", то при фильтрации по COMMENTS будет искаться точное совпадение;
  • ACTIVE - флаг активности [Y|N]
  • IN_RESULTS_TABLE - флаг включения в HTML таблицу результатов [Y|N];
  • IN_EXCEL_TABLE - флаг включения в Excel таблицу результатов [Y|N];
  • IN_FILTER - флаг включения в HTML таблицу результатов [Y|N];
  • REQUIRED - флаг обязательности ответа на вопрос веб-формы [Y|N].
* - допускается сложная логика
is_filtered | Ссылка на переменную, хранящую флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

См. также

  • Поля CFormField
  • CFormField::GetByID
  • CFormField::GetBySID

Примеры использования

<?
$FORM_ID = 4; // ID веб-формы

// сформируем массив фильтра
$arFilter = Array(
  "ID"                    => "140 | 141",     // вопрос с ID=140 или с ID=141
  "ID_EXACT_MATCH"        => "Y",             // точное совпадение при фильтрации по ID
  "SID"                   => "VS_BIRTHDAY",   // символьный идентификатор
  "SID_EXACT_MATCH"       => "Y",             // точное совпадение с симв. идентификатором
  "TITLE"                 => "День рождения", // текст вопроса
  "TITLE_EXACT_MATCH"     => "N",             // вхождение при фильтрации по тексту вопроса
  "ACTIVE"                => "Y",             // флаг активности
  "IN_RESULTS_TABLE"      => "Y",             // флаг вхождение в HTML таблицу результатов
  "IN_EXCEL_TABLE"        => "N",             // флаг вхождения в Excel таблицу результатов
  "IN_FILTER"             => "Y",             // флаг вхождения в фильтр
  "REQUIRED"              => "Y",             // флаг обязательности ответа на вопрос
);

// получим список всех вопросов веб-формы #4
$rsQuestions = CFormField::GetList(
    $FORM_ID,
    "N",
    $by="s_id",
    $order="desc",
    $arFilter,
    $is_filtered
    );
while ($arQuestion = $rsQuestions->Fetch())
{
    echo "<pre>"; print_r($arQuestion); echo "</pre>";
}
?>


Reset

CFormField::Reset

bool
CFormField::Reset(
 int field_id,
 string check_rights = "Y"
)

Удаляет все значения ответов из результатов по заданному вопросу/полю. Возвращает "true" в случае положительного результата, и "false" - в противном случае.

Параметры функции

Параметр | Описание
field_id | ID вопроса/поля.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для успешного выполнения данной операции необходимо иметь право [30] Полный доступ на веб-форму, к которой принадлежит field_id.

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CForm::Reset
  • CFormResult::Reset

Примеры использования

<?
$FIELD_ID = 4;
// удалим все ответы из результатов на вопрос с ID=140
if (CFormField::Reset($FIELD_ID))
{
    echo "Операция успешна.";
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


Set

CFormField::Set

mixed
CFormField::Set(
 array fields,
 mixed field_id = false,
 string check_rights = "Y"
)

Добавляет новый вопрос/поле или обновляет существующий. Возвращает ID обновленного или добавленного вопроса/поля в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр Описание
fields Массив значений, в качестве ключей массива допустимы:
  • SID* - символьный идентификатор вопроса/поля;
  • FORM_ID* - ID веб-формы;
  • ACTIVE - флаг активности; допустимы следующие значения:
    • Y - вопрос/поле активен;
    • N - вопрос/поле не активен (по умолчанию).
  • ADDITIONAL - допустимы следующие значения:
    • Y - данная запись является полем веб-формы;
    • N - данная запись является вопросом веб-формы (по умолчанию).
  • FIELD_TYPE* - тип поля, допустимые следующие значения:
    • text - текст;
    • integer - число;
    • date - дата.
  • TITLE - текст вопроса либо заголовок поля.
  • TITLE_TYPE* - тип вопроса; допустимы следующие значения:
    • text - текст;
    • html - HTML код.
  • C_SORT - порядок сортировки;
  • REQUIRED* - флаг обязательности ответа на вопрос:
    • Y - ответ на данный вопрос обязателен;
    • N - ответ на данный вопрос обязателен (по умолчанию).
  • FILTER_TITLE - подпись к полю фильтра;
  • IN_RESULTS_TABLE - флаг вхождения в HTML таблицу результатов:
    • Y - ответ на данный вопрос либо значения поля веб-формы отражены в HTML таблице результатов;
    • N - ответ на данный вопрос либо значения поля веб-формы отражены в HTML таблице результатов (по умолчанию).
  • IN_EXCEL_TABLE - флаг вхождения в Excel таблицу результатов:
    • Y - ответ на данный вопрос либо значения поля веб-формы отражены в Excel таблице результатов
    • N - ответ на данный вопрос либо значения поля веб-формы отражены в Excel таблице результатов (по умолчанию).
  • RESULTS_TABLE_TITLE - заголовок столбца в таблицах результатов;
  • COMMENTS - служебный комментарий;
  • arIMAGE** - массив, описывающий изображение вопроса, допустимы следующие ключи этого массива:
    • name - имя файла;
    • size - размер файла;
    • tmp_name - временный путь на сервере;
    • type - тип загружаемого файла;
    • del - если значение равно "Y", то изображение будет удалено;
    • MODULE_ID - идентификатор модуля "Веб-формы" - form
  • arANSWER** - массив, описывающий ответы на вопрос, со следующей структурой:
    Array
(
    [0] => Array
        (
            [ID] => ID
            [DELETE] => флаг необходимости удаления [Y|N]
            [MESSAGE] => параметр ANSWER_TEXT
            [VALUE] => параметр ANSWER_VALUE
            [C_SORT] => порядок сортировки
            [ACTIVE] => флаг активности [Y|N]
            [FIELD_TYPE] => тип, допустимы следующие значения:

                text - однострочное текстовое поле
                textarea - многострочное текстовое поле
                radio* - переключатель одиночного выбора (radio-кнопка)
                checkbox* - флаг множественного выбора (checkbox)
                dropdown* - элемент выпадающего списка одиночного выбора
                multiselect* - элемент списка множественного выбора
                date - поле для ввода даты
                image - поле для загрузки изображения
                file - поле для загрузки произвольного файла
                password - поле для ввода пароля

            [FIELD_WIDTH] => ширина поля ввода
            [FIELD_HEIGHT] => высота поля ввода
            [FIELD_PARAM] => дополнительные параметры;
                допустимо использование любого HTML кода;
                для типов помеченных символом * допустимо использование
                следующих зарезервированных строк:

                checked - ответ будет выбран (отмечен)
                          по умолчанию (синоним - selected)
                not_answer - выбор данного ответа не означает,
                          что был дан ответ на вопрос
                          (как правило это первый элемент выпадающего списка и
                          важно при REQUIRED="Y")
        )
    [1] => массив описывающий следующий ответ
    ...
)
  • arFILTER_USER** - массив полей фильтра для фильтрации по значению ответа, введенному с клавиатуры пользователем при заполнении веб-формы; в данном массиве допустимы следующие значения:
    • text - текстовое поле фильтра;
    • integer - поля фильтра для числового интервала;
    • date - поля фильтра для интервала дат;
    • exist - поле для фильтрации по факту существования введенного ответа.
  • arFILTER_ANSWER_TEXT** - массив полей фильтра для фильтрации по параметру ответа ANSWER_TEXT; в данном массиве допустимы следующие значения:
    • text - текстовое поле фильтра;
    • integer - поля фильтра для числового интервала;
    • dropdown - выпадающий список одиночного выбора;
    • exist - поле для фильтрации по факту существования.
  • arFILTER_ANSWER_VALUE** - массив полей фильтра для фильтрации по параметру ответа ANSWER_VALUE; в данном массиве допустимы следующие значения:
    • text - текстовое поле фильтра;
    • integer - поля фильтра для числового интервала;
    • dropdown - выпадающий список одиночного выбора;
    • exist - поле для фильтрации по факту существования.
  • arFILTER_FIELD* - массив полей фильтра для фильтрации по значению поля веб-формы:
    • text - текстовое поле фильтра;
    • integer - поля фильтра для числового интервала;
    • date - поля фильтра для интервала дат.

* - обязательно к заполнению;
* - заполняется только для полей веб-формы;
** - заполняется только для вопросов веб-формы.
field_id ID обновляемого вопроса/поля.
Параметр необязательный. По умолчанию - "false" (добавление нового вопроса/поля).
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для добавления нового вопроса/поля или обновления их параметров необходимо иметь право [30] Полный доступ на веб-форму указанную в fields["FORM_ID"].

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • Поля CFormField
  • Права на веб-форму
  • CFile::MakeFileArray

Примеры использования

<?
/*************************************************
         Добавление вопроса веб-формы
*************************************************/

// создадим массив описывающий изображение
// находящееся в файле на сервере
$arIMAGE = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/question.gif");
$arIMAGE["MODULE_ID"] = "form";

// формируем массив ответов
$arANSWER = array();

$arANSWER[] = array(
    "MESSAGE"     => "да",                           // параметр ANSWER_TEXT
    "C_SORT"      => 100,                            // порядок фортировки
    "ACTIVE"      => "Y",                            // флаг активности
    "FIELD_TYPE"  => "radio",                        // тип ответа
    "FIELD_PARAM" => "checked class=\"inputradio\""  // параметры ответа
    );

$arANSWER[] = array(
    "MESSAGE"     => "нет",
    "C_SORT"      => 200
    "ACTIVE"      => "Y",
    "FIELD_TYPE"  => "radio"
    );

// формируем массив полей
$arFields = array(
    "FORM_ID"              => 4,                     // ID веб-формы
    "ACTIVE"               => Y,                     // флаг активности
    "TITLE"                => "Вы женаты/замужем ?", // текст вопроса
    "TITLE_TYPE"           => "text",                // тип текста вопроса
    "SID"                  => "VS_MARRIED",          // символьный идентификатор вопроса
    "C_SORT"               => 400,                   // порядок сортировки
    "ADDITIONAL"           => "N",                   // мы добавляем вопрос веб-формы
    "REQUIRED"             => "Y",                   // ответ на данный вопрос обязателен
    "IN_RESULTS_TABLE"     => "Y",                   // добавить в HTML таблицу результатов
    "IN_EXCEL_TABLE"       => "Y",                   // добавить в Excel таблицу результатов
    "FILTER_TITLE"         => "Женат/замужем",       // подпись к полю фильтра
    "RESULTS_TABLE_TITLE"  => "Женат/замужем",       // заголовок столбца фильтра
    "arIMAGE"              => $arIMAGE,              // изображение вопроса
    "arFILTER_ANSWER_TEXT" => array("dropdown"),     // тип фильтра по ANSWER_TEXT
    "arANSWER"             => $arANSWER,             // набор ответов
);

// добавим новый вопрос
$NEW_ID = CFormField::Set($arFields);
if ($NEW_ID>0) echo "Добавлен вопрос с ID=".$NEW_ID;
else // ошибка
{
    // выводим текст ошибки
    global $strError;
    echo $strError;
}
?>
<?
/*************************************************
          Добавление поля веб-формы
*************************************************/

$arFields = array(
    "FORM_ID"             => 4
    "ACTIVE"              => "Y",
    "TITLE"               => "Рассчитанная стоимость",
    "SID"                 => "VS_PRICE",
    "C_SORT"              => 1000,
    "ADDITIONAL"          => "Y",
    "IN_RESULTS_TABLE"    => "Y",
    "IN_EXCEL_TABLE"      => "Y",
    "FIELD_TYPE"          => "text",
    "FILTER_TITLE"        => "Стоимость",
    "RESULTS_TABLE_TITLE" => "Стоимость",
    "arFILTER_FIELD"      => array("text")
    );

// добавим новое поле
$NEW_ID = CFormField::Set($arFields);
if ($NEW_ID>0) echo "Добавлено поле с ID=".$NEW_ID;
else // ошибка
{
    // выводим текст ошибки
    global $strError;
    echo $strError;
}
?>


Класс CFormOutput

CFormOutput - класс для работы с шаблонами форм

Использование класса

Класс используется для для управления визульным отображением формы. При выводе шаблона формы, ему передается переменная $FORM - инициализированный экземпляр класса. Шаблон формируется в виде HTML-кода со вставками вызовов методов класса (пример см. ниже). Возможно визуальное редактирование шаблона, а также, создание формы на основе шаблона.

Основные методы класса

Основные методы класса.

Метод | Описание
ShowApplyButton | Вывод кнопки "Применить".
ShowCaptcha | Вывод отформатированных полей ввода CAPTCHA.
ShowCaptchaField | Вывод поля для ввода текста CAPTCHA.
ShowCaptchaImage | Вывод изображения CAPTCHA.
ShowErrorMsg | Вывод ошибок модуля формы. Вызывается автоматически.
ShowFormDescription | Вывод описания формы.
ShowFormErrors | Вывод отформатированного списка ошибок валидатора формы.
ShowFormErrorsText | Вывод неотформатированного списка ошибок валидатора формы.
ShowFormFooter | Вывод завершающей части HTML-кода формы. Вставляется в конец шаблона автоматически.
ShowFormHeader | Вывод заголовка HTML-кода формы. Вставляется в начало шаблона автоматически.
ShowFormImage | Вывод картинки формы.
ShowFormNote | Вывод отформатированных заметок формы.
ShowFormNoteText | Вывод неотформатированных заметок формы.
ShowFormTitle | Вывод текстового заголовка формы.
ShowInput | Вывод поля формы.
ShowInputCaption | Вывод подписи поля формы.
ShowInputCaptionImage | Вывод картинки поля формы.
ShowRequired | Вывод метки "обязательное поле".
ShowResetButton | Вывод кнопки "Сбросить".
ShowSubmitButton | Вывод кнопки отправки формы.
SetInputDefaultValue | Устанавливает значение по умолчанию для поля веб-формы.

Методы для проверки условий. Все условные методы недоступны в режиме визуального редактора. Их можно использовать только в режиме редактирования PHP-кода.

Метод | Описание
isFormDescription | Имеет ли форма описание.
isFormErrors | Есть ли ошибки валидатора.
isFormImage | Имеет ли форма картинку.
isFormNote | Имеет ли форма заметки.
isFormTitle | Имеет ли форма текстовый заголовок.
isInputCaptionImage | Имеет ли поле формы картинку.
isUseCaptcha | Используется ли в форме CAPTCHA.

Пример шаблона формы

$FORM - экземпляр класса CFormOutput - создаётся и инициализируется автоматически вне шаблона. Вызов методов CFormOutput::ShowFormHeader() и CFormOutput::ShowFormFooter() также добавляется к шаблону автоматически.

<!-- Выведем описание формы -->
<table width="100%" cellpadding="2" cellspacing="0" border="0">
    <tr>
        <td align="center"><?=$FORM->ShowFormDescription()?></td>
    </tr>
</table>

<!-- Если есть ошибки валидатора - выведем их -->
<?if($FORM->isFormErrors()):?>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
    <tr>
        <td><?=$FORM->ShowFormErrors()?></td>
    </tr>
</table>
<?endif?>

<!-- Выведем поля формы -->
<table width="100%" cellpadding="2" cellspacing="0" border="0">
    <tr>
        <td width="40%" valign="top" align="right"><?=$FORM->ShowInputCaption('test_q')?>: </td>
        <td width="60%" valign="top"><?=$FORM->ShowInput('test_q')?></td>
    </tr>
    <tr>
        <td valign="top" align="right"><?=$FORM->ShowInputCaption('test_q_text')?>: </td>
        <td valign="top"><?=$FORM->ShowInput('test_q_text')?></td>
    </tr>
    <tr>
        <td valign="top" align="right"><?=$FORM->ShowInputCaption('test_q_textarea')?>: </td>
        <td valign="top"><?=$FORM->ShowInput('test_q_textarea')?></td>
    </tr>
</table>

<!-- Если используется CAPTCHA - выведем картинку и поле для ввода -->
<?if($FORM->isUseCaptcha()):?>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
    <tr>
        <td colspan="2" height="8"></td>
    </tr>
    <tr>
        <td width="40%" valign="top" align="right" class="text">Защита от автоматической регистрации: </td>
        <td width="60%" valign="top"><?=$FORM->ShowCaptchaImage()?></td>
    </tr>
    <tr>
        <td valign="top" align="right" class="text">Введите слово с картинки<?=$FORM->ShowRequired()?>: </td>
        <td valign="top"><?=$FORM->ShowCaptchaField()?></td>
    </tr>
</table>
<?endif?>

<!-- Выведем кнопки формы -->
<table width="100%" cellpadding="2" cellspacing="0" border="0">
    <tr>
        <td width="40%">&nbsp;</td>
        <td width="60%">
            <?=$FORM->ShowSubmitButton()?>&nbsp;
            <?=$FORM->ShowApplyButton()?>&nbsp;
            <?=$FORM->ShowResetButton()?>
        </td>
    </tr>
</table>

Если не предполагается использование страниц редактирования результата формы или просмотра списка результатов, то имеет смысл вставить в шаблон ответ веб-формы в обход основного шаблона:

<!-- Если есть ответ формы - выведем его в обход шаблона -->
<?if($FORM->isFormNote()):?>
<?=$FORM->ShowFormNote()?>
<?else:?>
<!-- здесь остальной шаблон веб-формы -->
<?endif?>


isFormDescription

CFormOutput::isFormDescription

bool
CFormOutput::isFormDescription(
);

Проверка условия "есть ли у формы текстовое описание".

Параметры функции

Нет параметров.

Возвращаемое значение

true, если у формы есть текстовое описание. false в противном случае.

Использование

<?if($FORM->isFormDescription()):?>Описание: <?=$FORM->ShowFormDescription()?><?endif?>

См. также

Класс CFormOutput
CFormOutput::ShowFormDescription


isFormErrors

CFormOutput::isFormErrors

bool
CFormOutput::isFormErrors(
);

Проверка условия "есть ли ошибки валидатора формы".

Параметры функции

Нет параметров.

Возвращаемое значение

true, если в процессе обработки результата формы обнаружены ошибки. false в противном случае.

Использование

<?if($FORM->isFormErrors()):?>Ошибки: <?=$FORM->ShowFormErrors()?><?endif?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormErrors
  • CFormOutput::ShowFormErrorsText
    •


isFormImage

CFormOutput::isFormImage

bool
CFormOutput::isFormImage(
);

Проверка условия "прикреплена ли к форме картинка".

Параметры функции

Нет параметров.

Возвращаемое значение

true, если к форме прикреплена картинка. false в противном случае.

Использование

<?if($FORM->isFormImage()):?>
<?=$FORM->ShowFormImage()?>
<?else:?>
<?=CFile::ShowImage("/myimages/form_default.jpg")?>
<?endif?>

См. также

  • Класс CFormOutput
  • CFile::ShowImage
  • CFormOutput::ShowFormImage
    •


isFormNote

CFormOutput::isFormNote

bool
CFormOutput::isFormNote(
);

Проверка условия "есть ли текстовые заметки".

Параметры функции

Нет параметров.

Возвращаемое значение

true, если у есть текстовые заметки. false в противном случае.

Использование

<?if($FORM->isFormNote()):?>Ответ: <?=$FORM->ShowFormNote()?><?endif?>

См. также

Класс CFormOutput
CFormOutput::ShowFormNote


isFormTitle

CFormOutput::isFormTitle

bool
CFormOutput::isFormTitle(
);

Проверка условия "есть ли у формы текстовый заголовок (название)".

Параметры функции

Нет параметров.

Возвращаемое значение

true, если у формы есть текстовый заголово (название). false в противном случае.

Использование

<?if($FORM->isFormTitle()):?>Описание: <?=$FORM->ShowFormTitle()?><?endif?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormTitle
    •


isInputCaptionImage

CFormOutput::isInputCaptionImage

bool
CFormOutput::isInputCaptionImage(
    string FIELD_SID
);

Проверка условия "прикреплена ли к вопросу с данным идентификатором картинка".

Параметры функции

Параметр | Описание
FIELD_SID | Строковой идентификатор поля вопроса. Обязательный параметр.

Возвращаемое значение

true, если к вопросу прикреплена картинка. false в противном случае.

Использование

<?=$FORM->ShowInputCaption('MYFIELD_5')?>:
<?=$FORM->ShowInput('MYFIELD_5')?><br />
<?if($FORM->isInputCaptionImage('MYFIELD_5')):?>
    <?=$FORM->ShowInputCaptionImage('MYFIELD_5')?>
<?else:?>
    <?=CFile::ShowImage("/myimages/form_field_default.jpg")?>
<?endif?>:

См. также

  • Класс CFormOutput
  • CFile::ShowImage
  • CFormOutput::ShowInput
  • CFormOutput::ShowInputCaption
  • CFormOutput::ShowInputCaptionImage
    •


isUseCaptcha

CFormOutput::isUseCaptcha

bool
CFormOutput::isUseCaptcha(
);

Проверка условия "форма использует CAPTCHA".

Параметры функции

Нет параметров.

Возвращаемое значение

true, если форма использует CAPTCHA. false в противном случае.

Использование

<?if($FORM->isUseCaptcha()):?>
<tr>
    <td colspan="2" height="8"></td>
</tr>
<tr>
    <td valign="top" align="right" class="text">Защита от автоматической регистрации:</td>
    <td valign="top"><?=$FORM->ShowCaptchaImage()?></td>
</tr>
<tr>
    <td valign="top" align="right" class="text">Введите слово с картинки<?=$FORM->ShowRequired()?>:</td>
    <td valign="top"><?=$FORM->ShowCaptchaField()?></td>
</tr>
<?endif?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowCaptcha
  • CFormOutput::ShowCaptchaField
  • CFormOutput::ShowCaptchaImage
    •


ShowApplyButton

CFormOutput::ShowApplyButton

string
CFormOutput::ShowApplyButton([
    string CAPTION = "",
    string CSSClass = ""
]
);

Возвращает HTML-код кнопки "Применить" формы создания/редактирования записи

Параметры функции

Параметр | Описание
CAPTION | Текст, расположенный на кнопке. Необязательный параметр. Если параметр пуст или не указан, то будет использовано значение по умолчанию.
CSSClass | CSS-класс кнопки. Необязательный параметр.

Возвращаемое значение

Возвращается HTML-код кнопки "Применить"

Использование

<?=$FORM->ShowApplyButton("Применить", "form-button-apply")?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowResetButton
  • CFormOutput::ShowSubmitButton
    •


ShowCaptcha

CFormOutput::ShowCaptcha

string
CFormOutput::ShowCaptcha(
);

Возвращает комбинацию изображения CAPTCHA и поля для ввода

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращается HTML-код обоих элементов

Использование

<?=$FORM->ShowCaptcha()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowCaptchaField
  • CFormOutput::ShowCaptchaImage
  • CFormOutput::isUseCaptcha
    •


ShowCaptchaField

CFormOutput::ShowCaptchaField

string
CFormOutput::ShowCaptchaField(
);

Возвращает код поля для ввода CAPTCHA

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращается HTML-код поля для ввода CAPTCHA

Использование

<?=$FORM->ShowCaptchaField()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowCaptcha
  • CFormOutput::ShowCaptchaImage
  • CFormOutput::isUseCaptcha
    •


ShowCaptchaImage

CFormOutput::ShowCaptchaImage

string
CFormOutput::ShowCaptchaImage(
);

Возвращает HTML-код для вставки изображения CAPTCHA

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращается HTML-код для вставки изображения CAPTCHA

Использование

<?=$FORM->ShowCaptchaImage()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowCaptcha
  • CFormOutput::ShowCaptchaField
  • CFormOutput::isUseCaptcha
    •


ShowErrorMsg

CFormOutput::ShowErrorMsg

string
CFormOutput::ShowErrorMsg(
);

Возвращает код ошибки инициализации формы

Параметры функции

Нет параметров.

Возвращаемое значение

Функция возвращает одну из следующих строк, либо пустую строку, если ошибок нет

Строка | Описание
FORM_NOT_FOUND | Формы с переданным WEB_FORM_ID не существует
FORM_ACCESS_DENIED | Не хватает прав доступа к форме

Проверка наличия ошибки и вывод соответствующего ей языкового сообщения производится автоматически при инициализации формы

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormErrors
  • CFormOutput::ShowFormErrorsText
    •


ShowFormDesctiption

CFormOutput::ShowFormDesctiption

string
CFormOutput::ShowFormDescription([
    string CSSClass = ""
]
);

Вывод описательного текста формы

Параметры функции

Параметр | Описание
CSSClass | CSS-класс который нужно применить к выводимому тексту. Необязательный параметр. Если для описания формы выставлено значение "HTML", то параметр игнорируется.

Возвращаемое значение

Возвращает описательный текст формы

Использование

<?=$FORM->ShowFormDescription("form-description-text")?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormTitle
  • CFormOutput::ShowFormImage
  • CFormOutput::isFormDescription
    •


ShowFormErrors

CFormOutput::ShowFormErrors

string
CFormOutput::ShowFormErrors(
);

Вывод отформатированных ошибок валидатора формы

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращает отфоматированный список ошибок валидатора формы. Если ошибок нет, возвращается пустая строка.

Использование

<?=$FORM->ShowFormErrors()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormErrorsText
  • CFormOutput::isFormErrors
    •


ShowFormErrorsText

CFormOutput::ShowFormErrorsText

string
CFormOutput::ShowFormErrorsText(
);

Вывод неотформатированных ошибок валидатора формы

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращает неотфоматированный список ошибок валидатора формы. Если ошибок нет, возвращается пустая строка.

Использование

<font color="#FF0000"><?=$FORM->ShowFormErrorsText()?></font>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormErrors
  • CFormOutput::isFormErrors
    •


ShowFormFooter

CFormOutput::ShowFormFooter

string
CFormOutput::ShowFormFooter(
);

Завершение вывода формы

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращает завершающий HTML-код формы. В том числе, тэг </form>.

Использование

При создании шаблона формы редактором, добавляется в конец шаблона автоматически.

<?=$FORM->ShowFormFooter()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormHeader
    •


ShowFormHeader

CFormOutput::ShowFormHeader

string
CFormOutput::ShowFormHeader(
);

Вывод HTML-заголовка формы

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращает HTML-код заголовка формы. В том числе, тэг <form>, скрытые поля.

Использование

При создании шаблона формы редактором, добавляется в начало шаблона автоматически.

<?=$FORM->ShowFormHeader()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormFooter
    •


ShowFormImage

CFormOutput::ShowFormImage

string
CFormOutput::ShowFormImage(
[
    string $sAlign = "",
    int $iMaxW = 0
    int $iMaxH = 0
    string $bPopup = "N",
    string $strPopupTitle = "",
    string $sHSpace = "",
    string $sVSpace = "",
    string $sBorder = ""
]
);

Вывод изображения, прикрепленного к описанию формы

Параметры метода

Параметры метода идентичны параметрам CFile::ShowImage

Параметр | Описание
sAlign | Расположение изображения относительно текста. Может принимать одно из четырех значений - LEFT, CENTER, RIGHT (регистр не имеет значения) или пустое. Необязательный параметр.
iMaxW | Максимальная ширина изображения. Если ширина картинки больше iMaxW, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
iMaxH | Максимальная высота изображения. Если высота картинки больше iMaxH, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
bPopup | Открывать ли при клике на изображении дополнительное popup окно с увеличенным изображением. Необязательный. Должен приниметь одно из двух значений - "Y" или "N" (с учётом регистра). По умолчанию - "N".
strPopupTitle | Текст всплывающей подсказки на изображении (только если bPopup = "Y") Необязательный. По умолчанию выводится фраза "Нажмите чтобы увеличить" на языке страницы.
sHSpace | Устанавливает вертикальный отступ картинки от окружающего текста в пикселях. Необязательный. По умолчанию - "0" - без отступа.
sVSpace | Устанавливает горизонтальный отступ картинки от окружающего текста в пикселях. Необязательный. По умолчанию - "0" - без отступа.
sBorder | Устанавливает толщину рамки вокруг изображения. Необязательный. По умолчанию равен "0" - без рамки:

Возвращаемое значение

Возвращает HTML-код для вставки изображения в формы

Использование

<?=$FORM->ShowFormImage("CENTER", 250, 250, "Y", GetMessage("FORM_ENLARGE"), 0, 0)?>

См. также

  • Класс CFormOutput
  • CFile::ShowImage
  • CFormOutput::ShowFormDescription
  • CFormOutput::ShowFormTitle
  • CFormOutput::isFormImage
    •


ShowFormNote

CFormOutput::ShowFormNote

string
CFormOutput::ShowFormNote(
);

Вывод отформатированных информационных сообщений формы

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращает отфоматированные информационные сообщения формы (напр. "Ваша заявка принята"). Если сообщений нет, возвращается пустая строка.

Использование

<?=$FORM->ShowFormNote()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormNoteText
  • CFormOutput::isFormNote
    •


ShowFormNoteText

CFormOutput::ShowFormNoteText

string
CFormOutput::ShowFormNoteText(
);

Вывод неотформатированных информационных сообщений формы

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращает неотфоматированные информационные сообщения формы (напр. "Ваша заявка принята"). Если сообщений нет, возвращается пустая строка.

Использование

<?=$FORM->ShowFormNoteText()?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormNoteText
  • CFormOutput::isFormNote
    •


ShowFormTitle

CFormOutput::ShowFormTitle

string
CFormOutput::ShowFormTitle([
    string CSSClass = ""
]
);

Вывод текстового заголовка формы

Параметры функции

Параметр | Описание
CSSClass | CSS-класс который нужно применить к выводимому тексту. Необязательный параметр.

Возвращаемое значение

Возвращает текстовый заголовок (название) формы

Использование

<?=$FORM->ShowFormTitle("form-title")?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowFormDescription
  • CFormOutput::ShowFormImage
  • CFormOutput::isFormTitle
    •


ShowInput

CFormOutput::ShowInput

string
CFormOutput::ShowInput(
    string $FIELD_SID[,
    string $CSSClass = ""]
);

Вставка полей ответа на вопрос в шаблон. Параметры поля ввода задаются в настройках вопроса.

Параметры функции

Параметр | Описание
FIELD_SID | Строковой идентификатор поля вопроса. Обязательный параметр.
CSSClass | CSS-класс для подписи к полю ввода. Необязательный параметр.

Возвращаемое значение

Возвращается HTML-код для вставки полей формы

Использование

<?=$FORM->ShowInput('MYFIELD_5')?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowInputCaption
  • CFormOutput::ShowInputCaptionImage
    •


ShowInputCaption

CFormOutput::ShowInputCaption

string
CFormOutput::ShowInputCaption(
    string $FIELD_SID[,
    string $CSSClass = ""]
);

Вставка в шаблон подписи поля ответа на вопрос.

Параметры функции

Параметр | Описание
FIELD_SID | Строковой идентификатор поля вопроса. Обязательный параметр.
CSSClass | CSS-класс подписи. Необязательный параметр. Если для выставлено значение "Текст вопроса - HTML", то параметр игнорируется.

Возвращаемое значение

Возвращается обработанная подпись поля формы.

Использование

<?=$FORM->ShowInputCaption('MYFIELD_5')?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowInput
  • CFormOutput::ShowInputCaptionImage
    •


ShowInputCaptionImage

CFormOutput::ShowInputCaptionImage

string
CFormOutput::ShowInputCaptionImage(
    string $FIELD_SID[,
    string $sAlign = "",
    int $iMaxW = 0
    int $iMaxH = 0
    string $bPopup = "N",
    string $strPopupTitle = "",
    string $sHSpace = "",
    string $sVSpace = "",
    string $sBorder = ""
]

);

Вывод изображения, прикрепленного к вопросу формы. Если изображение есть, возвращается HTML-код вставки. В противном случае - пустая строка.

Параметры метода

Параметры метода идентичны параметрам CFile::ShowImage

Параметр | Описание
FIELD_SID | Строковой идентификатор поля вопроса. Обязательный параметр.
sAlign | Расположение изображения относительно текста. Может принимать одно из четырех значений - LEFT, CENTER, RIGHT (регистр не имеет значения) или пустое. Необязательный параметр.
iMaxW | Максимальная ширина изображения. Если ширина картинки больше iMaxW, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
iMaxH | Максимальная высота изображения. Если высота картинки больше iMaxH, то она будет пропорционально смаштабирована. Необязательный. По умолчанию - "0" - без ограничений.
bPopup | Открывать ли при клике на изображении дополнительное popup окно с увеличенным изображением. Необязательный. Должен приниметь одно из двух значений - "Y" или "N" (с учётом регистра). По умолчанию - "N".
strPopupTitle | Текст всплывающей подсказки на изображении (только если bPopup = "Y") Необязательный. По умолчанию выводится фраза "Нажмите чтобы увеличить" на языке страницы.
sHSpace | Устанавливает вертикальный отступ картинки от окружающего текста в пикселях. Необязательный. По умолчанию - "0" - без отступа.
sVSpace | Устанавливает горизонтальный отступ картинки от окружающего текста в пикселях. Необязательный. По умолчанию - "0" - без отступа.
sBorder | Устанавливает толщину рамки вокруг изображения. Необязательный. По умолчанию равен "0" - без рамки:

Возвращаемое значение

Возвращает HTML-код для вставки изображения в форму

Использование

<?=$FORM->ShowInputCaptionImage('MYFIELD_5', 'LEFT', 50, 50, "N", "", 5, 5)?>

См. также

  • Класс CFormOutput
  • CFile::ShowImage
  • CFormOutput::ShowInput
  • CFormOutput::ShowInputCaption
  • CFormOutput::isInputCaptionImage
    •


ShowRequired

CFormOutput::ShowRequired

string
CFormOutput::ShowRequired(
);

Вывод пометки "обязательное поле" - *. При выводе подписи к полю посредством CFormOutput::ShowInputCaption пометка вставаляется автоматически.

Параметры функции

Нет параметров.

Возвращаемое значение

Возвращается HTML-код пометки

Использование

Первый обязательный вопрос <?=$FORM->ShowRequired()?>:<?=$FORM->ShowInput('REQ_FIELD_1')?><br />
<?=$FORM->ShowInputCaption('REQ_FIELD_2'):<?=$FORM->ShowInput('REQ_FIELD_2')?><br />

См. также

  • Класс CFormOutput
  • CFormOutput::ShowInput
  • CFormOutput::ShowInputCaption
    •


ShowResetButton

CFormOutput::ShowResetButton

string
CFormOutput::ShowResetButton([
    string CAPTION = "",
    string CSSClass = ""
]
);

Возвращает HTML-код кнопки "Сбросить" формы создания/редактирования записи

Параметры функции

Параметр | Описание
CAPTION | Текст, расположенный на кнопке. Если параметр пуст или не указан, то будет использовано значение по умолчанию. Необязательный параметр.
CSSClass | CSS-класс кнопки. Необязательный параметр.

Возвращаемое значение

Возвращается HTML-код кнопки "Сбросить"

Использование

<?=$FORM->ShowResetButton("Отменить изменения", "form-button-reset")?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowApplyButton
  • CFormOutput::ShowSubmitButton
    •


ShowSubmitButton

CFormOutput::ShowSubmitButton

string
CFormOutput::ShowSubmitButton([
    string CAPTION = "",
    string CSSClass = ""
]
);

Возвращает HTML-код кнопки отправки формы создания/редактирования записи

Параметры функции

Параметр | Описание
CAPTION | Текст, расположенный на кнопке. Если параметр пуст или не указан, то будет использовано значение параметра "Подпись на кнопке" вкладки "Свойства" страницы редактирования параметров веб-формы, либо значение по умолчанию. Необязательный параметр.
CSSClass | CSS-класс кнопки. Необязательный параметр.

Возвращаемое значение

Возвращается HTML-код кнопки отправки формы

Использование

<?=$FORM->ShowSubmitButton("Отправить заявку", "form-button-submit")?>

См. также

  • Класс CFormOutput
  • CFormOutput::ShowApplyButton
  • CFormOutput::ShowResetButton
    •


Класс CFormResult

CFormResult - класс для работы с результатами.

Поля

Поле | Тип | Описание
ID | int | Идентификатор результата.
FORM_ID | int | Идентификатор веб-формы.
TIMESTAMP_X | datetime | Время последнего изменения.
DATE_CREATE | datetime | Время создания.
STATUS_ID | int | Идентификатор текущего статуса.
USER_ID | int | ID пользователя, создавшего результата (автор результата).
USER_AUTH | char | Флаг авторизованности автора результата в момент создания результата [Y|N].
STAT_GUEST_ID | int | Идентификатор посетителя, создавшего результат (инициализируется модулем "Статистика" в момент создания результата).
STAT_SESSION_ID | int | Идентификатор сессии, в которой был создан результат (инициализируется модулем "Статистика" в момент создания результата).

Методы

Метод | Описание
Add | Создает новый результат.
Update | Обновляет результат.
SetField | Для указанного результата обновляет значения ответа на вопрос или обновляет значение поля веб-формы.
GetList | Возвращает список результатов.
GetByID | Возвращает поля результата.
GetDataByID | Возвращает ряд массивов, содержащих данные по значениям ответов на вопросы веб-формы, а также значения полей веб-формы для указанного результата.
GetDataByIDForHTML | Возвращает массив значений ответов на вопросы веб-формы, а также значения полей веб-формы для указанного результата. Ключи данного массива в точности соответствуют правилам формирования имен HTML полей для веб-формы.
GetFileByAnswerID | Возвращает параметры файла, загруженного в качестве значения ответа типа "file" или "image".
Reset | Удаляет значения ответов и значения полей веб-формы для указанного результата.
Delete | Удаляет указанный результат.
Mail | Создает почтовое событие.
SetEvent | Создает событие в модуле "Статистика".
SetStatus | Устанавливает указанный статус для указанного результата.
GetCount | Возвращает количество результатов указанной веб-формы.
GetPermissions | Возвращает массив прав на результат в зависимости от его статуса.


Add

CFormResult::Add

mixed
CFormResult::Add(
 int form_id,
 array values = false,
 string check_rights = "Y",
 int user_id = false
)

Создает новый результат веб-формы. В случае успеха - возвращает ID нового результата, в противном случае - "false".

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
values Массив со значениями ответов. Массив имеет следующую структуру:
array(
    "имя HTML поля ответа 1" => "значение ответа 1",
    "имя HTML поля ответа 2" => "значение ответа 2",
    ...
    "имя HTML поля ответа N" => "значение ответа N"
)
Правила формирования "имен HTML полей ответов" и "значений ответов" описаны в разделе "Имена HTML полей веб-форм".
Пример:
Array
(
    [form_text_586] => Иванов Иван Иванович
    [form_date_587] => 10.03.1992
    [form_textarea_588] => г. Мурманск
    [form_radio_VS_MARRIED] => 589
    [form_checkbox_VS_INTEREST] => Array
        (
            [0] => 592
            [1] => 593
            [2] => 594
        )

    [form_dropdown_VS_AGE] => 597
    [form_multiselect_VS_EDUCATION] => Array
        (
            [0] => 603
            [1] => 604
        )

    [form_text_606] => 2345
    [form_image_607] => 1045
)
Параметр необязательный. По умолчанию - "false" (будет взят стандартный массив $_REQUEST).
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для создания нового результата необходимо иметь право [10] Заполнение веб-формы на веб-форму form_id.

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).
user_id ID пользователя, который будет записан как создатель данного результата.

Параметр необязательный. По умолчанию - "false" (будет взят ID текущего пользователя).

См. также

  • CFormResult::Update
  • CFormResult::SetField;
  • CFormResult::GetDataByIDForHTML

Примеры использования

<?
// ID веб-формы
$FORM_ID = 4;

// массив описывающий загруженную на сервер фотографию
$arImage = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/photo.gif");

// массив значений ответов
$arValues = array (
    "form_text_586"                 => "Иванов Иван",    // "Фамилия, имя, отчество"
    "form_date_587"                 => "01.06.1904",     // "Дата рождения"
    "form_textarea_588"             => "г. Москва",      // "Адрес"
    "form_radio_VS_MARRIED"         => 590,              // "Женаты/замужем?"
    "form_checkbox_VS_INTEREST"     => array(612, 613),  // "Увлечения"
    "form_dropdown_VS_AGE"          => 601,              // "Возраст"
    "form_multiselect_VS_EDUCATION" => array(602, 603),  // "Образование"
    "form_text_606"                 => 300,              // "Доход"
    "form_image_607"                => $arImage          // "Фотография"
)

// создадим новый результат
if ($RESULT_ID = CFormResult::Add($FORM_ID, $arValues))
{
    echo "Результат #".$RESULT_ID." успешно создан";
}
else
{
    global $strError;
    echo $strError;
}
?>


Delete

CFormResult::Delete

bool
CFormResult::Delete(
 int result_id,
 string check_rights = "Y"
)

Удаляет указанный результат. В случае успеха функция возвращает "true", иначе - "false".

Параметры функции

Параметр | Описание
result_id | ID результата.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - права не нужно проверять.
Для успешного удаления результата необходимо обладать следующими правами:
  1. На веб-форму, к которой принадлежит редактируемый результат:

    [20] Работа со всеми результатами в соответствии с их статусами

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

    [15] Работа со своим результатом в соответствии с его статусом.
  2. На статус в котором находится редактируемый результат необходимо иметь право:

    [DELETE] удаление.
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CForm::Delete
  • CFormField::Delete;
  • CFormAnswer::Delete
  • CFormStatus::Delete

Примеры использования

<?
$RESULT_ID = 189; // ID результата

// удалим результат с проверкой прав текущего пользователя
if (CFormResult::Delete($RESULT_ID))
{
    echo "Результат # ".$RESULT_ID." успешно удален.";
}
else // ошибка
{
    global $strError;
    echo $strError;
}
?>


GetByID

CFormResult::GetByID

CDBResult
CFormResult::GetByID(
 int result_id
)

Возвращает поля результата, а также некоторые поля веб-формы и поля статуса в виде объекта класса CDBResult.

Структура массива в объекте, возвращаемого данной функцией:

Array
(
    [ID] => ID результата
    [TIMESTAMP_X] => время изменения результата
    [DATE_CREATE] => дата создания результата
    [FORM_ID] => ID веб-формы
    [USER_ID] => ID пользователя создавшего результат (автор)
    [USER_AUTH] => флаг авторизованности автора при создании результата [Y|N]
    [STAT_GUEST_ID] => ID посетителя создавшего результат
    [STAT_SESSION_ID] => ID сессии в которой был создан результат
    [STATUS_ID] => ID статуса в котором находится результат
    [STATUS_TITLE] => заголовок статуса в котором находится результат
    [STATUS_DESCRIPTION] => описание статуса в котором находится результат
    [STATUS_CSS] => имя CSS класса в котором находится результат
    [SID] => символьный идентификатор веб-формы
    [NAME] => заголовок веб-формы
    [IMAGE_ID] => ID изображения веб-формы
    [DESCRIPTION] => описание веб-формы
    [DESCRIPTION_TYPE] => тип описания веб-формы [text|html]
)

Параметры функции

Параметр | Описание
result_id | ID результата.

См. также

  • Поля CFormResult;
  • CFormResult::GetList
  • CFormResult::GetDataByID;
  • CForm::GetResultAnswerArray

Примеры использования

<?
$rsResult = CFormResult::GetByID(189);
$arResult = $rsResult->Fetch();
echo "<pre>"; print_r($arResult); echo "</pre>";
?>


GetCount

CFormResult::GetCount

int
CFormResult::GetCount(
 int form_id
)

Возвращает количество результатов указанной веб-формы.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.

Примеры использования

<?
$FORM_ID = 4; // ID веб-формы
echo "Количество результатов веб-формы #".$FORM_ID.": ".CFormResult::GetCount($FORM_ID);
?>


GetDataByID

CFormResult::GetDataByID

array
CFormResult::GetDataByID(
 int result_id,
 array field,
 array &result,
 array &answer
)

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

Формат массива возвращаемый функцией:

Array
(
  [символьный идентификатор вопроса 1] => массив описывающий ответы на вопрос 1
    Array
      (
        [0] => массив описывающий ответ 1
          Array
          (
            [RESULT_ID]           => ID результата
            [FIELD_ID]            => ID вопроса
            [SID]                 => символьный идентификатор вопроса
            [TITLE]               => текст вопроса
            [TITLE_TYPE]          => тип текста вопроса [text|html]
            [FILTER_TITLE]        => заголовок поля фильтра
            [RESULTS_TABLE_TITLE] => заголовок столбца таблицы результатов
            [ANSWER_ID]           => ID ответа
            [ANSWER_TEXT]         => параметр ответа ANSWER_TEXT
            [ANSWER_VALUE]        => параметр ответа ANSWER_VALUE
            [USER_TEXT]           => текст введенный с клавиатуры
            [USER_DATE]           => введенная дата (если FIELD_TYPE=date)
            [USER_FILE_ID]        => ID файла (если FIELD_TYPE=[file|image])
            [USER_FILE_NAME]      => имя файла
            [USER_FILE_IS_IMAGE]  => "Y" - FIELD_TYPE=image; "N" - FIELD_TYPE=file
            [USER_FILE_HASH]      => хэш файла (если FIELD_TYPE=file)
            [USER_FILE_SUFFIX]    => суффикс к расширению файла (если FIELD_TYPE=file)
            [USER_FILE_SIZE]      => размер файла (если FIELD_TYPE=[file|image])
            [FIELD_TYPE]          => тип ответа
            [FIELD_WIDTH]         => ширина поля ответа
            [FIELD_HEIGHT]        => высота поля ответа
            [FIELD_PARAM]         => параметр поля ответа
          )
        [1] => массив описывающий ответ 2
        [2] => массив описывающий ответ 3
        ...
        [N-1] => массив описывающий ответ N
      )
  [символьный идентификатор вопроса 2] => массив описывающий ответы на вопрос 2
  [символьный идентификатор вопроса 3] => массив описывающий ответы на вопрос 3
  ...
  [символьный идентификатор вопроса N] => массив описывающий ответы на вопрос N
)

Параметры функции

Параметр | Описание
result_id | ID результата.
field | Массив символьных идентификаторов вопросов или полей веб-формы, значения которых необходимо получить.
result Ссылка на массив полей результата, а также некоторых полей веб-формы и полей статуса. Структура данного массива:
Array
(
    [ID] => ID результата
    [TIMESTAMP_X] => время изменения результата
    [DATE_CREATE] => дата создания результата
    [FORM_ID] => ID веб-формы
    [USER_ID] => ID пользователя создавшего результат (автор)
    [USER_AUTH] => флаг авторизованности автора при создании результата [Y|N]
    [STAT_GUEST_ID] => ID посетителя создавшего результат
    [STAT_SESSION_ID] => ID сессии в которой был создан результат
    [STATUS_ID] => ID статуса в котором находится результат
    [STATUS_TITLE] => заголовок статуса в котором находится результат
    [STATUS_DESCRIPTION] => описание статуса в котором находится результат
    [STATUS_CSS] => имя CSS класса в котором находится результат
    [SID] => символьный идентификатор веб-формы
    [NAME] => заголовок веб-формы
    [IMAGE_ID] => ID изображения веб-формы
    [DESCRIPTION] => описание веб-формы
    [DESCRIPTION_TYPE] => тип описания веб-формы [text|html]
)
answer Ссылка на массив, описывающий значения ответов на вопросы или значения полей веб-формы для указанного результата result_id. Структура данного массива:
Array
(
  [символьный идентификатор вопроса 1] => массив описывающий ответы на вопрос 1
    Array
    (
      [ID ответа 1] => массив описывающий ответ 1
        Array
        (
          [RESULT_ID]           => ID результата
          [FIELD_ID]            => ID вопроса
          [SID]                 => символьный идентификатор вопроса
          [TITLE]               => текст вопроса
          [TITLE_TYPE]          => тип текста вопроса [text|html]
          [FILTER_TITLE]        => заголовок поля фильтра
          [RESULTS_TABLE_TITLE] => заголовок столбца таблицы результатов
          [ANSWER_ID]           => ID ответа
          [ANSWER_TEXT]         => параметр ответа ANSWER_TEXT
          [ANSWER_VALUE]        => параметр ответа ANSWER_VALUE
          [USER_TEXT]           => текст введенный с клавиатуры
          [USER_DATE]           => введенная дата (если FIELD_TYPE=date)
          [USER_FILE_ID]        => ID файла (FIELD_TYPE=[file|image])
          [USER_FILE_NAME]      => имя файла
          [USER_FILE_IS_IMAGE]  => "Y" - FIELD_TYPE=image; "N" - FIELD_TYPE=file
          [USER_FILE_HASH]      => хэш файла (если FIELD_TYPE=file)
          [USER_FILE_SUFFIX]    => суффикс к расширению файла (FIELD_TYPE=file)
          [USER_FILE_SIZE]      => размер файла (если FIELD_TYPE=[file|image])
          [FIELD_TYPE]          => тип ответа
          [FIELD_WIDTH]         => ширина поля ответа
          [FIELD_HEIGHT]        => высота поля ответа
          [FIELD_PARAM]         => параметр поля ответа
        )
      [ID ответа 2] => массив описывающий ответ 2
      [ID ответа 3] => массив описывающий ответ 3
      ...
      [ID ответа N] => массив описывающий ответ N
    )
  [символьный идентификатор вопроса 2] => массив описывающий ответы на вопрос 2
  [символьный идентификатор вопроса 3] => массив описывающий ответы на вопрос 3
  ...
  [символьный идентификатор вопроса N] => массив описывающий ответы на вопрос N
)

См. также

  • Поля CFormResult;
  • Поля CForm
  • CForm::GetResultAnswerArray

Примеры использования

<?
$RESULT_ID = 189; // ID результата

$arAnswer = CFormResult::GetDataByID(
    $RESULT_ID,
    array("VS_INTEREST"),  // вопрос "Какие области знаний вас интересуют?"
    $arResult,
    $arAnswer2);

// выведем поля результата
echo "<pre>"; print_r($arResult); echo "</pre>";

// выведем значения ответов
echo "<pre>"; print_r($arAnswer); echo "</pre>";

// выведем значения ответов в несколько ином формате
echo "<pre>"; print_r($arAnswer2); echo "</pre>";
?>

<?
$RESULT_ID = 189; // ID результата

// получим данные по всем вопросам
$arAnswer = CFormResult::GetDataByID(
    $RESULT_ID,
    array(),
    $arResult,
    $arAnswer2);

// выведем поля результата
echo "<pre>"; print_r($arResult); echo "</pre>";

// выведем значения ответов
echo "<pre>"; print_r($arAnswer); echo "</pre>";

// выведем значения ответов в несколько ином формате
echo "<pre>"; print_r($arAnswer2); echo "</pre>";
?>


GetDataByIDForHTML

CFormResult::GetDataByIDForHTML

array
CFormResult::GetDataByIDForHTML(
 int result_id,
 string get_fields = "N"
)

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

Ключи возвращаемого массива в точности соответствуют правилам формирования имен HTML полей для веб-формы.

Пример массива, возвращаемого функцией:

Array
(
    [form_text_586] => Иванов Иван Иванович
    [form_date_587] => 10.03.1992
    [form_textarea_588] => г. Мурманск
    [form_radio_VS_MARRIED] => 589
    [form_checkbox_VS_INTEREST] => Array
        (
            [0] => 592
            [1] => 593
            [2] => 594
        )

    [form_dropdown_VS_AGE] => 597
    [form_multiselect_VS_EDUCATION] => Array
        (
            [0] => 603
            [1] => 604
        )

    [form_text_606] => 2345
    [form_image_607] => 1045
)

Параметры функции

Параметр | Описание
result_id | ID результата.
get_fields | Если значение данного параметра равно "Y", то в в массиве возвращаемом данной функцией будет также значения полей веб-формы; в противном случае, в возвращаемом массиве будут только значения ответов на вопросов веб-формы. Параметр необязательный. По умолчанию - "N".

См. также

  • Имена HTML полей
  • CFormResult::Add
  • CFormResult::Update
  • CForm::Check

Примеры использования

<?
$RESULT_ID = 189; // ID результата

// получим данные результата
$arValues = CFormResult::GetDataByIDForHTML($RESULT_ID, "Y");

// выведем ответ на вопрос "Фамилия, имя, отчество"
echo $arValues["form_text_586"]; // "Иванов Василий"

// выведем фотографию загруженную в качестве ответа на вопрос "Фотография"
CFile::ShowImage($arValues["form_image_607"], 200, 200, "border=0", "", true);

// выведем значение поля веб-формы "Рассчитанная стоимость"
echo $arValues["form_textarea_ADDITIONAL_149"]; // 134 руб.
?>


GetFileByAnswerID

CFormResult::GetFileByAnswerID

mixed
CFormResult::GetFileByAnswerID(
 int result_id,
 int answer_id
)

Возвращает массив, содержащий ряд параметров файла, загруженного в поле ответа типа "image" или "file" для указанного результата. В случае успеха функция возвратит массив, в противном случае - "false".

Структура возвращаемого массива:

Array
(
  [USER_FILE_ID]        => ID файла
  [USER_FILE_NAME]      => имя файла
  [USER_FILE_IS_IMAGE]  => "Y" - если тип ответа "image"; "N" - если тип ответа "file"
  [USER_FILE_HASH]      => хэш файла (если тип ответа "file")
  [USER_FILE_SUFFIX]    => суффикс к расширению файла (если тип ответа "file")
  [USER_FILE_SIZE]      => размер файла в байтах
)

Параметры функции

Параметр | Описание
result_id | ID результата.
answer_id | ID ответа.

См. также

  • CFormResult::GetDataByID

Примеры использования

<?
$RESULT_ID = 189; // ID результата
$ANSWER_ID = 148; // ID ответа

// получим данные по изображению
$arImage = CFormResult::GetFileByAnswerID($RESULT_ID, $ANSWER_ID);

// выведем изображение
echo CFile::ShowImage($arImage["USER_FILE_ID"], 0, 0, "border=0", "", true);
?>


GetList

CFormResult::GetList

CDBResult
CFormResult::GetList(
 int form_id,
 string &by = "s_timestamp",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 string check_rights = "Y",
 mixed limit = false
)

Возвращает список результатов веб-формы в виде объекта класса CDBResult.

Примечание
Возвращаемый список содержит только поля результата. Значения ответов и полей можно получить с помощью функции CForm::GetResultAnswerArray или CFormResult::GetDataByID.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
by Ссылка на переменную с полем для сортировки; может принимать значения:
  • s_id - ID результата;
  • s_date_create - дата создания;
  • s_timestamp - дата изменения (значение по умолчанию);
  • s_user_id - ID пользователя, создавшего результат;
  • s_guest_id - ID посетителя, создавшего результат;
  • s_session_id - ID сессии, в которой был создан результат;
  • s_status - ID статуса.
order Ссылка на переменную с порядком сортировки. Допустимы следующие значения:
  • desc - по убыванию (значение по умолчанию);
  • asc - по возрастанию.
filter Массив содержащий параметры фильтра. В массиве допустимы следующие ключи:
  • ID* - ID результата (по умолчанию будет искаться точное совпадение);
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • STATUS_ID* - ID статуса (по умолчанию будет искаться точное совпадение);
  • STATUS_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по STATUS_ID будет искаться вхождение;
  • TIMESTAMP_1 - левое значение интервала ("с") по дате изменения (задается в формате даты текущего сайта);
  • TIMESTAMP_2 - правое значение интервала ("по") по дате изменения (задается в формате даты текущего сайта);
  • DATE_CREATE_1 - левое значение интервала ("с") по дате создания (задается в формате даты текущего сайта);
  • DATE_CREATE_2 - правое значение интервала ("по") по дате создания (задается в формате даты текущего сайта);
  • TIME_CREATE_1 - левое значение интервала ("с") по дате создания в полном формате (дата и время);
  • TIME_CREATE_2 - правое значение интервала ("по") по дате создания в полном формате (дата и время);
  • REGISTERED - флаг зарегистрированности автора результата; допустимы следующие значения:
    • Y - автор был зарегистрирован как пользователь;
    • N - автор не был зарегистрирован как пользователь.
  • USER_AUTH - флаг авторизованности автора результата; допустимы следующие значения:
    • Y - автор был авторизован;
    • N - автор не был авторизован.
  • USER_ID* - ID пользователя, создавшего результат (автор результата) (по умолчанию будет искаться точное совпадение);
  • USER_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по USER_ID будет искаться вхождение;
  • GUEST_ID* - ID посетителя создавшего результат (автор результата) (по умолчанию будет искаться точное совпадение);
  • GUEST_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по GUEST_ID будет искаться вхождение;
  • SESSION_ID* - ID сессии в которой был создан результат (по умолчанию будет искаться точное совпадение);
  • SESSION_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SESSION_ID будет искаться вхождение;
  • FIELDS - массив, содержащий параметры фильтра для фильтрации результатов по значениям ответов и полей веб-формы. Каждый элемент данного массива представляет из себя массив, описывающий параметры фильтра по вопросу или полю веб-формы; ключами подобного массива могут быть:
    • SID - символьный идентификатор вопроса или поля веб-формы;
    • PARAMETER_NAME - тип данных по которым фильтруем, допустимы следующие значения:
      • USER - фильтруем по ответам введенных авторами с клавиатуры;
      • ANSWER_TEXT - фильтруем по параметру ANSWER_TEXT;
      • ANSWER_VALUE - фильтруем по параметру ANSWER_VALUE.
    • VALUE - значение, по которому фильтруем (допускается сложная логика);
    • FILTER_TYPE - тип фильтра, определяет, как интерпретировать данные по которым фильтруем:
      • integer - означает, что данные, по которым будет осуществляться фильтрация, считать числами (используется только с PARAMETER_NAME=[USER|ANSWER_TEXT|ANSWER_VALUE]);
      • text - означает, что данные, по которым будет осуществляться фильтрация, должны обрабатываться как текстовые поля (используется только с PARAMETER_NAME=[USER|ANSWER_TEXT|ANSWER_VALUE]);
      • date - означает, что данные по которым будет осуществляться фильтрация, должны обрабатываться как даты (используется только с PARAMETER_NAME=USER);
      • answer_id - означает, что фильтрация будет производиться только по прямому совпадению с ID ответа (при этом PARAMETER_NAME не имеет значения).
    • PART - если тип фильтра FILTER_TYPE=[integer|date], то данное поле должносодержать одно из трех значений:
      • 0 - прямое совпадение со значением;
      • 1 - левое значение интервала ("с");
      • 2 - правое значение интервала ("по")
    • EXACT_MATCH - если FILTER_TYPE="text", то в данном поле можно задать следующие значения:
      • Y - прямое совпадение;
      • N - будет искаться вхождение (по умолчанию).
is_filtered | Ссылка на переменную хранящую флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - права не нужно проверять.
Для того чтобы результат попал в результирующий список, необходимо обладать следующими правами:
  1. На веб-форму form_id:

    [20] Работа со всеми результатами в соответствии с их статусами

    или

    [15] Работа со своим результатом в соответствии с его статусом - в этом случае результирующий список будет состоять только из тех результатов создателем которых является текущий пользователь.
  2. На статус, в котором находится результат, необходимо иметь право:

    [VIEW] просмотр

    или

    [EDIT] редактирование

    или

    [DELETE] удаление
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).
limit Максимальное количество результатов, которые войдут в результирующий список.

Параметр необязательный. По умолчанию - "false" (без ограничений).

См. также

  • Поля CFormResult
  • CFormResult::GetDataByID
  • CForm::GetResultAnswerArray

Примеры использования

<?
// ID веб-формы
$FORM_ID = 4;

// фильтр по полям результата
$arFilter = array(
    "ID"                   => "12"              // ID результата
    "ID_EXACT_MATCH"       => "N"               // вхождение
    "STATUS_ID"            => "9 | 10",         // статус
    "TIMESTAMP_1"          => "10.10.2003",     // изменен "с"
    "TIMESTAMP_2"          => "15.10.2003",     // изменен "до"
    "DATE_CREATE_1"        => "10.10.2003",     // создан "с"
    "DATE_CREATE_2"        => "12.10.2003",     // создан "до"
    "REGISTERED"           => "Y",              // был зарегистрирован
    "USER_AUTH"            => "N",              // не был авторизован
    "USER_ID"              => "45 | 35",        // пользователь-автор
    "USER_ID_EXACT_MATCH"  => "Y",              // точное совпадение
    "GUEST_ID"             => "4456 | 7768",    // посетитель-автор
    "SESSION_ID"           => "456456 | 778768" // сессия
    );

// фильтр по вопросам
$arFields = array();

$arFields[] = array(
    "CODE"              => "GAME_ID",       // код поля по которому фильтруем
    "FILTER_TYPE"       => "integer",       // фильтруем по числовому полю
    "PARAMETER_NAME"    => "USER",          // по значению введенному с клавиатуры
    "VALUE"             => $arGame["ID"],   // значение по которому фильтруем
    "PART"              => 0                // прямое совпадение со значением (не интервал)
    );

$arFields[] = array(
    "CODE"              => "GAME_NAME",     // код поля по которому фильтруем
    "FILTER_TYPE"       => "text",          // фильтруем по числовому полю
    "PARAMETER_NAME"    => "USER",          // фильтруем по введенному значению
    "VALUE"             => "Tetris",        // значение по которому фильтруем
    "EXACT_MATCH"       => "Y"              // ищем точное совпадение
    );

$arFields[] = array(
    "CODE"              => "GENRE_ID",      // код поля по которому фильтруем
    "FILTER_TYPE"       => "integer",       // фильтруем по числовому полю
    "PARAMETER_NAME"    => "ANSWER_VALUE",  // фильтруем по параметру ANSWER_VALUE
    "VALUE"             => "3",             // значение по которому фильтруем
    "PART"              => 1                // с
    );

$arFields[] = array(
    "CODE"              => "GENRE_ID",      // код поля по которому фильтруем
    "FILTER_TYPE"       => "integer",       // фильтруем по числовому полю
    "PARAMETER_NAME"    => "ANSWER_VALUE",  // фильтруем по параметру ANSWER_VALUE
    "VALUE"             => "6",             // значение по которому фильтруем
    "PART"              => 2                // по
    );

$arFilter["FIELDS"] = $arFields;

// выберем первые 10 результатов
$rsResults = CFormResult::GetList($FORM_ID,
    ($by="s_timestamp"),
    ($order="desc"),
    $arFilter,
    $is_filtered,
    "Y",
    10);
while ($arResult = $rsResults->Fetch())
{
    echo "<pre>"; print_r($arResult); echo "</pre>";
}


GetPermissions

CFormResult::GetPermissions

array
CFormResult::GetPermissions(
 int result_id,
 int &current_status_id
)

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

В результирующем массиве могут быть следующие символьные обозначения прав:

  • VIEW - право на просмотр результата;
  • EDIT - право на редактирование результата;
  • DELETE - право на удаление результата.

Примечание
Права на результат, по сути, являются правами на статус, в котором находится данный результат.

Параметры функции

Параметр | Описание
result_id | ID результата.
current_status_id | Ссылка на переменную, в которую будет сохранен ID статуса, указанного результата result_id.

См. также

  • Права на результат
  • CFormStatus::GetPermissions
  • CFormStatus::GetPermissionList
  • CForm::GetPermission

Примеры использования

<?
$RESULT_ID = 189; // ID результата

// получим массив прав
$arPerm = CFormResult::GetPermissions($RESULT_ID, $current_status_id);

echo "Результат #".$RESULT_ID." находится в статусе ".$current_status_id;

if (in_array("VIEW", $arPerm))
    echo "У вас есть право на просмотр результата #".$RESULT_ID;

if (in_array("EDIT", $arPerm))
    echo "У вас есть право на редактирование результата #".$RESULT_ID;

if (in_array("DELETE", $arPerm))
    echo "У вас есть право на удаление результата #".$RESULT_ID;
?>


Mail

CFormResult::Mail

bool
CFormResult::Mail(
 int result_id,
 mixed template_id = false
)

Создает почтовое событие для отсылки данных результата по e-mail. Возвращает "true" в случае успеха, в противном случае - "false".

Параметры функции

Параметр | Описание
result_id | ID результата.
template_id | ID почтового шаблона. Параметр необязательный. По умолчанию - "false" (будут использованы почтовые шаблоны из настроек соответствующей веб-формы).

Примеры использования

<?
$RESULT_ID = 189; // ID результата

// создадим почтовое событие для отсылки по EMail данных результата
if (CFormResult::Mail($RESULT_ID))
{
    echo "Почтовое событие успешно создано.";
}
else // ошибка
{
    global $strError;
    echo $strError;
}
?>


Reset

CFormResult::Reset

bool
CFormResult::Reset(
 int result_id,
 bool del_files = true,
 string del_fields = "N",
 array exception = array()
)

Удаляет все значения ответов на вопросы веб-формы, а также значения полей веб-формы для указанного результата. Сам результат при этом остается. Если в процессе работы функции ошибок не возникло, то функция возвращает "true".

Параметры функции

Параметр | Описание
result_id | ID результата.
del_files | Флаг необходимости удаления файлов, загруженных в качестве значения ответа на вопрос. Параметр необязательный. По умолчанию - "true" (файлы необходимо удалить).
del_fields | Флаг необходимости удаления значений полей веб-формы. Параметр необязательный. По умолчанию - "N" (значения полей необходимо удалить).
exception | Массив ID вопросов и полей веб-формы, для которых не нужно удалять значения. Параметр необязательный. По умолчанию - пустой массив.

См. также

  • CForm::Reset;
  • CFormField::Reset

Примеры использования

<?
$RESULT_ID = 189; // ID результата

// удалим все значения ответов на вопросы и полей веб-формы
// вместе с файлами
// исключение составят вопросы с ID = 140 и ID = 141
CFormResult::Reset($RESULT_ID, true, "Y", array(140, 141));
?>


SetEvent

CFormResult::SetEvent

bool
CFormResult::SetEvent(
 int result_id,
 string event1 = false,
 string event2 = false,
 string event3 = false,
 mixed money = "",
 mixed currency = "",
 mixed goto = "",
 mixed chargeback = "N"
)

Создает событие в модуле "Статистика". Возвращает "true" в случае успеха, в противном случае - "false".

Параметры функции

Параметр | Описание
result_id | ID результата.
event1 | Идентификатор типа события - event1. Параметр необязательный. По умолчанию - "false" (будет равен "form").
event2 | Идентификатор типа события - event2. Параметр необязательный. По умолчанию - "false" (будет равен символьному идентификатору соответствующей веб-формы).
event3 | Дополнительный параметр события - event3. Параметр необязательный. По умолчанию - "false" (будет равен ссылке, ведущей на административную страницу просмотра результата result_id).
money | Денежная сумма события. Параметр необязательный. По умолчанию - "".
currency | Трехсимвольный идентификатор валюты денежной суммы money. Параметр необязательный. По умолчанию - "".
chargeback | Если в данный параметр передано значение "Y", при создании события в модуле "Статистика" денежная сумма money будет зафиксирована с отрицательным знаком. Параметр необязательный. По умолчанию - "N".

Примеры использования

<?
$RESULT_ID = 189; // ID результата

// создадим событие в модуле "Статистика"
if (CFormResult::SetEvent($RESULT_ID))
{
    echo "Событие успешно создано.";
}
else // ошибка
{
    global $strError;
    echo $strError;
}
?>


SetField

CFormResult::SetField

CFormResult::SetField(
 int result_id,
 string field_sid,
 mixed value = false
)

Для указанного результата обновляет значения ответа на вопрос или обновляет значение поля.

Параметры функции

Параметр | Описание
result_id | ID результата.
field_sid | Символьный идентификатор вопроса или поля.
value Значение, которое необходимо сохранить. В зависимости от типа обновляемого поля, данный параметр имеет различный формат.
  • При обновлении значения поля, в данном параметре достаточно указать новое значение обновляемого поля.
  • При обновлении значений ответов на вопрос, формат данного параметра следующий:
    array (
        ID ответа 1 => значение ответа 1,
        ID ответа 2 => значение ответа 2,
    ...
)
    Если ответ принадлежит к одним из следующих типов:
    • radio - переключатель одиночного выбора (radio-кнопка);
    • checkbox - флаг множественного выбора (checkbox);
    • dropdown - элемент выпадающего списка одиночного выбора;
    • multiselect - элемент списка множественного выбора,
    то в качестве "значения ответа" достаточно указать "" (пустое значение).

    Если ответ имеет один из следующих типов:
    • text - однострочное текстовое поле;
    • textarea - многострочное текстовое поле;
    • date - поле для ввода даты;
    • password - поле для ввода пароля,
    то в качестве "значения ответа" необходимо указать значение, которое могло бы быть введено с клавиатуры при ответе на данный вопрос.

    Если ответ имеет один из следующих типов:
    • image - поле для загрузки изображения;
    • file - поле для загрузки произвольного файла.
    то в качестве "значения ответа" необходимо указать массив, описывающий файл и имеющий следующий ключи:
    • name - имя файла;
    • size - размер файла;
    • tmp_name - временный путь на сервере;
    • type - тип загружаемого файла.
    Такой массив можно получить с помощью функции CFile::MakeFileArray.
Параметр value необязательный. По умолчанию - false (значение поля или значение ответа на вопрос будут просто удалены).

См. также

  • CFormResult::Update
  • CFile::MakeFileArray

Примеры использования

$RESULT_ID = 186;

/**************************************************************
            Обновление значений ответов на вопросы
**************************************************************/

// обновим ответ на вопрос "Фамилия, имя, отчество"
$arVALUE = array();
$FIELD_SID = "VS_NAME"; // символьный идентификатор вопроса
$ANSWER_ID = 586; // ID поля ответа
$arVALUE[$ANSWER_ID] = "Иванов Иван";
CFormResult::SetField($RESULT_ID, $FIELD_SID, $arVALUE);

// обновим ответ на вопрос "Дата рождения"
$arVALUE = array();
$FIELD_SID = "VS_BIRTHDAY"; // символьный идентификатор вопроса
$ANSWER_ID = 587; // ID поля ответа
$arVALUE[$ANSWER_ID] = "18.06.1975";
CFormResult::SetField($RESULT_ID, $FIELD_SID, $arVALUE);

// обновим ответ на вопрос "Какие области знаний вас интересуют?"
$arVALUE = array();
$FIELD_SID = "VS_INTEREST"; // символьный идентификатор вопроса
$arVALUE[612] = ""; // ID поля ответа "математика"
$arVALUE[613] = ""; // ID поля ответа "физика"
$arVALUE[614] = ""; // ID поля ответа "история"
CFormResult::SetField($RESULT_ID, $FIELD_SID, $arVALUE);

// обновим ответ на вопрос "Фотография"
$arVALUE = array();
$FIELD_SID = "VS_PHOTO"; // символьный идентификатор вопроса
$ANSWER_ID = 607; // ID поля ответа
$path = $_SERVER["DOCUMENT_ROOT"]."/images/news.gif"; // путь к файлу
$arVALUE[$ANSWER_ID] = CFile::MakeFileArray($path);
CFormResult::SetField($RESULT_ID, $FIELD_SID, $arVALUE);

// обновим ответ на вопрос "Резюме"
$arVALUE = array();
$FIELD_SID = "VS_RESUME"; // символьный идентификатор вопроса
$ANSWER_ID = 610; // ID поля ответа
$path = $_SERVER["DOCUMENT_ROOT"]."/docs/alawarauthorarea.doc"; // путь к файлу
$arVALUE[$ANSWER_ID] = CFile::MakeFileArray($path);
CFormResult::SetField($RESULT_ID, $FIELD_SID, $arVALUE);

/**************************************************************
                Обновление значений полей
**************************************************************/

// обновим значение поля "Рассчитанная стоимость"
$FIELD_SID = "VS_PRICE"; // символьный идентификатор вопроса
$VALUE = "155";
CFormResult::SetField($RESULT_ID, $FIELD_SID, $VALUE);
?>


SetStatus

CFormResult::SetStatus

bool
CFormResult::SetStatus(
 int result_id,
 int status_id,
 string check_rights = "Y"
)

Устанавливает новый статус для результата. Возвращает "true" в случае успеха, в противном случае - "false".

Параметры функции

Параметр | Описание
result_id | ID результата.
status_id | ID нового статуса.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - права не нужно проверять.
Для успешной установки нового статуса для указанного результата необходимо обладать следующими правами:
  1. На веб-форму к которой принадлежит редактируемый результат:

    [20] Работа со всеми результатами в соответствии с их статусами

    или, в случае, если вы являетесь создателем удаляемого результата, достаточно права:

    [15] Работа со своим результатом в соответствии с его статусом
  2. На статус, в котором находится редактируемый результат, необходимо иметь право:

    [EDIT] редактирование
  3. На новый статус status_id необходимо иметь право:

    [MOVE] перевод результатов в данный статус
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

Примеры использования

<?
$RESULT_ID = 189; // ID результата
$STATUS_ID = 1; // ID статуса "Опубликовано"

// установим новый статус для результата
// с проверкой прав текущего пользователя
if (CFormResult::SetStatus($RESULT_ID, $STATUS_ID))
{
    echo "Статус #".$STATUS_ID." для результата #".$RESULT_ID." успешно установлен.";
}
else // ошибка
{
    global $strError;
    echo $strError;
}
?>


Update

CFormResult::Update

bool
CFormResult::Update(
 int result_id,
 array values = false,
 string update_fields = "N",
 string check_rights = "Y"
)

Обновляет все значения ответов и полей результата веб-формы. В случае успеха возвращает "true", в противном случае - "false".

Параметры функции

Параметр | Описание
result_id | ID результата.
values Массив со значениями ответов и полей веб-формы. Массив имеет следующую структуру:
array(
    "имя HTML поля 1" => "значение 1",
    "имя HTML поля 2" => "значение 2",
    ...
    "имя HTML поля N" => "значение N"
)
Правила формирования "имен HTML полей" и "значений" можно посмотреть здесь.
Пример:
Array
(
    [form_text_586] => Иванов Иван Иванович
    [form_date_587] => 10.03.1992
    [form_textarea_588] => г. Мурманск
    [form_radio_VS_MARRIED] => 589
    [form_checkbox_VS_INTEREST] => Array
        (
            [0] => 592
            [1] => 593
            [2] => 594
        )

    [form_dropdown_VS_AGE] => 597
    [form_multiselect_VS_EDUCATION] => Array
        (
            [0] => 603
            [1] => 604
        )

    [form_text_606] => 2345
    [form_image_607] => 1045
    [form_textarea_ADDITIONAL_149] => 155
)
Параметр необязательный. По умолчанию - "false" (будет взят стандартный массив $_REQUEST).
update_fiels Флаг необходимости обновления полей веб-формы. Возможны следующие значения:
  • Y - необходимо обновить;
  • N - не нужно обновлять.
Параметр необязательный. По умолчанию - "N" (не нужно обновлять).
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - права не нужно проверять.
Для успешного обновления результата необходимо обладать следующими правами:
  1. На веб-форму, к которой принадлежит редактируемый результат:

    [20] Работа со всеми результатами в соответствии с их статусами

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

    [15] Работа со своим результатом в соответствии с его статусом
  2. На статус, в котором находится редактируемый результат, необходимо иметь право:

    [EDIT] редактирование
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CFormResult::SetField
  • CFormResult::GetDataByIDForHTML
  • CFormResult::Add

Примеры использования

<?
// ID результата
$RESULT_ID = 186;

// массив описывающий загруженную на сервер фотографию
$arImage = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/photo.gif");

// массив значений ответов и полей веб-формы
$arValues = array (
    "form_text_586"                 => "Иванов Иван",    // "Фамилия, имя, отчество"
    "form_date_587"                 => "01.06.1904",     // "Дата рождения"
    "form_textarea_588"             => "г. Москва",      // "Адрес"
    "form_radio_VS_MARRIED"         => 590,              // "Женаты/замужем?"
    "form_checkbox_VS_INTEREST"     => array(612, 613),  // "Увлечения"
    "form_dropdown_VS_AGE"          => 601,              // "Возраст"
    "form_multiselect_VS_EDUCATION" => array(602, 603),  // "Образование"
    "form_text_606"                 => 300,              // "Доход"
    "form_image_607"                => $arImage,         // "Фотография"
    "form_textarea_ADDITIONAL_149"  => "155 рублей"      // "Рассчитанная сумма"
)

//обновим результат
if (CFormResult::Update($RESULT_ID, $arValues, "Y"))
{
    echo "Результат #".$RESULT_ID." успешно обновлен.";
}
else
{
    global $strError;
    echo $strError;
}
?>


Класс CFormStatus

CFormStatus - класс для работы со статусами.

Поля

Поле | Тип | Описание
ID | int | Идентификатор статуса.
FORM_ID | int | Идентификатор веб-формы.
TIMESTAMP_X | datetime | Время последнего изменения параметров статуса.
ACTIVE | char | Флаг активности статуса [Y|N].
C_SORT | int | Индекс сортировки статуса.
TITLE | varchar(255) | Заголовок статуса.
DESCRIPTION | varchar(2000) | Описание статуса.
DEFAULT_VALUE | char | Флаг установки у результата данного статуса по умолчанию [Y|N].
CSS | varchar(255) | Имя CSS класса для вывода заголовка статуса.
HANDLER_OUT | varchar(255) | Путь относительно корня к обработчику, вызываемому при смене у результата данного статуса на другой.
HANDLER_IN | varchar(255) | Путь относительно корня к обработчику, вызываемому при смене у результата какого-либо статуса на данный.

Методы

Метод | Описание
Set | Добавляет новый статус либо обновляет параметры существующего.
GetList | Возвращает список статусов указанной веб-формы.
GetByID | Возвращает параметры статуса.
Copy | Копирует статус.
Delete | Удаляет статус.
GetPermissions | Возвращает массив прав текущего пользователя для указанного статуса.
GetPermissionList | Возвращает массивы групп пользователей с определёнными правами для указанного статуса.
GetDropdown | Возвращает список статусов в формате для вывода выпадающего списка одиночного выбора.


Copy

CFormStatus::Copy

mixed
CFormStatus::Copy(
 int status_id,
 string check_rights = "Y",
 mixed form_id = false
)

Копирует статус. Возвращает ID нового статуса в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр | Описание
status_id | ID статуса который необходимо скопировать.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для копирования статуса необходимо обладать нижеследующими правами:
  1. [25] просмотр параметров веб-формы на ту веб-форму, из которой идет копирование;
  2. [30] полный доступ на ту веб-форму, в которую копируется.
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).
form_id ID веб-формы в который необходимо скопировать статус.
Необязательный параметр. По умолчанию - "false" (текущая веб-форма).

См. также

  • CForm::Copy
  • CFormField::Copy
  • CFormAnswer::Copy

Примеры использования

<?
$status_id = 1; // ID статуса
// скопируем статус
if ($NEW_STATUS_ID = CFormStatus::Copy($status_id))
{
    echo "Статус #1 успешно скопирован в новый статус #".$NEW_STATUS_ID;
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


Delete

CFormStatus::Delete

bool
CFormStatus::Delete(
 int status_id,
 string check_rights = "Y"
)

Удаляет статус. Возвращает "true" в случае положительного результата, и "false" - в противном случае.

Примечание
Статусы, в которых находится хотя бы один результат, невозможно удалить.

Параметры функции

Параметр | Описание
status_id | ID удаляемого статуса.
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для успешного выполнения удаления необходимо иметь право [30] Полный доступ на веб-форму, к которой принадлежит status_id.
Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • CForm::Delete
  • CFormField::Delete
  • CFormAnswer::Delete
  • CFormResult::Delete

Примеры использования

<?
$status_id = 1; // ID статуса
// удалим статус
if (CFormStatus::Delete($status_id))
{
    echo "Статус #1 успешно удален.";
}
else
{
    // выведем текст ошибки
    global $strError;
    echo $strError;
}
?>


GetByID

CFormStatus::GetByID

CDBResult
CFormStatus::GetByID(
 int status_id
)

Возвращает параметры статуса в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
status_id | ID статуса.

См. также

  • Поля CFormStatus
  • CFormStatus::GetList

Примеры использования

<?
$status_id = 1; // ID статуса
$rsStatus = CFormStatus::GetByID($status_id);
$arStatus = $rsStatus->Fetch();
echo "<pre>"; print_r($arStatus); echo "</pre";
?>


GetDropDown

CFormStatus::GetDropDown

CDBResult
CFormStatus::GetDropDown(
 int form_id,
 array permission = array("MOVE"),
 int owner_user_id = 0
)

Возвращает список статусов в виде объекта класса CDBResult в формате, пригодном для вывода выпадающего списка одиночного выбора.

Результирующий список будет состоять из статусов указанной веб-формы form_id. Статус будет включен в результирующий список только в том случае, если текущий пользователь обладает хотя бы одним из прав, указанных в параметре permission.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
permission Массив прав, одним из которых должен обладать текущий пользователь. В данном массиве возможны следующие значения:
  • VIEW - право на просмотр;
  • MOVE - право на перевод;
  • EDIT - право на редактирование;
  • DELETE - право на удаление.
Параметр необязательный. По умолчанию - array("MOVE") (право на перевод результатов в соответствующий статус).
owner_user_id Если данная функция используется для построения выпадающего списка доступных статусов конкретного результата, то в данном параметре необходимо указать ID пользователя, создавшего данный результат (владелец результата, поле результата - USER_ID).

Параметр необязательный. По умолчанию - 0.

См. также

  • Права на результат

Примеры использования

<?
$FORM_ID = 4; // ID веб-формы

// получим список всех доступных статусов
// для которых есть право просмотра у текущего пользователя
$rsStatuses = CFormStatus::GetDropdown($FORM_ID, array("VIEW"));

// выведем выпадающий список
echo SelectBox("STATUS_ID", $rsStatuses, "(выберете статус)", htmlspecialchars($STATUS_ID));
?>


GetList

CFormStatus::GetList

CDBResult
CFormStatus::GetList(
 int form_id,
 string &by = "s_sort",
 string &order = "asc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список статусов в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
form_id | ID веб-формы.
by Ссылка на переменную с полем для сортировки результирующего списка, может принимать значения:
  • s_id - ID статуса;
  • s_sort - индекс сортировки;
  • s_timestamp - время последнего изменения статуса;
  • s_active - флаг активности;
  • s_default - флаг установки по умолчанию;
  • s_title - заголовок;
  • s_description - описание;
  • s_results - количество результатов находящихся в данном статусе.
оrder Ссылка на переменную с порядком сортировки, может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации. В массиве допустимы следующие ключи:
  • ID* - ID статуса (по умолчанию будет искаться точное совпадение);
  • ID_EXACT_MATCH - если значение равно "N", при фильтрации по ID будет искаться вхождение;
  • ACTIVE - флаг активности, допустимые следующие значения:
    • Y - статус активен;
    • N - статус не активен.
  • TITLE* - заголовок статуса (по умолчанию будет искаться вхождение);
  • TITLE_EXACT_MATCH - если значение равно "Y", то при фильтрации по TITLE будет искаться точное совпадение;
  • DESCRIPTION* - описание статуса (по умолчанию будет искаться вхождение);
  • DESCRIPTION_EXACT_MATCH - если значение равно "Y", то при фильтрации по DESCRIPTION будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Ссылка на переменную хранящую флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

См. также

  • Поля CFormStatus
  • CFormStatus::GetByID

Примеры использования

<?
$FORM_ID = 4; // ID веб-формы

// сформируем массив фильтра
$arFilter = Array(
    "ID"                       => "1 | 4",       // ID статуса равен 1 или 4
    "ID_EXACT_MATCH"           => "Y",           // точное совпадение для ID
    "ACTIVE"                   => "Y",           // флаг активности
    "TITLE"                    => "опубликован", // заголовок
    "TITLE_EXACT_MATCH"        => "N",           // точное совпадение для TITLE
    "DESCRIPTION"              => "конечный",    // описание
    "DESCRIPTION_EXACT_MATCH"  => "N",           // точное совпадение для DESCRIPTION
);

// получим список всех ответов вопроса #143
$rsStatuses = CFormStatus::GetList(
    $FORM_ID,
    $by="s_id",
    $order="desc",
    $arFilter,
    $is_filtered
    );
while ($arStatus = $rsStatuses->Fetch())
{
    echo "<pre>"; print_r($arStatus); echo "</pre>";
}
?>


GetPermissionList

CFormStatus::GetPermissionList

CFormStatus::GetPermissionList(
 int status_id,
 array &can_view,
 array &can_move,
 array &can_edit,
 array &can_delete
)

Возвращает массивы групп пользователей, имеющих определённые права на указанный статус.

Параметры функции

Параметр | Описание
status_id | ID статуса.
can_view | Ссылка на массив для хранения ID групп пользователей, обладающих правом на просмотр результата, находящемся в статусе status_id.
can_move | Ссылка на массив для хранения ID групп пользователей, обладающих правом перевода результатов в статус status_id.
can_edit | Ссылка на массив для хранения ID групп пользователей, обладающих правом редактирования результатов, находящихся в статусе status_id.
can_edit | Ссылка на массив для хранения ID групп пользователей, обладающих правом удаления результатов, находящихся в статусе status_id.

См. также

  • Права на результат
  • CForm::GetPermission
  • CFormResult::GetPermissions

Примеры использования

<?
$STATUS_ID = 1;

// получим массив групп обладающих определёнными правами на статус #1
CFormStatus::GetPermissionList($STATUS_ID, $arVIEW, $arMOVE, $arEDIT, $arDELETE);

// выведем массив групп обладающих правом
// просмотра результатов находящихся в статусе #1
echo "<pre>"; print_r($arVIEW); echo "</pre>";

// выведем массив групп обладающих правом
// перевода результатов в статус #1
echo "<pre>"; print_r($arMOVE); echo "</pre>";

// выведем массив групп обладающих правом
// редактирования результатов находящихся в статусе #1
echo "<pre>"; print_r($arEDIT); echo "</pre>";

// выведем массив групп обладающих правом
// удаления результатов находящихся в статусе #1
echo "<pre>"; print_r($arDELETE); echo "</pre>";

?>


GetPermissions

CFormStatus::GetPermissions

array
CFormStatus::GetPermissions(
 int status_id
)

Возвращает массив прав текущего пользователя на указанный статус. В качестве значений данного массива допустимы:

  • VIEW - право на просмотр результатов в данном статусе;
  • MOVE - право на перевод результатов в данный статус;
  • EDIT - право на редактирование результатов в данном статусе;
  • DELETE - право на удаление результатов в данном статусе.

Параметры функции

Параметр | Описание
status_id | ID статуса.

См. также

  • Права на результат
  • CForm::GetPermission
  • CFormResult::GetPermissions

Примеры использования

<?
$STATUS_ID = 1;

// получим права текущего пользователя для указанного статуса
$arPerm = CFormStatus::GetPermissions($STATUS_ID);

if (in_array("VIEW", $arPerm))
    echo "У вас есть право на просмотр результатов в данном статусе";

if (in_array("EDIT", $arPerm))
    echo "У вас есть право на редактирование результатов в данном статусе";

if (in_array("MOVE", $arPerm))
    echo "У вас есть право на установку данного статуса результатам";

if (in_array("DELETE", $arPerm))
    echo "У вас есть право на удаление результатов в данном статусе";
?>


Set

CFormStatus::Set

mixed
CFormStatus::Set(
 array fields,
 mixed status_id = false,
 string check_rights = "Y"
)

Добавляет новый статус или обновляет существующий. Возвращает ID обновленного или добавленного статуса в случае положительного результата, в противном случае - "false".

Параметры функции

Параметр Описание
fields Массив значений, в качестве ключей массива допустимы:
  • FORM_ID* - ID веб-формы;
  • TITLE* - заголовок статуса;
  • C_SORT - порядок сортировки;
  • ACTIVE - флаг активности; допустимы следующие значения:
    • Y - ответ активен;
    • N - ответ не активен (по умолчанию).
  • DESCRIPTION - описание статуса;
  • CSS - имя CSS класса для вывода заголовка статуса;
  • HANDLER_OUT - путь относительно корня к обработчику, вызываемому при смене у результата данного статуса на какой либо другой;
  • HANDLER_IN - путь относительно корня к обработчику, вызываемому при смене у результата какого либо статуса на данный;
  • DEFAULT_VALUE - флаг установки статуса по умолчанию, допустимы следующие значения:
    • Y - статус будет устанавливаться;
    • N - статус не будет устанавливаться (по умолчанию).
  • arPERMISSION_VIEW* - массив ID групп пользователей, имеющих право "Просмотр результатов в данном статусе";
  • arPERMISSION_MOVE* - массив ID групп пользователей, имеющих право "Перевод результатов в данный статус";
  • arPERMISSION_EDIT* - массив ID групп пользователей, имеющих право "Редактирование результатов в данном статусе";
  • arPERMISSION_DELETE* - массив ID групп пользователей, имеющих право "Удаление результатов в данном статусе".

* - обязательно к заполнению.
* - в данных массивах может быть элемент со значением "0", означающий создателя результата.
status_id ID обновляемого статуса.
Параметр необязательный. По умолчанию - "false" (добавление нового статуса).
check_rights Флаг необходимости проверки прав текущего пользователя. Возможны следующие значения:
  • Y - права необходимо проверить;
  • N - право не нужно проверять.
Для обновления статуса, либо создания нового статуса необходимо иметь право [30] Полный доступ на форму указанную в fields["FORM_ID"].

Параметр необязательный. По умолчанию - "Y" (права необходимо проверить).

См. также

  • Поля CFormStatus

Примеры использования

<?
$FORM_ID = 4; // ID веб-формы

$arFields = array(
    "FORM_ID"             => $FORM_ID,               // ID веб-формы
    "C_SORT"              => 100,                    // порядок сортировки
    "ACTIVE"              => "Y",                    // статус активен
    "TITLE"               => "Опубликовано",         // заголовок статуса
    "DESCRIPTION"         => "Окончательный статус", // описание статуса
    "CSS"                 => "statusgreen",          // CSS класс
    "HANDLER_OUT"         => "",                     // обработчик
    "HANDLER_IN"          => "",                     // обработчик
    "DEFAULT_VALUE"       => "N",                    // не по умолчанию
    "arPERMISSION_VIEW"   => array(2),               // право просмотра для всех
    "arPERMISSION_MOVE"   => array(),                // право перевода только админам
    "arPERMISSION_EDIT"   => array(),                // право редактирование для админам
    "arPERMISSION_DELETE" => array(),                // право удаления только админам
);

$NEW_ID = CFormStatus::Set($arFields);
if ($NEW_ID>0) echo "Успешно добавлен ID=".$NEW_ID;
else // ошибка
{
    // выводим текст ошибки
    global $strError;
    echo $strError;
}
?>


Класс CFormValidator

CFormValidator - класс для работы с валидаторами.

Методы

Метод | Описание
Clear | Очищает список валидаторов, назначенных на вопрос.
Execute | Применяет валидатор к значению.
GetAllList | Возвращает полный список зарегистрированных валидаторов с возможностью фильтрации.
GetList | Возвращает список валидаторов, назначенных вопросу.
GetListForm | Возвращает список валидаторов, назначенных полям формы.
GetSettings | Возвращает массив параметров валидатора.
GetSettingsArray | Возвращает массив настроек валидатора, примененного к конкретному вопросу.
GetSettingsString | Возвращает строку настроек валидатора для сохранения в БД.
Set | Привязывает валидатор с заданными настроками к вопросу.
SetBatch | Привязывает набор валидаторов с заданными настроками к вопросу.


Clear

CFormValidator::Clear

CFormValidator::Clear(
 int FIELD_ID,
)

Удаляет все валидаторы, назначенные данному вопросу/полю.

Параметры функции

Параметр | Описание
FIELD_ID | ID поля.


Execute

CFormValidator::Execute

bool
CFormValidator::Execute(
 array arValidator,
 array arQuestion,
 array arAnswers,
 array arValues,
)

Выполняет валидатор для заданных значений ответов в применении к вопросу.

Параметры функции

Параметр | Описание
arValidator Описательный массив валидатора, один из элементов массива, возвращаемого методом CFormValidator::GetList. Должен содержать следующие параметры:
  • NAME - идентификатор валидатора
  • PARAMS - массив значений настроек валидатора
arQuestion | Описание вопроса. Во входящих в поставку валидаторах не используется, но может быть использован в собственных валидаторах.
arAnswers | Массив описаний ответов вопроса. Во входящих в поставку валидаторах не используется, но может быть использован в собственных валидаторах.
arValues | Массив ответов на вопрос в формате array('значение1', 'значение2', .... 'значение n').


GetAllList

CFormValidator::GetAllList

CDBResult
CFormValidator::GetAllList(
 mixed arFilter = array(),
)

Возвращает список зарегистрированных валидаторов в виде объекта класса CDBResult.

Параметры функции

Параметр Описание
arFilter Массив для фильтрации. В массиве допустимы следующие ключи:
  • TYPE - список типов полей;

Пример использования

if (CModule::IncludeModule("form"))
{
  $arFilter = array("TYPE" => array("text", "textarea"));

  $sType = "<b>".implode("</b>, <b>", $arFilter["TYPE"])."</b>";

  $rsValidators = CFormValidator::GetAllList($arFilter);
  if ($rsValidators->SelectedRowsCount() > 0)
  {
    echo "Найденные валидаторы для полей типа ".$sType.":<ul>";
    while ($arValidator = $rsValidators->GetNext())
    {
      echo "<li>[".$arValidator["NAME"]."] ".$arValidator["DESCRIPTION"]."</li>";
    }
    echo "</ul>";
  }
  else
  {
    echo "Валидаторов, применимых к полям типа ".$sType." не обнаружено.";
  }
}
else
{
  ShowError('Модуль веб-форм не установлен');
}


GetList

CFormValidator::GetList

CDBResult
CFormValidator::GetList(
 int FIELD_ID,
 mixed arFilter = array(),
 string &by = "s_sort",
 string &order = "asc",
)

Возвращает список заданных для поля валидаторов в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
FIELD_ID | ID вопроса.
arFilter Массив для фильтрации. В массиве допустимы следующие ключи:
  • ACTIVE - флаг активности валидатора;
  • NAME - идентификатор валидатора;
by Ссылка на переменную с полем для сортировки результирующего списка. Может принимать значения:
  • VALIDATOR_SID - ID валидатора;
  • C_SORT - индекс сортировки.
оrder Ссылка на переменную с порядком сортировки. Может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.


GetListForm

CFormValidator::GetListForm

CDBResult
CFormValidator::GetListForm(
 int FORM_ID,
 mixed arFilter = array(),
 string &by = "s_sort",
 string &order = "asc",
)

Возвращает список валидаторов, заданных для полей формы, в виде объекта класса CDBResult.

Параметры функции

Параметр | Описание
FORM_ID | ID веб-формы.
arFilter Массив для фильтрации. В массиве допустимы следующие ключи:
  • FIELD_ID - ID вопроса;
  • ACTIVE - флаг активности валидатора;
  • NAME - идентификатор валидатора;
by Ссылка на переменную с полем для сортировки результирующего списка. Может принимать значения:
  • VALIDATOR_SID - ID валидатора;
  • C_SORT - индекс сортировки.
оrder Ссылка на переменную с порядком сортировки. Может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.


GetSettings

CFormValidator::GetSettings

array
CFormValidator::GetSettings(
 array arValidator,
)

Возвращает список настроек валидатора. Аналогично прямому вызову метода возврата настроек валидатора.

Параметры функции

Параметр | Описание
arValidator | Описательный массив валидатора (например, полученный из результата метода CFormValidators::GetAllList).


GetSettingsArray

CFormValidator::GetSettingsArray

array
CFormValidator::GetSettingsArray(
 array arValidator,
 string strParams
)

Возвращает список настроек валидатора со значениями после обратного преобразования строки, занесенной в базу. Аналогичен прямому вызову метода обратного преобразования (CONVERT_FROM_DB) валидатора. При вызове методов CFormValidator::GetList и CFormValidator::GetListForm вызывается автоматически.

Параметры функции

Параметр | Описание
arValidator | Описательный массив валидатора (например, полученный из результата метода CFormValidators::GetList).
strParams | Строка со значениями настроек, хранящаяся в БД.


GetSettingsString

CFormValidator::GetSettingsString

string
CFormValidator::GetSettingsString(
 array arValidator,
 array arParams
)

Возвращает список настроек валидатора со значениями, преобразованный для занесения в базу. Аналогичен прямому вызову метода преобразования настроек (CONVERT_TO_DB) валидатора. При вызове методов CFormValidator::Set и CFormValidator::SetBatch вызывается автоматически.

Параметры функции

Параметр | Описание
arValidator | Описательный массив валидатора (например, полученный из результата метода CFormValidators::GetList).
arParams | Массив значений настроек валидатора.


Set

CFormValidator::Set

bool
CFormValidator::Set(
 int WEB_FORM_ID,
 int FIELD_ID,
 string VALIDATOR_SID,
 array arParams = array(),
)

Прикрепляет валидатор с заданными настройками к полю формы. Возвращает true в случае успеха операции и false в случае ошибки (валидатора с таким ID не существует, ошибка в валидаторе и т.д.)

Параметры функции

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
FIELD_ID | ID вопроса.
VALIDATOR_SID | Идентификатор валидатора.
arParams | Массив значений параметров валидатора.


SetBatch

CFormValidator::SetBatch

CFormValidator::SetBatch(
 int WEB_FORM_ID,
 int FIELD_ID,
 array arValidators = array(),
)

Прикрепляет группу валидаторов с заданными настройками к полю формы. Аналогична вызову CFormValidator::Set для каждого валидатора группы.

Параметры функции

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
FIELD_ID | ID вопроса.
arValidators Массив валидаторов. Каждый элемент массива должен представлять собой ассоциативный массив с ключами:
  • NAME - идентификатор валидатора;
  • PARAMS - массив параметрова валидатора.


События веб-форм

Все события вызываются перед соответствующим вызовом файлов-обработчиков статуса результата. Возврат обработчиком каких-либо значений не предполагается. Те обработчики, для которых это указано (onBefore*), могут возвращать какие-либо сообщения посредством генерации системного исключения (CMain::ThrowException()). В случае появления такого исключения все последующие операции с результатом прерываются (включая обработчики статусов веб-формы). При этом все равно вызываются все обработчики текущего события. Данные, передаваемые по ссылкам, допускают непосредственное изменение значений.

Событие | Описание
onBeforeResultAdd | Вызывается перед добавлением нового результата веб-формы.
onAfterResultAdd | Вызывается после добавления нового результата веб-формы.
onBeforeResultUpdate | Вызывается перед сохранением изменений существующего результата.
onAfterResultUpdate | Вызывается после сохранения изменений результата веб-формы.
onBeforeResultDelete | Вызывается перед удалением результата веб-формы.
onBeforeResultStatusChange | Вызывается перед изменением статуса результата веб-формы.
onAfterResultStatusChange | Вызывается после изменения статуса результата веб-формы.


onAfterResultAdd

функция-обработчик(
 int WEB_FORM_ID,
 int RESULT_ID
);
Обработчики события вызываются после добавления нового результата веб-формы. Может быть использовано для совершения каких-либо дополнительных операций с результатом веб-формы, например, для рассылки дополнительных уведомлений посредством электронной почты. Для изменения полей результата веб-формы стоит использовать CFormResult::SetField(). Возврат обработчиком каких-либо значений не предполагается.

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
RESULT_ID | ID результата.

См. также

  • Событие "onBeforeResultAdd"
  • Событие "onAfterResultUpdate"

Пример функции-обработчика:

function my_onAfterResultAddUpdate($WEB_FORM_ID, $RESULT_ID)
{
  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6)
  {
    // запишем в дополнительное поле 'user_ip' IP-адрес пользователя
    CFormResult::SetField($RESULT_ID, 'user_ip', $_SERVER["REMOTE_ADDR"]);
  }
}

// зарегистрируем функцию как обработчик двух событий
AddEventHandler('form', 'onAfterResultAdd', 'my_onAfterResultAddUpdate');
AddEventHandler('form', 'onAfterResultUpdate', 'my_onAfterResultAddUpdate');


onAfterResultStatusChange

функция-обработчик(
 int WEB_FORM_ID,
 int RESULT_ID,
 int NEW_STATUS_ID,
 string(1) CHECK_RIGHTS
);
Обработчики события вызываются после изменения статуса результата веб-формы. Может быть использовано, например, для каких-либо дополнительных уведомлений посредством электронной почты, а также, как замена обработчика статуса веб-формы. Возврат обработчиком каких-либо значений не предполагается. Для изменения полей результата веб-формы стоит использовать CFormResult::SetField().

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
RESULT_ID | ID результата.
NEW_STATUS_ID | ID статуса.
CHECK_RIGHTS | Флаг "Проверять права" (Y|N).

См. также

  • Событие "onBeforeResultStatusChange"

Пример функции-обработчика:

function my_onAfterResultStatusChange($WEB_FORM_ID, $RESULT_ID, $NEW_STATUS_ID, $CHECK_RIGHTS)
{
  global $USER;

  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6)
  {
    // 1 - статус "в проверке" (по умолчанию), 2 - статус "принято"
    // запишем в скрытое поле 'status_user' идентификатор пользователя,
    // совершившего изменение статуса.
    if ($NEW_STATUS_ID == 2)
      CFormResult::SetField($RESULT_ID, 'status_user', $USER->ID);
  }
}

// зарегистрируем функцию как обработчик события
AddEventHandler('form', 'onAfterResultStatusChange', 'my_onAfterResultStatusChange');


onAfterResultUpdate

функция-обработчик(
 int WEB_FORM_ID,
 int RESULT_ID,
 string(1) CHECK_RIGHTS
);
Обработчики события вызываются после сохранения изменений результата веб-формы. Может быть использовано для совершения каких-либо дополнительных операций с результатом веб-формы, например, для рассылки дополнительных уведомлений посредством электронной почты. Возврат обработчиком каких-либо значений не предполагается. Для изменения полей результата веб-формы стоит использовать CFormResult::SetField().

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
RESULT_ID | ID результата.
CHECK_RIGHTS | Флаг "Проверять права" (Y|N).

См. также

  • Событие "onBeforeResultUpdate"
  • Событие "onAfterResultAdd"

Пример функции-обработчика:

function my_onAfterResultAddUpdate($WEB_FORM_ID, $RESULT_ID)
{
  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6)
  {
    // запишем в дополнительное поле 'user_ip' IP-адрес пользователя
    CFormResult::SetField($RESULT_ID, 'user_ip', $_SERVER["REMOTE_ADDR"]);
  }
}

// зарегистрируем функцию как обработчик двух событий
AddEventHandler('form', 'onAfterResultAdd', 'my_onAfterResultAddUpdate');
AddEventHandler('form', 'onAfterResultUpdate', 'my_onAfterResultAddUpdate');


onBeforeResultAdd

функция-обработчик(
 int WEB_FORM_ID,
 array &arFields,
 array &arrVALUES
);
Обработчики события вызываются перед добавлением нового результата веб-формы. Может быть использовано для каких-либо дополнительных проверок или изменения значения полей результата веб-формы. Возврат обработчиком каких-либо значений не предполагается. Ошибки нужно возвращать посредством $APPLICATION->ThrowException().

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
arFields | Массив полей результата для записи в БД.
arrVALUES | Массив значений ответов результата веб-формы.

См. также

  • Событие "onAfterResultAdd"
  • Событие "onBeforeResultUpdate"

Пример функции-обработчика

function my_onBeforeResultAddUpdate($WEB_FORM_ID, $arFields, $arrVALUES)
{
  global $APPLICATION;

  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6)
  {
    // в текстовый вопрос с ID=135 должен содержать целое число, большее 5ти.
    $arrVALUES['form_text_135'] = intval($arrVALUES['form_text_135']);
    if ($arrVALUES['form_text_135'] < 5)
    {
      // если значение не подходит - отправим ошибку.
      $APPLICATION->ThrowException('Значение должно быть больше или равно 5!');
    }
  }
}

// зарегистрируем функцию как обработчик двух событий
AddEventHandler('form', 'onBeforeResultAdd', 'my_onBeforeResultAddUpdate');
AddEventHandler('form', 'onBeforeResultUpdate', 'my_onBeforeResultAddUpdate');


onBeforeResultDelete

функция-обработчик(
 int WEB_FORM_ID,
 int RESULT_ID,
 string(1) CHECK_RIGHTS
);
Обработчики события вызываются перед удалением результата веб-формы. Может быть использовано, например, для рассылки дополнительных уведомлений посредством электронной почты или для запрета удаления результата. Возврат обработчиком каких-либо значений не предполагается. Ошибки можно возвращать посредством $APPLICATION->ThrowException().

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
RESULT_ID | ID результата.
CHECK_RIGHTS | Флаг "Проверять права" (Y|N).

Пример функции-обработчика:

function my_onBeforeResultDelete($WEB_FORM_ID, $RESULT_ID, $CHECK_RIGHTS)
{
  global $APPLICATION;

  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6 && $RESULT_ID == 1)
  {
      $APPLICATION->ThrowException('Этот результат нельзя удалить!');
  }
}

// зарегистрируем функцию как обработчик события
AddEventHandler('form', 'onBeforeResultDelete', 'my_onBeforeResultDelete');


onBeforeResultStatusChange

функция-обработчик(
 int WEB_FORM_ID,
 int RESULT_ID,
 int &NEW_STATUS_ID,
 string(1) CHECK_RIGHTS
);
Обработчики события вызываются перед изменением статуса результата веб-формы. Может быть использовано для каких-либо дополнительных проверок или даже для изменения нового статуса, а также, как замена обработчика статуса веб-формы. Возврат обработчиком каких-либо значений не предполагается. Ошибки можно возвращать посредством $APPLICATION->ThrowException().

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
RESULT_ID | ID результата.
NEW_STATUS_ID | ID статуса.
CHECK_RIGHTS | Флаг "Проверять права" (Y|N).

См. также

  • Событие "onAfterResultStatusChange"

Пример функции-обработчика:

function my_onBeforeResultStatusChange($WEB_FORM_ID, $RESULT_ID, $NEW_STATUS_ID, $CHECK_RIGHTS)
{
  global $USER;

  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6)
  {
    // 1 - статус "в проверке" (по умолчанию), 2 - статус "принято"
    // результатам, присланным пользователем с правами администратора
    // автоматически присвоим статус "принято".
    if ($USER->IsAdmin() && $NEW_STATUS_ID == 1)
      $NEW_STATUS_ID = 2;
  }
}

// зарегистрируем функцию как обработчик события
AddEventHandler('form', 'onBeforeResultStatusChange', 'my_onBeforeResultStatusChange');


onBeforeResultUpdate

функция-обработчик(
 int WEB_FORM_ID,
 int RESULT_ID,
 array &arFields,
 array &arrVALUES,
 string(1) CHECK_RIGHTS
);
Обработчики события вызываются перед сохранением изменений существующего результата веб-формы. Может быть использовано для каких-либо дополнительных проверок или изменения значения полей результата веб-формы. Возврат обработчиком каких-либо значений не предполагается. Ошибки можно возвращать посредством $APPLICATION->ThrowException().

Параметры

Параметр | Описание
WEB_FORM_ID | ID веб-формы.
RESULT_ID | ID результата.
arFields | Массив полей результата для записи в БД.
arrVALUES | Массив значений ответов результата веб-формы.
CHECK_RIGHTS | Флаг "Проверять права" (Y|N).

См. также

  • Событие "onAfterResultUpdate"

Пример функции-обработчика:

function my_onBeforeResultAddUpdate($WEB_FORM_ID, $arFields, $arrVALUES)
{
  global $APPLICATION;

  // действие обработчика распространяется только на форму с ID=6
  if ($WEB_FORM_ID == 6)
  {
    // в текстовый вопрос с ID=135 должен содержать целое число, большее 5ти.
    $arrVALUES['form_text_135'] = intval($arrVALUES['form_text_135']);
    if ($arrVALUES['form_text_135'] < 5)
    {
      // если значение не подходит - отправим ошибку.
      $APPLICATION->ThrowException('Значение должно быть больше или равно 5!');
    }
  }
}

// зарегистрируем функцию как обработчик двух событий
AddEventHandler('form', 'onBeforeResultAdd', 'my_onBeforeResultAddUpdate');
AddEventHandler('form', 'onBeforeResultUpdate', 'my_onBeforeResultAddUpdate');


Для разработчиков

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


Инсталляция

Этапы установки

Для инсталляции модуля вам необходимо выполнить следующее:

  1. Убедитесь, что версия ядра не менее чем 3.0.14 (версию ядра можно узнать в левом нижнем углу административных страниц). Инсталлятор не даст вам установить модуль, если версия ядра не соответствует требуемой.
  2. Выберите группу администраторов документооборота. При необходимости создайте ее.
  3. Нажмите кнопку Установить на странице списка модулей.
  4. Выберите начальные установки модуля.
  5. Нажмите кнопку Установить.
  6. После окончания установки создайте необходимые статусы документов, а также раздайте права группам на эти статусы.
  7. Убедитесь, что версия модуля Управление статикой не ниже чем 3.0.7.
  8. В меню Управление статикой выберите каталоги, файлы которых будут редактироваться в режиме документооборота. Дайте право Документооборот для групп, имеющих право редактировать документ в режиме документооборота (но не публиковать его). Для групп, имеющих право публикации документа, необходимо дать право Запись на выбранные вами каталоги.
  9. Если у вас установлена версия ядра не менее чем 3.0.14, то для корректной работы панели управления в файле "/bitrix/php_interface/include/prolog_include.php" необходимо внести следующие изменения:
    1. Если у вас данный файл содержит следующий код:

      if($USER->IsAdmin())
{
    require($_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/top_panel.css");
}
      то вам необходимо удалить его.

    2. Если данный файл содержит код:

      if(CModule::IncludeModule("fileman") && $USER->IsAdmin())
{
    require($_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/include/top_panel.php");
}
      то вам необходимо заменить его на

      $APPLICATION->GetPanel();

Таблицы

Инсталляция подразумевает создание следующих таблиц в базе:

Таблица | Назначение
b_workflow_document | Документы.
b_workflow_file | Файлы загруженных в документы.
b_workflow_log | История изменений документов.
b_workflow_move | История перемещения документа по статусам (кто, когда, с какого и на какой статус)
b_workflow_preview | Файлы предпросмотра.
b_workflow_status | Статусы.
b_workflow_status2group | Связка статусов с группами пользователей.

Когда таблицы подготовлены, происходит копирование всех необходимых скриптов для администрирования из каталога

\bitrix\modules\workflow\install\public\admin\

в каталог

\bitrix\admin\ :

Файл | Описание
workflow_list.php | Список документов.
workflow_edit.php | Редактирование документа.
workflow_status_list.php | Список статусов.
workflow_status_edit.php | Редактирование статуса.
workflow_history_list.php | Список исторических записей.
workflow_history_view.php | Просмотр исторической записи.
workflow_preview.php | Скрипт создающий файл предпросмотра и перенаправляющий на него.
workflow_dialog.php | Служебный файл для показа диалоговых окон.
workflow_file_download.php | Файл позволяющий просмотреть загруженный в документ файлы.
workflow_filelist.php | Список файлов и каталогов.
workflow_get_file.php | Вызывает диалоговое окно для выбора файла документа.
workflow_select_fname.php |

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


Информация для разработчиков

Перед использованием модуля необходимо проверить, установлен ли он и подключить его при помощи конструкции:

<?
if (CModule::IncludeModule("sale"))
{
   //здесь можно использовать функции модуля
}
?>

Некоторые термины модуля

Базовая валюта для данного сайта - валюта, в которой осуществляются операции по продаже товаров на данном сайте. Устанавливается на странице глобальных настроек модуля Интернет-Магазина. Понятие базовой валюты в модуле Интернет-Магазина отличается от понятия базовой валюты в модуле Валют.


Интеграция с платежными системами

Под платежными системами в этой статье понимаются любые способы оплаты заказа: как платежные системы, принимающие платежи on-line, так и банковские переводы, и т.п.

Разные платежные системы предлагают различные интерфейсы для интеграции (взаимодействия). Зачастую эти интерфейсы отличаются кардинально: например, интеграция с системой PayFlow Pro требует выполнения запросов к платежной системе при помощи устанавливаемого на сервер SDK, а интеграция со сбербанком требует распечатки квитанции сбербанка. Поэтому интеграция с платежными системами осуществляется посредством php-скриптов, называемых обработчиками платежных систем.

Обработчики платежных систем (далее просто обработчики) задаются индивидуально для каждого типа плательщика каждой платежной системы в форме управления платежными системами. При оформлении заказа вызывается один из трех обработчиков выбранной покупателем платежной системы для выбранного типа плательщика. Обработчики платежных систем определяются по именам файлов:

  • payment.php - если обработчик вызывается в после фактического сохранения всех параметров заказа в базу данных. Применяется в стандартном компоненте процедуры заказа;
  • pre_payment.php - если требуется вызвать обработчик в внутри процедуры заказа (для тех обработчиков, которые могут сразу произвести оплату заказа и вернуть результат). Применяется в двушаговом компоненте процедуры заказа;
  • action.php - применяется для снятия с карты заданной суммы денег (только для обработчиков, которые могут сразу произвести оплату заказа и вернуть результат). Например, при продлении подписки.

Алгоритм работы (содержимое) обработчика полностью определяется интерфейсами, которые предоставляет соответствующая платежная система.

Типичные обработчики

Типичным обработчиком для платежной системы, которая не осуществляет on-line платежи, является вывод на экран счета (или квитанции), готового к печати на принтере. Примерами таких обработчиков являются счет или квитанция перевода через сбербанк.

Такой обработчик обычно представляет собой файл, который выводит необходимое для данного документа форматирование и вставляет в соответствующих местах параметры заказа.

Пример такого обработчика можно посмотреть в шаблонах платежных систем сбербанка (/bitrix/modules/sale/payment/sberbank.php), банковского перевода (/bitrix/modules/sale/payment/bill.php).

Типичным обработчиком для платежной системы, которая осуществляет платежи on-line, является вывод на экран HTML-формы, которая отправляет данные платежной системе. Примерами таких платежных систем являются Assist, AuthorizeNet, Payflow, WorldPay.

Вид, набор полей и прочие параметры HTML-формы полностью зависят от платежной системы. Конкретное описание формы, которая требуется данной платежной системе, следует искать в документации по этой платежной системе.

Пример такого обработчика можно посмотреть в шаблонах платежных систем Assist (/bitrix/modules/sale/payment/assist.php), AuthorizeNet (/bitrix/modules/sale/payment/authorizenet.php), Paypal (/bitrix/modules/sale/payment/paypal.php) и т.д.

Параметры, которые необходимы платежным системам, можно получать из параметров заказа, которые доступны в обработчике в массиве $arOrder, а так же из значений свойств заказа, которые можно получить следующим образом:

// В результате выполнения следующего кода мы получим ассоциативный массив,
// в котором мнемоническим кодам свойств заказа (или ID свойств, если мнемонические коды не установлены)
// будут поставлены значения свойств, которые были введены при оформлении этого заказа
// $ORDER_ID - код заказа - предустановленная переменная для обработчика
$arCurOrderProps = array();
$db_res = CSaleOrderPropsValue::GetList(($b=""), ($o=""), array("ORDER_ID"=>$ORDER_ID));
while ($ar_res = $db_res->Fetch())
   $arCurOrderProps[(strlen($ar_res["CODE"])>0) ? $ar_res["CODE"] : $ar_res["ID"]] = $ar_res["VALUE"];

// Теперь можно сформировать форму, которая нужна данной платежной системе,
// определив соответствие между свойствами заказа в базе и параметрами,
// необходимыми платежной системе
if (isset($arCurOrderProps["ADDRESS"])):
   ?><input type="hidden" name="address" value="<?= htmlspecialchars($arCurOrderProps["ADDRESS"]) ?>"><?
endif;
if (isset($arCurOrderProps["ZIP"])):
   ?><input type="hidden" name="postcode" value="<?= htmlspecialchars($arCurOrderProps["ZIP"]) ?>"><?
endif;
// Мы записали значение, которое покупатель ввел для свойства с кодом ADDRESS, в то поле, в котором
// платежная система принимает адрес покупателя. Мы записали значение, которое покупатель ввел для
// свойства с кодом ZIP, в то поле, в котором платежная система принимает почтовый индекс.

Как правило платежные системы с on-line платежами предоставляют один из двух (иногда оба) типов интерфейса для интеграции: 1. форма с параметрами заказа отправляется на сайт платежной системы, где покупатель заполняет дополнительные формы (например, вводит номер пластиковой карты) и производит фактическую оплату, 2. все параметры заполняются на сайте и формируется запрос к платежной системе, в ответе на который она сообщает результат оплаты.

Первый тип интерфейса является наиболее простым для интеграции. В обработчике достаточно создать HTML-форму, которая будет отправлять данные на сайт платежной системы, и добавить в форму необходимые платежной системе поля. Конкретные параметры необходимо смотреть в системе помощи по конкретной платежной системе. Пример такого обработчика можно посмотреть в шаблоне платежной системы Assist (/bitrix/modules/sale/payment/assist.php).

Второй тип является более сложным для интеграции, но зато он является более гибким в плане возможностей. Пример такого обработчика можно посмотреть в шаблоне платежной системы AuthorizeNet (/bitrix/modules/sale/payment/authorizenet.php). Общая структура кода обработчика в этом случае может быть примерно такой:

// Если готовы запросить платежную систему
if ($_REQUEST["pay_this_order"]=="Y")
{
   // Соберем в $strPostQueryString строку параметров запроса
   $strPostQueryString = "x_login=".urlencode("login");

   $arCurOrderProps = array();
   $db_res = CSaleOrderPropsValue::GetList(($b=""), ($o=""), array("ORDER_ID"=>$ORDER_ID));
   while ($ar_res = $db_res->Fetch())
      $arCurOrderProps[(strlen($ar_res["CODE"])>0) ? $ar_res["CODE"] : $ar_res["ID"]] = $ar_res["VALUE"];

   if (isset($arCurOrderProps["ADDRESS"]))
      $strPostQueryString .= "&x_address=".urlencode($arCurOrderProps["ADDRESS"]);

    * * *

   if (isset($arCurOrderProps["ZIP"]))
      $strPostQueryString .= "&x_ship_to_zip=".urlencode($arCurOrderProps["ZIP"]);

   // Запросим платежную систему
   $strResult = QueryGetData("some_url.net", 443, "/some_path/file.dll", $strPostQueryString, $errno, $errstr, "POST", "ssl://");

   // В $strResult вернулся ответ платежной системы. Его вид зависит от платежной системы.
   // Можно обработать его и сохранить в соответствующих полях заказа.

    * * *

}
else
{
   ?>
   <form action="" method="post">
      Credit card number: <input type="text" name="ccard_num" size="30"><br>
      * * * <br>
      CVV2: <input type="text" name="ccard_code" size="5"><br>
      <input type="hidden" name="CurrentStep" value="<?= $CurrentStep ?>">
      <input type="hidden" name="ORDER_ID" value="<?= $ORDER_ID ?>">
      <input type="hidden" name="pay_this_order" value="Y">
      <input type="submit" value="Proceed">
   </form>
   <?
}

В последнем случае (интерфейс типа 2) модуль Интернет-магазина сразу получает результат работы платежной системы, пригодный для дальнейшей обработки заказа.

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

  1. Необходимо создать в публичной части сайта (например, в папке /bitrix/php_interface/include/payment/) файл запроса статуса. За основу можно взять один из предустановленных скриптов из папки /bitrix/modules/sale/payment/ (например, assist_res.php).
  2. Необходимо изменить скрипт таким образом, чтобы он соответствовал интерфейсу платежной системы.
  3. Необходимо в форме редактирования параметров соответствующей платежной системы (в административной части сайта) указать, для каких обработчиков платежных систем действует этот скрипт автоматического получения статуса заказа.

Часто платежная система не предоставляет интерфейса для получения статуса оплаты заказа, но отправляет письма с указанием результата оплаты. В этом случае можно автоматически устанавливать статус оплаты в заказе с помощью модуля Почты (mail). Для этого необходимо создать соответствующий обработчик почты и настроить его работу с модулем. Подробности есть в системе помощи по модулю Почты (mail).

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


Создание собственных автоматизированных обработчиков служб доставки

В этом разделе

  • Структура обработчика
  • Описание обработчика
  • Параметры обработчика
  • Обработка параметров
  • Проверка совместимости
  • Обработчик
    •
  • Интеграция обработчика
  • Пример
  • Post factum

    • Структура обработчика

    Автоматизированные обработчики служб доставки позволяют программным образом реализовать произвольную логику расчёта стоимости доставки на основе параметров заказа и собственных настроек. Алгоритмы расчёта могут быть произвольными - фиксированная стоимость, запросы к удаленным web-сервисам, расчёт на основе собственных таблиц данных и т.д.

    Обработчик представляет собой класс или набор функций следующей структуры:

    Метод | Описание
Описание обработчика | Функция, возвращающая описание обработчика, названия методов, список профилей обработчика и пр.
Настройки обработчика | Функция, возвращающая массив настроек обработчика
Обработка настроек | Набор функций, отвечающий за подготовку настроек к занесению в БД и обратное преобразование.
Проверка совместимости | Метод, осуществляющий проверку совместимости профилей данного обработчика с заказом.
Функция расчёта | Метод, осуществляющий расчёт стоимости доставки на основе настроек обработчика и параметров заказа.

    Поскольку работать с набором отдельных функций неудобно, рекомендуется объединить их в класс (пространство имен). Исходя из этой рекомендации будет идти дальнейшее описание, а также, реализован приводимый пример. В примере обработчик "Курьерская доставки" реализован в виде класса CDeliveryMySimple.

    Описание обработчика

    Описание обработчика представляет собой метод, возвращающий ассоциативный массив следующей структуры:

    Параметр | Описание
SID | Уникальный строковой идентификатор обработчика.
NAME | Название обработчика.
DESCRIPTION | Текстовое описание обработчика
DESCRIPTION_INNER | Внутреннее описание обработчика, отображаемое при конфигурации обработчика в Панели Управления.
BASE_CURRENCY | Идентификатор базовой валюты обработчика
HANDLER | Путь к файлу обработчика. Нужен для корректного автоматического копирования обработчика (ещё не реализовано). В подавляющем большинстве случаев достаточно значения __FILE__
GETCONFIG | Название метода, возвращающего массив настроек валидатора. В случае реализации обработчика в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
DBSETSETINGS | Название метода, отвечающего за проверку настроек обработчика и преобразование массива настроек в строку для сохранения. В случае реализации обработчика в виде класса, значение представляет собой массив ("имя_класса", "имя_метода"). В случае отсутствия этого метода массив настроек будет сохранен в базу в сериализованном виде.
DBGETSETTINGS | Название метода, отвечающего за обратное преобразование строки настроек обработчика в массив. В случае реализации обработчика в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
COMPABILITY | Название метода, отвечающего за дополнительную проверку совместимости профилей обработки с параметрами заказа. Если метод отсутствует, дополнительная проверка не будет проводиться. В случае реализации обработчика в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
CALCULATOR | Название метода, осуществляющего расчёт стоимости доставки. В случае реализации обработчика в виде класса, значение представляет собой массив ("имя_класса", "имя_метода").
PROFILES | Массив профилей обработки. Должен содержать хотя бы один профиль. Формат описания см. ниже.

    Описание профилей представляет собой массив следующего формата:

"строковой_идентификато_профиля" => array(
  "TITLE" => "название_профиля",
  "DESCRIPTION" => "описание_профиля",
  // веса указываются в граммах
  "RESTRICTIONS_WEIGHT" => array(минимальный_вес, максимальный_вес),
  // суммы указываются в базовой валюте обработчика
  "RESTRICTIONS_SUM" => array(минимальная_сумма_заказа, максимальная_сумма_заказа)
);

    Если массив RESTRICTIONS_WEIGHT или RESTRICTIONS_SUM содержит один элемент, то он считается минимальным значением. Если никаких ограничений не требуется, нужно указать array(0).

    Пример:

function Init()
{
  return array(
    /* Basic description */
    "SID" => "simple",
    "NAME" => "Доставка курьером",
    "DESCRIPTION" => "",
    "DESCRIPTION_INNER" =>
"Простой обработчик курьерской доставки. Для функционирования необходимо "
."наличие хотя бы одной группы местоположений. При настройке обработчика указывается "
."фиксированная стоимость доставки для каждой группы местоположений. Для того, чтобы "
."группа не участвовала в обработке, оставьте пустым поле стоимости для этой группы."
."<br />"
."<a href=\"/bitrix/admin/sale_location_group_admin.php?lang=ru\" target=\"_blank\">"
."Редактировать группы местоположений"
."</a>.",
    "BASE_CURRENCY" => COption::GetOptionString("sale", "default_currency", "RUB"),

    "HANDLER" => __FILE__,

    /* Handler methods */
    "DBGETSETTINGS" => array("CDeliverySimple", "GetSettings"),
    "DBSETSETTINGS" => array("CDeliverySimple", "SetSettings"),
    "GETCONFIG" => array("CDeliverySimple", "GetConfig"),

    "COMPABILITY" => array("CDeliverySimple", "Compability"),
    "CALCULATOR" => array("CDeliverySimple", "Calculate"),

    /* List of delivery profiles */
    "PROFILES" => array(
      "simple" => array(
        "TITLE" => "доставка",
        "DESCRIPTION" => "Срок доставки до 3 дней",

        "RESTRICTIONS_WEIGHT" => array(0),
        "RESTRICTIONS_SUM" => array(0),
      ),
    )
  );
}
    Параметры валидатора

    Метод, заданный элементом GETCONFIG, должен возвращать массив элементов вида:

    array(
  "CONFIG_GROUPS" => array(
    "идентификатор_группы1" => "название_группы1",
    "идентификатор_группы2" => "название_группы2",
    /* ...................... */
  ),
  "CONFIG" => array(
    "идентфикатор_параметра1" => array(
      "TITLE" = > "название_параметра1",
      "TYPE" => "тип_параметра1",
      "DEFAULT" => "значение_по_умолчанию_параметра1",
      "GROUP" => "идентфикатор_группы_параметра1",
      "VALUES" => array(
        "значение1_параметра1" => "наименование_значения1_параметра1",
        "значение2_параметра1" => "наименование_значения2_параметра1",
        /* ....................... */
      )
    ),

    /* ........................ */
  )
)

    Группы параметров, описываемые в элементе массива с ключом "CONFIG_GROUPS" отображаются в виде отдельных вкладок в форме редактирования параметров обработчика, содержащих параметры, приписанные к этой группе. Элемент массива с ключом "CONFIG" задает список параметров. Тип параметра может принимать одно из следующих значений:

    • STRING - поле для ввода текста
    • PASSWORD - поле для ввода пароля
    • CHECKBOX - элемент типа "флажок" со значением 'Y'
    • RADIO - набор вариантов в виде радио-кнопок
    • DROPDOWN - набор вариантов в виде выпадающего списка
    • MULTISELECT - набор вариантов в виде списка со множественным выбором
    • RADIO - набор вариантов в виде радио-кнопок

    Для типов параметра подразумевающий выбор из нескольких вариантов значений (DROPDOWN, MULTISELECT и RADIO) список значений задается элементом описательного массива с ключом "VALUES". Для остальных типов параметров этот элемент игнорируется.

    Пример:

function GetConfig()
{
  $arConfig = array(
    "CONFIG_GROUPS" => array(
      "all" => "Стоимость доставки",
    ),

    "CONFIG" => array(),
  );

  // параметрами обработчика в данном случае являются значения стоимости доставки в различные группы местоположений.
  // для этого сформируем список параметров на основе списка групп
  $dbLocationGroups = CSaleLocationGroup::GetList();
  while ($arLocationGroup = $dbLocationGroups->Fetch())
  {
    $arConfig["CONFIG"]["price_".$arLocationGroup["ID"]] = array(
      "TYPE" => "STRING",
      "DEFAULT" => "",
      "TITLE" =>
        "Стоимость доставки в группу \""
        .$arLocationGroup["NAME"]."\" "
        .(".COption::GetOptionString("sale", "default_currency", "RUB").')',
      "GROUP" => "all",
    );
  }

  return $arConfig;
}
    Обработка параметров

    Обработка параметров обработчика требует двух методов, задаваемых в описании параметрами DBSETSETTINGS и DBGETSETTINGS. Первый из них получает на вход массив значений параметров вида "идентфикатор_параметра" => "значение_параметра" и должен вернуть их строковое представление. Второй - совершить обратное преобразование. Оба метода могут также совершать произвольные манипуляции со значениями параметров.

    Пример:

function SetSettings($arSettings)
{
  // Проверим список значений стоимости. Пустые значения удалим из списка.
  foreach ($arSettings as $key => $value)
  {
    if (strlen($value) > 0)
      $arSettings[$key] = doubleval($value);
    else
      unset($arSettings[$key]);
  }

  // вернем значения в виде сериализованного массива.
  // в случае более простого списка настроек можно применить более простые методы сериализации.
  return serialize($arSettings);
}

function GetSettings($strSettings)
{
  // вернем десериализованный массив настроек
  return unserialize($strSettings);
}
    Проверка совместимости

    Проверка совместимости профилей обработчика с заказом осуществляется методом, задаваемым в описании параметром "COMPABILITY". Этот метод принимает на вход 2 параметра - описательный массив заказа и массив настроек обработчика. В качестве ответа метода ожидается массив, содержащий идентификаторы подходящих для данного заказа профилей доставки. Проверка, задаваемая значениями "RESTRICTIONS_WEIGHT" и "RESTRICTIONS_SUM" в настройках профиля, производится вне обработчика и здесь не требуется. Формат принимаемых на вход данных следующий:

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

    Ключ | Описание
WEIGHT | Суммарный вес заказа.
PRICE | Суммарная стоимость заказа.
LOCATION_FROM | ID местоположения магазина, настраиваемого в настройках модуля "Интернет-магазин".
LOCATION_TO | ID местоположения, указываемого клиентом при оформлении заказа.

    Второй параметр представляет собой значение массива, заданного элементом с ключом "CONFIG" в списке настроек обработчика, к каждому элементу которого добавлено значение параметра с ключом "VALUE".

    В рассматриваемом нами примере единственная условие совместимости - это наличие в настройках обработчика значения стоимости доставки хотя бы для одной из групп местоположений, в которые входит местоположение, передаваемое в заказе.

    Пример:

// введем служебный метод, определяющий группу местоположения и возвращающий стоимость для этой группы.
function __GetLocationPrice($LOCATION_ID, $arConfig)
{
  // получим список групп для переданного местоположения
  $dbLocationGroups = CSaleLocationGroup::GetLocationList(array("LOCATION_ID" => $LOCATION_ID));

  while ($arLocationGroup = $dbLocationGroups->Fetch())
  {
    if (
      array_key_exists('price_'.$arLocationGroup["LOCATION_GROUP_ID"], $arConfig)
      &&
      strlen($arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"] > 0)
    )
    {
      // если есть непустая запись в массиве настроек для данной группы, вернем ее значение
      return $arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"];
    }
  }

  // если не найдено подходящих записей, вернем false
  return false;
}

// метод проверки совместимости в данном случае практически аналогичен рассчету стоимости
function Compability($arOrder, $arConfig)
{
  // проверим наличие стоимости доставки
  $price = CDeliverySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig);

  if ($price === false)
    return array(); // если стоимость не найдено, вернем пустой массив - не подходит ни один профиль
  else
    return array('simple'); // в противном случае вернем массив, содержащий идентфиикатор единственного профиля доставки
}
    Обработчик

    Основной метод расчёта стоимости доставки получает на вход следующие параметры:

    • идентификатор профиля доставки;
    • массив настроек обработчика доставки;
    • описательный массив заказа;
    • текущий шаг расчёта;
    • временные данные, переданные с прошлого шага расчёта.

    На выход обработчик должен дать стоимость доставки в валюте, задаваемой в параметрах, либо массив следующей структуры:

    Ключ | Описание
    RESULT Идентификатор ответа. Возможные значения:
    • "OK" - стоимость доставки успешно рассчитана;
    • "ERROR" - в процессе расчёта произошла ошибка;
    • "NEXT_STEP" - необходимо перейти на следующий шаг для продолжения расчёта.
    VALUE | Значение стоимости доставки в валюте, задаваемой в параметрах. (RESULT = 'OK')
    TRANSIT | Длительность доставки в днях (RESULT = 'OK'). Если отсутствует, то длительность не выводится.
    TEXT | Текст ошибки или текст, сопровождающий переход на следующий шаг (RESULT = {'ERROR'|'NEXT_STEP'}).
    TEMP | Строка, содержащая промежуточные данные, передаваемые следующему шагу (RESULT = 'NEXT_STEP').

    В описываемом нами примере многошаговый процесс не подразумевается, потому, расчёт осуществляется просто.

    Пример:

function Calculate($profile, $arConfig, $arOrder, $STEP, $TEMP = false)
{
  // служебный метод рассчета определён выше, нам достаточно переадресовать на выход возвращаемое им значение.
  return array(
    "RESULT" => "OK",
    "VALUE" => CDeliverySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig)
  );
}

    Интеграция обработчика

    Путь к автоматически подключаемым файлам обработчиков устанавливается в настройках модуля "Интернет-магазин". Путь по умолчанию - /bitrix/php_interface/include/sale_delivery/ Такие файлы должны иметь префикс delivery_, в противном случае, они будут проигнорированы. Если система обнаружит файл, имеющее то же название, что и системный, то он будет подключаться вместо системного. Подключение автоматизированной доставки в файле производится установкой описательного метода в качестве обработчика события onSaleDeliveryHandlersBuildList.

    Пример

    Подытожив все вышесказанное, сформируем обработчик простой доставки. Класс обработчика расположим в файле /bitrix/php_interface/include/sale_delivery/delivery_mysimple.php

<?
// Листинг файла /bitrix/php_interface/include/sale_delivery/delivery_mysimple.php

CModule::IncludeModule("sale");

class CDeliveryMySimple
{
  function Init()
  {
    return array(
      /* Основное описание */
      "SID" => "simple",
      "NAME" => "Доставка курьером",
      "DESCRIPTION" => "",
      "DESCRIPTION_INNER" =>
"Простой обработчик курьерской доставки. Для функционирования необходимо "
."наличие хотя бы одной группы местоположений. При настройке обработчика указывается "
."фиксированная стоимость доставки для каждой группы местоположений. Для того, чтобы "
."группа не участвовала в обработке, оставьте пустым поле стоимости для этой группы."
."<br />"
."<a href=\"/bitrix/admin/sale_location_group_admin.php?lang=ru\" target=\"_blank\">"
."Редактировать группы местоположений"
."</a>.",
      "BASE_CURRENCY" => COption::GetOptionString("sale", "default_currency", "RUB"),

      "HANDLER" => __FILE__,

      /* Методы обработчика */
      "DBGETSETTINGS" => array("CDeliverySimple", "GetSettings"),
      "DBSETSETTINGS" => array("CDeliverySimple", "SetSettings"),
      "GETCONFIG" => array("CDeliverySimple", "GetConfig"),

      "COMPABILITY" => array("CDeliverySimple", "Compability"),
      "CALCULATOR" => array("CDeliverySimple", "Calculate"),

      /* Список профилей доставки */
      "PROFILES" => array(
        "simple" => array(
          "TITLE" => "доставка",
          "DESCRIPTION" => "Срок доставки до 3 дней",

          "RESTRICTIONS_WEIGHT" => array(0), // без ограничений
          "RESTRICTIONS_SUM" => array(0), // без ограничений
        ),
      )
    );
  }

  // настройки обработчика
  function GetConfig()
  {
    $arConfig = array(
      "CONFIG_GROUPS" => array(
        "all" => "Стоимость доставки",
      ),

      "CONFIG" => array(),
    );

    // настройками обработчика в данном случае являются значения стоимости доставки в различные группы местоположений.
    // для этого сформируем список настроек на основе списка групп

    $dbLocationGroups = CSaleLocationGroup::GetList();
    while ($arLocationGroup = $dbLocationGroups->Fetch())
    {
      $arConfig["CONFIG"]["price_".$arLocationGroup["ID"]] = array(
        "TYPE" => "STRING",
        "DEFAULT" => "",
        "TITLE" =>
          "Стоимость доставки в группу \""
          .$arLocationGroup["NAME"]."\" "
          .(".COption::GetOptionString("sale", "default_currency", "RUB").')',
        "GROUP" => "all",
      );
    }

    return $arConfig;
  }

  // подготовка настроек для занесения в базу данных
  function SetSettings($arSettings)
  {
    // Проверим список значений стоимости. Пустые значения удалим из списка.
    foreach ($arSettings as $key => $value)
    {
      if (strlen($value) > 0)
        $arSettings[$key] = doubleval($value);
      else
        unset($arSettings[$key]);
    }

    // вернем значения в виде сериализованного массива.
    // в случае более простого списка настроек можно применить более простые методы сериализации.
    return serialize($arSettings);
  }

  // подготовка настроек, полученных из базы данных
  function GetSettings($strSettings)
  {
    // вернем десериализованный массив настроек
    return unserialize($strSettings);
  }

  // введем служебный метод, определяющий группу местоположения и возвращающий стоимость для этой группы.
  function __GetLocationPrice($LOCATION_ID, $arConfig)
  {
    // получим список групп для переданного местоположения
    $dbLocationGroups = CSaleLocationGroup::GetLocationList(array("LOCATION_ID" => $LOCATION_ID));

    while ($arLocationGroup = $dbLocationGroups->Fetch())
    {
      if (
        array_key_exists('price_'.$arLocationGroup["LOCATION_GROUP_ID"], $arConfig)
        &&
        strlen($arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"] > 0)
      )
      {
      // если есть непустая запись в массиве настроек для данной группы, вернем ее значение
        return $arConfig['price_'.$arLocationGroup["LOCATION_GROUP_ID"]]["VALUE"];
      }
    }

    // если не найдено подходящих записей, вернем false
    return false;
  }

  // метод проверки совместимости в данном случае практически аналогичен рассчету стоимости
  function Compability($arOrder, $arConfig)
  {
    // проверим наличие стоимости доставки
    $price = CDeliverySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig);

    if ($price === false)
      return array(); // если стоимость не найдено, вернем пустой массив - не подходит ни один профиль
    else
      return array('simple'); // в противном случае вернем массив, содержащий идентфиикатор единственного профиля доставки
  }

  // собственно, рассчет стоимости
  function Calculate($profile, $arConfig, $arOrder, $STEP, $TEMP = false)
  {
    // служебный метод рассчета определён выше, нам достаточно переадресовать на выход возвращаемое им значение.
    return array(
      "RESULT" => "OK",
      "VALUE" => CDeliverySimple::__GetLocationPrice($arOrder["LOCATION_TO"], $arConfig)
    );
  }
}

// установим метод onSaleDeliveryHandlersBuildList в качестве обработчика события
AddEventHandler("sale", "onSaleDeliveryHandlersBuildList", array('CDeliveryMySimple', 'Init'));
?>

    Post factum

    Несколько советов в завершение:

    • Если Ваш обработчик использует какие-либо ресурсоемкие вычисления, обращения к базе данных, запросы к удаленным серверам и т.д., то категорически рекомендуется использовать тот или иной вариант кеширования результата, реализованный таким образом, чтобы запоминались результаты хотя бы для заказа с данными параметрами. Это необходимо из-за того, что в процессе оформления и обработки заказа запрос к обработчику на расчёт стоимости заказа может происходить несколько раз. В поставляемых обработчиках используется механизм управляемого кеширования, настроенный с учётом специфики алгоритма вычисления стоимости конкретной службой доставки.
    • Для кастомизации системного обработчика достаточно скопировать его файл (вместе с сопутствующими файлами, лежащими обычно в каталоге с тем же названием) в каталог /bitrix/php_interface/include/sale_deivery/ с сохранением имени. В этом случае он будет подключаться вместо системного.

    См. также

  • Кеширование
  • События
  • AddEventHandler
    •


Загрузка каталога из 1С

Данный раздел описывает протокол обмена информацией между программным комплексом «1С: Предприятие 8.1» и «1С-Битрикс: Управление сайтом».

Инициатором обмена во всех случаях выступает «1С: Предприятие». Обмен производится в формате CommerceML 2.0 (CML 2.0).

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

Загрузка каталога из 1С в «1С-Битрикс: Управление сайтом»

  1. Загрузка каталога начинается с того, что 1С отправляет http-запрос вместе с http-авторизацией следующего вида:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=catalog&mode=checkauth

    На этот запрос система «1С-Битрикс: Управление сайтом» отвечает тремя строками (используется разделитель строк "\n"):
    1. слово "success";
    2. имя Cookie;
    3. значение Cookie.

    Примечание:
    Все последующие запросы к 1С-Битрикс сопровождаются выставлением со стороны 1С имени и значения Cookie, полученными по команде "checkauth".

  2. Далее следует запрос вида:
    http://<сайт>/bitrix/admin/1c_import.php?mode=init

    В ответ 1С-Битрикс выдает две строчки:
    1. zip=yes, если сервер поддерживает обмен в zip-формате. В этом случае файлы на следующем шаге должны быть упакованы в zip-формате
      или
      zip=no, в таком случае файлы не должны быть упакованы, а передаются каждый по отдельности.
    2. file_limit=<число>, где <число> - максимально допустимый размер файла в байтах для передачи за один запрос. Если размер файла больше, то он должен быть порезан на части.
  3. Затем 1С запросами вида:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=catalog&mode=file&filename=<имя файла>
    загружает на сервер файлы обмена в формате CommerceML 2, посылая содержимое файла или его части в виде POST.

    В случае успешной записи файла 1С-Битрикс выдает "success".
  4. На последнем шаге по запросу из 1С проводится пошаговая загрузка каталога:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=catalog&mode=import&filename=<имя файла>

    Во время загрузки система «1С-Битрикс: Управление сайтом» может отвечать в одном из следующих форматов:
    1. Если в первой строке содержится слово "progress" - это означает необходимость послать тот же запрос повторно. В этом случае во второй строке будет возвращен текущий статус обработки, объем загруженных данных, статус импорта и т.д.
    2. Если в строке содержится слово "success", то это сообщает об успешном окончании обработки файла <имя файла>.

Примечание:
Если в ходе какого-либо запроса произошла ошибка, то ответ системы 1С-Битрикс будет иметь вид: в первой строке слово "failure", а на следующих - описание ошибки, произошедшей в процессе обработки запроса.

Если произошла необрабатываемая ошибка уровня ядра продукта или sql-запроса, то в таком случае будет возвращен html-код.


Обмен заказами с 1С

Данный раздел описывает протокол обмена информацией между программным комплексом «1С: Предприятие 8.1» и «1С-Битрикс: Управление сайтом».

Инициатором обмена во всех случаях выступает «1С: Предприятие». Обмен производится в формате CommerceML 2.0 (CML 2.0).

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

Аналогично загрузке каталога в 1С-Битрикс происходит и обмен заказами с 1С:

  1. Обмен заказами начинается с того, что 1С посылает http-запрос вместе с http-авторизацией следующего вида: http://<сайт>/bitrix/admin/1c_exchange.php?type=sale&mode=checkauth

    На этот запрос система 1С-Битрикс отвечает тремя строками (используется разделитель строк "\n"):
    1. слово "success";
    2. имя Cookie;
    3. значение Cookie.

    Примечание:
    все последующие запросы к 1С-Битрикс сопровождаются выставлением со стороны 1С имени и значения Cookie, полученными по команде "checkauth".

  2. Далее следует запрос 1С вида:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=sale&mode=init

    В ответ 1С-Битрикс выдает две строчки:
    1. zip=yes, если сервер поддерживает обмен в zip-формате. В этом случае файлы на следующем шаге должны быть упакованы в zip-формате
      или
      zip=no, в таком случае файлы не должны быть упакованы, а передаются каждый по отдельности.
    2. file_limit=<число>, где <число> - максимально допустимый размер файла в байтах для передачи за один запрос. Если размер файла больше, то он должен быть порезан на части.
  3. Затем отправляется запрос вида:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=sale&mode=query

    Сайт отдает заказы в формате CML 2. В случае успешного получения и записи заказов в 1С совершается запрос вида:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=sale&mode=success
  4. Затем из 1С отправляется запрос вида:
    http://<сайт>/bitrix/admin/1c_exchange.php?type=sale&mode=file&filename=<имя файла>
    который загружает на сервер файл обмена, посылая содержимое файла в виде POST.

    В случае успешной записи файла 1С-Битрикс выдает "success". Дополнительно на следующих строчках могут содержаться замечания по загрузке.

Примечание:
Если в ходе какого-либо запроса произошла ошибка, то ответ системы 1С-Битрикс будет иметь вид:
в первой строке слово "failure", а на следующих - описание ошибки, произошедшей в процессе обработки запроса.
Если произошла необрабатываемая ошибка уровня ядра продукта или sql-запроса, то в таком случае будет возвращен html-код.


События

События, связанные с работой Интернет-магазина:

  • OnBeforeOrderDelete - событие вызывается в методе CSaleOrder::Delete и может быть использовано для отмены удаления:
    ID - идентификатор заказа.

  • OnOrderDelete - событие вызывается в момент удаления заказа:
    ID - идентификатор заказа.

  • OnSaleBeforePayOrder - событие вызывается в методе CSaleOrder::PayOrder и может быть использовано для отмены оплаты заказа и отмены снятия оплаты:
    ID - идентификатор заказа;
    val - флаг оплаты (Y - выставление оплаты, N - снятие оплаты);
    bWithdraw - значение true отражает изменение флага на внутреннем счете пользователя; значение false изменяет только флаг, не затрагивая счет;
    bPay - если параметр bWithdraw установлен в true, то установка параметра bPay в true приведет к тому, что необходимая сумма денег будет внесена на счет покупателя перед оплатой, а установка в false приведет к тому, что оплата будет происходить целиком с внутреннего счета; если параметр bWithdraw установлен в false, то операции со счетом не производятся и значение параметра bPay не играет роли;
    recurringID - должен быть равен 0;
    arAdditionalFields - массив дополнительно обновляемых параметров (обычно это номер и дата платежного поручения).

  • OnSalePayOrder - событие вызывается в момент оплаты заказа:
    ID - идентификатор заказа;
    val - флаг оплаты (Y - выставление оплаты, N - снятие оплаты).

  • OnSaleBeforeDeliveryOrder - событие вызывается в методе CSaleOrder::DeliverOrder и может быть использовано для отмены разрешения/запрещения доставки:
    ID - идентификатор заказа;
    val - флаг разрешения доставки (Y - разрешено, N - запрещено).

  • OnSaleDeliveryOrder - событие вызывается в момент разрешения доставки заказа:
    ID - идентификатор заказа;
    val - флаг разрешения доставки (Y - разрешено, N - запрещено).

  • OnSaleBeforeCancelOrder - событие вызывается в методе CSaleOrder::CancelOrder и может быть использовано для отмены "Отмены заказа":
    ID - идентификатор заказа;
    val - флаг отмены (Y - отменен, N - неотменен).

  • OnSaleCancelOrder - событие вызывается в момент отмены заказа:
    ID - идентификатор заказа;
    val - флаг отмены (Y - отменен, N - неотменен).

  • OnSaleBeforeStatusOrder - событие вызывается в методе CSaleOrder::StatusOrder и может быть использовано для изменения статуса заказа:
    ID - идентификатор заказа;
    val - идентификатор статуса.

  • OnSaleStatusOrder - событие вызывается в момент смены статуса заказа:
    ID - идентификатор заказа;
    val - идентификатор статуса.

  • OnSaleStatusEMail - событие вызывается в момент формирования письма клиенту о смене статуса заказа. Может быть использовано для переопределения текста письма или его дополнения (для этого обработчик события должен возвращать необходимый текст):
    ID - идентификатор заказа;
    val - идентификатор статуса.

  • OnBeforeOrderAdd - событие вызывается в методе CSaleOrder::Add и может быть использовано для отмены добавления заказа:
    arFields - массив полей заказа.

  • OnOrderAdd - событие вызывается в момент добавления заказа:
    ID - идентификатор заказа;
    arFields - массив полей заказа.

  • OnBeforeOrderUpdate - событие вызывается в методе CSaleOrder::Update и может быть использовано для отмены изменения заказа:
    ID - идентификатор заказа;
    arFields - массив полей заказа.

  • OnOrderUpdate - событие вызывается после изменения заказа:
    ID - идентификатор заказа;
    arFields - массив полей заказа.

  • OnBeforePersonTypeUpdate - событие вызывается в методе CSalePersonType::Update и может быть использовано для отмены изменения типа плательщика:
    ID - идентификатор типа плательщика;
    arFields - массив полей типа плательщика.

  • OnPersonTypeUpdate - событие вызывается после изменения типа плательщика:
    ID - идентификатор типа плательщика;
    arFields - массив полей типа плательщика.

  • OnBeforePersonTypeDelete - событие вызывается в методе CSalePersonType::Delete и может быть использовано для отмены удаления типа плательщика:
    ID - идентификатор типа плательщика.

  • OnPersonTypeDelete - событие вызывается после удаления типа плательщика:
    ID - идентификатор типа плательщика.
  • OnBeforePersonTypeAdd - событие вызывается в методе CSalePersonType::Add и может быть использовано для отмены добавления типа плательщика:
    arFields - массив полей типа плательщика.

  • OnPersonTypeAdd - событие вызывается после добавления типа плательщика:
    ID - идентификатор типа плательщика;
    arFields - массив полей типа плательщика.

  • OnBeforeStatusAdd - событие вызывается в методе CSaleStatus::Add и может быть использовано для отмены добавления статуса заказа:
    ID - идентификатор статуса;
    arFields - массив полей статуса.

  • OnStatusAdd - событие вызывается после добавления статуса заказа:
    ID - идентификатор статуса;
    arFields - массив полей статуса.

  • OnBeforeStatusUpdate - событие вызывается в методе CSaleStatus::Update и может быть использовано для отмены изменения статуса заказа:
    ID - идентификатор статуса;
    arFields - массив полей статуса.

  • OnStatusUpdate - событие вызывается после изменения статуса заказа:
    ID - идентификатор статуса;
    arFields - массив полей статуса.

  • OnBeforeStatusDelete - событие вызывается в методе CSaleStatus::Delete и может быть использовано для отмены удаления статуса заказа:
    ID - идентификатор статуса.

  • OnStatusDelete - событие вызывается после удаления статуса заказа:
    ID - идентификатор статуса.

  • OnSaleUserDelete - событие вызывается при удалении пользователя Интернет-магазина:
    ID - идентификатор пользователя Интернет-магазина.

  • OnAffiliateGetSections - событие вызывается в методе CSaleAffiliate::CalculateAffiliate, если модуль товара не catalog. Позволяет задать секции для товара, расположенного не в модуле каталог, используемые для планов аффилиатов:
    BASKET_MODULE - идентификатор модуля товара корзины;
    BASKET_PRODUCT_ID - идентификатор товара.

  • OnOrderListFilter - событие вызывается при формировании фильтра для списка заказов в административной части. Позволяет модифицировать значения фильтра. Для этого обработчик события должен вернуть модифицированный массив фильтра:
    arFilter - массив фильтра.

  • OnBasketItiSave - событие вызывается при запуске скрипта редактирования заказа в административной части. Возвращаемое значение - путь к PHP скрипту. Указаный скрипт дергается на сервере при каждом нажатии на кнопку "Cохранить" товара в заказе. Позволяет подменять параметры товара в заказе:
    ID - идентификатор заказа.

  • OnProductSearchFormIBlock - событие вызывается при формировании фильтра для выбора товаров для заказа. Позволяет модифицировать значения фильтра. Для этого обработчик события должен вернуть модифицированный массив фильтра:
    arFilter - массив фильтра.

  • OnProductSearchForm - событие вызывается для каждого товара в форме поиска товара. Возвращаемое значение - массив (в формате JScript) новых параметров товара. Может использоваться, если товары в заказе должны иметь не те параметры, которые они имеют в каталоге:
    ID - код товара;
    arParams - текущее значение, передающееся в качестве параметров товара (массив в формате JScript).

  • OnBeforeCountryUpdate - событие вызывается в методе CSaleLocation::UpdateCountry и может быть использовано для отмены изменения страны доставки:
    ID - идентификатор страны;
    arFields - массив полей страны.

  • OnCountryUpdate - событие вызывается после изменения страны доставки:
    ID - идентификатор страны;
    arFields - массив полей страны.

  • OnBeforeCountryDelete - событие вызывается в методе CSaleLocation::DeleteCountry и может быть использовано для отмены удаления страны доставки:
    ID - идентификатор страны.

  • OnCountryDelete - событие вызывается после удаления страны доставки:
    ID - идентификатор страны.

  • OnBeforeCityUpdate - событие вызывается в методе CSaleLocation::UpdateCity и может быть использовано для отмены изменения города доставки:
    ID - идентификатор города;
    arFields - массив полей города.

  • OnCityUpdate - событие вызывается после изменения города доставки:
    ID - идентификатор города;
    arFields - массив полей города.

  • OnBeforeCityDelete - событие вызывается в методе CSaleLocation::DeleteCity и может быть использовано для отмены удаления города доставки:
    ID - идентификатор города.

  • OnCityDelete - событие вызывается после удаления города доставки:
    ID - идентификатор города.

  • OnBeforeLocationUpdate - событие вызывается в методе CSaleLocation::Update и может быть использовано для отмены изменения местоположения доставки:
    ID - идентификатор местоположения;
    arFields - массив полей местоположения.

  • OnLocationUpdate - событие вызывается после изменения местоположения доставки:
    ID - идентификатор местоположения;
    arFields - массив полей местоположения.

  • OnBeforeLocationDelete - событие вызывается в методе CSaleLocation::Delete и может быть использовано для отмены удаления местоположения доставки:
    ID - идентификатор местоположения.

  • OnLocationDelete - событие вызывается после удаления местоположения доставки:
    ID - идентификатор местоположения.

  • OnBeforeCountryAdd - событие вызывается в методе CSaleLocation::AddCountry и может быть использовано для отмены добавления страны доставки:
    arFields - массив полей страны.

  • OnCountryAdd - событие вызывается после добавления страны доставки:
    ID - идентификатор страны;
    arFields - массив полей страны.

  • OnBeforeCityAdd - событие вызывается в методе CSaleLocation::AddCity и может быть использовано для отмены добавления города доставки:
    arFields - массив полей города.

  • OnCityAdd - событие вызывается после добавления города доставки:
    ID - идентификатор города;
    arFields - массив полей города.

  • OnBeforeLocationAdd - событие вызывается в методе CSaleLocation::Add и может быть использовано для отмены добавления местоположения доставки:
    arFields - массив полей местоположения.

  • OnLocationAdd - событие вызывается после добавления местоположения доставки:
    ID - идентификатор местоположения;
    arFields - массив полей местоположения.

  • OnBeforeLocationGroupUpdate - событие вызывается в методе CSaleLocationGroup::Update и может быть использовано для отмены изменения группы местоположений доставки:
    ID - идентификатор группы местоположений;
    arFields - массив полей группы местоположений.

  • OnLocationGroupUpdate - событие вызывается после изменения группы местоположений доставки:
    ID - идентификатор группы местоположений;
    arFields - массив полей группы местоположений.

  • OnBeforeLocationGroupDelete - событие вызывается в методе CSaleLocationGroup::Delete и может быть использовано для отмены удаления группы местоположений доставки:
    ID - идентификатор группы местоположений.

  • OnLocationGroupDelete - событие вызывается после удаления группы местоположений доставки:
    ID - идентификатор группы местоположений.

  • OnBeforeLocationGroupAdd - событие вызывается в методе CSaleLocationGroup::Add и может быть использовано для отмены добавления группы местоположений доставки:
    arFields - массив полей группы местоположений.

  • OnLocationGroupAdd - событие вызывается после добавления группы местоположений доставки:
    ID - идентификатор группы местоположений;
    arFields - массив полей группы местоположений.

  • onSaleDeliveryHandlersBuildList - событие вызывается при формировании списка обработчиков автоматизированных служб доставки.

  • onSaleDeliveryHandlerCalculate
    onSaleDeluveryHandlerCalculate_$SID
    Эти два события вызываются после совершения рассчета стоимости доставки (первый - для любого обработчика, второй для обработчика службы доставки со строковым идентификатором $SID). Входные параметры:
    string $SID - строковой идентификатор службы доставки;
    string $profile - строковой идентификатор профиля доставки;
    array $arOrder - ассоциативный массив, описывающий заказ. Ключи: WEIGHT - суммарный вес заказа; PRICE - суммарная стоимость заказа; LOCATION_FROM - идентификатор местоположения точки отправления; LOCATION_TO - идентификатор местоположения точки доставки;
    array $arReturn - ассоциативный массив результата, возвращенный обработчиком заказа.
    В качестве результата обработчика события ожидается массив, аналогичный по структуре параметру $arReturn;

    • Дополнительно смотрите также документацию по службам доставки.


Классы модуля магазина

Следующие PHP классы используются в модуле интернет-магазина.

Классы

Класс | Описание
CSaleAuxiliary | Класс для облегчения предоставления платного доступа к ресурсам.
CSaleBasket | Класс для работы с корзиной покупателей.
CSaleDelivery | Класс для работы со службами (методами) доставки.
CSaleDiscount | Класс для работы со скидками на сумму заказа.
CSaleLocation | Класс для работы с местоположениями.
CSaleLocationGroup | Класс для работы с группами местоположений.
CSaleOrder | Класс для работы с заказами.
CSaleOrderProps | Класс для работы с набираемыми свойствами заказов.
CSaleOrderPropsGroup | Класс для работы с группами свойств заказов.
CSaleOrderPropsValue | Класс для работы со значениями свойств заказов.
CSaleOrderPropsVariant | Класс для работы с вариантами значений свойств заказов.
CSaleOrderTax | Класс для работы с суммами налогов, которые начисляются для каждого заказа.
CSaleOrderUserProps | Класс для работы с профилями покупателей.
CSaleOrderUserPropsValue | Класс для работы со значениями свойств заказов, сохраняемыми в профилях покупателей.
CSalePaySystem | Класс для работы с платежными системами.
CSalePaySystemAction | Класс для работы с обработчиками платежных систем.
CSalePersonType | Класс для работы с типами плательщиков.
CSaleRecurring | Класс для работы с возобновляемыми подписками.
CSaleStatus | Класс для работы со статусами заказов.
CSaleTax | Класс для работы с налогами.
CSaleTaxRate | Класс для работы со ставками налогов.
CSaleUserAccount | Класс для работы с внутренними счетами клиентов.
CSaleUserCards | Класс для работы с платежными картами.
CSaleUserTransact | Класс для работы с платежными транзакциями.


CSaleAuxiliary

Методы класса

Метод | Описание
DeleteByTime | Метод удаляет всю информацию о временном доступе, которая старше указанного времени.
DeleteByUserID | Метод удаляет всю информацию о временном доступе пользователя с кодом userID.
GetByID | Метод выбирает параметры информации о временном доступе с кодом ID.
GetByParams | Метод выбирает параметры информации о временном доступе к ресурсу с идентификатором itemMD5 для пользователя с кодом userID.
GetList | Функция возвращает результат выборки записей информации о временном доступе в соответствии со своими параметрами.
Update | Метод изменяет параметры записи с кодом ID информации о временном доступе к ресурсу в соответствии с данными из массива arFields.
Add | Метод добавляет новую запись с информацией о временном доступе к ресурсу в соответствии с данными из массива arFields.
CheckAccess | Метод проверяет, может ли посетитель с кодом userID получить доступ к ресурсу с идентифицирующей строкой itemMD5.
Delete | Метод удаляет информацию о временном доступе с кодом ID.


Add

CSaleAuxiliary::Add

int
CSaleAuxiliary::Add(
 array arFields
);

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

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой информации о временном доступе к ресурсу, ключами в котором являются названия параметров, а значениями - соответствующие значения. Допустимые ключи:
  • USER_ID - код пользователя;
  • ITEM - ресурс, доступ к которому разрешен;
  • ITEM_MD5 - идентификатор ресурса (строка, однозначно идентифицирующая ресурс);
  • DATE_INSERT - дата вставки записи.

Возвращаемые значения

Метод возвращает код вставленной записи или false в случае ошибки.


CheckAccess

CSaleAuxiliary::CheckAccess

bool
CSaleAuxiliary::CheckAccess(
 int userID,
 string itemMD5,
 int periodLength,
 string periodType
);

Метод проверяет, может ли посетитель с кодом userID получить доступ к ресурсу с идентифицирующей строкой itemMD5. Период, в течение которого пользователь имеет доступ к ресурсу, задается длиной periodLength и типом periodType.

Параметры функции

Параметр | Описание
userID | Код пользователя.
itemMD5 | Строка, однозначно идентифицирующая ресурс (идентификатор ресурса).
periodLength | Длина периода, в течение которого пользователь имеет доступ к ресурсу.
periodType | Тип длины периода, в течение которого пользователь имеет доступ к ресурсу. Допустимые значения: I - минута, H - час, D - сутки, W - неделя, M - месяц, Q - квартал, S - полугодие, Y - год.

Возвращаемые значения

true, если пользователь может получить доступ к данному ресурсу, и false - в противном случае.

Пример использования

<?
if (CSaleAuxiliary::CheckAccess($USER->GetID(), "pict.jpg", 2, "D"))
{
    echo '<a href="'.pict.jpg.'">Файл доступен для скачивания</a>';
}
else
{
    echo "Файл не доступен для скачивания";
}
?>


Delete

CSaleAuxiliary::Delete

bool
CSaleAuxiliary::Delete(
 int ID
);

Метод удаляет информацию о временном доступе с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

true в случае успешного удаления и false в противном случае.


DeleteByTime

CSaleAuxiliary::DeleteByTime

bool
CSaleAuxiliary::DeleteByTime(
 int periodLength,
 sring periodType
);

Метод удаляет всю информацию о временном доступе, которая старше указанного времени.

Параметры функции

Параметр | Описание
periodLength | Длина периода времени, в течение которого пользователь имеет доступ к ресурсу.
periodType Тип длины периода времени, в течение которого пользователь имеет доступ к ресурсу. Допустимые значения:
  • I - минута;
  • H - час;
  • D - сутки;
  • W - неделя;
  • M - месяц;
  • Q - квартал;
  • S - полугодие;
  • Y - год.

Возвращаемые значения

true в случае успешного удаления и false в противном случае.

Пример использования

<?
// Удалим все записи старше 2 дней
CSaleAuxiliary::DeleteByTime(2, "D");
?>


DeleteByUserID

CSaleAuxiliary::DeleteByUserID

bool
CSaleAuxiliary::DeleteByUserID(
 int userID
);

Метод удаляет всю информацию о временном доступе пользователя с кодом userID.

Параметры функции

Параметр | Описание
userID | Код пользователя.

Возвращаемые значения

true в случае успешного удаления и false в противном случае.


GetByID

CSaleAuxiliary::GetByID

array
CSaleAuxiliary::GetByID(
 int ID
);

Метод выбирает параметры информации о временном доступе с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров информации о временном доступе с ключами:

  • ID - код записи;
  • USER_ID - код пользователя;
  • ITEM - ресурс, доступ к которому разрешен;
  • ITEM_MD5 - идентификатор ресурса (строка, однозначно идентифицирующая ресурс);
  • TIMESTAMP_X - дата изменения;
  • DATE_INSERT - дата вставки записи.


GetByParams

CSaleAuxiliary::GetByParams

array
CSaleAuxiliary::GetByParams(
 int userID,
 string itemMD5
);

Метод выбирает параметры информации о временном доступе к ресурсу с идентификатором itemMD5 для пользователя с кодом userID.

Параметры функции

Параметр | Описание
userID | Код пользователя.
itemMD5 | Идентификатор ресурса (строка, однозначно идентифицирующая ресурс).

Возвращаемые значения

Метод возвращает ассоциативный массив параметров информации о временном доступе с ключами:

  • ID - код записи
  • USER_ID - код пользователя
  • ITEM - ресурс, доступ к которому разрешен
  • ITEM_MD5 - идентификатор ресурса (строка, однозначно идентифицирующая ресурс)
  • TIMESTAMP_X - дата изменения
  • DATE_INSERT - дата вставки записи


GetList

CSaleAuxiliary::GetList

CDBResult
CSaleAuxiliary::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей информации о временном доступе в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле информации о временном доступе, а в качестве "направление_сортировкиN" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи информации о временном доступе. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляN" может стоять любое поле информации о временном доступе.

Пример фильтра:
array("USER_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_ID (код пользователя) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи информации о временном доступе. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле информации о временном доступе. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров информации о временном доступе с ключами:

  • ID - код записи;
  • USER_ID - код пользователя;
  • ITEM - ресурс, доступ к которому разрешен;
  • ITEM_MD5 - идентификатор ресурса (строка, однозначно идентифицирующая ресурс);
  • TIMESTAMP_X - дата изменения;
  • DATE_INSERT - дата вставки записи.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


Update

CSaleAuxiliary::Update

int
CSaleAuxiliary::Update(
 int ID,
 array arFields
);

Метод изменяет параметры записи с кодом ID информации о временном доступе к ресурсу в соответствии с данными из массива arFields.

Параметры функции

Параметр | Описание
ID | Код записи.
arFields Ассоциативный массив параметров новой информации о временном доступе к ресурсу, ключами в котором являются названия параметров, а значениями - соответствующие значения. Допустимые ключи:
  • USER_ID - код пользователя;
  • ITEM - ресурс, доступ к которому разрешен;
  • ITEM_MD5 - идентификатор ресурса (строка, однозначно идентифицирующая ресурс);
  • DATE_INSERT - дата вставки записи.

Возвращаемые значения

Метод возвращает код измененной записи или false в случае ошибки.


CSaleBasket

Методы класса

Метод | Описание
Init | Функция инициализирует внутренний код владельца корзины.
Update | Функция обновляет параметры товара с кодом ID на основании массива arFields.
GetByID | Функция возвращает параметры записи корзины с кодом ID
GetList | Функция возвращает результат выборки записей из корзины в соответствии со своими параметрами.
UpdatePrice | Функция актуализирует параметры записи с кодом ID корзины на основании функции обратного вызова для поддержки актуальности корзины.
OrderBasket | Функция привязывает к заказу с кодом OrderID товары из корзины, которые доступны к покупке и не являются отложенными.
Add | Функция добавляет товар в корзину, если его ещё нет, и обновляет параметры товара с увеличением количества, если он уже находится в корзине.
GetBasketUserID | Функция возвращает внутренний код владельца корзины.
Delete | Функция удаляет запись корзины с кодом ID.
Delete | Функция удаляет из корзины все записи с внутренним кодом владельца fUserID.


Add

CSaleBasket::Add

int
CSaleBasket::Add(
  array arFields
);

Функция добавляет товар в корзину, если его ещё нет, и обновляет параметры товара с увеличением количества, если он уже находится в корзине. В массиве arFields перечисляются все параметры товара, которые нужны для работы модуля Интернет-магазина (т.е. этот модуль не зависит от других модулей и работает полностью самостоятельно).

Интернет-магазин не зависит от других модулей, поэтому товары в корзину модуля продаж могут добавляться из любого места (например, из торгового каталога или со статической страницы). Для некоторых модулей существуют функции - оболочки, облегчающие добавление товара в корзину (например, для модуля catalog существуют функции Add2Basket и Add2BasketByProductID).

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров элемента корзины, содержащий следующие ключи:
  • PRODUCT_ID - уникальный в рамках модуля код товара (обязательное поле);
  • PRODUCT_PRICE_ID - дополнительный код товара;
  • PRICE - стоимость единицы товара (обязательное поле);
  • CURRENCY - валюта стоимости единицы товара (обязательное поле), если валюта отличается от базовой валюты для данного сайта, то стоимость будет автоматически сконвертирована по текущему курсу;
  • WEIGHT - вес единицы товара;
  • QUANTITY - количество единиц товара;
  • LID - сайт, на котором сделана покупка (обязательное поле);
  • DELAY - флаг "товар отложен" (Y/N);
  • CAN_BUY - флаг "товар можно купить" (Y/N) - может устанавливаться автоматически про наличии функции обратного вызова для поддержки актуальности корзины;
  • NAME - название товара (обязательное поле);
  • CALLBACK_FUNC - название функции обратного вызова для поддержки актуальности корзины (описание ниже);
  • MODULE - модуль, добавляющий товар в корзину;
  • NOTES - особые заметки, например, тип цены;
  • ORDER_CALLBACK_FUNC - название функции обратного вызова для оформления заказа (описание ниже);
  • DETAIL_PAGE_URL - ссылка на страницу детального просмотра товара;
  • CANCEL_CALLBACK_FUNC - название функции обратного вызова для отмены заказа (описание ниже);
  • PAY_CALLBACK_FUNC - название функции обратного вызова, которая вызывается при установке флага "Доставка разрешена" заказа;
  • PROPS - массив свойств товара, который сохраняется в корзине. Каждый элемент этого массива является массивом следующего формата:
    array("NAME"  => "Название свойства",
      "CODE"  => "Код свойства",
      "VALUE" => "Значение свойства",
      "SORT"  => "Индекс сортировки")

Возвращаемые значения

Функция возвращает код элемента корзины, в который попал данный товар.

Пример использования

<?
if (CModule::IncludeModule("sale"))
{
  $arFields = array(
    "PRODUCT_ID" => 51,
    "PRODUCT_PRICE_ID" => 0,
    "PRICE" => 138.54,
    "CURRENCY" => "RUR",
    "WEIGHT" => 530,
    "QUANTITY" => 1,
    "LID" => LANG,
    "DELAY" => "N",
    "CAN_BUY" => "Y",
    "NAME" => "Чемодан кожаный",
    "CALLBACK_FUNC" => "MyBasketCallback",
    "MODULE" => "my_module",
    "NOTES" => "",
    "ORDER_CALLBACK_FUNC" => "MyBasketOrderCallback",
    "DETAIL_PAGE_URL" => "/".LANG."/detail.php?ID=51"
  );

  $arProps = array();

  $arProps[] = array(
    "NAME" => "Цвет",
    "CODE" => "color",
    "VALUE" => "черный"
  );

  $arProps[] = array(
    "NAME" => "Размер",
    "VALUE" => "1.5 x 2.5"
  );

  $arFields["PROPS"] = $arProps;

  CSaleBasket::Add($arFields);
}
?>

Функция обратного вызова для поддержки актуальности корзины

Функция обратного вызова вызывается (если установлена) при каждом чтении корзины для обновления параметров содержащихся в корзине товаров. Например, если после добавления товара в корзину изменилась его цена или товар сняли с продажи, то использование функции обратного вызова позволяет соответственно обновить данные в корзине. В поле CALLBACK_FUNC записывается только имя функции обратного вызова. Для некоторых модулей функции обратного вызова уже написаны (например, для модуля catalog функция обратного вызова называется CatalogBasketCallback($PRODUCT_ID, $QUANTITY = 0, $renewal = "N"))

array CALLBACK_FUNC(
 int PRODUCT_ID [,
 int QUANTITY,
 char renewal]
);

Функция обратного вызова должна возвращать массив той же структуры, что и входной массив функции CSaleBasket::Add(array arFields). Если функция возвращает пустой массив, то это означает, что данный товар не доступен для покупки.

Параметры функции обратного вызова

PRODUCT_ID
Код товара, находящегося в корзине.
QUANTITY
Количество товаров в корзине.
renewal
Равен "Y", если функция вызывается для продления подписки, и "N" в остальных случаях.
Пример создания функции обратного вызова

<?
function MyBasketCallback($PRODUCT_ID, $QUANTITY = 0)
{
  $arResult = array();

  $iProductQuantity = GetProductQuantity($PRODUCT_ID);
  if ($iProductQuantity<=0)
    return $arResult;    // товар кончился, возвращаем пустой массив

  $arResult = array(
    "PRODUCT_PRICE_ID" => 0,
    "PRICE" => 125.2,
    "CURRENCY" => "RUR",
    "WEIGHT" => 530,
    "NAME" => "Чемодан кожаный",
    "CAN_BUY" => "Y"
  );

  if (IntVal($QUANTITY)>0 && ($iProductQuantity-$QUANTITY)<0)
    $arResult["QUANTITY"] = $iProductQuantity;    // товара осталось
                     // меньше, чем в корзине, поэтому уменьшаем
                     // количество товара в корзине

  return $arResult;
}
?>

Функция обратного вызова для оформления заказа

Функция обратного вызова для оформления заказа вызывается (если установлена) в момент оформления заказа на данный товар. Например, если отслеживается количество оставшихся в магазине единиц товара, то использование функции обратного вызова заказа позволяет соответственно уменьшить количество оставшихся в магазине единиц товара. В поле ORDER_CALLBACK_FUNC записывается только имя функции обратного вызова заказа. Для некоторых модулей функции обратного вызова заказа уже написаны (например, для модуля catalog функция обратного вызова заказа называется CatalogBasketOrderCallback($PRODUCT_ID, $QUANTITY))

void ORDER_CALLBACK_FUNC(
 int PRODUCT_ID,
 int QUANTITY
);

Функция не возвращает значений.

Параметры функции обратного вызова заказа

PRODUCT_ID
Код товара, находящегося в корзине.
QUANTITY
Количество товаров в корзине.
Пример создания функции обратного вызова заказа

<?
function MyBasketOrderCallback($PRODUCT_ID, $QUANTITY)
{
   UpdateProductQuantity($PRODUCT_ID, $QUANTITY);
}
?>

Функция обратного вызова для отмены заказа

Функция обратного вызова для отмены заказа вызывается при отмене или удалении заказа. Она служит как правило для возвращения в продажу зарезервированого для заказа количества товара. В поле CANCEL_CALLBACK_FUNC записывается только имя функции обратного вызова заказа. Для некоторых модулей функции обратного вызова заказа уже написаны (например, для модуля catalog функция обратного вызова заказа называется CatalogBasketCancelCallback($PRODUCT_ID, $QUANTITY, $bCancel))

void CANCEL_CALLBACK_FUNC(
int PRODUCT_ID,
int QUANTITY,
bool bCancel
);

Функция не возвращает значений.

Параметры функции обратного вызова заказа.

PRODUCT_ID

Код товара, находящегося в корзине.

QUANTITY

Количество товаров в корзине.

bCancel

true, если отменяется заказ, и false, если отменяется.

Пример создания функции обратного вызова заказа

function MyBasketCancelCallback($PRODUCT_ID, $QUANTITY, $bCancel)
{
    $PRODUCT_ID = IntVal($PRODUCT_ID);
    $QUANTITY = IntVal($QUANTITY);
    $bCancel = ($bCancel ? True : False);

    if ($bCancel)
        UpdateProductQuantity($PRODUCT_ID, -$QUANTITY);
    else
        UpdateProductQuantity($PRODUCT_ID, $QUANTITY);
}

Функция обратного вызова при разрешении доставки

Функция обратного вызова при разрешении доставки вызывается при разрешении доставки заказа. Она может служить для привязки пользователя к каким-либо группам пользователей, для начисления на счет пользователя каких-либо сумм и для других действий, которые должны произойти в момент выполнения заказа. В поле PAY_CALLBACK_FUNC записывается только имя функции обратного вызова. Для некоторых модулей функции обратного вызова заказа уже написаны (например, для модуля catalog функция обратного вызова заказа называется CatalogPayOrderCallback($productID, $userID, $bPaid, $orderID))

array PAY_CALLBACK_FUNC(
 int productID,
 int userID,
 bool bPaid,
 int orderID
);

Функция может вернуть одно из следующих значений:

  • массив для вставки в продление заказа;
  • true, если функция отработала успешно, но вставлять в продление ничего не надо;
  • false, если функция во время работы функции произошли ошибки.

Параметры функции обратного вызова при разрешении доставки

productID

Код товара, находящегося в корзине.

userID

Код пользователя, осуществившего заказ.

bPaid

true, если доставка заказа разрешена, и false, если запрещена

orderID

Код заказа.

Пример создания функции обратного вызова

function MyBasketPayOrderCallback($productID, $userID, $bPaid, $orderID)
{
    global $DB;

    $productID = IntVal($productID);
    $userID = IntVal($userID);
    $bPaid = ($bPaid ? True : False);
    $orderID = IntVal($orderID);

    if ($userID <= 0)
        return False;

    if ($orderID <= 0)
        return False;

    if (!array_key_exists($productID, $GLOBALS["arMP3Sums"]))
        return False;

    if (!($arOrder = CSaleOrder::GetByID($orderID)))
        return False;

    $currentPrice = 10;
    $currentCurrency = "USD";

    if (!CSaleUserAccount::UpdateAccount($userID,
                                         ($bPaid ? $currentPrice : -$currentPrice),
                                         $currentCurrency, "MANUAL", $orderID))
        return False;

    return True;
}


Delete

CSaleBasket::Delete

bool
CSaleBasket::Delete(
 int ID
);

Функция удаляет запись корзины с кодом ID.

Пример использования

<?
if (CSaleBasket::Delete(22))
    echo "Запись успешно удалена";
?>


DeleteAll

CSaleBasket::DeleteAll

bool
CSaleBasket::DeleteAll(
 int fUserID[,
 bool bIncOrdered = false]
);

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

Параметры функции

Параметр | Описание
fUserID | Внутренний код владельца.
bIncOrdered | Если флаг равен false (по-умолчанию), то удаляются только записи из корзины. Если флаг равен true, то удаляются и те записи, которые относятся к уже сделанным заказам.

Пример использования

<?
if (CSaleBasket::DeleteAll(3, False))
    echo "Корзина пользователя с внутренним кодом 3 успешно удалена";
?>


GetByID

CSaleBasket::GetByID

array
CSaleBasket::GetByID(
  int ID
);

Функция возвращает параметры записи корзины с кодом ID

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

Возвращается ассоциативный массив параметров с ключами:

Ключ | Описание
ID | Код записи.
PRODUCT_ID | Уникальный в рамках модуля код товара.
PRODUCT_PRICE_ID | Дополнительный код товара.
PRICE | Стоимость единицы товара.
CURRENCY | Валюта стоимости единицы товара.
WEIGHT | Вес единицы товара.
QUANTITY | Количество единиц товара.
LID | Сайт, на котором сделана покупка.
DELAY | Флаг "товар отложен" (Y/N)
CAN_BUY | Флаг "товар можно купить" (Y/N)
NAME | Название товара.
CALLBACK_FUNC | Название функции обратного вызова для поддержки актуальности корзины.
MODULE | Модуль, добавляющий товар в корзину.
NOTES | Особые заметки, например, тип цены.
ORDER_CALLBACK_FUNC | Название функции обратного вызова для оформления заказа.
DETAIL_PAGE_URL | Ссылка на страницу детального просмотра товара.
FUSER_ID | Внутренний код владельца корзины (не совпадает с кодом пользователя)
ORDER_ID | Код заказа, в который вошла эта запись (товар). Для товаров, которые помещены в корзину, но ещё не заказаны, это поле равно NULL.
DATE_INSERT | Дата добавления товара в корзину.
DATE_UPDATE | Дата последнего изменения записи.
DISCOUNT_PRICE | Скидка на товар. Значение устанавливается только после оформления заказа.
CANCEL_CALLBACK_FUNC | Название функции обратного вызова для отмены заказа.
PAY_CALLBACK_FUNC | Название функции обратного вызова, которая вызывается при установке флага заказа "Доставка разрешена".

Обратите внимание, что этот метод возвращает данные, которые были актуальны на момент последнего выполнения для этой записи функции обратного вызова для поддержки актуальности корзины (либо на момент добавления записи, если функция обратного вызова не выполнялась или не установлена).

Пример использования

<?
// Выведем актуальную корзину для текущего пользователя

$arBasketItems = array();

$dbBasketItems = CSaleBasket::GetList(
    array(
            "NAME" => "ASC",
            "ID" => "ASC"
        ),
    array(
            "FUSER_ID" => CSaleBasket::GetBasketUserID(),
            "LID" => SITE_ID,
            "ORDER_ID" => "NULL"
        ),
    false,
    false,
    array("ID",
          "CALLBACK_FUNC",
          "MODULE",
          "PRODUCT_ID",
          "QUANTITY",
          "DELAY",
          "CAN_BUY",
          "PRICE",
          "WEIGHT")
    );

while ($arItems = $dbBasketItems->Fetch())
{
    if (strlen($arItems["CALLBACK_FUNC"]) > 0)
    {
        CSaleBasket::UpdatePrice($arItems["ID"],
                                 $arItems["CALLBACK_FUNC"],
                                 $arItems["MODULE"],
                                 $arItems["PRODUCT_ID"],
                                 $arItems["QUANTITY"]);
        $arItems = CSaleBasket::GetByID($arItems["ID"]);
    }

    $arBasketItems[] = $arItems;
}

// Печатаем массив, содержащий актуальную на текущий момент корзину
echo "<pre>";
print_r($arBasketItems);
echo "</pre>";
?>


GetList

CSaleBasket::GetList

CDBResult
CSaleBasket::GetList(
  array arOrder = array(),
  array arFilter = array(),
  array arGroupBy = false,
  array arNavStartParams = false,
  array arSelectFields = array()
);

Функция возвращает результат выборки записей из корзины в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле корзины, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи корзины. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле корзины.

Пример фильтра:
array("+>=ORDER_ID" => 20)
Этот фильтр означает "выбрать все записи, в которых значение в поле ORDER_ID больше или равно 20 либо не установлено (т.е. null или ноль)".
Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи корзины. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле корзины. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
    любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код записи.
PRODUCT_ID | Уникальный в рамках модуля код товара.
PRODUCT_PRICE_ID | Дополнительный код товара.
PRICE | Стоимость единицы товара.
CURRENCY | Валюта стоимости единицы товара.
WEIGHT | Вес единицы товара.
QUANTITY | Количество единиц товара.
LID | Сайт, на котором сделана покупка.
DELAY | Флаг "товар отложен" (Y/N)
CAN_BUY | Флаг "товар можно купить" (Y/N)
NAME | Название товара.
CALLBACK_FUNC | Название функции обратного вызова для поддержки актуальности корзины.
MODULE | Модуль, добавляющий товар в корзину.
NOTES | Особые заметки, например, тип цены.
ORDER_CALLBACK_FUNC | Название функции обратного вызова для оформления заказа.
DETAIL_PAGE_URL | Ссылка на страницу детального просмотра товара.
FUSER_ID | Внутренний код владельца корзины (не совпадает с кодом пользователя)
ORDER_ID | Код заказа, в который вошла эта запись (товар). Для товаров, которые помещены в корзину, но ещё не заказаны, это поле равно NULL.
DATE_INSERT | Дата добавления товара в корзину.
DATE_UPDATE | Дата последнего изменения записи.
CANCEL_CALLBACK_FUNC | Название функции обратного вызова для отмены заказа.
PAY_CALLBACK_FUNC | Название функции обратного вызова, которая вызывается при установке флага заказа "Доставка разрешена".
DISCOUNT_PRICE | Скидка на товар. Значение устанавливается только после оформления заказа.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем актуальную корзину для текущего пользователя

$arBasketItems = array();

$dbBasketItems = CSaleBasket::GetList(
        array(
                "NAME" => "ASC",
                "ID" => "ASC"
            ),
        array(
                "FUSER_ID" => CSaleBasket::GetBasketUserID(),
                "LID" => SITE_ID,
                "ORDER_ID" => "NULL"
            ),
        false,
        false,
        array("ID", "CALLBACK_FUNC", "MODULE",
              "PRODUCT_ID", "QUANTITY", "DELAY",
              "CAN_BUY", "PRICE", "WEIGHT")
    );
while ($arItems = $dbBasketItems->Fetch())
{
    if (strlen($arItems["CALLBACK_FUNC"]) > 0)
    {
        CSaleBasket::UpdatePrice($arItems["ID"],
                                 $arItems["CALLBACK_FUNC"],
                                 $arItems["MODULE"],
                                 $arItems["PRODUCT_ID"],
                                 $arItems["QUANTITY"]);
        $arItems = CSaleBasket::GetByID($arItems["ID"]);
    }

    $arBasketItems[] = $arItems;
}

// Печатаем массив, содержащий актуальную на текущий момент корзину
echo "<pre>";
print_r($arBasketItems);
echo "</pre>";
?>


GetBasketUserID

CSaleBasket::GetBasketUserID

int
CSaleBasket::GetBasketUserID();

Функция возвращает внутренний код владельца корзины.

Пример использования

<?
// Выберем записи корзины текущего пользователя

$dbBasketItems = CSaleBasket::GetList(
        array(
                "NAME" => "ASC",
                "ID" => "ASC"
                ),
        array(
                "FUSER_ID" => CSaleBasket::GetBasketUserID(),
                "LID" => SITE_ID,
                "ORDER_ID" => "NULL"
                ),
        false,
        false,
        array()
        );
?>


GetPropsList

CSaleBasket::GetPropsList

CDBResult
CSaleBasket::GetPropsList(
  array arOrder = array(),
  array arFilter = array(),
  array arGroupBy = false,
  array arNavStartParams = false,
  array arSelectFields = array()
);

Функция возвращает результат выборки записей из свойств корзины в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле корзины, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи корзины. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание,
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра,
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле корзины.

Пример фильтра:
array("!~VALUE" => "JOHN*")
Этот фильтр означает "выбрать все записи, в которых значение в поле VALUE не начинается с символов JOHN".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи корзины. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле корзины. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа
    любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код записи.
BASKET_ID | Код элемента корзины, к которому привязано данное свойство.
NAME | Название свойства.
VALUE | Значение свойства.
CODE | Мнемонический код свойства.
SORT | Индекс сортировки свойства.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем все свойства элемента корзины с кодом $basketID
$db_res = CSaleBasket::GetPropsList(
        array(
                "SORT" => "ASC",
                "NAME" => "ASC"
            ),
        array("BASKET_ID" => $basketID)
    );
while ($ar_res = $db_res->Fetch())
{
   echo $ar_res["NAME"]."=".$ar_res["VALUE"]."<br>";
}
?>


Init

CSaleBasket::Init

Данная функция устарела и не рекомендуется к применению. Для того чтобы получить внутренний код владельца корзины, следует пользоваться методом CSaleBasket::GetBasketUserID.

CSaleBasket::Init();

Функция инициализирует внутренний код владельца корзины. После инициализации внутренний код доступен в сессионной переменной $_SESSION["SALE_USER_ID"].
Внутренний код необходимо обязательно инициализировать перед использованием. Функции-оболочки (например, GetBasketList()) автоматически вызывают инициализацию внутреннего кода владельца корзины.
Повторные вызовы функции инициализации внутреннего кода владельца корзины игнорируются системой.

Пример использования

<?
// Выберем содержимое корзины текущего пользователя на текущем сайте
// (полный функционал, включающий актуализацию корзины, выполняется функцией GetBasketList())
CSaleBasket::Init();
$db_res = CSaleBasket::GetList(($b=""), ($o=""), array("FUSER_ID"=>$_SESSION["SALE_USER_ID"], "LID"=>SITE_ID, "ORDER_ID"=>"NULL"));
?>


OrderBasket

CSaleBasket::OrderBasket

CSaleBasket::OrderBasket(
  int OrderID,
  int FUSER_ID = 0,
  string strLang = SITE_ID,
  array arDiscounts = false
);

Функция привязывает к заказу с кодом OrderID товары из корзины, которые доступны к покупке и не являются отложенными. Эта функция выполняется при оформлении заказа на товары корзины.

Параметры функции

Параметр | Описание
OrderID | Код заказа, к которому привязываются товары из корзины.
FUSER_ID | Внутренний код владельца корзины. Если не установлен (равен нулю) или текущий пользователь не имеет прав на запись на модуль Интернет-магазина, то берется внутренний код для текущего пользователя.
strLang | Сайт, корзина которого отправляется в заказ. Если не установлен, то берется текущий сайт.
arDiscounts | Ассоциативный массив величин скидок, в котором кодами являются коды записей в корзине, а значениями - соответствующие величины скидок. Если не установлен (равен false), то скидки не сохраняются.

Пример использования

<?
// Привяжем записи корзины текущего пользователя на текущем сайте к заказу с кодом $ORDER_ID
// Установим, что скидка была 5%

$arDiscounts = array();

$arRes = GetBasketList();
for ($i = 0; $i<count($arRes); $i++)
{
   if ($arRes[$i]["DELAY"]=="N" && $arRes[$i]["CAN_BUY"]=="Y")
   {
      $curDiscount = roundEx(DoubleVal($arRes[$i]["PRICE"])*5/100, 2);
      $arDiscounts[IntVal($arRes[$i]["ID"])] = $curDiscount;
   }
}

// Здесь создаем заказ и учитываем в его цене величину скидки
 * * *
// Теперь в $ORDER_ID записан код заказа

CSaleBasket::OrderBasket($ORDER_ID, $_SESSION["SALE_USER_ID"], SITE_ID, $arDiscounts);
?>


Update

CSaleBasket::Update

int
CSaleBasket::Update(
 int ID,
 array arFields
);

Функция обновляет параметры товара с кодом ID на основании массива arFields.

Параметры функции

Параметр | Описание
ID | Код элемента корзины.
arFields Ассоциативный массив новых параметров элемента корзины, содержащий следующие ключи:
  • PRODUCT_ID - уникальный в рамках модуля код товара;
  • PRODUCT_PRICE_ID - дополнительный код товара;
  • PRICE - стоимость единицы товара ;
  • CURRENCY - валюта стоимости единицы товара;
  • WEIGHT - вес единицы товара;
  • QUANTITY - количество единиц товара, если значение элемента массива с этим ключем равно нулю, то товар удаляется из корзины;
  • LID - сайт, на котором сделана покупка;
  • DELAY - флаг "товар отложен" (Y/N);
  • CAN_BUY - флаг "товар можно купить" (Y/N) - может устанавливаться автоматически про наличии функции обратного вызова для поддержки актуальности корзины;
  • NAME - название товара (обязательное поле);
  • CALLBACK_FUNC - название функции обратного вызова для поддержки актуальности корзины (подробности в описании метода CSaleBasket::Add);
  • MODULE - модуль, добавляющий файл в корзину;
  • NOTES - особые заметки, например, тип цены;
  • ORDER_CALLBACK_FUNC - название функции обратного вызова для оформления заказа (подробности в описании метода CSaleBasket::Add);
  • DETAIL_PAGE_URL - ссылка на страницу детального просмотра товара;
  • PROPS - массив свойств товара, который сохраняется в корзине. Каждый элемент этого массива является массивом следующего формата:
    array("NAME"  => "Название свойства",
      "CODE"  => "Код свойства",
      "VALUE" => "Значение свойства",
      "SORT"  => "Индекс сортировки")

Возвращаемые значения

Функция возвращает код элемента корзины, который был изменен.

Пример использования

<?
// Изменим количество товара в записи $ID корзины на 2 штуки и отложим товар
$arFields = array(
   "QUANTITY" => 2,
   "DELAY" => "Y"
);
CSaleBasket::Update($ID, $arFields);
?>


UpdatePrice

CSaleBasket::UpdatePrice

CSaleBasket::UpdatePrice(
  int ID,
  string CALLBACK_FUNC = "",
  string MODULE = "",
  int PRODUCT_ID = 0,
  int QUANTITY = 0
);

Функция актуализирует параметры записи с кодом ID корзины на основании функции обратного вызова для поддержки актуальности корзины CALLBACK_FUNC

Параметры функции

Параметр | Описание
ID | Код записи в корзине.
CALLBACK_FUNC | Название функции обратного вызова для поддержки актуальности корзины.
MODULE | Модуль, добавивший товар в корзину.
PRODUCT_ID | Код товара.
QUANTITY | Количество товара в корзине.

Пример использования

<?
// GetBasketList() - стандартная функция модуля Интернет-Магазина

function GetBasketList()
{
   CSaleBasket::Init();
   $arRes = array();
   $db_res = CSaleBasket::GetList(($by="NAME"), ($order="ASC"), array("FUSER_ID"=>$_SESSION["SALE_USER_ID"], "LID"=>SITE_ID, "ORDER_ID"=>"NULL"));

   while ($res = $db_res->GetNext())
   {
      if (strlen($res["CALLBACK_FUNC"])>0)
      {
         CSaleBasket::UpdatePrice($res["ID"], $res["CALLBACK_FUNC"], $res["MODULE"], $res["PRODUCT_ID"], $res["QUANTITY"]);
         $res = CSaleBasket::GetByID($res["ID"]);
      }
      $arRes[] = $res;
   }
   return $arRes;
}

$arBasket = GetBasketList();

echo "<pre>";
print_r($arBasket);
echo "</pre>";
?>


Класс CSaleDelivery

Методы класса

Метод | Описание
GetByID | Функция возвращает параметры службы доставки с кодом ID.
GetLocationList | Функция возвращает набор местоположений по фильтру arFilter.
Update | Функция изменяет параметры доставки с кодом ID на новые значения из массива arFields.
Delete | Функция удаляет доставку с кодом ID.
GetList | Функция возвращает результат выборки записей из служб доставки в соответствии со своими параметрами.
Add | Функция добавляет новый способ (службу) доставки с параметрами из массива arFields.


Add

CSaleDelivery::Add

int
CSaleDelivery::Add(
  array arFields
);

Функция добавляет новый способ (службу) доставки с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров доставки, ключами в котором являются названия параметров доставки, а значениями - значения параметров.

Допустимые ключи:
  • NAME - название доставки (обязательное, задается на языке сайта, к которому привязана эта доставка);
  • LID - код сайта, к которому привязана эта доставка;
  • PERIOD_FROM - минимальный срок доставки;
  • PERIOD_TO - максимальный срок доставки;
  • PERIOD_TYPE - единица измерения срока: D - дни, H - часы, M - месяцы;
  • WEIGHT_FROM - минимальный вес заказа, для которого возможна эта доставка (единица измерения должна быть едина на сайте);
  • WEIGHT_TO - максимальный вес заказа, для которого возможна эта доставка (единица измерения должна быть едина на сайте);
  • ORDER_PRICE_FROM - минимальная стоимость заказа, для которой возможна эта доставка;
  • ORDER_PRICE_TO - максимальная стоимость заказа, для которой возможна эта доставка;
  • ORDER_CURRENCY - валюта ограничений по стоимости;
  • ACTIVE - флаг (Y/N) активности доставки;
  • PRICE - стоимость доставки;
  • CURRENCY - валюта стоимости доставки;
  • SORT - индекс сортировки;
  • DESCRIPTION - описание доставки;
  • LOCATIONS - массив массивов вида:
    array("LOCATION_ID" => "код местоположения или
                        группы местоположений",
      "LOCATION_TYPE"=>"L - для местоположения,
                        G - для группы")
    содержащий местоположения и группы местоположений, для которых работает эта доставка

Возвращаемые значения

Возвращает код добавленной записи или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "NAME" => "Доставка курьером",
   "LID" => "ru",
   "PERIOD_FROM" => 1,
   "PERIOD_TO" => 3,
   "PERIOD_TYPE" => "D",
   "WEIGHT_FROM" => 0,
   "WEIGHT_TO" => 2500,
   "ORDER_PRICE_FROM" => 0,
   "ORDER_PRICE_TO" => 10000,
   "ORDER_CURRENCY" => "RUR",
   "ACTIVE" => "Y",
   "PRICE" => 58,
   "CURRENCY" => "RUR",
   "SORT" => 100,
   "DESCRIPTION" => "Заказ будет доставлен Вам в течение 3 - 10 рабочих дней после передачи его в курьерскую службу.",
   "LOCATIONS" => array(
      array("LOCATION_ID"=>1, "LOCATION_TYPE"=>"L"),
      array("LOCATION_ID"=>3, "LOCATION_TYPE"=>"G")
      )
);

$ID = CSaleDelivery::Add($arFields);
if ($ID<=0)
   echo "Ошибка добавления доставки";
?>


Delete

CSaleDelivery::Delete

bool
CSaleDelivery::Delete(
  int ID
);

Функция удаляет доставку с кодом ID

Параметры функции

Параметр | Описание
ID | Код доставки.

Возвращаемые значения

Возвращает true в случае успешного удаления и false - в противном случае.

Пример использования

<?
CSaleDelivery::Delete(8);
?>


GetByID

CSaleDelivery::GetByID

array
CSaleDelivery::GetByID(
  int ID
);

Функция возвращает параметры службы доставки с кодом ID

Параметры функции

Параметр | Описание
ID | Код службы доставки.

Возвращаемые значения

Возвращается ассоциативный массив параметров доставки с ключами:

Ключ | Описание
ID | Код службы доставки.
NAME | Название доставки.
LID | Код сайта, к которому привязана эта доставка.
PERIOD_FROM | Минимальный срок доставки.
PERIOD_TO | Максимальный срок доставки.
PERIOD_TYPE | Единица измерения срока: D - дни, H - часы, M - месяцы.
WEIGHT_FROM | Минимальный вес заказа, для которого возможна эта доставка (единица измерения едина на сайте).
WEIGHT_TO | Максимальный вес заказа, для которого возможна эта доставка (единица измерения едина на сайте).
ORDER_PRICE_FROM | Минимальная стоимость заказа, для которой возможна эта доставка.
ORDER_PRICE_TO | Максимальная стоимость заказа, для которой возможна эта доставка.
ORDER_CURRENCY | Валюта ограничений по стоимости.
ACTIVE | Флаг (Y/N) активности доставки.
PRICE | Стоимость доставки.
CURRENCY | Валюта стоимости доставки.
SORT | Индекс сортировки.
DESCRIPTION | Описание доставки.

Пример использования

<?
// $DELIVERY_ID - код службы доставки

$arDeliv = CSaleDelivery::GetByID($DELIVERY_ID);
if ($arDeliv)
{
   echo "Доставка \"".$arDeliv["NAME"]."\" стоит ".CurrencyFormat($arDeliv["PRICE"], $arDeliv["CURRENCY"]);
}
?>


GetList

CSaleDelivery::GetList

CDBResult
CSaleDelivery::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из служб доставки в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле корзины, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи службы доставки. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле корзины.

Пример фильтра:
array("+<=WEIGHT_FROM" => 1000)
Этот фильтр означает "выбрать все записи, в которых значение в поле WEIGHT_FROM (вес от) меньше либо равно 1000 или значение не установлено (null или ноль)".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи служб доставки. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле служб доставки. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров доставки с ключами:

Ключ | Описание
ID | Код службы доставки.
NAME | Название доставки.
LID | Код сайта, к которому привязана эта доставка.
PERIOD_FROM | Минимальный срок доставки.
PERIOD_TO | Максимальный срок доставки.
PERIOD_TYPE | Единица измерения срока: D - дни, H - часы, M - месяцы.
WEIGHT_FROM | Минимальный вес заказа, для которого возможна эта доставка (единица измерения едина на сайте).
WEIGHT_TO | Максимальный вес заказа, для которого возможна эта доставка (единица измерения едина на сайте).
ORDER_PRICE_FROM | Минимальная стоимость заказа, для которой возможна эта доставка.
ORDER_PRICE_TO | Максимальная стоимость заказа, для которой возможна эта доставка.
ORDER_CURRENCY | Валюта ограничений по стоимости.
ACTIVE | Флаг (Y/N) активности доставки.
PRICE | Стоимость доставки.
CURRENCY | Валюта стоимости доставки.
SORT | Индекс сортировки.
DESCRIPTION | Описание доставки.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выберем отсортированные по индексу сортировки, а потом (при равных индексах) по имени
// активные службы доставки, доступные для текущего сайта, заказа с весом $ORDER_WEIGHT и
// стоимостью $ORDER_PRICE (в базовой валюте текущего сайта), доставки в
// местоположение $DELIVERY_LOCATION
$db_dtype = CSaleDelivery::GetList(
    array(
            "SORT" => "ASC",
            "NAME" => "ASC"
        ),
    array(
            "LID" => SITE_ID,
            "+<=WEIGHT_FROM" => $ORDER_WEIGHT,
            "+>=WEIGHT_TO" => $ORDER_WEIGHT,
            "+<=ORDER_PRICE_FROM" => $ORDER_PRICE,
            "+>=ORDER_PRICE_TO" => $ORDER_PRICE,
            "ACTIVE" => "Y",
            "LOCATION" => $DELIVERY_LOCATION
        ),
    false,
    false,
    array()
);
if ($ar_dtype = $db_dtype->Fetch())
{
   echo "Вам доступны следующие способы доставки:<br>";
   do
   {
      echo $ar_dtype["NAME"]." - стоимость ".CurrencyFormat($ar_dtype["PRICE"], $ar_dtype["CURRENCY"])."<br>";
   }
   while ($ar_dtype = $db_dtype->Fetch())
}
else
{
   else "Доступных способов доставки не найдено<br>";
}
?>


GetLocationList

CSaleDelivery::GetLocationList

CDBResult
CSaleDelivery::GetLocationList(
  array arFilter = Array()
);

Функция возвращает набор местоположений по фильтру arFilter

Параметры функции

Параметр Описание
arFilter Фильтр представляет собой ассоциативный массив, в котором ключами являются названия параметров, а значениями - условия.

Допустимые ключи:
  • DELIVERY_ID - код доставки;
  • LOCATION_ID - код местоположения или группы местоположений;
  • LOCATION_TYPE - тип (L - местоположение, G - группа местоположений).

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
DELIVERY_ID | Код службы доставки.
LOCATION_ID | Код местоположения или группы местоположений.
LOCATION_TYPE | Тип (L - местоположение, G - группа местоположений)


Update

CSaleDelivery::Update

int
CSaleDelivery::Update(
  int ID,
  array arFields
);

Функция изменяет параметры доставки с кодом ID на новые значения из массива arFields

Параметры функции

Параметр | Описание
ID | Код доставки.
arFields Ассоциативный массив новых параметров доставки, ключами в котором являются названия параметров доставки, а значениями - значения параметров.
Допустимые ключи:
  • NAME - название доставки (обязательное, задается на языке сайта, к которому привязана эта доставка);
  • LID - код сайта, к которому привязана эта доставка;
  • PERIOD_FROM - минимальный срок доставки;
  • PERIOD_TO - максимальный срок доставки;
  • PERIOD_TYPE - единица измерения срока: D - дни, H - часы, M - месяцы;
  • WEIGHT_FROM - минимальный вес заказа, для которого возможна эта доставка (единица измерения должна быть едина на сайте);
  • WEIGHT_TO - максимальный вес заказа, для которого возможна эта доставка (единица измерения должна быть едина на сайте);
  • ORDER_PRICE_FROM - минимальная стоимость заказа, для которой возможна эта доставка;
  • ORDER_PRICE_TO - максимальная стоимость заказа, для которой возможна эта доставка;
  • ORDER_CURRENCY - валюта ограничений по стоимости;
  • ACTIVE - флаг (Y/N) активности доставки;
  • PRICE - стоимость доставки;
  • CURRENCY - валюта стоимости доставки;
  • SORT - индекс сортировки;
  • DESCRIPTION - описание доставки;
  • LOCATIONS - массив массивов вида:
    array("LOCATION_ID" => "код местоположения или
                        группы местоположений",
      "LOCATION_TYPE"=>"L - для местоположения,
                        G - для группы")
    содержащий местоположения и группы местоположений, для которых работает эта доставка

Возвращаемые значения

Возвращает код изменяемой записи или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "NAME" => "Доставка курьером",
   "LID" => "ru",
   "PERIOD_FROM" => 1,
   "PERIOD_TO" => 3,
   "PERIOD_TYPE" => "D",
   "WEIGHT_FROM" => 0,
   "WEIGHT_TO" => 2500,
   "ORDER_PRICE_FROM" => 0,
   "ORDER_PRICE_TO" => 10000,
   "ORDER_CURRENCY" => "RUR",
   "ACTIVE" => "Y",
   "PRICE" => 58,
   "CURRENCY" => "RUR",
   "SORT" => 100,
   "DESCRIPTION" => "Заказ будет доставлен Вам в течение 3 - 10 рабочих дней после передачи его в курьерскую службу.",
   "LOCATIONS" => array(
      array("LOCATION_ID"=>1, "LOCATION_TYPE"=>"L"),
      array("LOCATION_ID"=>3, "LOCATION_TYPE"=>"G")
      )
);

if (!CSaleDelivery::Update($ID, $arFields))
   echo "Ошибка изменения доставки";
?>


Класс CSaleDeliveryHandler

Методы класса

Метод | Описание
GetList | Функция возвращает список обработчиков автоматизированных служб доставки, для которых установлены настройки в БД.
GetAdminList | Функция возвращает список всех имеющихся обработчиков автоматизированных служб доставки.
GetBySID | Функция служит для получения информации о конкретном обработчике по его строковому идентификатору.
GetHandlerCompability | Функция возвращает список профилей обработчика, подходящих конкретному заказу.
Calculate | Вызов одного шага расчёта стоимости доставки.
CalculateFull | Вызов полного цикла расчёта стоимости доставки.


Calculate

CSaleDeliveryHandler::Calculate

array
CSaleDeliveryHandler::Calculate(
 int STEP,
 string SID,
 string profile,
 array arOrder,
 string currency,
 mixed TMP = false,
 mixed SITE_ID = false
);

Вызов одного шага расчёта стоимости доставки.

Параметры функции

Параметр | Описание
STEP | Текущий шаг расчёта.
SID | Строковый идентификатор обработчика.
profile | Идентификатор профиля обработчика.
arOrder Массив заказа:
  • WEIGHT - суммарный вес заказа в граммах;
  • PRICE - суммарная стоимость заказа в базовой валюте магазина;
  • LOCATION_FROM - ID местоположения магазина, настраиваемого в настройках модуля "Интернет-магазин";
  • LOCATION_TO - ID местоположения, указываемого клиентом при оформлении заказа.
currency | Идентификатор валюты.
TMP | Временные данные с предыдущего шага.
SITE_ID | Идентификатор сайта. По умолчанию используется текущий.

Возвращаемые значения

Возвращается ассоциативный массив следующей структуры:

Ключ | Описание
RESULT Идентификатор ответа. Возможные значения:
  • "OK" - стоимость доставки успешно рассчитана;
  • "ERROR" - в процессе расчёта произошла ошибка;
  • "NEXT_STEP" - необходимо перейти на следующий шаг для продолжения расчёта.
VALUE | Значение стоимости доставки в валюте, задаваемой в параметрах метода - currency. (RESULT = 'OK')
TRANSIT | Длительность доставки в днях (RESULT = 'OK'). Если обработчик доставки не возвращает длительность, то этот параметр отсутствует.
TEXT | Текст ошибки или текст, сопровождающий переход на следующий шаг (RESULT = {'ERROR'|'NEXT_STEP'}).
TEMP | Строка, содержащая промежуточные данные, которые нужно передать следующему шагу (RESULT = 'NEXT_STEP').


CalculateFull

CSaleDeliveryHandler::CalculateFull

array
CSaleDeliveryHandler::CalculateFull(
    string SID,
    string profile,
    array arOrder,
    string currency,
    mixed SITE_ID = false
);

Вызов полного цикла расчёта. В случае, если обработчик службы доставки осуществляет расчёт за один шаг, метод аналогичен CSaleDeliveryHandler::Calculate(). В противном случае метод автоматически выполнит переход на следующий шаг расчёта.

Параметры функции

Параметр | Описание
SID | Строковый идентификатор обработчика.
profile | Идентификатор профиля обработчика.
arOrder Массив заказа:
  • WEIGHT - суммарный вес заказа в граммах;
  • PRICE - суммарная стоимость заказа в базовой валюте магазина;
  • LOCATION_FROM - ID местоположения магазина, настраиваемого в настройках модуля "Интернет-магазин";
  • LOCATION_TO - ID местоположения, указываемого клиентом при оформлении заказа.
currency | Идентификатор валюты.
SITE_ID | Идентификатор сайта. По умолчанию используется текущий.

Возвращаемые значения

Возвращается ассоциативный массив следующей структуры:

Ключ | Описание
RESULT Идентификатор ответа. Возможные значения:
  • "OK" - стоимость доставки успешно рассчитана;
  • "ERROR" - в процессе расчёта произошла ошибка.
VALUE | Значение стоимости доставки в валюте, задаваемой в параметрах метода - currency. (RESULT = 'OK').
TRANSIT | Длительность доставки в днях (RESULT = 'OK'). Если обработчик доставки не возвращает длительность, то этот параметр отсутствует.
TEXT | Текст ошибки (RESULT = 'ERROR').

Пример использования

$arOrder = array(
  "ORDER_WEIGHT" => "10", // вес заказа в граммах
  "ORDER_PRICE" => "100", // стоимость заказа в базовой валюте магазина
  "LOCATION_FROM" => COption::GetOptionInt('sale', 'location'), // местоположение магазина
  "LOCATION_TO" => 55892, // местоположение доставки
);

$currency = CSaleLang::GetLangCurrency(SITE_ID);

$dbHandler = CSaleDeliveryHandler::GetBySID('simple');
if ($arHandler = $dbHandler->Fetch())
{
  $arProfiles = CSaleDeliveryHandler::GetHandlerCompability($arOrder, $arHandler);
  if (is_array($arProfiles) && count($arProfiles) > 0)
  {
    $arProfiles = array_keys($arProfiles);
    $arReturn = CSaleDeliveryHandler::CalculateFull(
      'simple', // идентификатор службы доставки
      $arProfiles[0], // идентификатор профиля доставки
      $arOrder, // заказ
      $currency // валюта, в которой требуется вернуть стоимость
    );

    if ($arReturn["RESULT"] == "OK")
    {
      ShowNote('Стоимость доставки успешно рассчитана!');
      echo 'Стоимость доставки: '.CurrencyFormat($arReturn["VALUE"], $currency).'<br />';
      if (is_set($arReturn['TRANSIT']) && $arReturn['TRANSIT'] > 0)
      {
        echo 'Длительность доставки: '.$arReturn['TRANSIT'].' дней.<br />';
      }
    }
    else
    {
      ShowError('Не удалось рассчитать стоимость доставки! '.$arResult['ERROR']);
    }
  }
  else
  {
    ShowError('Невозможно доставить заказ!');
  }
}
else
{
  ShowError('Обработчик не найден!');
}


GetAdminList

CSaleDeliveryHandler::GetAdminList

CDBResult
CSaleDeliveryHandler::GetAdminList(
array arSort = array("SORT" => "ASC")
);

Функция возвращает список всех имеющихся обработчиков. Список обработчиков строится на основе события onSaleDeliveryHandlersBuildList.

Параметры функции

Параметр Описание
arSort Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array("параметр_сортировки" => "направление_сортировки" [, ...])

В качестве параметра сортировки может выступать одно из следующих значений:

  • SORT - параметр "сортировка";
  • NAME - наименования службы доставки;
  • SID - строковой идентификатор службы доставки;
  • HANDLER - путь к обработчику службы доставки;
  • ACTIVE - флаг активности службы доставки.

В качестве "направление_сортировки" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Значение по умолчанию - массив array("SORT" => "ASC") - означает, что результат будет отсортирован по возрастанию.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий записи со структурой, аналогичной CSaleDeliveryHandlers::GetList() с единственным изменением:

Ключ | Описание
INSTALLED | Флаг, показывающий, есть ли в БД конфигурация для данного обработчика (Y|N).

Пример использования

CModule::IncludeModule('sale');

$dbResult = CSaleDeliveryHandler::GetAdminList(
  array(
    'SORT' => 'ASC',
    'NAME' => 'ASC'
  )
);
echo '<ul>';
while ($arResult = $dbResult->GetNext())
{
  echo '<li>('.$arResult['SID'].') <b>'.$arResult['NAME'].'</b><br />';
  echo '<small>'.$arResult['DESCRIPTION'].'</small></li>';
}
echo '</ul>';


GetBySID

CSaleDeliveryHandler::GetBySID

CDBResult
CSaleDeliveryHandler::GetBySID(
string SID,
mixed SITE_ID = false
);

Данная функция служит для получения информации по конкретному обработчику по его строковому идентификатору.

Параметры функции

Параметр | Описание
SID | Строковый идентификатор обработчика.
SITE_ID | Идентификатор сайта. По умолчанию используется текущий.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий запись со структурой, аналогичной CSaleDeliveryHandlers::GetList().

Пример использования

CModule::IncludeModule('sale');

$dbResult = CSaleDeliveryHandler::GetBySID('cpcr');

if ($arResult = $dbResult->GetNext())
{
  echo '('.$arResult['SID'].') <b>'.$arResult['NAME'].'</b><br />';
  echo '<small>'.$arResult['DESCRIPTION'].'</small><ul>';
  foreach ($arResult['PROFILES'] as $profile_id => $arProfile)
  {
    echo '<li>('.$profile_id.') '.$arProfile['TITLE'].'</li>';
  }
  echo '</ul>';
}
else
{
  echo 'Обработчик не найден';
}


GetHandlerCompability

CSaleDeliveryHandler::GetHandlerCompability

array|bool
CSaleDeliveryHandler::GetHandlerCompability(
array arOrder,
 array arHandler,
 mixed SITE_ID = SITE_ID
);

Функция возвращает список профилей обработчика, подходящих данному заказу. Осуществляется проверка по весу и стоимости, а также вызывается метод COMPABILITY обработчика.

Параметры функции

Параметр | Описание
arOrder Массив заказа. Представляет собой ассоциативный массив с ключами:
  • WEIGHT - суммарный вес заказа в граммах;
  • PRICE - суммарная стоимость заказа в базовой валюте магазина;
  • LOCATION_FROM - ID местоположения магазина, настраиваемого в настройках модуля "Интернет-магазин";
  • LOCATION_TO - ID местоположения, указываемого клиентом при оформлении заказа.
arHandler | Описательный массив обработчика, возвращаемый методами CSaleDeliveryHandler::GetBySID(), CSaleDeliveryHandler::GetList(), CSaleDeliveryHandler::GetAdminList(),
SITE_ID | Идентификатор сайта. По умолчанию используется текущий.

Возвращаемые значения

Метод возвращает массив профилей доставки, подходящих для данного заказа, либо false в случае, если ни один из профилей не подходит. Массив возвращается в том формате, в котором он указан в элементе "PROFILES" описательного массива обработчика, т.е.

Array
(
  "строковый_идентификатор_профиля" => Array
    (
      "TITLE" => "название_профиля",
      "DESCRIPTION" => "описание_профиля",
      "RESTRICTIONS_WEIGHT" => Array
        (
          /* ограничения обработчика по весу */
        ),

      "RESTRICTIONS_SUM" => Array
        (
          /* ограничения обработчика по стоимости */
        ),

      "ACTIVE" => "флаг_активности_профиля",
    ),
/* ................... */
)


GetList

CSaleDeliveryHandler::GetList

CDBResult
CSaleDeliveryHandler::GetList(
array arSort = array("SORT" => "ASC"),
 array arFilter = array()
);

Функция возвращает список обработчиков автоматизированных служб доставки, для которых установлены настройки в БД.

Параметры функции

Параметр Описание
arSort Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array("параметр_сортировки" => "направление_сортировки" [, ...])

В качестве параметра сортировки может выступать одно из следующих значений:

  • SORT - параметр "сортировка";
  • NAME - наименования службы доставки;
  • SID - строковой идентификатор службы доставки;
  • HANDLER - путь к обработчику службы доставки;
  • ACTIVE - флаг активности службы доставки.

В качестве "направление_сортировки" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Значение по умолчанию - массив array("SORT" => "ASC") - означает, что результат будет отсортирован по возрастанию.
arFilter Массив, в соответствии с которым фильтруются записи службы доставки.
Массив имеет вид:
array("фильтруемое_поле"=>"значения_фильтра" [, ...])
"фильтруемое_поле" может принимать значения:
  • ACTIVE - фильтр по активности (Y|N); передача значения
                "ACTIVE"=>"ALL" выводит все элементы без учета их
        состояния;
по умолчанию выводятся только активные элементы;
  • SITE_ID - по сайту; ; передача значения "SITE_ID"=>"ALL" выводит настройки для всех сайтов;
    по умолчанию получаются настройки службы доставки только для текущего сайта;
  • SID - по строковому идентификатору обработчика;
  • HANDLER - фильтр по части пути к файлу обработчика.
  • COMPABILITY - проверка совместимости обработчика с параметрами заказа;
    значение должно быть массивом данных по заказу следующей структуры:
    • WEIGHT - суммарный вес заказа;
    • PRICE - суммарная стоимость заказа;
    • LOCATION_FROM - ID местоположения магазина (устанавливается в настройках модуля);
    • LOCATION_TO - ID местоположения, указанному при оформлении заказа.
Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий записи следующей структуры:

Ключ | Описание
SID | Строковой идентификатор обработчика доставки.
NAME | Наименование службы доставки.
DESCRIPTION | Описание службы доставки.
DESCRIPTION_INNER | "Внутреннее" описание функционала обработчика службы доставки.
LID | Идентификатор сайта, для которого установлены настройки.
ACTIVE | Флаг активности службы доставки.
SORT | Значение параметра сортировки для данной службы доставки.
BASE_CURRENCY | Идентификатор валюты, в которой работает обработчик службы доставки.
TAX_RATE | Значение наценки, автоматически добавляемой к стоимости доставки (%).
HANDLER | Путь к файлу обработчика доставки.
DBSETSETTINGS | callback к методу обработчика, обеспечивающему сохранение массива настроек в БД.
DBGETSETTINGS | callback к методу обработчика, обеспечивающему получение массива настроек из БД.
GETCONFIG | callback к методу обработчика, возвращающему список настроек обработчика.
COMPABILITY | callback к методу обработчика, осуществляющему проверку применимости обработчика к заказу.
CALCULATE | callback к методу обработчика, осуществляющему расчёт стоимости доставки.
PROFILES Массив профилей обработки доставки. Представляет собой ассоциативный массив вида:
Array
(
    "строковый_идентификатор_профиля" => Array
        (
            "TITLE" => "название_профиля",
            "DESCRIPTION" => "описание_профиля",
            "RESTRICTIONS_WEIGHT" => Array
                (
                    /* ограничения обработчика по весу */
                ),

            "RESTRICTIONS_SUM" => Array
                (
                    /* ограничения обработчика по стоимости */
                ),

            "ACTIVE" => "флаг_активности_профиля",
        ),
/* ................... */
)
CONFIG | Массив настроек обработчика доставки со значениями. Подробнее см. Руководство по созданию автоматизированных обработчиков доставки.
PROFILE_USE_DEFAULT | Значение флага "используются параметры профилей по умолчанию" (Y|N).

Пример использования

CModule::IncludeModule('sale');

$dbResult = CSaleDeliveryHandler::GetList(
  array(
    'SORT' => 'ASC',
    'NAME' => 'ASC'
  ),
  array(
    'ACTIVE' => 'Y'
  )
);
echo '<ul>';
while ($arResult = $dbResult->GetNext())
{
  echo '<li>('.$arResult['SID'].') <b>'.$arResult['NAME'].'</b><br />';
  echo '<small>'.$arResult['DESCRIPTION'].'</small></li>';
}
echo '</ul>';


Класс CSaleDiscount

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из служб доставки в соответствии со своими параметрами.
GetByID | Функция возвращает параметры скидки с кодом ID.
Update | Функция обновляет параметры скидки с кодом ID на параметры из массива arFields.
Delete | Функция удаляет скидку с кодом ID.
Add | Функция добавляет новую скидку на сумму заказа с параметрами из массива arFields.


Add

CSaleDiscount::Add

int
CSaleDiscount::Add(
  array arFields
);

Функция добавляет новую скидку на сумму заказа с параметрами из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров скидки, ключами в котором являются названия параметров скидки, а значениями - значения параметров.

Допустимые ключи:
  • LID - код сайта, к которому привязана эта скидка;
  • PRICE_FROM - общая стоимость заказа, начиная с которой предоставляется эта скидка;
  • PRICE_TO - общая стоимость заказа, до достижения которой предоставляется эта скидка;
  • CURRENCY - валюта денежных полей в записи;
  • DISCOUNT_VALUE - величина скидки;
  • DISCOUNT_TYPE - тип величины скидки (P - величина задана в процентах, V - величина задана в абсолютной сумме);
  • ACTIVE - флаг (Y/N) активности скидки;
  • SORT - индекс сортировки (если по сумме заказа доступно несколько скидок, то берется первая по сортировке)

Возвращаемые значения

Возвращается код добавленной скидки или false в случае ошибки.


Delete

CSaleDiscount::Delete

bool
CSaleDiscount::Delete(
  int ID
);

Функция удаляет скидку с кодом ID

Параметры функции

Параметр | Описание
ID | Код скидки.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleDiscount::GetByID

array
CSaleDiscount::GetByID(
  int ID
);

Функция возвращает параметры скидки с кодом ID

Параметры функции

Параметр | Описание
ID | Код скидки.

Возвращаемые значения

Ассоциативный массив параметров скидки с ключами:

Ключ | Описание
ID | Код скидки.
LID | Код сайта, к которому привязана эта скидка.
PRICE_FROM | Общая стоимость заказа, начиная с которой предоставляется эта скидка.
PRICE_TO | Общая стоимость заказа, до достижения которой предоставляется эта скидка.
CURRENCY | Валюта денежных полей в записи.
DISCOUNT_VALUE | Величина скидки.
DISCOUNT_TYPE | Тип величины скидки (P - величина задана в процентах, V - величина задана в абсолютной сумме).
ACTIVE | Флаг (Y/N) активности скидки.
SORT | Индекс сортировки (если по сумме заказа доступно несколько скидок, то берется первая по сортировке).


GetList

CSaleDiscount::GetList

CDBResult
CSaleDiscount::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле корзины, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи скидки. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле корзины.

Пример фильтра:
array("!CURRENCY" => "USD")
Этот фильтр означает "выбрать все записи, в которых значение в поле CURRENCY (валюта) не равно USD".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи скидок. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле служб доставки. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код скидки.
LID | Код сайта, к которому привязана эта скидка.
PRICE_FROM | Общая стоимость заказа, начиная с которой предоставляется эта скидка.
PRICE_TO | Общая стоимость заказа, до достижения которой предоставляется эта скидка.
CURRENCY | Валюта денежных полей в записи.
DISCOUNT_VALUE | Величина скидки.
DISCOUNT_TYPE | Тип величины скидки (P - величина задана в процентах, V - величина задана в абсолютной сумме).
ACTIVE | Флаг (Y/N) активности скидки.
SORT | Индекс сортировки (если по сумме заказа доступно несколько скидок, то берется первая по сортировке).

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выберем величину активной скидки для текущего сайта и стоимости
// заказа $ORDER_PRICE (в базовой валюте этого сайта)
$db_res = CSaleDiscount::GetList(
        array("SORT" => "ASC"),
        array(
                "LID" => SITE_ID,
                "ACTIVE" => "Y",
                "PRICE" => $ORDER_PRICE
            ),
        false,
        false,
        array()
    );
if ($ar_res = $db_res->Fetch())
{
   echo "Наша скидка - ";
   if ($ar_res["DISCOUNT_TYPE"] == "P")
   {
      echo $ar_res["DISCOUNT_VALUE"]."%";
   }
   else
   {
      echo CurrencyFormat($ar_res["DISCOUNT_VALUE"], $ar_res["CURRENCY"]);
   }
}
?>


Update

CSaleDiscount::Update

int
CSaleDiscount::Update(
  int ID,
  array arFields
);

Функция обновляет параметры скидки с кодом ID на параметры из массива arFields

Параметры функции

Параметр | Описание
ID | Код скидки.
arFields Ассоциативный массив новых параметров скидки, ключами в котором являются названия параметров, а значениями - новые значения. Допустимо указание не всех ключей, а только тех, значения которых необходимо изменить.
Допустимые ключи:
  • LID - код сайта, к которому привязана эта скидка;
  • PRICE_FROM - общая стоимость заказа, начиная с которой предоставляется эта скидка;
  • PRICE_TO - общая стоимость заказа, до достижения которой предоставляется эта скидка;
  • CURRENCY - валюта денежных полей в записи;
  • DISCOUNT_VALUE - величина скидки;
  • DISCOUNT_TYPE - тип величины скидки (P - величина задана в процентах, V - величина задана в абсолютной сумме);
  • ACTIVE - флаг (Y/N) активности скидки;
  • SORT - индекс сортировки (если по сумме заказа доступно несколько скидок, то берется первая по сортировке)

Возвращаемые значения

Возвращается код измененной скидки или false в случае ошибки.


Класс CSaleLocation

Методы класса

Метод | Описание
GetCountryByID | Функция возвращает языконезависимые параметры страны с кодом ID.
GetCountryLangByID | Функция возвращает языкозависимые параметры страны по ее коду ID и языку strLang.
GetCityByID | Функция возвращает языконезависимые параметры города с кодом ID.
GetCityLangByID | Функция возвращает языкозависимые параметры города по его коду ID и языку strLang.
UpdateCountry | Функция изменяет параметры страны с кодом ID на новые параметры из массива arFields.
DeleteCountry | Функция удаляет страну с кодом ID. Связаные с этой страной местоположения не изменяются.
UpdateCity | Функция изменяет параметры города с кодом ID на значения из массива arFields.
DeleteCity | Функция удаляет город с кодом ID. Местоположение, с которым связан этот город, не изменяется.
UpdateLocation | Функция обновляет параметры местоположения с кодом ID в соответствии с параметрами из массива arFields.
Add | Функция добавляет новое местоположение включая страну и город местоположения, если нужно.
Update | Функция обновляет параметры местоположения с кодом ID в соответствии с параметрами из массива arFields. Обновляются также страна и город этого местоположения.
Delete | Функция удаляет местоположение с кодом ID. Функция также удаляет город этого местоположения, страну этого местоположения (если она не входит больше ни в одно другое местоположение), а так же связи этого местоположения с группами местоположений и службами доставки.
GetList | Функция возвращает набор местоположений, удовлетворяющих фильтру arFilter.
GetByID | Функция возвращает параметры местоположения с кодом ID, включая параметры страны и города.
GetCountryList | Функция возвращает набор стран по фильтру arFilter, отсортированный по массиву arOrder.
AddCountry | Функция добавляет новую страну с параметрами из массива arFields.
AddCity | Функция добавляет новый город с параметрами из массива arFields.
AddLocation | Функция добавляет новое местоположение на основании параметров массива arFields.
DeleteAll | Функция удаляет все местоположения из базы.


Add

CSaleLocation::Add

int
CSaleLocation::Add(
 array arFields
);

Функция добавляет новое местоположение включая страну и город местоположения, если нужно.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров местоположения с ключами:
  • SORT - индекс сортировки;
  • COUNTRY_ID - код страны (если такая страна уже есть, иначе код должен быть нулем, и должен быть заполнен ключ COUNTRY);
  • COUNTRY - массив с параметрами страны (если страна уже есть и установлен ключ COUNTRY_ID, то этот ключ заполнять не нужно);
  • WITHOUT_CITY - флаг (Y/N), означающий, что это местоположение без города (только страна) (если значением с этим ключом является N, то необходимо заполнить ключ CITY);
  • CITY - массив с параметрами города (если установлен флаг WITHOUT_CITY в значение Y, то этот ключ заполнять не нужно);
Массив с параметрами страны должен содержать ключи:
  • NAME - название страны (не зависящее от языка);
  • SHORT_NAME - сокращенное название страны - абревиатура (не зависящее от языка);
  • <код языка> - ключом является код языка, а значением ассоциативный массив вида:
    array("LID" => "код языка",
      "NAME" => "название страны на этом языке",
      "SHORT_NAME" => "сокращенное название страны
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.
Массив с параметрами города должен содержать ключи:
  • NAME - название города (не зависящее от языка);
  • SHORT_NAME - сокращенное название города - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида:
    array("LID" => "код языка",
      "NAME" => "название города на этом языке",
      "SHORT_NAME" => "сокращенное название города
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код добавленного местоположения или false у случае ошибки.

Пример использования

<?
$arFields = array(
   "SORT" => 100,
   "COUNTRY_ID" => 0,
   "WITHOUT_CITY" => "N"
);

$arCountry = array(
   "NAME" => "Russian Federation",
   "SHORT_NAME" => "Russia",
   "ru" => array(
      "LID" => "ru",
      "NAME" => "Российская федерация",
      "SHORT_NAME" => "Россия"
      ),
   "en" => array(
      "LID" => "en",
      "NAME" => "Russian Federation",
      "SHORT_NAME" => "Russia"
      )
);

$arFields["COUNTRY"] = $arCountry;

$arCity = array(
   "NAME" => "Kaliningrad",
   "SHORT_NAME" => "Kaliningrad",
   "ru" => array(
      "LID" => "ru",
      "NAME" => "Калининград",
      "SHORT_NAME" => "Калининград"
      ),
   "en" => array(
      "LID" => "en",
      "NAME" => "Kaliningrad",
      "SHORT_NAME" => "Kaliningrad"
      )
);

$arFields["CITY"] = $arCity;

$ID = CSaleLocation::Add($arFields);
if (IntVal($ID)<=0)
   echo "Ошибка добавления местоположения";
?>


AddCity

CSaleLocation::AddCity

int
CSaleLocation::AddCity(
 array arFields
);

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

Параметры функции

Параметр Описание
arFields Ассоциативный массив с параметрами города должен содержать ключи:
  • NAME - название города (не зависящее от языка);
  • SHORT_NAME - сокращенное название города - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида
    array("LID" => "код языка",
      "NAME" => "название города на этом языке",
      "SHORT_NAME" => "сокращенное название города
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код добавленного города или false в случае ошибки.

Пример использования

<?
$arCity = array(
   "NAME" => "Kaliningrad",
   "SHORT_NAME" => "Kaliningrad",
   "ru" => array(
      "LID" => "ru",
      "NAME" => "Калининград",
      "SHORT_NAME" => "Калининград"
      ),
   "en" => array(
      "LID" => "en",
      "NAME" => "Kaliningrad",
      "SHORT_NAME" => "Kaliningrad"
      )
);

$ID = CSaleLocation::AddCity($arCity);
if (IntVal($ID)<=0)
   echo "Ошибка добавления города";
?>


AddCountry

CSaleLocation::AddCountry

int
CSaleLocation::AddCountry(
 array arFields
);

Функция добавляет новую страну с параметрами из массива arFields.

Параметры функции

Параметр Описание
arFields Массив с параметрами страны должен содержать ключи:
  • NAME - название страны (не зависящее от языка);
  • SHORT_NAME - сокращенное название страны - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида
    array("LID" => "код языка",
      "NAME" => "название страны на этом языке",
      "SHORT_NAME" => "сокращенное название страны
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код добавленного местоположения или false у случае ошибки.

Пример использования

<?
$arCountry = array(
   "NAME" => "Russian Federation",
   "SHORT_NAME" => "Russia",
   "ru" => array(
      "LID" => "ru",
      "NAME" => "Российская федерация",
      "SHORT_NAME" => "Россия"
      ),
   "en" => array(
      "LID" => "en",
      "NAME" => "Russian Federation",
      "SHORT_NAME" => "Russia"
      )
);

$ID = CSaleLocation::AddCountry($arCountry);
if (IntVal($ID)<=0)
   echo "Ошибка добавления страны";
?>


AddLocation

CSaleLocation::AddLocation

int
CSaleLocation::AddLocation(
  array arFields
);

Функция добавляет новое местоположение на основании параметров массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров местоположения с ключами:
  • SORT - индекс сортировки;
  • COUNTRY_ID - код страны;
  • CITY_ID - код страны.

Возвращаемые значения

Возвращается код добавленного местоположения или false у случае ошибки.

Пример использования

<?
// Добавим местоположение из страны с кодом 2 и города с кодом 10
$ID = CSaleLocation::AddLocation(
      array(
         "COUNTRY_ID" => 2,
         "CITY_ID" => 10
         )
      );
?>


Delete

CSaleLocation::Delete

bool
CSaleLocation::Delete(
  int ID
);

Функция удаляет местоположение с кодом ID. Функция так же удаляет город этого местоположения, страну этого местоположения (если она не входит больше ни в одно другое местоположение), а так же связи этого местоположения с группами местоположений и службами доставки.

Параметры функции

Параметр | Описание
ID | Код местоположения.

Возвращаемые значения

Функция возвращает true в случае успешного удаления местоположения и false - в противном случае.

Пример использования

<?
if (!CSaleLocation::Delete(12))
   echo "Ошибка удаления местоположения";
?>


DeleteAll

CSaleLocation::DeleteAll

CSaleLocation::DeleteAll();

Функция удаляет все местоположения из базы.


DeleteCity

CSaleLocation::DeleteCity

bool
CSaleLocation::DeleteCity(
  int ID
);

Функция удаляет город с кодом ID. Местоположение, с которым связан этот город, не изменяется.

Параметры функции

Параметр | Описание
ID | Код города.

Возвращаемые значения

Функция возвращает true в случае успешного удаления местоположения и false - в противном случае.

Пример использования

<?
if (!CSaleLocation::DeleteCity(12))
   echo "Ошибка удаления города";
?>


DeleteCountry

CSaleLocation::DeleteCountry

bool
CSaleLocation::DeleteCountry(
  int ID
);

Функция удаляет страну с кодом ID. Связаные с этой страной местоположения не изменяются.

Параметры функции

Параметр | Описание
ID | Код страны.

Возвращаемые значения

Функция возвращает true в случае успешного удаления местоположения и false - в противном случае.

Пример использования

<?
if (!CSaleLocation::DeleteCountry(12))
   echo "Ошибка удаления страны";
?>


GetByID

CSaleLocation::GetByID

array
CSaleLocation::GetByID(
  int ID,
  string strLang = LANGUAGE_ID
);

Функция возвращает параметры местоположения с кодом ID, включая параметры страны и города. Параметры, зависящие от языка возвращаются для языка strLang

Параметры функции

Параметр | Описание
ID | Код местоположения.
strLang | Язык параметров, зависящих от языка. По умолчанию равен текущему языку.

Возвращаемые значения

Возвращает ассоциативный массив с ключами:

Ключ | Описание
ID | Код местоположения.
COUNTRY_ID | Код страны.
CITY_ID | Код города.
SORT | Индекс сортировки.
COUNTRY_NAME_ORIG | Языконезависимое название страны.
COUNTRY_SHORT_NAME | Языконезависимое сокращенное название страны.
COUNTRY_NAME_LANG | Языкозависимое название страны.
CITY_NAME_ORIG | Языконезависимое название города.
CITY_SHORT_NAME | Языконезависимое сокращенное название города.
CITY_NAME_LANG | Языкозависимое название города.
COUNTRY_NAME | Языкозависимое название страны, если оно есть. Иначе - языконезависимое название страны.
CITY_NAME | Языкозависимое название города, если оно есть. Иначе - языконезависимое название города.

Пример использования

<?
$arLocs = CSaleLocation::GetByID(22, LANGUAGE_ID);
echo $arLocs["COUNTRY_NAME"]." - ".$arLocs["CITY_NAME"];
?>


GetCityByID

CSaleLocation::GetCityByID

array
CSaleLocation::GetCityByID(
  int ID
);

Функция возвращает языконезависимые параметры города с кодом ID

Параметры функции

Параметр | Описание
ID | Код города.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код города.
NAME | Языконезависимое название города.
SHORT_NAME | Языконезависимое короткое название города.


GetCityLangByID

CSaleLocation::GetCityLangByID

array
CSaleLocation::GetCityLangByID(
  int ID,
  string strLang = LANGUAGE_ID
);

Функция возвращает языкозависимые параметры города по его коду ID и языку strLang

Параметры функции

Параметр | Описание
ID | Код города.
strLang | Язык. По умолчанию равен текущему языку.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код записи.
CITY_ID | Код города.
LID | Язык.
NAME | Языкозависимое название города.
SHORT_NAME | Языкозависимое короткое название города.


GetCountryByID

CSaleLocation::GetCountryByID

array
CSaleLocation::GetCountryByID(
  int ID
);

Функция возвращает языконезависимые параметры страны с кодом ID

Параметры функции

Параметр | Описание
ID | Код страны.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код страны.
NAME | Языконезависимое название страны.
SHORT_NAME | Языконезависимое короткое название страны.


GetCountryLangByID

CSaleLocation::GetCountryLangByID

array
CSaleLocation::GetCountryLangByID(
  int ID,
  string strLang = LANGUAGE_ID
);

Функция возвращает языкозависимые параметры страны по ее коду ID и языку strLang

Параметры функции

Параметр | Описание
ID | Код страны.
strLang | Язык.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код записи.
CITY_ID | Код страны.
LID | Язык.
NAME | Языкозависимое название страны.
SHORT_NAME | Языкозависимое короткое название страны.


GetCountryList

CSaleLocation::GetCountryList

CDBResult
CSaleLocation::GetCountryList(
 array arOrder = Array("NAME_LANG"=>"ASC"),
 array arFilter = Array(),
 string strLang = LANGUAGE_ID
);

Функция возвращает набор стран по фильтру arFilter, отсортированный по массиву arOrder. Языкозависимые параметры берутся для языка strLang

Параметры функции

Параметр | Описание
arOrder Ассоциативный массив для сортировки записей. Сортировка осуществляется последовательно по каждой паре ключ-значение. Ключами являются названия параметров, а значениями - направления сортировки.

Допустимые ключи:
  • NAME_LANG - языкозависимое название страны;
  • ID - код страны;
  • NAME - языконезависимое название страны;
  • SHORT_NAME - языконезависимое сокращенное название страны.
Допустимые значения:
  • ASC - по возрастанию;
  • DESC - по убыванию.
arFilter Ассоциативный массив для фильтрации записей - выбираются только те записи, которые удовлетворяют фильтру. Ключами являются названия параметров, а значениями - условия на значения.

Допустимые ключи:
  • ID - код страны;
  • NAME - языконезависимое название страны.
strLang | Язык, на котором выбираются языкозависимые параметры. По умолчанию равен текущему языку.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код страны.
NAME_ORIG | Языконезависимое название страны.
SHORT_NAME | Языконезависимое короткое название страны.
NAME | Языкозависимое название страны.
NAME_LANG | Языкозависимое название страны, если оно есть. Иначе языконезависимое название страны.


GetList

CSaleLocation::GetList

CDBResult
CSaleLocation::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает набор местоположений, удовлетворяющих фильтру arFilter. Возвращаются так же параметры стран и городов местоположений. Набор отсортирован в соответствии с массивом arOrder. Языкозависимые параметры выбираются для языка strLang.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле местоположения, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи местоположений. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле местоположения.

Пример фильтра:
array("COUNTRY_ID" => 15)
Этот фильтр означает "выбрать все записи, в которых значение в поле COUNTRY_ID (код страны) равно 15".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи местоположений. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле местоположений. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код местоположения.
COUNTRY_ID | Код страны.
CITY_ID | Код города.
SORT | Индекс сортировки.
COUNTRY_NAME_ORIG | Языконезависимое название страны.
COUNTRY_SHORT_NAME | Языконезависимое короткое название страны.
COUNTRY_NAME_LANG | Языкозависимое название страны.
CITY_NAME_ORIG | Языконезависимое название города.
CITY_SHORT_NAME | Языконезависимое короткое название города.
CITY_NAME_LANG | Языкозависимое название города.
COUNTRY_NAME | Языкозависимое название страны, если оно установлено. Иначе - языконезависимое название страны.
CITY_NAME | Языкозависимое название города, если оно установлено. Иначе - языконезависимое название города.

Пример использования

<?// Выведем выпадающий список местоположений?>

<select name="LOCATION">
   <?
   $db_vars = CSaleLocation::GetList(
        array(
                "SORT" => "ASC",
                "COUNTRY_NAME_LANG" => "ASC",
                "CITY_NAME_LANG" => "ASC"
            ),
        array("LID" => LANGUAGE_ID),
        false,
        false,
        array()
    );
   while ($vars = $db_vars->Fetch()):
      ?>
      <option value="<?= $vars["ID"]?>"><?= htmlspecialchars($vars["COUNTRY_NAME"]." - ".$vars["CITY_NAME"])?></option>
      <?
   endwhile;
   ?>
</select>
?>


Update

CSaleLocation::Update

int
CSaleLocation::Update(
  int ID,
  array arFields
);

Функция обновляет параметры местоположения с кодом ID в соответствии с параметрами из массива arFields. Обновляются так же страна и город этого местоположения.

Параметры функции

Параметр | Описание
ID | Код местоположения.
arFields Ассоциативный массив параметров местоположения с ключами:
  • SORT - индекс сортировки;
  • COUNTRY_ID - код страны (если такая страна уже есть, иначе код должен быть нулем, и должен быть заполнен ключ COUNTRY);
  • COUNTRY - массив с параметрами страны (должен быть заполнен, если не установлен ключ COUNTRY_ID или если ключ CHANGE_COUNTRY установлен в значение Y);
  • CHANGE_COUNTRY - флаг (Y/N), изменять ли параметры страны (долны быть установлены ключи COUNTRY_ID и COUNTRY);
  • WITHOUT_CITY - флаг (Y/N), означающий, что это местоположение без города (только страна) (если значением с этим ключем является N, то необходимо заполнить ключ CITY);
  • CITY_ID - код города (если такой город уже есть, иначе код должен быть нулем, и должен быть заполнен ключ CITY);
  • CITY - массив с параметрами города (если установлен флаг WITHOUT_CITY в значение Y, то этот ключ заполнять не нужно);
Массив с параметрами страны должен содержать ключи:
  • NAME - название страны (не зависящее от языка);
  • SHORT_NAME - сокращенное название страны - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида
    array("LID" => "код языка",
      "NAME" => "название страны на этом языке",
      "SHORT_NAME" => "сокращенное название страны
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.
Массив с параметрами города должен содержать ключи:
  • NAME - название города (не зависящее от языка);
  • SHORT_NAME - сокращенное название города - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида
    array("LID" => "код языка",
      "NAME" => "название города на этом языке",
      "SHORT_NAME" => "сокращенное название города
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код измененного местоположения или false у случае ошибки.

Пример использования

<?
$arFields = array(
   "SORT" => 100,
   "COUNTRY_ID" => 8,
   "WITHOUT_CITY" => "N"
);

$arCity = array(
   "NAME" => "Kaliningrad",
   "SHORT_NAME" => "Kaliningrad",
   "ru" => array(
      "LID" => "ru",
      "NAME" => "Калининград",
      "SHORT_NAME" => "Калининград"
      ),
   "en" => array(
      "LID" => "en",
      "NAME" => "Kaliningrad",
      "SHORT_NAME" => "Kaliningrad"
      )
);

$arFields["CITY"] = $arCity;

if (!CSaleLocation::Update(6, $arFields))
   echo "Ошибка изменения местоположения";
?>


UpdateCity

CSaleLocation::UpdateCity

int
CSaleLocation::UpdateCity(
  int ID,
  array arFields
);

Функция изменяет параметры города с кодом ID на значения из массива arFields

Параметры функции

Параметр | Описание
ID | Код города.
arFields Массив с параметрами города должен содержать ключи:
  • NAME - название города (не зависящее от языка);
  • SHORT_NAME - сокращенное название города - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида
    array("LID" => "код языка",
      "NAME" => "название города на этом языке",
      "SHORT_NAME" => "сокращенное название города
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код измененного города или false у случае ошибки.


UpdateCountry

CSaleLocation::UpdateCountry

int
CSaleLocation::UpdateCountry(
  int ID,
  array arFields
);

Функция изменяет параметры страны с кодом ID на новые параметры из массива arFields

Параметры функции

Параметр | Описание
ID | Код страны.
arFields Массив с параметрами страны должен содержать ключи:
  • NAME - название страны (не зависящее от языка);
  • SHORT_NAME - сокращенное название страны - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида
    array("LID" => "код языка",
      "NAME" => "название страны на этом языке",
      "SHORT_NAME" => "сокращенное название страны
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код измененной страны или false у случае ошибки.


UpdateLocation

CSaleLocation::UpdateLocation

int
CSaleLocation::UpdateLocation(
  int ID,
  array arFields
);

Функция обновляет параметры местоположения с кодом ID в соответствии с параметрами из массива arFields.

Параметры функции

Параметр | Описание
ID | Код местоположения.
arFields Ассоциативный массив параметров местоположения с ключами:
  • SORT - индекс сортировки;
  • COUNTRY_ID - код страны;
  • CITY_ID - код города (если такой город уже есть, иначе код должен быть нулем, и должен быть заполнен ключ CITY).

Возвращаемые значения

Возвращается код измененного местоположения или false у случае ошибки.


Класс CSaleLocationGroup

Методы класса

Метод | Описание
GetLocationList | Функция возвращает набор местоположений, связанных с группами местоположений, удовлетворяющих фильтру arFilter.
GetGroupLangByID | Функция возвращает языкозависимые параметры группы местоположений с кодом ID для языка с кодом strLang.
Update | Функция обновляет параметры группы местоположений с кодом ID на значения из массива arFields.
Delete | Функция удаляет группу местоположений с кодом ID. Местоположения, входящие в эту группу, не изменяются.
GetList | Функция возвращает набор групп местоположений, удовлетворяющих фильтру arFilter. Группы отсортированы в соответствии с массивом arOrder.
GetByID | Функция возвращает параметры группы местоположений с кодом ID. Языкозависимые параметры возвращаются для языка с кодом strLang.
Add | Функция добавляет новую группу местоположений с параметрами из массива arFields.


Add

CSaleLocationGroup::Add

int
CSaleLocationGroup::Add(
  array arFields
);

Функция добавляет новую группу местоположений с параметрами из массива arFields.

Параметры функции

Параметр Описание
arFields Массив значений параметров группы местоположений, ключами в котором являются имена параметров.

Допустимые ключи:
  • SORT - индекс сортировки;
  • LOCATION_ID - массив кодов местоположений, которые входят в эту группу;
  • LANG - массив языкозависимых параметров группы, каждый элемент которого имеет вид
    array("LID"=>"язык параметров",
      "NAME"=>"Название группы")

Возвращаемые значения

Возвращается код добавленной группы или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "SORT" => 150,
   "LOCATION_ID" => array(12, 34, 35, 36, 37),
   "LANG" => array(
      array("LID" => "ru", "NAME" => "Группа 1"),
      array("LID" => "en", "NAME" => "Group 1")
   )
);

$ID = CSaleLocationGroup::Add($arFields);
if (IntVal($ID)<=0)
   echo "Ошибка добавления группы";
?>


Delete

CSaleLocationGroup::Delete

bool
CSaleLocationGroup::Delete(
  int ID
);

Функция удаляет группу местоположений с кодом ID. Местоположения, входящие в эту группу, не изменяются.

Параметры функции

Параметр | Описание
ID | Код группы местоположений.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.

Пример использования

<?
if (!CSaleLocationGroup::Delete(2))
   echo "Ошибка удаления группы местоположений";
?>


GetByID

CSaleLocationGroup::GetByID

array
CSaleLocationGroup::GetByID(
  int ID,
  string strLang = LANGUAGE_ID
);

Функция возвращает параметры группы местоположений с кодом ID. Языкозависимые параметры возвращаются для языка с кодом strLang

Параметры функции

Параметр | Описание
ID | Код группы местоположений.
strLang | Код языка для языкозависимых параметров. По умолчанию равен текущему языку.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код группы местоположений.
SORT | Индекс сортировки.
NAME | Название группы.
LID | Язык названия.


GetGroupLangByID

CSaleLocationGroup::GetGroupLangByID

array
CSaleLocationGroup::GetGroupLangByID(
  int ID,
  string strLang = LANGUAGE_ID
);

Функция возвращает языкозависимые параметры группы местоположений с кодом ID для языка с кодом strLang

Параметры функции

Параметр | Описание
ID | Код группы местоположений.
strLang | Код языка.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код записи.
LOCATION_GROUP_ID | Код группы местоположений.
NAME | Название группы.
LID | Язык названия.

Пример использования

<?
$arGroupLang = CSaleLocationGroup::GetGroupLangByID(2, "en");
echo $arGroupLang["NAME"];
?>


GetList

CSaleLocationGroup::GetList

CDBResult
CSaleLocationGroup::GetList(
  array arOrder = Array("NAME"=>"ASC"),
  array arFilter = Array(),
  string strLang = LANGUAGE_ID
);

Функция возвращает набор групп местоположений, удовлетворяющих фильтру arFilter. Группы отсортированы в соответствии с массивом arOrder.

Параметры функции

Параметр | Описание
arOrder Ассоциативный массив для указания сортировки результирующего набора групп. Каждая пара ключ-значение массива применяется последовательно. Ключами являются названия полей для сортировки, а значениями - направления сортировки.

Допустимые ключи:
  • ID - код группы местоположений;
  • NAME - название группы;
  • SORT - индекс сортировки.
Допустимые значения:
  • ASC - по возрастанию;
  • DESC - по убыванию.
arFilter Фильтр представляет собой ассоциативный массив, в котором ключами являются названия параметров группы, а значениями - условия на значения

Допустимые ключи:
  • ID - код группы местоположения.
strLang | Код языка для языкозависимых параметров. По умолчанию равен текущему языку.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы с ключами:

Ключ | Описание
ID | Код группы местоположений.
SORT | Индекс сортировки.
NAME | Название группы.
LID | Язык названия.

Пример использования

<select name="LOCATION2" size="5" multiple>
   <?
   $db_vars = CSaleLocationGroup::GetList(Array("NAME"=>"ASC"), array(), LANGUAGE_ID);
   while ($vars = $db_vars->Fetch()):
      ?>
      <option value="<?= $vars["ID"]?>"><?= htmlspecialchars($vars["NAME"])?></option>
      <?
   endwhile;
   ?>
</select>


GetLocationList

CSaleLocationGroup::GetLocationList

CDBResult
CSaleLocationGroup::GetLocationList(
  array arFilter = Array()
);

Функция возвращает набор местоположений, связанных с группами местоположений, удовлетворяющих фильтру arFilter.

Параметры функции

Параметр Описание
arFilter Фильтр представляет собой ассоциативный массив, в котором ключами являются названия параметров записи, а значениями - условия на значения

Допустимые ключи:
  • LOCATION_ID - код местоположения;
  • LOCATION_GROUP_ID - код группы местоположений.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы с ключами:

Ключ | Описание
LOCATION_ID | Код местоположения.
LOCATION_GROUP_ID | Код группы местоположений.

Пример использования

<?
// Выберем все местоположения группы 2
$db_res = CSaleLocationGroup::GetLocationList(array("LOCATION_GROUP_ID"=>2));
while ($ar_res = $db_res->Fetch())
{
   echo $ar_res["LOCATION_ID"].", ";
}
?>


Update

CSaleLocationGroup::Update

int
CSaleLocation::Update(
  int ID,
  array arFields
);

Функция обновляет параметры местоположения с кодом ID в соответствии с параметрами из массива arFields. Обновляются так же страна и город этого местоположения.

Параметры функции

Параметр | Описание
ID | Код местоположения.
arFields Ассоциативный массив параметров местоположения с ключами:
  • SORT - индекс сортировки;
  • COUNTRY_ID - код страны (если такая страна уже есть, иначе код должен быть нулем, и должен быть заполнен ключ COUNTRY);
  • COUNTRY - массив с параметрами страны (должен быть заполнен, если не установлен ключ COUNTRY_ID или если ключ CHANGE_COUNTRY установлен в значение Y);
  • CHANGE_COUNTRY - флаг (Y/N), изменять ли параметры страны (долны быть установлены ключи COUNTRY_ID и COUNTRY);
  • WITHOUT_CITY - флаг (Y/N), означающий, что это местоположение без города (только страна) (если значением с этим ключем является N, то необходимо заполнить ключ CITY);
  • CITY_ID - код города (если такой город уже есть, иначе код должен быть нулем, и должен быть заполнен ключ CITY);
  • CITY - массив с параметрами города (если установлен флаг WITHOUT_CITY в значение Y, то этот ключ заполнять не нужно);
Массив с параметрами страны должен содержать ключи:
  • NAME - название страны (не зависящее от языка);
  • SHORT_NAME - сокращенное название страны - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида

array("LID" => "код языка",
      "NAME" => "название страны на этом языке",
      "SHORT_NAME" => "сокращенное название страны
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.
Массив с параметрами города должен содержать ключи:
  • NAME - название города (не зависящее от языка);
  • SHORT_NAME - сокращенное название города - абревиатура (не зависящее от языка);
  • <код языка> - ключем является код языка, а значением ассоциативный массив вида

array("LID" => "код языка",
      "NAME" => "название города на этом языке",
      "SHORT_NAME" => "сокращенное название города
                       (аббревиатура) на этом языке")
    Эта пара ключ-значение должна присутствовать для каждого языка системы.

Возвращаемые значения

Возвращается код измененного местоположения или false у случае ошибки.

Пример использования

<?
$arFields = array(
   "SORT" => 100,
   "COUNTRY_ID" => 8,
   "WITHOUT_CITY" => "N"
);

$arCity = array(
   "NAME" => "Kaliningrad",
   "SHORT_NAME" => "Kaliningrad",
   "ru" => array(
      "LID" => "ru",
      "NAME" => "Калининград",
      "SHORT_NAME" => "Калининград"
      ),
   "en" => array(
      "LID" => "en",
      "NAME" => "Kaliningrad",
      "SHORT_NAME" => "Kaliningrad"
      )
);

$arFields["CITY"] = $arCity;

if (!CSaleLocation::Update(6, $arFields))
   echo "Ошибка изменения местоположения";
?>


CSaleOrder

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.
GetByID | Функция возвращает параметры заказа с кодом ID.
PayOrder | Функция меняет значение флага "заказ оплачен" (поле PAYED) на значение параметра Val для заказа с кодом ID.
DeliverOrder | Функция меняет значение флага "доставка разрешена" (поле ALLOW_DELIVERY) на значение параметра Val для заказа с кодом ID.
CancelOrder | Функция меняет значение флага "заказ отменён" (поле CANCELED) на значение параметра Val для заказа с кодом ID.
StatusOrder | Функция меняет значение статуса заказа (поле STATUS_ID) на значение параметра Val для заказа с кодом ID.
CommentsOrder | Функция устанавливает новое значение Val комментария (поле COMMENTS) к заказу с кодом ID
Delete | Функция удаляет заказ с кодом ID.
Add | Функция добавляет новый заказ с параметрами из массива arFields.
Update | Функция изменяет параметры заказа с кодом ID на новые параметры из массива arFields.


Add

CSaleOrder::Add

int
CSaleOrder::Add(
  array arFields
);

Функция добавляет новый заказ с параметрами из массива arFields. Перед добавлением заказа вызываются обработчики события OnBeforeOrderAdd модуля магазина, а после добавления - обработчики события OnOrderAdd модуля магазина.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров заказа, ключами в котором являются названия параметров заказа, а значениями - новые значения.
Допустимые ключи:
  • LID - код сайта, на котором сделан заказ;
  • PERSON_TYPE_ID - тип плательщика, к которому принадлежит посетитель, сделавший заказ (заказчик);
  • PAYED - флаг (Y/N) оплачен ли заказ;
  • DATE_PAYED - дата оплаты заказа;
  • EMP_PAYED_ID - код пользователя (сотрудника магазина), который установил флаг оплаченности;
  • CANCELED - флаг (Y/N) отменён ли заказ;
  • DATE_CANCELED - дата отмены заказа;
  • EMP_CANCELED_ID - код пользователя, который установил флаг отмены заказа;
  • REASON_CANCELED - текстовое описание причины отмены заказа;
  • STATUS_ID - код статуса заказа;
  • EMP_STATUS_ID - код пользователя (сотрудника магазина), который установил текущий статус заказа;
  • PRICE_DELIVERY - стоимость доставки заказа;
  • ALLOW_DELIVERY - флаг (Y/N) разрешена ли доставка (отгрузка) заказа;
  • DATE_ALLOW_DELIVERY - дата, когда была разрешена доставка заказа;
  • EMP_ALLOW_DELIVERY_ID - код пользователя (сотрудника магазина), который разрешил доставку заказа;
  • PRICE - общая стоимость заказа;
  • CURRENCY - валюта стоимости заказа;
  • DISCOUNT_VALUE - общая величина скидки;
  • USER_ID - код пользователя заказчика;
  • PAY_SYSTEM_ID - платежная система, которой (будет) оплачен заказа;
  • DELIVERY_ID - способ (служба) доставки заказа;
  • USER_DESCRIPTION - описание заказа заказчиком;
  • ADDITIONAL_INFO - дополнительная информация по заказу;
  • COMMENTS - произвольные комментарии;
  • TAX_VALUE - общая сумма налогов;
  • STAT_GID - параметр события в статистике;
  • PS_STATUS - флаг (Y/N) статуса платежной системы - успешно ли оплачен заказ (для платежных систем, которые позволяют автоматически получать данные по проведенным через них заказам);
  • PS_STATUS_CODE - код статуса платежной системы (значение зависит от системы);
  • PS_STATUS_DESCRIPTION - описание результата работы платежной системы;
  • PS_STATUS_MESSAGE - сообщение от платежной системы;
  • PS_SUM - сумма, которая была реально оплачена через платежную систему;
  • PS_CURRENCY - валюта суммы;
  • PS_RESPONSE_DATE - дата получения статуса платежной системы;
  • SUM_PAID - сумма, которая уже была оплачена покупателем по данному счету (например, с внутреннего счета);
  • PAY_VOUCHER_NUM - номер платежного поручения;
  • PAY_VOUCHER_DATE - дата платежного поручения.

Возвращаемые значения

Возвращается код добавленного заказа или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "LID" => "en",
   "PERSON_TYPE_ID" => 1,
   "PAYED" => "N",
   "CANCELED" => "N",
   "STATUS_ID" => "N",
   "PRICE" => 279.32,
   "CURRENCY" => "USD",
   "USER_ID" => IntVal($USER->GetID()),
   "PAY_SYSTEM_ID" => 3,
   "PRICE_DELIVERY" => 11.37,
   "DELIVERY_ID" => 2,
   "DISCOUNT_VALUE" => 1.5,
   "TAX_VALUE" => 0.0,
   "USER_DESCRIPTION" => ""
);

// add Guest ID
if (CModule::IncludeModule("statistic"))
   $arFields["STAT_GID"] = CStatistic::GetEventParam();

$ORDER_ID = CSaleOrder::Add($arFields);
$ORDER_ID = IntVal($ORDER_ID);
?>


CancelOrder

CSaleOrder::CancelOrder

int
CSaleOrder::CancelOrder(
  int ID,
  string Val,
  string Descr = ""
);

Функция меняет значение флага "заказ отменён" (поле CANCELED) на значение параметра Val для заказа с кодом ID. Кроме флага отмены заказа, устанавливаются также поля даты изменения значения флага (DATE_CANCELED) и кода пользователя, изменившего значение флага (EMP_CANCELED_ID). Поле с описанием причины отмены заказа (REASON_CANCELED) заполняется значением параметра Descr.

Если заказ был оплачен, то при отмене снимается флаг оплаты с возвращением денег на счет покупателя. Если заказ был частично оплачен, то при отмене внесённая сумма возвращается на счет покупателя.

Перед отменой заказа вызываются обработчики события OnSaleBeforeCancelOrder модуля магазина, в которых можно отменить отмену заказа, вернув значение false. После отмены вызываются обработчики события OnSaleCancelOrder модуля магазина.

В случае отмены заказа генерируется почтовое событие типа SALE_ORDER_CANCEL.

Параметры функции

Параметр | Описание
ID | Код заказа.
Val | Новое значение флага отмены заказа (Y/N).
Descr | Описание причины отмены заказа.

Возвращаемые значения

Возвращается код заказа или false в случае ошибки.

Пример использования

<?
CSaleOrder::CancelOrder(25, "Y", "Потому что передумал");
?>


CommentsOrder

CSaleOrder::CommentsOrder

int
CSaleOrder::CommentsOrder(
  int ID,
  string Val
);

Функция устанавливает новое значение Val комментария (поле COMMENTS) к заказу с кодом ID

Параметры функции

Параметр | Описание
ID | Код заказа.
Val | Новое значение комментария.

Возвращаемые значения

Возвращается код заказа или false в случае ошибки.

Пример использования

<?
if (!CSaleOrder::CommentsOrder(12, "Не отгружать до оплаты!"))
   echo "Ошибка изменения комментария к заказу";
?>


Delete

CSaleOrder::Delete

bool
CSaleOrder::Delete(
  int ID
);

Функция удаляет заказ с кодом ID. При этом если заказ отменяется, если не был отменён, снимается флаг оплаты с возвращением денег на счет покупателя, если он был оплачен, и снимается флаг разрешения доставки, если он был установлен.

Перед удалением заказа вызываются обработчики события OnBeforeOrderDelete модуля магазина, в которых можно отменить удаление вернув значение false. Непосредственно перед удалением вызываются обработчики события OnOrderDelete модуля магазина.

Параметры функции

Параметр | Описание
ID | Код заказа.

Возвращаемые значения

Возвращается true при успешном удалении и false - в противном случае.

Пример использования

<?
CSaleOrder::Delete(23);
?>


DeliverOrder

CSaleOrder::DeliverOrder

int
CSaleOrder::DeliverOrder(
 int ID,
 string Val[,
 int recurringID = 0]
);

Функция меняет значение флага "доставка разрешена" (поле ALLOW_DELIVERY) на значение параметра Val для заказа с кодом ID.

Кроме флага разрешения доставки, устанавливаются также поля даты изменения значения флага (DATE_ALLOW_DELIVERY) и кода пользователя, изменившего значение флага (EMP_ALLOW_DELIVERY_ID).

При изменении флага "Доставка разрешена" для каждого элемента заказа (товара) вызывается функция обратного вызова из поля PAY_CALLBACK_FUNC корзины (если она установлена).

Перед изменением флага вызываются обработчики события OnSaleBeforeDeliveryOrder модуля магазина, в которых можно отменить изменение флага вернув значение false. После изменения флага вызываются обработчики события OnSaleDeliveryOrder модуля магазина.

В случае разрешения доставки генерируется почтовое событие типа SALE_ORDER_DELIVERY.

Параметры функции

Параметр | Описание
ID | Код заказа.
Val | Новое значение флага разрешения доставки (Y/N).
recurringID | Код продления подписки (если он есть).

Возвращаемые значения

Возвращается код заказа или false в случае ошибки.

Пример использования

<?
if (!CSaleOrder::DeliverOrder(23, "Y"))
   echo "Ошибка изменения заказа 23";
?>


GetByID

CSaleOrder::GetByID

array
CSaleOrder::GetByID(
  int ID
);

Функция возвращает параметры заказа с кодом ID.

Параметры функции

Параметр | Описание
ID | Код заказа.

Возвращаемые значения

Возвращается ассоциативный массив с ключами:

Ключ | Описание
ID | Код заказа.
LID | Код сайта, на котором сделан заказ.
PERSON_TYPE_ID | Тип плательщика, к которому принадлежит посетитель, сделавший заказ (заказчик)
PAYED | Флаг (Y/N) оплачен ли заказ.
DATE_PAYED | Дата оплаты заказа.
EMP_PAYED_ID | Код пользователя (сотрудника магазина), который установил флаг оплаченности.
CANCELED | Флаг (Y/N) отменён ли заказ.
DATE_CANCELED | Дата отмены заказа.
EMP_CANCELED_ID | Код пользователя, который установил флаг отмены заказа.
REASON_CANCELED | Текстовое описание причины отмены заказа.
STATUS_ID | Код статуса заказа.
DATE_STATUS | Дата изменения статуса заказа.
EMP_STATUS_ID | Код пользователя (сотрудника магазина), который установил текущий статус заказа.
PRICE_DELIVERY | Стоимость доставки заказа.
ALLOW_DELIVERY | Флаг (Y/N) разрешена ли доставка (отгрузка) заказа.
DATE_ALLOW_DELIVERY | Дата, когда была разрешена доставка заказа.
EMP_ALLOW_DELIVERY_ID | Код пользователя (сотрудника магазина), который разрешил доставку заказа.
PRICE | Общая стоимость заказа.
CURRENCY | Валюта стоимости заказа.
DISCOUNT_VALUE | Общая величина скидки.
USER_ID | Код пользователя заказчика.
PAY_SYSTEM_ID | Платежная система, которой (будет) оплачен заказа.
DELIVERY_ID | Способ (служба) доставки заказа.
DATE_INSERT | Дата добавления заказа.
DATE_UPDATE | Дата последнего изменения заказа.
USER_DESCRIPTION | Описание заказа заказчиком.
ADDITIONAL_INFO | Дополнительная информация по заказу.
PS_STATUS | Флаг (Y/N) статуса платежной системы - успешно ли оплачен заказ (для платежных систем, которые позволяют автоматически получать данные по проведенным через них заказам)
PS_STATUS_CODE | Код статуса платежной системы (значение зависит от системы)
PS_STATUS_DESCRIPTION | Описание результата работы платежной системы.
PS_STATUS_MESSAGE | Сообщение от платежной системы.
PS_SUM | Сумма, которая была реально оплачена через платежную систему.
PS_CURRENCY | Валюта суммы.
PS_RESPONSE_DATE | Дата получения статуса платежной системы.
COMMENTS | Произвольные комментарии.
TAX_VALUE | Общая сумма налогов.
STAT_GID | Параметр события в статистике.
SUM_PAID | Сумма, которая уже была оплачена покупателем по данному счету (например, с внутреннего счета).
PAY_VOUCHER_NUM | Номер платежного поручения.
PAY_VOUCHER_DATE | Дата платежного поручения.

Пример использования

<?
if (!($arOrder = CSaleOrder::GetByID($ORDER_ID)))
{
   echo "Заказ с кодом ".$ORDER_ID." не найден";
}
else
{
   echo "<pre>";
   print_r($arOrder);
   echo "</pre>";
}
?>


GetList

CSaleOrder::GetList

CDBResult
CSaleOrder::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле местоположения, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи заказов. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("CANCELED" => "Y")
Этот фильтр означает "выбрать все записи, в которых значение в поле CANCELED (отменён) равно Y".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи заказов. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле заказов. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы с ключами:

Ключ | Описание
DATE_INSERT | Дата добавления заказа в формате текущего сайта.
DATE_UPDATE | Дата последнего изменения заказа в формате текущего сайта.
DATE_STATUS | Дата изменения статуса заказа в формате текущего сайта.
DATE_CANCELED | Дата изменения флага отмены заказа в формате текущего сайта.
DATE_PAYED | Дата изменения флага оплаты заказа в формате текущего сайта.
PS_RESPONSE_DATE | Дата получения статуса платежной системы в формате текущего сайта.
DATE_ALLOW_DELIVERY | Дата изменения флага разрешения доставки заказа в формате текущего сайта.
SUM_PAID | Сумма, которая уже была оплачена покупателем по данному счету (например, с внутреннего счета).
PAY_VOUCHER_NUM | Номер платежного поручения.
PAY_VOUCHER_DATE | Дата платежного поручения.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем даты всех заказов текущего пользователя за текущий месяц, отсортированные по дате заказа
$arFilter = Array(
   "USER_ID" => $USER->GetID(),
   ">=DATE_INSERT" => date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")), mktime(0, 0, 0, date("n"), 1, date("Y")))
   );

$db_sales = CSaleOrder::GetList(array("DATE_INSERT" => "ASC"), $arFilter);
while ($ar_sales = $db_sales->Fetch())
{
   echo $ar_sales["DATE_INSERT_FORMAT"]."<br>";
}
?>


PayOrder

CSaleOrder::PayOrder

int
CSaleOrder::PayOrder(
 int ID,
 string val[,
 bool bWithdraw = True[,
 bool bPay = True[,
 int recurringID = 0[,
 array arAdditionalFields = array()]]]]
);

Функция меняет значение флага "заказ оплачен" (поле PAYED) на значение параметра Val для заказа с кодом ID. Кроме флага оплаты заказа, устанавливаются также поля даты изменения значения флага (DATE_PAYED) и кода пользователя, изменившего значение флага (EMP_PAYED_ID).

Перед изменением флага вызываются обработчики события OnSaleBeforePayOrder модуля магазина, в которых можно отменить изменение флага вернув значение false. После изменения флага вызываются обработчики события OnSalePayOrder модуля магазина.

В случае установки флага генерируется почтовое событие типа SALE_ORDER_PAID.

Параметры функции

Параметр | Описание
ID | Код заказа.
Val | Новое значение флага отмены заказа (Y/N).
bWithdraw | Значение true отражает изменение флага на внутреннем счете пользователя. Значение false изменяет только флаг, не затрагивая счет.
bPay | Если параметр bWithdraw установлен в true, то установка параметра bPay в true приведет к тому, что необходимая сумма денег будет внесена на счет покупателя перед оплатой, а установка в false приведет к тому, что оплата будет происходить целиком с внутреннего счета. Если параметр bWithdraw установлен в false, то операции со счетом не производятся и значение параметра bPay не играет роли.
recurringID | Должен быть равен 0.
arAdditionalFields | Массив дополнительно обновляемых параметров (обычно это номер и дата платежного поручения).

Возвращаемые значения

Возвращается код заказа или false в случае ошибки.

Пример использования

<?
if (!CSaleOrder::PayOrder($ID, "Y", True, True, 0, array("PAY_VOUCHER_NUM" => "19210")))
{
   echo "Ошибка обновления заказа";
}
?>


StatusOrder

CSaleOrder::StatusOrder

int
CSaleOrder::StatusOrder(
  int ID,
  string Val
);

Функция меняет значение статуса заказа (поле STATUS_ID) на значение параметра Val для заказа с кодом ID. Кроме статуса заказа устанавливаются так же поля даты изменения статуса заказа (DATE_STATUS) и кода пользователя, изменившего статус заказа (EMP_STATUS_ID).

Перед изменением статуса вызываются обработчики события OnSaleBeforeStatusOrder модуля магазина, в которых можно отменить изменение статуса вернув значение false. После изменения флага вызываются обработчики события OnSaleStatusOrder модуля магазина.

Генерируется почтовое событие типа SALE_STATUS_CHANGED_<код статуса>, если есть подходящий почтовый шаблон. Иначе генерируется почтовое событие типа SALE_STATUS_CHANGED.

Параметры функции

Параметр | Описание
ID | Код заказа.
Val | Код статуса заказа.

Возвращаемые значения

Возвращается код заказа или false в случае ошибки.

Пример использования

<?
if (!CSaleOrder::StatusOrder($ID, "F"))
   echo "Ошибка установки нового статуса заказа";
?>


Update

CSaleOrder::Update

int
CSaleOrder::Update(
  int ID,
  array arFields
);

Функция изменяет параметры заказа с кодом ID на новые параметры из массива arFields. Перед добавлением заказа вызываются обработчики события OnBeforeOrderUpdate модуля магазина, а после добавления - обработчики события OnOrderUpdate модуля магазина.

Параметры функции

Параметр | Описание
ID | Код заказа.
arFields Ассоциативный массив параметров заказа, ключами в котором являются названия параметров заказа, а значениями - новые значения.
Допустимые ключи:
  • LID - код сайта, на котором сделан заказ;
  • PERSON_TYPE_ID - тип плательщика, к которому принадлежит посетитель, сделавший заказ (заказчик);
  • PAYED - флаг (Y/N) оплачен ли заказ;
  • DATE_PAYED - дата оплаты заказа;
  • EMP_PAYED_ID - код пользователя (сотрудника магазина), который установил флаг оплаты;
  • CANCELED - флаг (Y/N) отменён ли заказ;
  • DATE_CANCELED - дата отмены заказа;
  • EMP_CANCELED_ID - код пользователя, который установил флаг отмены заказа;
  • REASON_CANCELED - текстовое описание причины отмены заказа;
  • STATUS_ID - код статуса заказа;
  • EMP_STATUS_ID - код пользователя (сотрудника магазина), который установил текущий статус заказа;
  • PRICE_DELIVERY - стоимость доставки заказа;
  • ALLOW_DELIVERY - флаг (Y/N) разрешена ли доставка (отгрузка) заказа;
  • DATE_ALLOW_DELIVERY - дата, когда была разрешена доставка заказа;
  • EMP_ALLOW_DELIVERY_ID - код пользователя (сотрудника магазина), который разрешил доставку заказа;
  • PRICE - общая стоимость заказа;
  • CURRENCY - валюта стоимости заказа;
  • DISCOUNT_VALUE - общая величина скидки;
  • USER_ID - код пользователя заказчика;
  • PAY_SYSTEM_ID - платежная система, которой (будет) оплачен заказа;
  • DELIVERY_ID - способ (служба) доставки заказа;
  • USER_DESCRIPTION - описание заказа заказчиком;
  • ADDITIONAL_INFO - дополнительная информация по заказу;
  • COMMENTS - произвольные комментарии;
  • TAX_VALUE - общая сумма налогов;
  • STAT_GID - параметр события в статистике;
  • PS_STATUS - флаг (Y/N) статуса платежной системы - успешно ли оплачен заказ (для платежных систем, которые позволяют автоматически получать данные по проведенным через них заказам);
  • PS_STATUS_CODE - код статуса платежной системы (значение зависит от системы);
  • PS_STATUS_DESCRIPTION - описание результата работы платежной системы;
  • PS_STATUS_MESSAGE - сообщение от платежной системы;
  • PS_SUM - сумма, которая была реально оплачена через платежную систему;
  • PS_CURRENCY - валюта суммы;
  • PS_RESPONSE_DATE - дата получения статуса платежной системы;
  • SUM_PAID - сумма, которая уже была оплачена покупателем по данному счету (например, с внутреннего счета);
  • PAY_VOUCHER_NUM - номер платежного поручения;
  • PAY_VOUCHER_DATE - дата платежного поручения.

Возвращаемые значения

Возвращается код добавленного заказа или false в случае ошибки.

Пример использования

<?
$arOrder = CSaleOrder::GetByID($ID);
if ($arOrder)
{
   $arFields = array(
      "PAYED" => "Y",
      "DATE_PAYED" => Date(CDatabase::DateFormatToPHP(CLang::GetDateFormat("FULL", LANG))),
      "USER_ID" => $arOrder["USER_ID"],
      "EMP_PAYED_ID" => $USER->GetID()
   );
   CSaleOrder::Update($ID, $arFields);
}
?>


Класс CSaleOrderProps

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.
GetByID | Функция возвращает параметры свойства с кодом ID заказа.
Update | Функция изменяет параметры свойства с кодом ID заказа на значения из массива arFields.
Delete | Функция удаляет свойство с кодом ID заказа. Существующие в базе значения этого свойства отвязываются от удаляемого свойства. Удаляются связанные значения из профиля покупателя.
Add | Функция добавляет новое свойство заказа с параметрами из массива arFields.


Add

CSaleOrderProps::Add

int
CSaleOrderProps::Add(
  array arFields
);

Функция добавляет новое свойство заказа с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив, в котором ключами являются названия параметров свойства, а значениями - значения этих параметров.

Допустимые ключи:
  • PERSON_TYPE_ID - тип плательщика;
  • NAME - название свойства (тип плательщика зависит от сайта, а сайт - от языка; название должно быть на соответствующем языке);
  • TYPE - тип свойства. Допустимые значения:
    • CHECKBOX - флаг;
    • TEXT - строка текста;
    • SELECT - выпадающий список значений;
    • MULTISELECT - список со множественным выбором;
    • TEXTAREA - многострочный текст;
    • LOCATION - местоположение;
    • RADIO - переключатель.
  • REQUIED - флаг (Y/N) обязательное ли поле;
  • DEFAULT_VALUE - значение по умолчанию;
  • SORT - индекс сортировки;
  • USER_PROPS - флаг (Y/N) входит ли это свойство в профиль покупателя;
  • IS_LOCATION - флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта стоимости доставки (только для свойств типа LOCATION);
  • PROPS_GROUP_ID - код группы свойств;
  • SIZE1 - ширина поля (размер по горизонтали);
  • SIZE2 - высота поля (размер по вертикали);
  • DESCRIPTION - описание свойства;
  • IS_EMAIL - флаг (Y/N) использовать ли значение свойства как E-Mail покупателя;
  • IS_PROFILE_NAME - флаг (Y/N) использовать ли значение свойства как название профиля покупателя;
  • IS_PAYER - флаг (Y/N) использовать ли значение свойства как имя плательщика;
  • IS_LOCATION4TAX - флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта налогов (только для свойств типа LOCATION);
  • CODE - мнемонический код свойства.

Возвращаемые значения

Возвращается код добавленного свойства заказа.

Пример использования

<?
$arFields = array(
   "PERSON_TYPE_ID" => 2,
   "NAME" => "Комплектация",
   "TYPE" => "RADIO",
   "REQUIED" => "Y",
   "DEFAULT_VALUE" => "F",
   "SORT" => 100,
   "CODE" => "COMPLECT",
   "USER_PROPS" => "N",
   "IS_LOCATION" => "N",
   "IS_LOCATION4TAX" => "N",
   "PROPS_GROUP_ID" => 1,
   "SIZE1" => 0,
   "SIZE2" => 0,
   "DESCRIPTION" => "",
   "IS_EMAIL" => "N",
   "IS_PROFILE_NAME" => "N",
   "IS_PAYER" => "N"
);

// Если установлен код свойства, то изменяем свойство с этим кодом,
// иначе добавляем новой свойство
if ($ID>0)
{
   if (!CSaleOrderProps::Update($ID, $arFields))
   {
      echo "Ошибка изменения параметров свойства";
   }
   else
   {
      // Обновим мнемонический код у значений свойства
      // (хранение избыточных данных для оптимизации работы)
      $db_order_props_tmp =
          CSaleOrderPropsValue::GetList(($b="NAME"),
                                        ($o="ASC"),
                                        Array("ORDER_PROPS_ID"=>$ID));
      while ($ar_order_props_tmp = $db_order_props_tmp->Fetch())
      {
         CSaleOrderPropsValue::Update($ar_order_props_tmp["ID"],
                                      array("CODE" => "COMPLECT"));
      }
   }
}
else
{
   $ID = CSaleOrderProps::Add($arFields);
   if ($ID<=0)
      echo "Ошибка добавления свойства";
}
?>


Delete

CSaleOrderProps::Delete

bool
CSaleOrderProps::Delete(
  int ID
);

Функция удаляет свойство с кодом ID заказа. Существующие в базе значения этого свойства отвязываются от удаляемого свойства. Удаляются связанные значения из профиля покупателя.

Параметры функции

Параметр | Описание
ID | Код удаляемого свойства.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в случае ошибки.

Пример использования

<?
if (!CSaleOrderProps::Delete(12))
   echo "Ошибка удаления свойства";
?>


GetByID

CSaleOrderProps::GetByID

array
CSaleOrderProps::GetByID(
  int ID
);

Функция возвращает параметры свойства с кодом ID заказа.

Параметры функции

Параметр | Описание
ID | Код свойства заказа.

Возвращаемые значения

Возвращается ассоциативный массив параметров свойства с ключами:

Ключ | Описание
ID | Код свойства заказа.
PERSON_TYPE_ID | Тип плательщика.
NAME | Название свойства.
TYPE Тип свойства. Допустимые значения:
  • CHECKBOX - флаг,
  • TEXT - строка текста,
  • SELECT - выпадающий список значений,
  • MULTISELECT - список со множественным выбором,
  • TEXTAREA - многострочный текст,
  • LOCATION - местоположение,
  • RADIO - переключатель.
REQUIED | Флаг (Y/N) обязательное ли поле.
DEFAULT_VALUE | Значение по умолчанию.
SORT | Индекс сортировки.
USER_PROPS | Флаг (Y/N) входит ли это свойство в профиль покупателя.
IS_LOCATION | Флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта стоимости доставки (только для свойств типа LOCATION)
PROPS_GROUP_ID | Код группы свойств.
SIZE1 | Ширина поля (размер по горизонтали).
SIZE2 | Высота поля (размер по вертикали).
DESCRIPTION | Описание свойства.
IS_EMAIL | Флаг (Y/N) использовать ли значение свойства как E-Mail покупателя.
IS_PROFILE_NAME | Флаг (Y/N) использовать ли значение свойства как название профиля покупателя.
IS_PAYER | Флаг (Y/N) использовать ли значение свойства как имя плательщика.
IS_LOCATION4TAX | Флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта налогов (только для свойств типа LOCATION)
CODE | Мнемонический код свойства.

Пример использования

<?
if ($arOrderProps = CSaleOrderProps::GetByID($ID))
{
   echo "<pre>";
   print_r($arOrderProps);
   echo "</pre>";
}
?>


GetList

CSaleOrderProps::GetList

CDBResult
CSaleOrderProps::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле местоположения, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи свойств заказа. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("REQUIED" => "Y")
Этот фильтр означает "выбрать все записи, в которых значение в поле REQUIED (обязательно для заполнения) равно Y".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи свойств заказа. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле свойств заказа. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров свойств с ключами:

Ключ | Описание
ID | Код свойства заказа.
PERSON_TYPE_ID | Тип плательщика.
NAME | Название свойства.
TYPE Тип свойства. Допустимые значения:
  • CHECKBOX - флаг,
  • TEXT - строка текста,
  • SELECT - выпадающий список значений,
  • MULTISELECT - список со множественным выбором,
  • TEXTAREA - многострочный текст,
  • LOCATION - местоположение,
  • RADIO - переключатель.
REQUIED | Флаг (Y/N) обязательное ли поле.
DEFAULT_VALUE | Значение по умолчанию.
SORT | Индекс сортировки.
USER_PROPS | Флаг (Y/N) входит ли это свойство в профиль покупателя.
IS_LOCATION | Флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта стоимости доставки (только для свойств типа LOCATION)
PROPS_GROUP_ID | Код группы свойств.
SIZE1 | Ширина поля (размер по горизонтали).
SIZE2 | Высота поля (размер по вертикали).
DESCRIPTION | Описание свойства.
IS_EMAIL | Флаг (Y/N) использовать ли значение свойства как E-Mail покупателя.
IS_PROFILE_NAME | Флаг (Y/N) использовать ли значение свойства как название профиля покупателя.
IS_PAYER | Флаг (Y/N) использовать ли значение свойства как имя плательщика.
IS_LOCATION4TAX | Флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта налогов (только для свойств типа LOCATION)
CODE | Мнемонический код свойства.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем форму для ввода свойств заказа для группы свойств с кодом 5, которые входят в профиль покупателя, для типа плательщика с кодом 2
$db_props = CSaleOrderProps::GetList(
        array("SORT" => "ASC"),
        array(
                "PERSON_TYPE_ID" => 2,
                "PROPS_GROUP_ID" => 5,
                "USER_PROPS" => "Y"
            ),
        false,
        false,
        array()
    );

if ($props = $db_props->Fetch())
{
   echo "Заполните параметры заказа:<br>";
   do
   {
      echo $props["NAME"];
      if ($props["REQUIED"]=="Y" ||
          $props["IS_EMAIL"]=="Y" ||
          $props["IS_PROFILE_NAME"]=="Y" ||
          $props["IS_LOCATION"]=="Y" ||
          $props["IS_LOCATION4TAX"]=="Y" ||
          $props["IS_PAYER"]=="Y")
      {
         echo "*";
      }
      echo ": ";

      if ($props["TYPE"]=="CHECKBOX")
      {
         echo '<input type="checkbox" class="inputcheckbox" name="ORDER_PROP_'.$props["ID"].'" value="Y"'.(($props["DEFAULT_VALUE"]=="Y")?" checked":"").'>';
      }
      elseif ($props["TYPE"]=="TEXT")
      {
         echo '<input type="text" class="inputtext" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:30).'" maxlength="250" value="'.htmlspecialchars($props["DEFAULT_VALUE"]).'" name="ORDER_PROP_'.$props["ID"].'">";
      }
      elseif ($props["TYPE"]=="SELECT")
      {
         echo '<select name="ORDER_PROP_'.$props["ID"].'" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:1).'">';
         $db_vars = CSaleOrderPropsVariant::GetList(($by="SORT"), ($order="ASC"), Array("ORDER_PROPS_ID"=>$props["ID"]));
         while ($vars = $db_vars->Fetch())
         {
            echo '<option value="'.$vars["VALUE"].'"'.(($vars["VALUE"]==$props["DEFAULT_VALUE"])?" selected":"").'>'.htmlspecialchars($vars["NAME"]).'</option>';
         }
         echo '</select>';
      }
      elseif ($props["TYPE"]=="MULTISELECT")
      {
         echo '<select multiple name="ORDER_PROP_'.$props["ID"].'[]" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:5).'">';
         $arDefVal = Split(",", $props["DEFAULT_VALUE"]);
         for ($i = 0; $i<count($arDefVal); $i++)
            $arDefVal[$i] = Trim($arDefVal[$i]);

         $db_vars = CSaleOrderPropsVariant::GetList(($by="SORT"), ($order="ASC"), Array("ORDER_PROPS_ID"=>$props["ID"]));
         while ($vars = $db_vars->Fetch())
         {
            echo '<option value="'.$vars["VALUE"].'"'.(in_array($vars["VALUE"], $arDefVal)?" selected":"").'>'.htmlspecialchars($vars["NAME"]).'</option>';
         }
         echo '</select>';
      }
      elseif ($props["TYPE"]=="TEXTAREA")
      {
         echo '<textarea rows="'.((IntVal($props["SIZE2"])>0)?$props["SIZE2"]:4).'" cols="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:40).'" name="ORDER_PROP_'.$props["ID"].'">'.htmlspecialchars($props["DEFAULT_VALUE"]).'</textarea>';
      }
      elseif ($props["TYPE"]=="LOCATION")
      {
         echo '<select name="ORDER_PROP_'.$props["ID"].'" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:1).'">';
         $db_vars = CSaleLocation::GetList(Array("SORT"=>"ASC", "COUNTRY_NAME_LANG"=>"ASC", "CITY_NAME_LANG"=>"ASC"), array(), LANGUAGE_ID);
         while ($vars = $db_vars->Fetch())
         {
            echo '<option value="'.$vars["ID"].'"".((IntVal($vars["ID"])==IntVal($props["DEFAULT_VALUE"]))?" selected":"").'>'.htmlspecialchars($vars["COUNTRY_NAME"]." - ".$vars["CITY_NAME"]).'</option>';
         }
         echo '</select>';
      }
      elseif ($props["TYPE"]=="RADIO")
      {
         $db_vars = CSaleOrderPropsVariant::GetList(($by="SORT"), ($order="ASC"), Array("ORDER_PROPS_ID"=>$props["ID"]));
         while ($vars = $db_vars->Fetch())
         {
            echo '<input type="radio" name="ORDER_PROP_'.$props["ID"].'" value="'.$vars["VALUE"].'"'.(($vars["VALUE"]==$props["DEFAULT_VALUE"])?" checked":"").'>'.htmlspecialchars($vars["NAME"]).'<br>';
         }
      }

      if (strlen($props["DESCRIPTION"])>0)
      {
         echo "<br><small>".$props["DESCRIPTION"]."</small>";
      }

      echo "<br>";
   }
   while ($props = $db_props->Fetch());
}
?>


Update

CSaleOrderProps::Update

int
CSaleOrderProps::Update(
  int ID,
  array arFields
);

Функция изменяет параметры свойства с кодом ID заказа на значения из массива arFields

Параметры функции

Параметр | Описание
ID | Код свойства заказа.
arFields Ассоциативный массив новых значений параметров свойства заказа, в котором ключами являются названия параметров свойства, а значениями - значения этих параметров.
Допустимые ключи:
  • PERSON_TYPE_ID - тип плательщика;
  • NAME - название свойства (тип плательщика зависит от сайта, а сайт - от языка; название должно быть на соответствующем языке);
  • TYPE - тип свойства. Допустимые значения:
    • CHECKBOX - флаг;
    • TEXT - строка текста;
    • SELECT - выпадающий список значений;
    • MULTISELECT - список со множественным выбором;
    • TEXTAREA - многострочный текст;
    • LOCATION - местоположение;
    • RADIO - переключатель.
  • REQUIED - флаг (Y/N) обязательное ли поле;
  • DEFAULT_VALUE - значение по умолчанию;
  • SORT - индекс сортировки;
  • USER_PROPS - флаг (Y/N) входит ли это свойство в профиль покупателя;
  • IS_LOCATION - флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта стоимости доставки (только для свойств типа LOCATION);
  • PROPS_GROUP_ID - код группы свойств;
  • SIZE1 - ширина поля (размер по горизонтали);
  • SIZE2 - высота поля (размер по вертикали);
  • DESCRIPTION - описание свойства;
  • IS_EMAIL - флаг (Y/N) использовать ли значение свойства как E-Mail покупателя;
  • IS_PROFILE_NAME - флаг (Y/N) использовать ли значение свойства как название профиля покупателя;
  • IS_PAYER - флаг (Y/N) использовать ли значение свойства как имя плательщика;
  • IS_LOCATION4TAX - флаг (Y/N) использовать ли значение свойства как местоположение покупателя для расчёта налогов (только для свойств типа LOCATION);
  • CODE - мнемонический код свойства.

Возвращаемые значения

Возвращается код измененного свойства заказа.

Пример использования

<?
$arFields = array(
   "PERSON_TYPE_ID" => 2,
   "NAME" => "Комплектация",
   "TYPE" => "RADIO",
   "REQUIED" => "Y",
   "DEFAULT_VALUE" => "F",
   "SORT" => 100,
   "CODE" => "COMPLECT",
   "USER_PROPS" => "N",
   "IS_LOCATION" => "N",
   "IS_LOCATION4TAX" => "N",
   "PROPS_GROUP_ID" => 1,
   "SIZE1" => 0,
   "SIZE2" => 0,
   "DESCRIPTION" => "",
   "IS_EMAIL" => "N",
   "IS_PROFILE_NAME" => "N",
   "IS_PAYER" => "N"
);

// Если установлен код свойства, то изменяем свойство с этим кодом,
// иначе добавляем новой свойство
if ($ID>0)
{
   if (!CSaleOrderProps::Update($ID, $arFields))
   {
      echo "Ошибка изменения параметров свойства";
   }
   else
   {
      // Обновим мнемонический код у значений свойства
      // (хранение избыточных данных для оптимизации работы)
      $db_order_props_tmp =
          CSaleOrderPropsValue::GetList(($b="NAME"),
                                        ($o="ASC"),
                                        Array("ORDER_PROPS_ID"=>$ID));
      while ($ar_order_props_tmp = $db_order_props_tmp->Fetch())
      {
         CSaleOrderPropsValue::Update($ar_order_props_tmp["ID"],
                                      array("CODE" => "COMPLECT"));
      }
   }
}
else
{
   $ID = CSaleOrderProps::Add($arFields);
   if ($ID<=0)
      echo "Ошибка добавления свойства";
}
?>


Класс CSaleOrderPropsGroup

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.
GetByID | Функция возвращает параметры группы свойств заказа с кодом ID.
Update | Функция обновляет параметры группы заказов с кодом ID на параметры из массива arFields.
Delete | Функция удаляет группу свойств с кодом ID.
Add | Функция добавляет новую группу свойств заказа. Группа используется только для группировки свойств.


Add

CSaleOrderPropsGroup::Add

int
CSaleOrderPropsGroup::Add(
  array arFields
);

Функция добавляет новую группу свойств заказа. Группа используется только для группировки свойств.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров группы свойств, в котором ключами являются названия параметров, а значениями - их значения.
Допустимые ключи:
  • PERSON_TYPE_ID - тип плательщика;
  • NAME - название группы (группа привязывается к типу плательщика, тип плательщика привязывается к сайту, сайт привязывается к языку, название задается на этом языке);
  • SORT - индекс сортировки.

Возвращаемые значения

Возвращается код добавленной группы или false в случае ошибки.


Delete

CSaleOrderPropsGroup::Delete

bool
CSaleOrderPropsGroup::Delete(
  int ID
);

Функция удаляет группу свойств с кодом ID. Так же удаляются свойства этой группы и другие сопутствующие данные. Значения свойств этой группы, привязанные к заказам, отвязываются от удаляемых свойств.
Если необходимо удалить только группу, то сначала от нее необходимо отвязать все свойства.

Параметры функции

Параметр | Описание
ID | Код группы свойств.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleOrderPropsGroup::GetByID

array
CSaleOrderPropsGroup::GetByID(
  int ID
);

Функция возвращает параметры группы свойств заказа с кодом ID

Параметры функции

Параметр | Описание
ID | Код группы заказов.

Возвращаемые значения

Возвращается ассоциативный массив параметров группы свойств с ключами:

Ключ | Описание
ID | Код группы заказов.
PERSON_TYPE_ID | Тип плательщика.
NAME | Название группы.
SORT | Индекс сортировки.

Пример использования

<?
if ($arPropsGroup = CSaleOrderPropsGroup::GetByID(3))
   echo $arPropsGroup["NAME"];
?>


GetList

CSaleOrderPropsGroup::GetList

CDBResult
CSaleOrderPropsGroup::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле местоположения, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи групп свойств. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("!PERSON_TYPE_ID" => 1)
Этот фильтр означает "выбрать все записи, в которых значение в поле PERSON_TYPE_ID (код типа плательщика) не равно 1".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи групп свойств. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле групп свойств. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров групп свойств с ключами:

Ключ | Описание
ID | Код группы заказов.
PERSON_TYPE_ID | Тип плательщика.
NAME | Название группы.
SORT | Индекс сортировки.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем все группы свойств для плательщика с кодом $PERSON_TYPE
$db_propsGroup = CSaleOrderPropsGroup::GetList(
        array("SORT" => "ASC"),
        array("PERSON_TYPE_ID" => $PERSON_TYPE),
        false,
        false,
        array()
    );

while ($propsGroup = $db_propsGroup->Fetch())
{
   echo $propsGroup["NAME"]."<br>";
}
?>


Update

CSaleOrderPropsGroup::Update

int
CSaleOrderPropsGroup::Update(
  int ID,
  array arFields
);

Функция обновляет параметры группы заказов с кодом ID на параметры из массива arFields

Параметры функции

Параметр | Описание
ID | Код группы заказов.
arFields Ассоциативный массив параметров группы свойств, в котором ключами являются названия параметров, а значениями - новые значения.

Допустимые ключи:
  • PERSON_TYPE_ID - тип плательщика;
  • NAME - название группы (группа привязывается к типу плательщика, тип плательщика привязывается к сайту, сайт привязывается к языку, название задается на этом языке);
  • SORT - индекс сортировки.

Возвращаемые значения

Возвращается код добавленной группы или false в случае ошибки.


Класс CSaleOrderPropsValue

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.
GetByID | Функция возвращает параметры значения с кодом ID свойства заказа.
Update | Функция обновляет параметры значения с кодом ID свойства заказа на параметры из массива arFields.
Add | Функция добавляет новое значение свойства к заказу на основании параметров arFields.
GetOrderProps | Функция возвращает набор значений свойств для заказа с кодом ORDER_ID.


Add

CSaleOrderPropsValue::Add

int
CSaleOrderPropsValue::Add(
  array arFields
);

Функция добавляет новое значение свойства к заказу на основании параметров arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров значения свойства, ключами в котором являются названия параметров значения свойства, а значениями - соответствующие значения.

Допустимые ключи:
  • ORDER_ID - код заказа (обязательное);
  • ORDER_PROPS_ID - код свойства;
  • NAME - название свойства;
  • VALUE - значение свойства (обязательное);
  • CODE - мнемонический код свойства.

Возвращаемые значения

Функция возвращает код добавленного значения свойства или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "ORDER_ID" => 124859,
   "ORDER_PROPS_ID" => 15,
   "NAME" => "Адрес доставки",
   "CODE" => "ADDRESS",
   "VALUE" => "ул. Строителей, дом 88, кв. 15"
);

CSaleOrderPropsValue::Add($arFields);
?>


GetByID

CSaleOrderPropsValue::GetByID

array
CSaleOrderPropsValue::GetByID(
  int ID
);

Функция возвращает параметры значения с кодом ID свойства заказа.

Параметры функции

Параметр | Описание
ID | Код значения свойства заказа.

Возвращаемые значения

Возвращается ассоциативный массив параметров значения свойства с ключами:

Ключ | Описание
ID | Код значения свойства заказа.
ORDER_ID | Код заказа.
ORDER_PROPS_ID | Код свойства.
NAME | Название свойства.
VALUE | Значение свойства.
CODE | Мнемонический код свойства.


GetList

CSaleOrderPropsValue::GetList

CDBResult
CSaleOrderPropsValue::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из заказов в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле местоположения, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи значений свойств. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("~CODE" => "SH*")
Этот фильтр означает "выбрать все записи, в которых значение в поле CODE (мнемонический код свойства) начинается с SH".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи значений свойств. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле значений свойств. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров значений свойств с ключами:

Ключ | Описание
ID | Код значения свойства заказа.
ORDER_ID | Код заказа.
ORDER_PROPS_ID | Код свойства.
NAME | Название свойства.
VALUE | Значение свойства.
CODE | Мнемонический код свойства.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Узнаем имя заказчика (т.е. значение, которое было введено в поле свойства
// заказа $ORDER_ID с установленным флагом IS_PAYER)
$PAYER_NAME = "";
$db_order = CSaleOrder::GetList(
        array("DATE_UPDATE" => "DESC"),
        array("ID" => $ORDER_ID)
    );
if ($arOrder = $db_order->Fetch())
{
   $db_props = CSaleOrderProps::GetList(
        array("SORT" => "ASC"),
        array(
                "PERSON_TYPE_ID" => $arOrder["PERSON_TYPE_ID"],
                "IS_PAYER" => "Y"
            )
    );
   if ($arProps = $db_props->Fetch())
   {
      $db_vals = CSaleOrderPropsValue::GetList(
            array("SORT" => "ASC"),
            array(
                    "ORDER_ID" => $ORDER_ID,
                    "ORDER_PROPS_ID" => $arProps["ID"]
                )
        );
      if ($arVals = $db_vals->Fetch())
        $PAYER_NAME = $arVals["VALUE"];
   }
}
echo $PAYER_NAME;
?>


GetOrderProps

CSaleOrderPropsValue::GetOrderProps

CDBResult
CSaleOrderPropsValue::GetOrderProps(
  int ORDER_ID
);

Функция возвращает набор значений свойств для заказа с кодом ORDER_ID. Кроме параметров значений свойств возвращаются также некоторые связанные значения.

Параметры функции

Параметр | Описание
ORDER_ID | Код заказа.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров значений свойств заказа (и сопутствующие параметры других объектов) с ключами:

Ключ | Описание
ID | Код значения свойства заказа.
ORDER_ID | Код заказа.
ORDER_PROPS_ID | Код свойства заказа.
NAME | Название свойства заказа (привязанное к значению)
VALUE | Значение свойства заказа.
CODE | Мнемонический код свойства заказа.
PROPERTY_NAME | Название свойства заказа.
TYPE | Тип свойства заказа.
PROPS_GROUP_ID | Код группы свойств заказа.
GROUP_NAME | Название группы свойств заказа.
IS_LOCATION | Флаг (Y/N) использовать ли это значение в качестве кода местоположения для получения стоимости доставки.
IS_EMAIL | Флаг (Y/N) использовать ли это значение в качестве email адреса покупателя.
IS_PROFILE_NAME | Флаг (Y/N) использовать ли это значение в качестве названия профиля покупателя.
IS_PAYER | Флаг (Y/N) использовать ли это значение в качестве имени покупателя.

Результирующий набор отсортирован последовательно по индексу сортировки группы свойств заказа, названию группы свойств заказа, индексу сортировки свойства заказа, названию свойства заказа.

Пример использования

<?
// Выведем все свойства заказа с кодом $ID, сгруппированые по группам свойств
$db_props = CSaleOrderPropsValue::GetOrderProps($ID);
$iGroup = -1;
while ($arProps = $db_props->Fetch())
{
   if ($iGroup!=IntVal($arProps["PROPS_GROUP_ID"]))
   {
      echo "<b>".$arProps["GROUP_NAME"]."</b><br>";
      $iGroup = IntVal($arProps["PROPS_GROUP_ID"]);
   }

   echo $arProps["NAME"].": ";

   if ($arProps["TYPE"]=="CHECKBOX")
   {
      if ($arProps["VALUE"]=="Y")
         echo "Да";
      else
         echo "Нет";
   }
   elseif ($arProps["TYPE"]=="TEXT" || $arProps["TYPE"]=="TEXTAREA")
   {
      echo htmlspecialchars($arProps["VALUE"]);
   }
   elseif ($arProps["TYPE"]=="SELECT" || $arProps["TYPE"]=="RADIO")
   {
      $arVal = CSaleOrderPropsVariant::GetByValue($arProps["ORDER_PROPS_ID"], $arProps["VALUE"]);
      echo htmlspecialchars($arVal["NAME"]);
   }
   elseif ($arProps["TYPE"]=="MULTISELECT")
   {
      $curVal = split(",", $arProps["VALUE"]);
      for ($i = 0; $i<count($curVal); $i++)
      {
         $arVal = CSaleOrderPropsVariant::GetByValue($arProps["ORDER_PROPS_ID"], $curVal[$i]);
         if ($i>0) echo ", ";
         echo htmlspecialchars($arVal["NAME"]);
      }
   }
   elseif ($arProps["TYPE"]=="LOCATION")
   {
      $arVal = CSaleLocation::GetByID($arProps["VALUE"], LANGUAGE_ID);
      echo htmlspecialchars($arVal["COUNTRY_NAME"]." - ".$arVal["CITY_NAME"]);
   }

   echo "<br>";
}
?>


Update

CSaleOrderPropsValue::Update

int
CSaleOrderPropsValue::Update(
  int ID,
  array arFields
);

Функция обновляет параметры значения с кодом ID свойства заказа на параметры из массива arFields

Параметры функции

Параметр | Описание
ID | Код знасения свойства заказа.
arFields Ассоциативный массив параметров значения свойства, ключами в котором являются названия параметров значения свойства, а значениями - соответствующие новые значения.

Допустимые ключи:
  • ORDER_ID - код заказа (обязательное);
  • ORDER_PROPS_ID - код свойства;
  • NAME - название свойства;
  • VALUE - значение свойства (обязательное);
  • CODE - мнемонический код свойства.

Возвращаемые значения

Функция возвращает код обновленного значения свойства или false в случае ошибки.

Пример использования

<?
CSaleOrderPropsValue::Update(8, array("CODE"=>"ADDRESS"));
?>


Класс CSaleOrderPropsVariant

Методы класса

Метод | Описание
GetList | Функция возвращает набор вариантов значений свойств заказа, удовлетворяющих фильтру.
GetByValue | Функция возвращает параметры варианта значения свойства заказа по коду свойства заказа и значению.
GetByID | Функция возвращает параметры варианта с кодом ID значения свойства заказа.
Update | Функция обновляет параметры варианта с кодом ID на значения из массива arFields.
Delete | Функция удаляет вариант с кодом ID значения свойства заказа.
DeleteAll | Функция удаляет все варианты значений для свойства с кодом ID заказа.
Add | Функция добавляет новый вариант для выбора значения в свойствах типа переключатель (RADIO) и списки (SELECT, MULTISELECT).


Add

CSaleOrderPropsVariant::Add

int
CSaleOrderPropsVariant::Add(
  array arFields
);

Функция добавляет новый вариант для выбора значения в свойствах типа переключатель (RADIO) и списки (SELECT, MULTISELECT)

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового варианта значения свойства заказа, ключами в котором являются названия параметров.
Допустимые ключи:
  • ORDER_PROPS_ID - код свойства заказа;
  • NAME - название варианта;
  • VALUE - значение варианта;
  • SORT - индекс сортировки;
  • DESCRIPTION - описание варианта.

Возвращаемые значения

Возвращается код добавленного варианта значения или false в случае ошибки.

Пример использования

<?
$arFieldsV = array(
   "ORDER_PROPS_ID" => 12,
   "VALUE" => "F",
   "NAME" => "В полной комплектации",
   "SORT" => 100,
   "DESCRIPTION" => "Доставка начинается после полного формирования заказа"
);

if (!CSaleOrderPropsVariant::Add($arFieldsV))
   echo "Ошибка добавления варианта значения";
?>


Delete

CSaleOrderPropsVariant::Delete

bool
CSaleOrderPropsVariant::Delete(
  int ID
);

Функция удаляет вариант с кодом ID значения свойства заказа.

Параметры функции

Параметр | Описание
ID | Код варианта значения свойства заказа.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в случае ошибки.

Пример использования

<?
CSaleOrderPropsVariant::Delete(12);
?>


DeleteAll

CSaleOrderPropsVariant::DeleteAll

bool
CSaleOrderPropsVariant::DeleteAll(
  int ID
);

Функция удаляет все варианты значений для свойства с кодом ID заказа.

Параметры функции

Параметр | Описание
ID | Код свойства заказа.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleOrderPropsVariant::GetByID

array
CSaleOrderPropsVariant::GetByID(
  int ID
);

Функция возвращает параметры варианта с кодом ID значения свойства заказа.

Параметры функции

Параметр | Описание
ID | Код варианта значения свойства заказа.

Возвращаемые значения

Возвращается ассоциативный массив значений параметров заказа с ключами:

Код | Описание
ID | Код варианта значения свойства заказа.
ORDER_PROPS_ID | Код свойства заказа.
NAME | Название варианта.
VALUE | Значение варианта.
SORT | Индекс сортировки.
DESCRIPTION | Описание варианта значения свойства заказа.


GetByValue

CSaleOrderPropsVariant::GetByValue

array
CSaleOrderPropsVariant::GetByValue(
  int PropID,
  string Value
);

Функция возвращает параметры варианта значения свойства заказа по коду свойства заказа и значению.

Параметры функции

Параметр | Описание
PropID | Код свойства заказа.
Value | Значение свойства.

Возвращаемые значения

Возвращается ассоциативный массив значений параметров заказа с ключами:

Код | Описание
ID | Код варианта значения свойства заказа.
ORDER_PROPS_ID | Код свойства заказа.
NAME | Название варианта.
VALUE | Значение варианта.
SORT | Индекс сортировки.
DESCRIPTION | Описание варианта значения свойства заказа.

Пример использования

<?
$arVal = CSaleOrderPropsVariant::GetByValue(12, "F");
echo $arVal["NAME"];
?>


GetList

CSaleOrderPropsVariant::GetList

CDBResult
CSaleOrderPropsVariant::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает набор вариантов значений свойств заказа, удовлетворяющих фильтру arFilter. Результирующий набор отсортирован по полю by в направлении order.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле вариантов значений свойств, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи вариантов значений свойств. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("~VALUE" => "SH*")
Этот фильтр означает "выбрать все записи, в которых значение в поле VALUE (значение) начинается с SH".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи вариантов значений свойств. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле значений свойств. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров с ключами:

Код | Описание
ID | Код варианта значения свойства заказа.
ORDER_PROPS_ID | Код свойства заказа.
NAME | Название варианта.
VALUE | Значение варианта.
SORT | Индекс сортировки.
DESCRIPTION | Описание варианта значения свойства заказа.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем форму для ввода свойств заказа для группы свойств с кодом 5, которые
// входят в профиль покупателя, для типа плательщика с кодом 2
$db_props = CSaleOrderProps::GetList(
        array("SORT" => "ASC"),
        array(
                "PERSON_TYPE_ID" => 2,
                "PROPS_GROUP_ID" => 5,
                "USER_PROPS" => "Y"
            )
    );
if ($props = $db_props->Fetch())
{
   echo "Заполните параметры заказа:<br>";
   do
   {
      echo $props["NAME"];
      if ($props["REQUIED"]=="Y" || $props["IS_EMAIL"]=="Y" ||
          $props["IS_PROFILE_NAME"]=="Y" || $props["IS_LOCATION"]=="Y" ||
          $props["IS_LOCATION4TAX"]=="Y" || $props["IS_PAYER"]=="Y")
      {
         echo "*";
      }
      echo ": ";

      if ($props["TYPE"]=="CHECKBOX")
      {
         echo '<input type="checkbox" class="inputcheckbox" name="ORDER_PROP_'.$props["ID"].'" value="Y"'.(($props["DEFAULT_VALUE"]=="Y")?" checked":"").'>';
      }
      elseif ($props["TYPE"]=="TEXT")
      {
         echo '<input type="text" class="inputtext" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:30).'" maxlength="250" value="'.htmlspecialchars($props["DEFAULT_VALUE"]).'" name="ORDER_PROP_'.$props["ID"].'">";
      }
      elseif ($props["TYPE"]=="SELECT")
      {
         echo '<select name="ORDER_PROP_'.$props["ID"].'" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:1).'">';
         $db_vars = CSaleOrderPropsVariant::GetList(
                array("SORT" => "ASC"),
                array("ORDER_PROPS_ID" => $props["ID"])
            );
         while ($vars = $db_vars->Fetch())
         {
            echo '<option value="'.$vars["VALUE"].'"'.(($vars["VALUE"]==$props["DEFAULT_VALUE"])?" selected":"").'>'.htmlspecialchars($vars["NAME"]).'</option>';
         }
         echo '</select>';
      }
      elseif ($props["TYPE"]=="MULTISELECT")
      {
         echo '<select multiple name="ORDER_PROP_'.$props["ID"].'[]" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:5).'">';
         $arDefVal = Split(",", $props["DEFAULT_VALUE"]);
         for ($i = 0; $i<count($arDefVal); $i++)
            $arDefVal[$i] = Trim($arDefVal[$i]);

         $db_vars = CSaleOrderPropsVariant::GetList(
                array("SORT" => "ASC"),
                array("ORDER_PROPS_ID" => $props["ID"])
            );
         while ($vars = $db_vars->Fetch())
         {
            echo '<option value="'.$vars["VALUE"].'"'.(in_array($vars["VALUE"], $arDefVal)?" selected":"").'>'.htmlspecialchars($vars["NAME"]).'</option>';
         }
         echo '</select>';
      }
      elseif ($props["TYPE"]=="TEXTAREA")
      {
         echo '<textarea rows="'.((IntVal($props["SIZE2"])>0)?$props["SIZE2"]:4).'" cols="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:40).'" name="ORDER_PROP_'.$props["ID"].'">'.htmlspecialchars($props["DEFAULT_VALUE"]).'</textarea>';
      }
      elseif ($props["TYPE"]=="LOCATION")
      {
         echo '<select name="ORDER_PROP_'.$props["ID"].'" size="'.((IntVal($props["SIZE1"])>0)?$props["SIZE1"]:1).'">';
         $db_vars = CSaleLocation::GetList(Array("SORT"=>"ASC", "COUNTRY_NAME_LANG"=>"ASC", "CITY_NAME_LANG"=>"ASC"), array("LID" => LANGUAGE_ID));
         while ($vars = $db_vars->Fetch())
         {
            echo '<option value="'.$vars["ID"].'"".((IntVal($vars["ID"])==IntVal($props["DEFAULT_VALUE"]))?" selected":"").'>'.htmlspecialchars($vars["COUNTRY_NAME"]." - ".$vars["CITY_NAME"]).'</option>';
         }
         echo '</select>';
      }
      elseif ($props["TYPE"]=="RADIO")
      {
         $db_vars = CSaleOrderPropsVariant::GetList(
                array("SORT" => "ASC"),
                array("ORDER_PROPS_ID" => $props["ID"])
            );
         while ($vars = $db_vars->Fetch())
         {
            echo '<input type="radio" name="ORDER_PROP_'.$props["ID"].'" value="'.$vars["VALUE"].'"'.(($vars["VALUE"]==$props["DEFAULT_VALUE"])?" checked":"").'>'.htmlspecialchars($vars["NAME"]).'<br>';
         }
      }

      if (strlen($props["DESCRIPTION"])>0)
      {
         echo "<br><small>".$props["DESCRIPTION"]."</small>";
      }

      echo "<br>";
   }
   while ($props = $db_props->Fetch());
}
?>


Update

CSaleOrderPropsVariant::Update

int
CSaleOrderPropsVariant::Update(
  int ID,
  array arFields
);

Функция обновляет параметры варианта с кодом ID на значения из массива arFields

Параметры функции

Параметр | Описание
ID | Код варианта значения свойства заказа.
arFields Ассоциативный массив параметров нового варианта значения свойства заказа, ключами в котором являются названия параметров.

Допустимые ключи:
  • ORDER_PROPS_ID - код свойства заказа;
  • NAME - название варианта;
  • VALUE - значение варианта;
  • SORT - индекс сортировки;
  • DESCRIPTION - описание варианта.

Возвращаемые значения

Возвращается код добавленного варианта значения или false в случае ошибки.


Класс CSaleOrderTax

Методы класса

Метод | Описание
Update | Функция изменяет сумму налога с кодом ID на основании массива arFields.
Delete | Функция удаляет сумму налога с кодом ID.
DeleteEx | Функция удаляет все суммы налогов для заказа с кодом ORDER_ID.
GetByID | Функция возвращает параметры суммы налогов с кодом ID.
GetList | Функция возвращает результат выборки записей из налогов заказа в соответствии со своими параметрами.
CountTaxes | Функция вычисляет общую сумму налогов на товар стоимостью Price. Налоги задаются в массиве arTaxList.
Add | Функция добавляет новую сумму налога к заказу.


Add

CSaleOrderTax::Add

int
CSaleOrderTax::Add(
  array arFields
);

Функция добавляет новую сумму налога к заказу.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой записи, ключами в котором являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • ORDER_ID - код заказа (обязательный);
  • TAX_NAME - название налога;
  • VALUE - величина налога (в процентах);
  • VALUE_MONEY - общая сумма этого налога;
  • APPLY_ORDER - порядок применения;
  • CODE - мнемонический код налога;
  • IS_PERCENT - должно быть значение "Y";
  • IS_IN_PRICE - флаг (Y/N) входит ли налог уже в цену товара.

Возвращаемые значения

Возвращается код добавленной суммы налога или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "ORDER_ID" => 12789,
   "TAX_NAME" => "НДС",
   "IS_PERCENT" => "Y",
   "VALUE" => 3.5,
   "VALUE_MONEY" => 6948.55,
   "APPLY_ORDER" => 300,
   "IS_IN_PRICE" => "N",
   "CODE" => "NDS"
);

CSaleOrderTax::Add($arFields);
?>


CountTaxes

CSaleOrderTax::CountTaxes

float
CSaleOrderTax::CountTaxes(
  float Price,
  array &arTaxList,
  string DefCurrency
);

Функция вычисляет общую сумму налогов на товар стоимостью Price. Налоги задаются в массиве arTaxList.

Параметры функции

Параметр | Описание
Price | Стоимость товара.
arTaxList Массив налогов, представляет собой массив ассоциативных массивов вида:
array("APPLY_ORDER"=>порядок_применения,
      "VALUE"=>величина_налога_в_процентах,
      "IS_IN_PRICE"=>"налог_входит_в_цену_Y/N")
DefCurrency | Базовая валюта для заказа.

Возвращаемые значения

Возвращается общая сумма налогов на товар. Кроме того в массиве arTaxList создаётся дополнительный ключ TAX_VAL, который содержит величину данного налога на товар.

Пример использования

<?
// Заполним массив активных налогов для текущего сайта, типа плательщика с кодом 2 и местоположения для начисления налогов с кодом 48
$arTaxList = array();

$arTaxFilter = array(
   "LID" => SITE_ID,
   "PERSON_TYPE_ID" => 2,
   "ACTIVE" => "Y",
   "LOCATION" => 48
);
$db_tax_rate_tmp = CSaleTaxRate::GetList(array("APPLY_ORDER"=>"ASC"), $arTaxFilter);
while ($ar_tax_rate_tmp = $db_tax_rate_tmp->Fetch())
{
   $arTaxList[] = $ar_tax_rate_tmp;
}

// Вычислим величину налогов на товар стоимостью 38.95
$TAX_PRICE_tmp = CSaleOrderTax::CountTaxes(38.95, $arTaxList, "RUR");

echo "Общая величина налогов: ".$TAX_PRICE_tmp."<br>";
echo "в том числе ";
for ($i = 0; $i<count($arTaxList); $i++)
{
   echo $arTaxList[$di]["NAME"]." - ".$arTaxList[$di]["TAX_VAL"]."<br>";
}
?>


Delete

CSaleOrderTax::Delete

bool
CSaleOrderTax::Delete(
  int ID
);

Функция удаляет сумму налога с кодом ID

Параметры функции

Параметр | Описание
ID | Код суммы налога.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


DeleteEx

CSaleOrderTax::DeleteEx

bool
CSaleOrderTax::DeleteEx(
  int ORDER_ID
);

Функция удаляет все суммы налогов для заказа с кодом ORDER_ID

Параметры функции

Параметр | Описание
ORDER_ID | Код заказа.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleOrderTax::GetByID

array
CSaleOrderTax::GetByID(
  int ID
);

Функция возвращает параметры суммы налогов с кодом ID

Параметры функции

Параметр | Описание
ID | Код суммы налогов.

Возвращаемые значения

Возвращается ассоциативный массив с ключами

Ключ | Описание
ID | Код суммы налогов.
ORDER_ID | Код заказа.
TAX_NAME | Название налога.
VALUE | Ставка налога.
VALUE_MONEY | Сумма налога.
APPLY_ORDER | Порядок применения.
CODE | Мнемонический код налога.
IS_IN_PRICE | Флаг (Y/N) включен ли налог в цену товара.
IS_PERCENT | Y


GetList

CSaleOrderTax::GetList

CDBResult
CSaleOrderTax::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле налогов заказа, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи налогов заказа. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("ORDER_ID" => 125)
Этот фильтр означает "выбрать все записи, в которых значение в поле ORDER_ID (код налога) равно 125".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи вариантов налогов заказа. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле налогов заказа. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы с ключами

Ключ | Описание
ID | Код суммы налогов.
ORDER_ID | Код заказа.
TAX_NAME | Название налога.
VALUE | Ставка налога.
VALUE_MONEY | Сумма налога.
APPLY_ORDER | Порядок применения.
CODE | Мнемонический код налога.
IS_IN_PRICE | Флаг (Y/N) включен ли налог в цену товара.
IS_PERCENT | Y

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
$arTaxList = array();
// Выберем все суммы налогов для заказа $ORDER_ID
$db_tax_list = CSaleOrderTax::GetList(array("APPLY_ORDER"=>"ASC"), Array("ORDER_ID"=>$ORDER_ID));

$iNds = -1;
$i = 0;
while ($ar_tax_list = $db_tax_list->Fetch())
{
   $arTaxList[$i] = $ar_tax_list;
   // определяем, какой из налогов - НДС, предполагая, что его мнемонический код - NDS
   if ($arTaxList[$i]["CODE"] == "NDS")
      $iNds = $i;

   $i++;
}
?>


Update

CSaleOrderTax::Update

int
CSaleOrderTax::Update(
  int ID,
  array arFields
);

Функция изменяет сумму налога с кодом ID на основании массива arFields

Параметры функции

Параметр | Описание
ID | Код суммы налога.
arFields Ассоциативный массив новых параметров записи, ключами в котором являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • ORDER_ID - код заказа;
  • TAX_NAME - название налога;
  • VALUE - величина налога;
  • VALUE_MONEY - общая сумма этого налога;
  • APPLY_ORDER - порядок применения;
  • CODE - мнемонический код налога;
  • IS_PERCENT - должно быть значение "Y";
  • IS_IN_PRICE - флаг (Y/N) входит ли налог уже в цену товара.

Возвращаемые значения

Возвращается код измененной суммы налога или false в случае ошибки.


Класс CSaleOrderUserProps

Методы класса

Метод | Описание
GetByID | Функция возвращает параметры профиля покупателя с кодом ID.
Update | Функция обновляет параметры профиля покупателя с кодом ID на значения из массива arFields.
Delete | Функция удаляет профиль покупателя с кодом ID. Вместе с профилем удаляются все его свойства.
Add | Функция сохраняет новый профиль покупателя с параметрами из массива arFields.
ClearEmpty | Функция удаляет все пустые профили из базы (т.е. профили, в которых нет свойств).
GetList | Функция возвращает результат выборки записей из профилей покупателя в соответствии со своими параметрами.


Add

CSaleOrderUserProps::Add

int
CSaleOrderUserProps::Add(
  array arFields
);

Функция сохраняет новый профиль покупателя с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового профиля. Ключами являются названия параметров, а значениями - соответствующие значения.

Допустимые ключи:
  • NAME - название профиля покупателя;
  • USER_ID - код пользователя, которому принадлежит профиль;
  • PERSON_TYPE_ID - тип плательщика;
  • DATE_UPDATE - дата последнего изменения.

Возвращаемые значения

Возвращается код добавленного профиля или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "NAME" => "Профиль 1",
   "USER_ID" => $USER->GetID(),
   "PERSON_TYPE_ID" => 2
);
$USER_PROPS_ID = CSaleOrderUserProps::Add($arFields);
?>


ClearEmpty

CSaleOrderUserProps::ClearEmpty

CSaleOrderUserProps::ClearEmpty();

Функция удаляет все пустые профили из базы (т.е. профили, в которых нет свойств).


Delete

CSaleOrderUserProps::Delete

bool
CSaleOrderUserProps::Delete(
  int ID
);

Функция удаляет профиль покупателя с кодом ID. Вместе с профилем удаляются все его свойства.

Параметры функции

Параметр | Описание
ID | Код профиля покупателя.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.

Пример использования

<?
CSaleOrderUserProps::Delete(12);
?>


GetByID

CSaleOrderUserProps::GetByID

array
CSaleOrderUserProps::GetByID(
  int ID
);

Функция возвращает параметры профиля покупателя с кодом ID

Параметры функции

Параметр | Описание
ID | Код профиля покупателя.

Возвращаемые значения

Возвращается ассоциативный массив параметров профиля покупателя с ключами:

Ключ | Описание
ID | Код профиля покупателя.
NAME | Название профиля.
USER_ID | Код пользователя, которому принадлежит профиль.
PERSON_TYPE_ID | Тип плательщика.
DATE_UPDATE | Дата последнего изменения профиля.

Пример использования

<?
if ($ar = CSaleOrderUserProps::GetByID(12))
{
   echo "<pre>";
   print_r($ar);
   echo "</pre>";
}
?>


GetList

CSaleOrderUserProps::GetList

CDBResult
CSaleOrderUserProps::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из профилей покупателя в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле налогов заказа, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи профилей покупателя. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("~NAME" => "John*")
Этот фильтр означает "выбрать все записи, в которых значение в поле NAME (название профиля) начинается с John".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи вариантов профилей покупателя. Массив имеет вид:
array("название_поля1",
"группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле профилей покупателя. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров профиля покупателя с ключами:

Ключ | Описание
ID | Код профиля покупателя.
NAME | Название профиля.
USER_ID | Код пользователя, которому принадлежит профиль.
PERSON_TYPE_ID | Тип плательщика.
DATE_UPDATE | Дата последнего изменения профиля.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выберем все профили покупателя для текущего пользователя,
// упорядочив результат по дате последнего изменения
$db_sales = CSaleOrderUserProps::GetList(
        array("DATE_UPDATE" => "DESC"),
        array("USER_ID" => $USER->GetID())
    );

while ($ar_sales = $db_sales->Fetch())
{
   echo $ar_sales["NAME"]."<br>";
}
?>


Update

CSaleOrderUserProps::Update

int
CSaleOrderUserProps::Update(
  int ID,
  array arFields
);

Функция обновляет параметры профиля покупателя с кодом ID на значения из массива arFields

Параметры функции

Параметр | Описание
ID | Код профиля покупателя.
arFields Ассоциативный массив новых параметров профиля. Ключами являются названия параметров, а значениями - соответствующие значения.

Допустимые ключи:
  • NAME - название профиля покупателя;
  • USER_ID - код пользователя, которому принадлежит профиль;
  • PERSON_TYPE_ID - тип плательщика;
  • DATE_UPDATE - дата последнего изменения.

Возвращаемые значения

Возвращается код измененного профиля или false в случае ошибки.

Пример использования

<?
// Изменим название профиля покупателя
$arFields = array(
   "NAME" => "Профиль 24"
);
if (!CSaleOrderUserProps::Update(258, $arFields))
   echo "Ошибка изменения профиля покупателя";
?>


Класс CSaleOrderUserPropsValue

Методы класса

Метод | Описание
GetByID | Функция возвращает параметры свойства с кодом ID профиля покупателя.
Delete | Функция удаляет свойство с кодом ID профиля покупателя.
DeleteAll | Функция удаляет все свойства профиля покупателя для профиля с кодом ID.
GetList | Функция возвращает результат выборки записей из значений свойств профилей покупателя в соответствии со своими параметрами.
Add | Функция добавляет новое свойство профиля покупателя в соответствии с массивом параметров arFields.


Add

CSaleOrderUserPropsValue::Add

int
CSaleOrderUserPropsValue::Add(
  array arFields
);

Функция добавляет новое свойство профиля покупателя в соответствии с массивом параметров arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового свойства профиля покупателя. Ключами в массиве являются названия параметров свойства, а значениями - соответствующие значения.

Допустимые ключи:
  • USER_PROPS_ID - код профиля покупателя;
  • ORDER_PROPS_ID - код свойства заказа;
  • NAME - название свойства заказа;
  • VALUE - значение свойства заказа в профиле.

Возвращаемые значения

Возвращается код добавленного свойства профиля покупателя или false в случае ошибки.

Пример использования

<?
$arFields = array(
   "USER_PROPS_ID" => 1258,
   "ORDER_PROPS_ID" => 12,
   "NAME" => "Почтовый индекс",
   "VALUE" => "236015"
);
CSaleOrderUserPropsValue::Add($arFields);
?>


Delete

CSaleOrderUserPropsValue::Delete

bool
CSaleOrderUserPropsValue::Delete(
  int ID
);

Функция удаляет свойство с кодом ID профиля покупателя.

Параметры функции

Параметр | Описание
ID | Код свойства профиля покупателя.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.

Пример использования

<?
CSaleOrderUserPropsValue::Delete(17);
?>


DeleteAll

CSaleOrderUserPropsValue::DeleteAll

bool
CSaleOrderUserPropsValue::DeleteAll(
  int ID
);

Функция удаляет все свойства профиля покупателя для профиля с кодом ID

Параметры функции

Параметр | Описание
ID | Код профиля покупателя.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleOrderUserPropsValue::GetByID

array
CSaleOrderUserPropsValue::GetByID(
  int ID
);

Функция возвращает параметры свойства с кодом ID профиля покупателя.

Параметры функции

Параметр | Описание
ID | Код свойства профиля покупателя.

Возвращаемые значения

Возвращается ассоциативный массив параметров свойства с ключами:

Ключ | Описание
ID | Код свойства профиля покупателя.
USER_PROPS_ID | Код профиля покупателя.
ORDER_PROPS_ID | Код свойства заказа.
NAME | Название свойства заказа.
VALUE | Значение свойства заказа, сохраненное в профиле покупателя.


GetList

CSaleOrderUserPropsValue::GetList

CDBResult
CSaleOrderUserPropsValue::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из значений свойств профилей покупателя в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле налогов заказа, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи значений свойств профилей покупателя. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("USER_PROPS_ID" => 120)
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_PROPS_ID (код профиля покупателя) равно 120".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи значений свойств профилей покупателя. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле значений свойств профилей покупателя. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров свойств с ключами:

Ключ | Описание
ID | Код свойства профиля покупателя.
USER_PROPS_ID | Код профиля покупателя.
ORDER_PROPS_ID | Код свойства заказа.
USER_VALUE_NAME | Название свойства заказа, сохраненное в профиле покупателя.
VALUE | Значение свойства заказа, сохраненное в профиле покупателя.
TYPE | Тип свойства заказа.
SORT | Индекс сортировки свойства заказа.
VARIANT_NAME | Название варианта значения свойства заказа со значением из профиля покупателя.
CODE | Мнемонический код свойства заказа.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем все свойства профиля покупателя с кодом $ID
$db_propVals = CSaleOrderUserPropsValue::GetList(($b="SORT"), ($o="ASC"), Array("USER_PROPS_ID"=>$ID));
while ($arPropVals = $db_propVals->Fetch())
{
   echo $arPropVals["USER_VALUE_NAME"]."=".$arPropVals["VALUE"]."<br>";
}
?>


Класс CSalePaySystem

Методы класса

Метод | Описание
Update | Функция обновляет параметры платежной системы с кодом ID в соответствии со значениями из массива arFields.
Delete | Функция удаляет платежную систему с кодом ID.
GetList | Функция возвращает результат выборки записей из платежных систем в соответствии со своими параметрами.
GetByID | Функция возвращает параметры платежной системы с кодом ID.
Add | Метод добавляет новую платежную систему на основании параметров из массива arFields.


Add

CSalePaySystem::Add

int
CSalePaySystem::Add(
 array arFields
);

Метод добавляет новую платежную систему на основании параметров из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой платежной системы, в котором ключами являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • LID - сайт платежной системы;
  • CURRENCY - валюта платежной системы;
  • NAME - название платежной системы;
  • ACTIVE - флаг (Y/N) активности платежной системы;
  • SORT - индекс сортировки;
  • DESCRIPTION - описание.

Возвращаемые значения

Возвращается код измененной записи или false в случае ошибки.


Delete

CSalePaySystem::Delete

bool
CSalePaySystem::Delete(
  int ID
);

Функция удаляет платежную систему с кодом ID. Если к платежной системе с кодом ID привязаны заказы, то эта платежная система удалена не будет.

Параметры функции

Параметр | Описание
ID | Код платежной системы.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.

Пример использования

<?
CSalePaySystem::Delete(25);
?>


GetByID

CSalePaySystem::GetByID

array
CSalePaySystem::GetByID(
  int ID,
  int PERSON_TYPE_ID = 0
);

Функция возвращает параметры платежной системы с кодом ID. Если установлен параметр PERSON_TYPE_ID, то возвращаются так же параметры соответствующего обработчика платежной системы.

Параметры функции

Параметр | Описание
ID | Код платежной системы.
PERSON_TYPE_ID | Код типа плательщика. Если установлен, то дополнительно возвращаются параметры соответствующего обработчика платежной системы. Иначе - только параметры самой платежной системы.

Возвращаемые значения

Возвращается ассоциативный массив параметров с ключами:

Ключ | Описание
ID | Код платежной системы.
LID | Сайт, на котором работает эта система.
CURRENCY | Валюта, с которой работает эта система.
NAME | Название платежной системы.
ACTIVE | Флаг (Y/N) активности системы.
SORT | Индекс сортировки.
DESCRIPTION | Описание платежной системы.
PSA_ID | Код обработчика платежной системы (возвращается, если в функцию передается тип плательщика)
PSA_NAME | Название обработчика (возвращается, если в функцию передается тип плательщика)
PSA_ACTION_FILE | Скрипт обработчика (возвращается, если в функцию передается тип плательщика)
PSA_RESULT_FILE | Скрипт запроса результатов (возвращается, если в функцию передается тип плательщика)
PSA_NEW_WINDOW | Флаг (Y/N) открывать ли скрипт обработчика в новом окне (возвращается, если в функцию передается тип плательщика)

Пример использования

<?
// Выведем название обработчика платежной системы с кодом $PAY_SYSTEM_ID
// для типа плательщика с кодом $PERSON_TYPE
if ($arPaySys = CSalePaySystem::GetByID($PAY_SYSTEM_ID, $PERSON_TYPE))
{
   echo $arPaySys["PSA_NAME"];
}
?>


GetList

CSalePaySystem::GetList

CDBResult
CSalePaySystem::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из платежных систем в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле платежных систем, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи платежных систем. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("!LID" => "en")
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_PROPS_ID (код профиля покупателя) равно 120".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи платежных систем. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле платежных систем. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Этот фильтр означает "выбрать все записи, в которых значение в поле LID (сайт системы) не равно en".

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров платежных систем с ключами:

Ключ | Описание
ID | Код платежной системы.
LID | Сайт, на котором работает эта система.
CURRENCY | Валюта, с которой работает эта система.
NAME | Название платежной системы.
ACTIVE | Флаг (Y/N) активности системы.
SORT | Индекс сортировки.
DESCRIPTION | Описание платежной системы.
PSA_ID | Код обработчика платежной системы (возвращается, если в функцию передается тип плательщика)
PSA_NAME | Название обработчика (возвращается, если в функцию передается тип плательщика)
PSA_ACTION_FILE | Скрипт обработчика (возвращается, если в функцию передается тип плательщика)
PSA_RESULT_FILE | Скрипт запроса результатов (возвращается, если в функцию передается тип плательщика)
PSA_NEW_WINDOW | Флаг (Y/N) открывать ли скрипт обработчика в новом окне (возвращается, если в функцию передается тип плательщика)
PSA_PERSON_TYPE_ID | Код типа плательщика.
PSA_PARAMS | Параметры вызова обработчика.
PSA_HAVE_PAYMENT | Есть вариант обработчика для работы после оформления заказа.
PSA_HAVE_ACTION | Есть вариант обработчика для мгновенного списания денег.
PSA_HAVE_RESULT | Есть скрипт запроса результатов.
PSA_HAVE_PREPAY | Есть вариант обработчика для работы во время оформления заказа.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем все активные платежные системы для текущего сайта, для типа плательщика с кодом 2, работающие с валютой RUR
$db_ptype = CSalePaySystem::GetList($arOrder = Array("SORT"=>"ASC", "PSA_NAME"=>"ASC"), Array("LID"=>SITE_ID, "CURRENCY"=>"RUR", "ACTIVE"=>"Y", "PERSON_TYPE_ID"=>2));
$bFirst = True;
while ($ptype = $db_ptype->Fetch())
{
   ?><input type="radio" name="PAY_SYSTEM_ID" value="<?echo $ptype["ID"] ?>"<?if ($bFirst) echo " checked";?>><b><?echo $ptype["PSA_NAME"] ?></b><br><?
   $bFirst = false;
   if (strlen($ptype["DESCRIPTION"])>0)
      echo $ptype["DESCRIPTION"]."<br>";
   ?><hr size="1" width="90%"><?
}
?>


Update

CSalePaySystem::Update

int
CSalePaySystem::Update(
  int ID,
  array arFields
);

Функция обновляет параметры платежной системы с кодом ID в соответствии со значениями из массива arFields

Параметры функции

Параметр | Описание
ID | Код платежной системы.
arFields Ассоциативный массив новых параметров платежной системы, в котором ключами являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • LID - сайт платежной системы;
  • CURRENCY - валюта платежной системы;
  • NAME - название платежной системы;
  • ACTIVE - флаг (Y/N) активности платежной системы;
  • SORT - индекс сортировки;
  • DESCRIPTION - описание.

Возвращаемые значения

Возвращается код измененной записи или false в случае ошибки.


Класс CSalePaySystemAction

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из обработчиков платежных систем в соответствии со своими параметрами.
GetByID | Функция возвращает параметры обработчика платежной системы с кодом ID.
Update | Функция обновляет параметры обработчика с кодом ID платежной системы в соответствии с массивом arFields.
Delete | Функция удаляет обработчик платежной системы с кодом ID.
Add | Метод добавляет новый обработчик платежной системы на основании параметров из массива arFields.


Add

CSalePaySystemAction::Add

int
CSalePaySystemAction::Add(
 array arFields
);

Метод добавляет новый обработчик платежной системы на основании параметров из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового обработчика платежной системы, ключами в котором являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • PAY_SYSTEM_ID - код платежной системы;
  • PERSON_TYPE_ID - код типа плательщика;
  • NAME - название платежной системы;
  • ACTION_FILE - скрипт платежной системы;
  • RESULT_FILE - скрипт получения результатов;
  • NEW_WINDOW - флаг (Y/N) открывать ли скрипт платежной системы в новом окне
  • PARAMS - параметры вызова обработчика
  • HAVE_PAYMENT - есть вариант обработчика для работы после оформления заказа
  • HAVE_ACTION - есть вариант обработчика для мгновенного списания денег
  • HAVE_RESULT - есть скрипт запроса результатов
  • HAVE_PREPAY - есть вариант обработчика для работы во время оформления заказа.

Возвращаемые значения

Возвращается код обновленной записи или false - в случае ошибки.


Delete

CSalePaySystemAction::Delete

bool
CSalePaySystemAction::Delete(
  int ID
);

Функция удаляет обработчик платежной системы с кодом ID

Параметры функции

Параметр | Описание
ID | Код обработчика платежной системы.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.

Пример использования

<?
CSalePaySystemAction::Delete(12);
?>


GetByID

CSalePaySystemAction::GetByID

array
CSalePaySystemAction::GetByID(
  int ID
);

Функция возвращает параметры обработчика платежной системы с кодом ID

Параметры функции

Параметр | Описание
ID | Код обработчика платежной системы.

Возвращаемые значения

Возвращается ассоциативный массив параметров обработчика платежной системы с ключами:

Ключ | Описание
ID | Код обработчика платежной системы.
PAY_SYSTEM_ID | Код платежной системы.
PERSON_TYPE_ID | Код типа плательщика.
NAME | Название платежной системы.
ACTION_FILE | Скрипт платежной системы.
RESULT_FILE | Скрипт получения результатов.
NEW_WINDOW | Флаг (Y/N) открывать ли скрипт платежной системы в новом окне.


GetList

CSalePaySystemAction::GetList

CDBResult
CSalePaySystemAction::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из обработчиков платежных систем в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле обработчиков платежных систем, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи обработчиков платежных систем. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("!PERSON_TYPE_ID" => 5)
Этот фильтр означает "выбрать все записи, в которых значение в поле PERSON_TYPE_ID (код типа плательщика) не равно 5".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи обработчиков платежных систем. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле обработчиков платежных систем. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Этот фильтр означает "выбрать все записи, в которых значение в поле LID (сайт системы) не равно en".

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров обработчиков платежных систем с ключами:

Ключ | Описание
ID | Код обработчика платежной системы.
PAY_SYSTEM_ID | Код платежной системы.
PERSON_TYPE_ID | Код типа плательщика.
NAME | Название платежной системы.
ACTION_FILE | Скрипт платежной системы.
RESULT_FILE | Скрипт получения результатов.
NEW_WINDOW | Флаг (Y/N) открывать ли скрипт платежной системы в новом окне.
PARAMS | Параметры вызова обработчика.
HAVE_PAYMENT | Есть вариант обработчика для работы после оформления заказа.
HAVE_ACTION | Есть вариант обработчика для мгновенного списания денег.
HAVE_RESULT | Есть скрипт запроса результатов.
HAVE_PREPAY | Есть вариант обработчика для работы во время оформления заказа.
PS_LID | Сайт платежной системы.
PS_CURRENCY | Валюта платежной системы.
PS_NAME | Название платежной системы.
PS_ACTIVE | Активность платежной системы.
PS_SORT | Индекс сортировки платежной системы.
PS_DESCRIPTION | Описание платежной системы.
PT_LID | Сайт типа плательщика.
PT_NAME | Название типа плательщика.
PT_SORT | Индекс сортировки типа плательщика.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


Update

CSalePaySystemAction::Update

int
CSalePaySystemAction::Update(
  int ID,
  array arFields
);

Функция обновляет параметры обработчика с кодом ID платежной системы в соответствии с массивом arFields.

Параметры функции

Параметр | Описание
ID | Код обработчика платежной системы.
arFields Ассоциативный массив новых параметров платежной системы, ключами в котором являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • PAY_SYSTEM_ID - код платежной системы;
  • PERSON_TYPE_ID - код типа плательщика;
  • NAME - название платежной системы;
  • ACTION_FILE - скрипт платежной системы;
  • RESULT_FILE - скрипт получения результатов;
  • NEW_WINDOW - флаг (Y/N) открывать ли скрипт платежной системы в новом окне
  • PARAMS - параметры вызова обработчика
  • HAVE_PAYMENT - есть вариант обработчика для работы после оформления заказа
  • HAVE_ACTION - есть вариант обработчика для мгновенного списания денег
  • HAVE_RESULT - есть скрипт запроса результатов
  • HAVE_PREPAY - есть вариант обработчика для работы во время оформления заказа.

Возвращаемые значения

Возвращается код обновленной записи или false - в случае ошибки.


Класс CSalePersonType

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из типов плательщика в соответствии со своими параметрами.
GetByID | Функция возвращает параметры типа плательщика с кодом ID.
Update | Функцияобновляет параметры типа плательщика с кодом ID.
Delete | Функция удаляет тип плательщика с кодом ID.
Add | Функция добавляет новый тип плательщика с параметрами из массива arFields.


Add

CSalePersonType::Add

Int
CSalePersonType::Add(
  array arFields
);

Функция добавляет новый тип плательщика с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового типа плательщиков, ключами в котором являются названия параметров, а значениями - соответствующие значения.
Допустимые ключи:
  • LID - код сайта, к которому привязан тип плательщика;
  • NAME - название типа плательщика;
  • SORT - индекс сортировки.

Возвращаемые значения

Возвращается код добавленного типа плательщика или false - в случае ошибки.


Delete

CSalePersonType::Delete

bool
CSalePersonType::Delete(
  int ID
);

Функция удаляет тип плательщика с кодом ID. Так же удаляются все связанные данные. Если есть заказы, привязанные к этому типу плательщика, то тип плательщика не может быть удален.

Параметры функции

Параметр | Описание
ID | Код типа плательщика.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSalePersonType::GetByID

array
CSalePersonType::GetByID(
  int ID
);

Функция возвращает параметры типа плательщика с кодом ID

Параметры функции

Параметр | Описание
ID | Код типа плательщика.

Возвращаемые значения

Возвращается ассоциативный массив параметров типа плательщика с ключами:

Ключ | Описание
ID | Код типа плательщика.
LID | Код сайта.
NAME | Название типа плательщика.
SORT | Индекс сортировки.

Пример использования

<?
if ($arPersType = CSalePersonType::GetByID($PERSON_TYPE_ID))
{
   echo "<pre>";
   print_r($arPersType);
   echo "</pre>";
}
?>


GetList

CSalePersonType::GetList

CDBResult
CSalePersonType::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из типов плательщика в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле типов плательщика, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи типов плательщика. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле типов плательщика.

Пример фильтра:
array("LID" => "en")
Этот фильтр означает "выбрать все записи, в которых значение в поле LID (код сайта) равно en".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи типов плательщика. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле типов плательщика. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Этот фильтр означает "выбрать все записи, в которых значение в поле LID (сайт системы) не равно en".

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров типов плательщиков с ключами:

Ключ | Описание
ID | Код типа плательщика.
LID | Код сайта.
NAME | Название типа плательщика.
SORT | Индекс сортировки.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем переключатели для выбора типа плательщика для текущего сайта
$db_ptype = CSalePersonType::GetList(($by="SORT"), ($order="ASC"), Array("LID"=>SITE_ID));
$bFirst = True;
while ($ptype = $db_ptype->Fetch())
{
   ?><input type="radio" name="PERSON_TYPE" value="<?echo $ptype["ID"] ?>"<?if ($bFirst) echo " checked";?>><?echo $ptype["NAME"] ?><br><?
   $bFirst = false;
}
?>


Update

CSalePersonType::Update

int
CSalePersonType::Update(
  int ID,
  array arFields
);

Функцияобновляет параметры типа плательщика с кодом ID

Параметры функции

Параметр | Описание
ID | Код типа плательщика.
arFields Ассоциативный массив новых параметров типа плательщиков, ключами в котором являются названия параметров, а значениями - соответствующие значения.

Допустимые ключи:
  • LID - код сайта, к которому привязан тип плательщика;
  • NAME - название типа плательщика;
  • SORT - индекс сортировки.

Возвращаемые значения

Возвращается код обновленного типа плательщика или false - в случае ошибки.


Класс CSaleRecurring

Методы класса

Метод | Описание
Update | Метод изменяет параметры записи на продление подписки в соответствии с параметрами из массива arFields.
Add | Метод добавляет новую запись на продление подписки в соответствии с параметрами из массива arFields.
Delete | Метод удаляет запись на продление подписки с кодом ID.
CheckRecurring | Метод удаляет ищет подписки, которые пора продлить, и пытается осуществить продление.
NextPayment | Метод осуществляет продление подписки с кодом ID.
CancelRecurring | Метод осуществляет отмену продления подписки с кодом ID.
GetList | Функция возвращает результат выборки записей информации и продлении подписки в соответствии со своими параметрами.
GetByID | Метод возвращает параметры информации о продлении с кодом ID.


Add

CSaleRecurring::Add

int
CSaleRecurring::Add(
 array arFields
);

Метод добавляет новую запись на продление подписки в соответствии с параметрами из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой записи продления подписки с ключами:
  • USER_ID - код пользователя;
  • MODULE - модуль, товар которого продлевается;
  • PRODUCT_ID - код продлеваемого товара;
  • PRODUCT_NAME - название продлеваемого товара;
  • PRODUCT_URL - ссылка на продлеваемый товар;
  • RECUR_SCHEME_TYPE - тип периода оплаты;
  • RECUR_SCHEME_LENGTH - длина периода оплаты;
  • WITHOUT_ORDER - флаг "Без оформления заказа";
  • ORDER_ID - код базового заказа для продления;
  • CANCELED - флаг отмены продления;
  • DESCRIPTION - описание;
  • CALLBACK_FUNC - функция обратного вызова для обновления параметров продления;
  • REMAINING_ATTEMPTS - количество оставшихся попыток осуществления продления;
  • SUCCESS_PAYMENT - успешное осуществление продления;
  • CANCELED_REASON - причина отмены;
  • DATE_CANCELED - дата отмены;
  • PRIOR_DATE - дата последнего продления;
  • NEXT_DATE - дата очередного продления.

Возвращаемые значения

Метод возвращает код добавленной записи или false в случае ошибки.


CancelRecurring

CSaleRecurring::CancelRecurring

bool
CSaleRecurring::CancelRecurring(
 int ID
 string val[,
 string description = ""]
);

Метод осуществляет отмену продления подписки с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи с информацией о продлении.
val | "Y", если подписка отменяется, и "N", если подписка восстанавливается.
description | Причина отмены подписки.

Возвращаемые значения

Метод возвращает код отменяемой записи или false в случае ошибки.


CheckRecurring

CSaleRecurring::CheckRecurring

void
CSaleRecurring::CheckRecurring();

Метод удаляет ищет подписки, которые пора продлить, и пытается осуществить продление. За раз осуществляется продление не более трех подписок. Этот метод можно вызывать из агентов или cron'а для автоматического продления подписки.

Параметры функции

Без параметров.

Возвращаемые значения

Метод не возвращает значений.


Delete

CSaleRecurring::Delete

bool
CSaleRecurring::Delete(
 int ID
);

Метод удаляет запись на продление подписки с кодом ID.

Параметры функции

Параметр | Описание
ID | Код удаляемой записи.

Возвращаемые значения

Метод возвращает true в случае успешного удаления или false в случае ошибки.


GetByID

CSaleRecurring::GetByID

bool
CSaleRecurring::GetByID(
 int ID
);

Метод возвращает параметры информации о продлении с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи с информацией о продлении.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров информации о продлении с ключами:

  • ID - код записи;
  • USER_ID - код пользователя;
  • MODULE - модуль, товар которого продлевается;
  • PRODUCT_ID - код продлеваемого товара;
  • PRODUCT_NAME - название продлеваемого товара;
  • PRODUCT_URL - ссылка на продлеваемый товар;
  • RECUR_SCHEME_TYPE - тип периода оплаты;
  • RECUR_SCHEME_LENGTH - длина периода оплаты;
  • WITHOUT_ORDER - флаг "Без оформления заказа";
  • ORDER_ID - код базового заказа для продления;
  • CANCELED - флаг отмены продления;
  • DESCRIPTION - описание;
  • CALLBACK_FUNC - функция обратного вызова для обновления параметров продления;
  • REMAINING_ATTEMPTS - количество оставшихся попыток осуществления продления;
  • SUCCESS_PAYMENT - успешное осуществление продления;
  • CANCELED_REASON - причина отмены;
  • DATE_CANCELED - дата отмены;
  • PRIOR_DATE - дата последнего продления;
  • NEXT_DATE - дата очередного продления;
  • TIMESTAMP_X - дата последнего изменения записи.

Замечание

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


GetList

CSaleRecurring::GetList

CDBResult
CSaleRecurring::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей информации и продлении подписки в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле информации о продлении подписки, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи информации о продлении подписки. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле информации о продлении подписки.

Пример фильтра:
array("USER_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_ID (код пользователя) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи информации о продлении подписки. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле информации о продлении подписки. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров информации и продлении подписки.

  • ID - код записи;
  • USER_ID - код пользователя;
  • MODULE - модуль, товар которого продлевается;
  • PRODUCT_ID - код продлеваемого товара;
  • PRODUCT_NAME - название продлеваемого товара;
  • PRODUCT_URL - ссылка на продлеваемый товар;
  • RECUR_SCHEME_TYPE - тип периода оплаты;
  • RECUR_SCHEME_LENGTH - длина периода оплаты;
  • WITHOUT_ORDER - флаг "Без оформления заказа";
  • ORDER_ID - код базового заказа для продления;
  • CANCELED - флаг отмены продления;
  • DESCRIPTION - описание;
  • CALLBACK_FUNC - функция обратного вызова для обновления параметров продления;
  • REMAINING_ATTEMPTS - количество оставшихся попыток осуществления продления;
  • SUCCESS_PAYMENT - успешное осуществление продления;
  • CANCELED_REASON - причина отмены;
  • DATE_CANCELED - дата отмены;
  • PRIOR_DATE - дата последнего продления;
  • NEXT_DATE - дата очередного продления;
  • TIMESTAMP_X - дата последнего изменения записи;
  • USER_LOGIN - логин пользователя;
  • USER_ACTIVE - флаг активности пользователя;
  • USER_NAME - имя пользователя;
  • USER_LAST_NAME - фамилия пользователя;
  • USER_EMAIL - E-Mail пользователя.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


NextPayment

CSaleRecurring::NextPayment

bool
CSaleRecurring::NextPayment(
 int ID
);

Метод осуществляет продление подписки с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи с информацией о продлении.

Возвращаемые значения

Метод возвращает true в случае успешного продления или false в случае ошибки.


Update

CSaleRecurring::Update

int
CSaleRecurring::Update(
 int ID,
  array arFields

);

Метод изменяет параметры записи на продление подписки в соответствии с параметрами из массива arFields.

Параметры функции

Параметр | Описание
ID | Код изменяемой записи на продление подписки.
arFields Ассоциативный массив новых параметров новой записи продления подписки с ключами:
  • USER_ID - код пользователя;
  • MODULE - модуль, товар которого продлевается;
  • PRODUCT_ID - код продлеваемого товара;
  • PRODUCT_NAME - название продлеваемого товара;
  • PRODUCT_URL - ссылка на продлеваемый товар;
  • RECUR_SCHEME_TYPE - тип периода оплаты;
  • RECUR_SCHEME_LENGTH - длина периода оплаты;
  • WITHOUT_ORDER - флаг "Без оформления заказа";
  • ORDER_ID - код базового заказа для продления;
  • CANCELED - флаг отмены продления;
  • DESCRIPTION - описание;
  • CALLBACK_FUNC - функция обратного вызова для обновления параметров продления;
  • REMAINING_ATTEMPTS - количество оставшихся попыток осуществления продления;
  • SUCCESS_PAYMENT - успешное осуществление продления;
  • CANCELED_REASON - причина отмены;
  • DATE_CANCELED - дата отмены;
  • PRIOR_DATE - дата последнего продления;
  • NEXT_DATE - дата очередного продления.

Возвращаемые значения

Метод возвращает код измененной записи или False в случае ошибки.


Класс CSaleStatus

Методы класса

Метод | Описание
Add | Функция добавляет новый статус заказа с параметрами из массива arFields.
Update | Функция изменяет параметры статуса заказа с кодом ID.
Delete | Функция удаляет статус заказа с кодом ID. Если в базе есть заказы, находящиеся в этом статусе, то этот статус удалить нельзя.
GetList | Функция возвращает результат выборки записей из статусов в соответствии со своими параметрами.
GetByID | Функция возвращает параметры статуса с кодом ID, включая языкозависимые параметры для языка strLang.


Add

CSaleStatus::Add

string
CSaleStatus::Add(
  array arFields
);

Функция добавляет новый статус заказа с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового статуса. Ключами в массиве являются названия параметров статуса, а значениями - соответствующие значения.
Допустимые ключи:
  • ID - код статуса (обязательный);
  • SORT - индекс сортировки;
  • LANG - массив ассоциативных массивов языкозависимых параметров статуса с ключами:
    • LID - язык;
    • NAME - название статуса на этом языке;
    • DESCRIPTION - описание статуса;
  • PERMS - массив ассоциативных массивов прав на доступ к изменению заказа в данном статусе с ключами:
    • GROUP_ID - группа пользователей;
    • PERM_TYPE - тип доступа (S - разрешен перевод заказа в данный статус, M - разрешено изменение заказа в данном статусе).

Возвращаемые значения

Возвращается код добавленного статуса или false в случае ошибки.


Delete

CSaleStatus::Delete

bool
CSaleStatus::Delete(
  string ID
);

Функция удаляет статус заказа с кодом ID. Если в базе есть заказы, находящиеся в этом статусе, то этот статус удалить нельзя.

Параметры функции

Параметр | Описание
ID | Код статуса заказа.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleStatus::GetByID

array
CSaleStatus::GetByID(
  string ID,
  string strLang = LANGUAGE_ID
);

Функция возвращает параметры статуса с кодом ID, включая языкозависимые параметры для языка strLang

Параметры функции

Параметр | Описание
ID | Код статуса заказа.
strLang | Язык, для которого возвращаются языкозависимые параметры. По умолчанию используется текущий язык.

Возвращаемые значения

Возвращается ассоциативный массив параметров статуса с ключами:

Ключ | Описание
ID | Код статуса заказа.
SORT | Индекс сортировки.
LID | Язык.
NAME | Название статуса.
DESCRIPTION | Описание статуса.

Пример использования

<?
if ($arStatus = CSaleStatus::GetByID($STATUS_ID))
{
   echo "<pre>";
   print_r($arStatus);
   echo "</pre>";
}
?>


GetList

CSaleStatus::GetList

CDBResult
CSaleStatus::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей из статусов в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле статусов, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи статусов. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле типов плательщика.

Пример фильтра:
array("LID" => "en")
Этот фильтр означает "выбрать все записи, в которых значение в поле LID (код сайта) равно en".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи статусов. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле статусов. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Этот фильтр означает "выбрать все записи, в которых значение в поле LID (сайт системы) не равно en".

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров статусов с ключами:

Ключ | Описание
ID | Код статуса заказа.
SORT | Индекс сортировки.
LID | Язык.
NAME | Название статуса.
DESCRIPTION | Описание статуса.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


Update

CSaleStatus::Update

string
CSaleStatus::Update(
  string ID,
  array arFields
);

Функция изменяет параметры статуса заказа с кодом ID

Параметры функции

Параметр | Описание
ID | Код статуса.
arFields Ассоциативный массив новых параметров статуса. Ключами в массиве являются названия параметров статуса, а значениями - соответствующие значения.
Допустимые ключи:
  • ID - код статуса (обязательный);
  • SORT - индекс сортировки;
  • LANG - массив ассоциативных массивов языкозависимых параметров статуса с ключами:
    • LID - язык;
    • NAME - название статуса на этом языке;
    • DESCRIPTION - описание статуса;
  • PERMS - массив ассоциативных массивов прав на доступ к изменению заказа в данном статусе с ключами:
    • GROUP_ID - группа пользователей;
    • PERM_TYPE - тип доступа (S - разрешен перевод заказа в данный статус, M - разрешено изменение заказа в данном статусе).

Возвращаемые значения

Возвращается код добавленного статуса или false в случае ошибки.


Класс CSaleTax

Методы класса

Метод | Описание
Update | Функция обновляет параметры налога с кодом ID.
Delete | Функция удаляет налог с кодом ID.
GetByID | Функция возвращает параметры налога с кодом ID.
GetList | Функция возвращает набор налогов, удовлетворяющих фильтру arFilter.
GetExemptList | Функция возвращает набор записей из таблицы освобождений от уплаты налогов, удовлетворяющих фильтру arFilter.
AddExempt | Функция добавляет новую запись в таблицу освобождения от налогов.
DeleteExempt | Функция удаляет записи, удовлетворяющие фильтру arFilter, из таблицы освобождений от уплаты налогов.
Add | Функция добавляет новый налог с параметрами из массива arFields.


Add

CSaleTax::Add

int
CSaleTax::Add(
  array arFields
);

Функция добавляет новый налог с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового налога, ключами в котором являются названия параметров, а значениями - соответствующие значения.

Допустимые параметры:
  • LID - сайт;
  • NAME - название налога;
  • DESCRIPTION - описание;
  • CODE - мнемонический код.

Возвращаемые значения

Возвращается код добавленного налога или false в случае ошибки.


AddExempt

CSaleTax::AddExempt

bool
CSaleTax::AddExempt(
  array arFields
);

Функция добавляет новую запись в таблицу освобождения от налогов.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой записи с ключами:
  • GROUP_ID - код группы пользователей, которая освобождается от уплаты налога;
  • TAX_ID - код налога, от уплаты которого освобождается группа пользователей.

Возвращаемые значения

Возвращается true в случае успешного добавления и false - в противном случае.


Delete

CSaleTax::Delete

bool
CSaleTax::Delete(
  int ID
);

Функция удаляет налог с кодом ID. Также удаляются ставки этого налога и освобождения от уплаты налога, относящиеся к этому налогу.

Параметры функции

Параметр | Описание
ID | Код налога.

Возвращаемые значения

Возвращается true в случае успешного добавления и false - в противном случае.


DeleteExempt

CSaleTax::DeleteExempt

bool
CSaleTax::DeleteExempt(
  array arFields
);

Функция удаляет записи, удовлетворяющие фильтру arFilter, из таблицы освобождений от уплаты налогов.

Параметры функции

Параметр Описание
arFields Ассоциативный массив условий для удаления записей. Ключами в массиве могут быть:
  • GROUP_ID - код группы пользователей, члены которой освобождены от уплаты налога;
  • TAX_ID - код налога, от уплаты которого освобождается группа пользователей.
В массиве должен присутствовать хотя бы один ключ.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае.


GetByID

CSaleTax::GetByID

array
CSaleTax::GetByID(
  int ID
);

Функция возвращает параметры налога с кодом ID

Параметры функции

Параметр | Описание
ID | Код налога.

Возвращаемые значения

Возвращается ассоциативный массив параметров налога с ключами:

Ключ | Описание
ID | Код налога.
LID | Сайт.
NAME | Название налога.
CODE | Мнемонический код налога.
DESCRIPTION | Описание налога.
TIMESTAMP_X | Дата последнего изменения записи.

Пример использования

<?
// Выведем параметры налога с кодом $TAX_ID
if ($arTax = CSaleTax::GetByID($TAX_ID))
{
   echo "<pre>";
   print_r($arTax);
   echo "</pre>";
}
?>


GetExemptList

CSaleTax::GetExemptList

CDBResult
CSaleTax::GetExemptList(
  array arFilter = Array()
);

Функция возвращает набор записей из таблицы освобождений от уплаты налогов, удовлетворяющих фильтру arFilter

Параметры функции

Параметр Описание
arFilter Ассоциативный массив для фильтрации записей. Ключами являются названия фильтруемых параметров, а значениями - условия на значения.

Допустимые ключи:
  • GROUP_ID - код группы пользователей, которая освобождается от уплаты налога;
  • TAX_ID - код налога, от уплаты которого освобождается группа пользователей.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров налогов с ключами:

Ключ | Описание
GROUP_ID | Код группы пользователей, которая освобождается от уплаты налога.
TAX_ID | Код налога, от уплаты которого освобождается группа пользователей.

Пример использования

<?
// Заполним массив налогов, от уплаты которых освобожден текущий пользователь
$arTaxExempt = array();
if ($USER->IsAuthorized())
{
   $arUserGroups = $USER->GetUserGroupArray();
   for ($ig = 0; $ig < count($arUserGroups); $ig++)
   {
      $db_tax_ex_tmp = CSaleTax::GetExemptList(Array("GROUP_ID"=>$arUserGroups[$ig]));
      while ($ar_tax_ex_tmp = $db_tax_ex_tmp->Fetch())
      {
         if (!in_array(IntVal($ar_tax_ex_tmp["TAX_ID"]), $arTaxExempt))
         {
            $arTaxExempt[] = IntVal($ar_tax_ex_tmp["TAX_ID"]);
         }
      }
   }
}
?>


GetList

CSaleTax::GetList

CDBResult
CSaleTax::GetList(
  array arOrder = Array("NAME"=>"ASC"),
  array arFilter = Array()
);

Функция возвращает набор налогов, удовлетворяющих фильтру arFilter. Результирующий набор упорядочен в соответствии с массивом arOrder.

Параметры функции

Параметр Описание
arOrder Ассоциативный массив условий сортировки. Каждая пара ключ-значение массива применяется последовательно. Ключами являются названия параметров, по значениям которых осуществляется сортировка, а значениями - направления сортировки.

Допустимые ключи:
  • NAME - название налога;
  • ID - код налога;
  • LID - сайт;
  • CODE - мнемонический код налога;
  • TIMESTAMP_X - дата последнего изменения записи.
arFilter Ассоциативный массив для фильтрации налогов. Ключами являются названия фильтруемых параметров, а значениями - условия на значения.

Допустимые ключи:
  • ID - код налога;
  • LID - сайт;
  • CODE - мнемонический код налога.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров налогов с ключами:

Ключ | Описание
ID | Код налога.
LID | Сайт.
NAME | Название налога.
CODE | Мнемонический код налога.
DESCRIPTION | Описание налога.
TIMESTAMP_X | Дата последнего изменения записи.


Update

CSaleTax::Update

int
CSaleTax::Update(
  int ID,
  array arFields
);

Функция обновляет параметры налога с кодом ID

Параметры функции

Параметр | Описание
ID | Код налога.
arFields Ассоциативный массив новых параметров налога, ключами в котором являются названия параметров, а значениями - соответствующие значения.

Допустимые параметры:
  • LID - сайт;
  • NAME - название налога;
  • DESCRIPTION - описание;
  • CODE - мнемонический код.

Возвращаемые значения

Функция возвращает код измененного налога или false в случае ошибки.


Класс CSaleTaxRate

Методы класса

Метод | Описание
Update | Функция изменяет параметры ставки налога с кодом ID.
Delete | Функция удаляет ставку налога с кодом ID.
GetByID | Функция возвращает параметры ставки налога с кодом ID.
Add | Функция добавляет новую ставку налога с параметрами из массива arFields.
GetList | Функция возвращает набор ставок налога, удовлетворяющих фильтру arFilter. Набор упорядочен в соответствии с массивом arOrder.


Add

CSaleTaxRate::Add

int
CSaleTaxRate::Add(
  array arFields
);

Функция добавляет новую ставку налога с параметрами из массива arFields

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой ставки налога. Ключами являются названия параметров ставки, а значениями - соответствующие значения.
Допустимые ключи:
  • TAX_ID - код налога;
  • PERSON_TYPE_ID - тип плательщика;
  • VALUE - величина налога (в процентах);
  • CURRENCY - валюта;
  • IS_PERCENT - всегда значение "Y";
  • IS_IN_PRICE - налог уже включен в цену товара;
  • APPLY_ORDER - порядок применения;
  • ACTIVE - флаг (Y/N) активности налога;
  • TAX_LOCATION - массив для указания местоположений и групп местоположений, для которых действует эта ставка. Каждый элемент массива представляет собой ассоциативный массив с ключами:
    • LOCATION_ID - код местоположения или группы местоположений;
    • LOCATION_TYPE - "L" для местоположения и "G" для группы местоположений.

Возвращаемые значения

Возвращается код добавленной ставки налога или false в случае ошибки.


Delete

CSaleTaxRate::Delete

bool
CSaleTaxRate::Delete(
  int ID
);

Функция удаляет ставку налога с кодом ID

Параметры функции

Параметр | Описание
ID | Код ставки налога.

Возвращаемые значения

Возвращается true в случае успешного удаления и false в противном случае.


GetByID

CSaleTaxRate::GetByID

array
CSaleTaxRate::GetByID(
  int ID
);

Функция возвращает параметры ставки налога с кодом ID

Параметры функции

Параметр | Описание
ID | Код ставки налога.

Возвращаемые значения

Возвращается ассоциативный массив параметров ставки налога с ключами

Ключ | Описание
ID | Код ставки налога.
TAX_ID | Код налога.
PERSON_TYPE_ID | Тип плательщика.
VALUE | Величина налога (в процентах)
CURRENCY | Валюта.
IS_PERCENT | Y
IS_IN_PRICE | Флаг (Y/N) входит ли уже налог в цену.
APPLY_ORDER | Порядок применения.
TIMESTAMP_X | Дата последнего изменения записи.
ACTIVE | Флаг (Y/N) активности ставки.


GetList

CSaleTaxRate::GetList

CDBResult
CSaleTaxRate::GetList(
  array arOrder = Array("APPLY_ORDER"=>"ASC"),
  array arFilter = Array()
);

Функция возвращает набор ставок налога, удовлетворяющих фильтру arFilter. Набор упорядочен в соответствии с массивом arOrder.

Параметры функции

Параметр Описание
arOrder Ассоциативный массив для сортировки результирующего набора ставок налогов. Набор сортируется последовательно по каждой паре ключ-значение массива. Ключами массива являются названия параметров ставки налога, по значениям которых осуществляется сортировка. Значениями являются направления сортировки.

Допустимые ключи:
  • APPLY_ORDER - порядок применения;
  • ID - код ставки налога;
  • LID - сайт налога;
  • CODE - мнемонический код налога;
  • TIMESTAMP_X - дата последнего изменения параметров ставки;
  • ACTIVE - флаг (Y/N) активности ставки;
  • NAME - название налога;
  • PERSON_TYPE_ID - тип плательщика ставки;
  • IS_IN_PRICE - флаг (Y/N) входит ли ставка налога в цену
Допустимые значения:
  • ASC - по возрастанию;
  • DESC - по убыванию.
arFilter Ассоциативный массив условий для отбора (фильтрации) ставок налогов. Ключами являются названия фильтруемых параметров ставки налога, а значениями - условия на значения.

Допустимые ключи:
  • ID - код ставки налога;
  • LID - сайт налога;
  • CODE - мнемонический код налога;
  • TAX_ID - код налога;
  • PERSON_TYPE_ID - тип плательщика ставки налога;
  • IS_IN_PRICE - флаг (Y/N) входит ли налог в цену;
  • ACTIVE - флаг (Y/N) активности ставки налога;
  • APPLY_ORDER - порядок применения;
  • LOCATION - код местоположения, в котором действует ставка.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий ассоциативные массивы параметров ставок налогов с ключами:

Ключ | Описание
ID | Код ставки налога.
TAX_ID | Код налога.
PERSON_TYPE_ID | Тип плательщика.
VALUE | Величина налога (в процентах)
CURRENCY | Валюта.
IS_PERCENT | Y
IS_IN_PRICE | Флаг (Y/N) входит ли уже налог в цену.
APPLY_ORDER | Порядок применения.
TIMESTAMP_X | Дата последнего изменения записи.
LID | Сайт налога.
NAME | Название налога.
CODE | Мнемонический код налога.
DESCRIPTION | Описание налога.
ACTIVE | Флаг (Y/N) активности ставки.

Пример использования

<?
// Заполним массив активных ставок налогов на текущем сайте для типа плательщика
// с кодом $PERSON_TYPE и местоположением плательщика с кодом $TAX_LOCATION

$arTaxList = array();

$arTaxFilter = array(
   "LID" => SITE_ID,
   "PERSON_TYPE_ID" => $PERSON_TYPE,
   "ACTIVE" => "Y",
   "LOCATION" => $TAX_LOCATION
);

$db_tax_rate_tmp = CSaleTaxRate::GetList(array("APPLY_ORDER"=>"ASC"), $arTaxFilter);
while ($ar_tax_rate_tmp = $db_tax_rate_tmp->Fetch())
{
   $arTaxList[] = $ar_tax_rate_tmp;
}
?>


Update

CSaleTaxRate::Update

int
CSaleTaxRate::Update(
  int ID,
  array arFields
);

Функция изменяет параметры ставки налога с кодом ID

Параметры функции

Параметр | Описание
ID | Код ставки налога.
arFields Ассоциативный массив новых параметров ставки налога. Ключами являются названия параметров ставки, а значениями - соответствующие значения.

Допустимые ключи:
  • TAX_ID - код налога;
  • PERSON_TYPE_ID - тип плательщика;
  • VALUE - величина налога (в процентах);
  • CURRENCY - валюта;
  • IS_PERCENT - всегда значение "Y";
  • IS_IN_PRICE - налог уже включен в цену товара;
  • APPLY_ORDER - порядок применения;
  • ACTIVE - флаг (Y/N) активности налога;
  • TAX_LOCATION - массив для указания местоположений и групп местоположений, для которых действует эта ставка. Каждый элемент массива представляет собой ассоциативный массив с ключами:
    • LOCATION_ID - код местоположения или группы местоположений;
    • LOCATION_TYPE - "L" для местоположения и "G" для группы местоположений.

Возвращаемые значения

Возвращается код измененной ставки налога или false в случае ошибки.


Класс CSaleUserAccount

Методы класса

Метод | Описание
Delete | Метод удаляет внутренний счет пользователя.
Pay | Метод снимает указанную сумму с внутреннего счета пользователя.
Withdraw | Метод снимает указанную сумму с внутреннего счета пользователя.
UpdateAccount | Метод изменяет сумму на счете пользователя с кодом userID.
GetByID | Метод возвращает ассоциативный массив параметров счета с кодом ID.
GetByUserID | Метод возвращает ассоциативный массив параметров счета с валютой currency для пользователя с кодом userID.
GetList | Функция возвращает результат выборки записей счетов в соответствии со своими параметрами.
Add | Метод добавляет новый счет пользователя в соответствии с параметрами из массива arFields.
Update | Метод изменяет параметры счета пользователя в соответствии с параметрами из массива arFields.


Add

CSaleUserAccount::Add

int
CSaleUserAccount::Add(
 array arFields
);

Метод добавляет новый счет пользователя в соответствии с параметрами из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров нового счета. Может содержать следующие ключи:
  • USER_ID - код пользователя-владельца
  • CURRENT_BUDGET - текущая сумма на счете
  • CURRENCY - валюта
  • NOTES - текстовое описание
  • LOCKED - флаг заблокированности счета
  • DATE_LOCKED - дата блокировки счета

Возвращаемые значения

Метод возвращает код добавленного счета или false в случае ошибки.


Delete

CSaleUserAccount::Delete

bool
CSaleUserAccount::Delete(
 int ID
);

Метод удаляет внутренний счет пользователя.

Параметры функции

Параметр | Описание
ID | Код удаляемого счета.

Возвращаемые значения

Метод возвращает true в случае успешного удаления и false в случае ошибки.


GetByID

CSaleUserAccount::GetByID

array
CSaleUserAccount::GetByID(
 int ID
);

Метод возвращает ассоциативный массив параметров счета с кодом ID.

Параметры функции

Параметр | Описание
ID | Код счета.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров счета с ключами:

  • ID - код счета;
  • USER_ID - код пользователя-владельца;
  • CURRENT_BUDGET - текущая сумма на счете;
  • CURRENCY - валюта;
  • NOTES - текстовое описание;
  • LOCKED - флаг заблокированности счета;
  • TIMESTAMP_X - дата последнего изменения;
  • DATE_LOCKED - дата блокировки счета.

Примечание

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

Пример использования

<? if ($ar = CSaleUserAccount::GetByID(5))
{ echo "На счете ".SaleFormatCurrency($ar["CURRENT_BUDGET"],
                                      $ar["CURRENCY"]); } ?>


GetByUserID

CSaleUserAccount::GetByUserID

array
CSaleUserAccount::GetByUserID(
 int userID,
 string currency
);

Метод возвращает ассоциативный массив параметров счета с валютой currency для пользователя с кодом userID.

Параметры функции

Параметр | Описание
userID | Код пользователя.
currency | Валюта счета.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров счета с ключами:

  • ID - код счета;
  • USER_ID - код пользователя-владельца;
  • CURRENT_BUDGET - текущая сумма на счете;
  • CURRENCY - валюта;
  • NOTES - текстовое описание;
  • LOCKED - флаг заблокированности счета;
  • TIMESTAMP_X - дата последнего изменения;
  • DATE_LOCKED - дата блокировки счета.

Примечание

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

Пример использования

<? if ($ar = CSaleUserAccount::GetByUserID(172, "USD"))
 { echo "На счете ".SaleFormatCurrency($ar["CURRENT_BUDGET"], $ar["CURRENCY"]); } ?>


GetList

CSaleUserAccount::GetList

CDBResult
CSaleUserAccount::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей счетов в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле счетов, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи счетов. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("USER_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_ID (код пользователя) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи счетов. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", ...)
В качестве "название_поляN" может стоять любое поле счетов. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров счетов:

  • ID - код счета;
  • USER_ID - код пользователя-владельца;
  • CURRENT_BUDGET - текущая сумма на счете;
  • CURRENCY - валюта;
  • NOTES - текстовое описание;
  • LOCKED - флаг заблокированности счета;
  • TIMESTAMP_X - дата последнего изменения;
  • DATE_LOCKED - дата блокировки счета Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выберем все счета (в разных валютах) пользователя с кодом 21
$dbAccountCurrency = CSaleUserAccount::GetList(
        array(),
        array("USER_ID" => "21"),
        false,
        false,
        array("CURRENT_BUDGET", "CURRENCY")
    );
while ($arAccountCurrency = $dbAccountCurrency->Fetch())
{
    echo "На счете ".$arAccountCurrency["CURRENCY"].": ";
    echo SaleFormatCurrency($arAccountCurrency["CURRENT_BUDGET"],
                            $arAccountCurrency["CURRENCY"])."<br>";
}

// Выберем, сумму счетов покупателей (сколько должен магазин покупателям)
$dbAccountCurrency = CSaleUserAccount::GetList(
        array("CURRENCY" => "ASC"),
        array(),
        array("CURRENCY", "SUM" => "CURRENT_BUDGET"),
        false,
        array("CURRENCY", "SUM" => "CURRENT_BUDGET")
    );
while ($arAccountCurrency = $dbAccountCurrency->Fetch())
{
    echo "В валюте ".$arAccountCurrency["CURRENCY"].": ";
    echo SaleFormatCurrency($arAccountCurrency["CURRENT_BUDGET"],
                            $arAccountCurrency["CURRENCY"])."<br>";
}
?>


Pay

CSaleUserAccount::Pay

bool
CSaleUserAccount::Pay(
 int userID,
 double paySum,
 string payCurrency[,
 int orderID = 0[,
 bool useCC = True]]
);

Метод снимает указанную сумму с внутреннего счета пользователя. Если на внутреннем счете не достаточно средств, то делается попытка снять дополнительные средства с пластиковой карточки пользователя.

Параметры функции

Параметр | Описание
userID | Код пользователя.
paySum | Снимаемая сумма.
payCurrency | Валюта снимаемой суммы.
orderID | Код заказа, если снятие денег относится к заказу.
useCC | Если true, то система пробует снять деньги с пластиковой карты пользователя при недостаточности средств на внутреннем счете. Если false, то пластиковая карта пользователя не задействуется.

Возвращаемые значения

Метод возвращает true в случае успешного снятия денег с внутреннего счета пользователя и false в случае невозможности снять указанную сумму.

Примечание

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

Пример использования

<?
// Снимем с рублевого счета текущего пользователя 3 рубля в счет оплаты заказа номер 21
$bSuccessPayment = CSaleUserAccount::Pay(
        $USER->GetID(),
        3,
        "RUR",
        21,
        False
    );
if ($bSuccessPayment)
    echo "Сумма для оплаты счета успешно снята";
?>


Update

CSaleUserAccount::Update

int
CSaleUserAccount::Update(
 int ID,
 array arFields
);

Метод изменяет параметры счета пользователя в соответствии с параметрами из массива arFields.

Параметры функции

Параметр | Описание
ID | Код изменяемого счета.
arFields Ассоциативный массив новых параметров счета. Может содержать следующие ключи:
  • USER_ID - код пользователя-владельца;
  • CURRENT_BUDGET - текущая сумма на счете;
  • CURRENCY - валюта;
  • NOTES - текстовое описание;
  • LOCKED - флаг заблокированности счета;
  • DATE_LOCKED - дата блокировки счета.

Возвращаемые значения

Метод возвращает код измененного счета или false в случае ошибки.


UpdateAccount

CSaleUserAccount::UpdateAccount

int
CSaleUserAccount::UpdateAccount(
 int userID,
 double sum,
 string currency[,
 string description = ""[,
 int orderID = 0[,
 string notes = ""]]]
);

Метод изменяет сумму на счете пользователя с кодом userID.

Параметры функции

Параметр | Описание
userID | Код пользователя.
sum | Величина изменения суммы на счете. Для увеличения суммы на счете величина должна быть со знаком "+" или без знака, а для уменьшения - со знаком "-".
currency | Валюта суммы.
description | Описание причины изменения суммы.
orderID | Код заказа, если изменение суммы относится к заказу.
notes | Произвольное текстовое описание.

Возвращаемые значения

Метод возвращает код пользовательского счета или false в случае ошибки.

Замечание

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

Пример использования

<?
// Напишем функцию обратного вызова, которая будет вызываться при изменении
// флага "Доставка разрешена" заказа и добавлять (или снимать) 100 USD на счет

function MyDeliveryOrderCallback($productID, $userID, $bPaid, $orderID)
{
    global $DB;

    // Обработаем входные параметры
    $productID = IntVal($productID);    // Код заказанного товара
    $userID = IntVal($userID);  // Код пользователя-покупателя
    $bPaid = ($bPaid ? True : False);   // Устанавливается или снимается флаг доставки
    $orderID = IntVal($orderID);    // Код заказа

    if ($userID <= 0)
        return False;

    if ($orderID <= 0)
        return False;

    // Внесем (снимем) деньги на счет
    if (!CSaleUserAccount::UpdateAccount(
            $userID,
            ($bPaid ? 100 : -100),
            "USD",
            "MANUAL",
            $orderID
        ))
        return False;

    return True;
}
?>


Withdraw

CSaleUserAccount::Withdraw

double
CSaleUserAccount::Withdraw(
 int userID,
 double paySum,
 string payCurrency[,
 int orderID = 0]
);

Метод снимает указанную сумму с внутреннего счета пользователя. Если на внутреннем счете не достаточно средств, то снимается максимально доступная сумма (т.е. все доступные средства).

Параметры функции

Параметр | Описание
userID | Код пользователя.
paySum | Снимаемая сумма.
payCurrency | Валюта снимаемой суммы.
orderID | Код заказа, если снятие денег относится к заказу.

Возвращаемые значения

Метод возвращает реально снятую со счета сумму или false в случае ошибки.

Замечание

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

Пример использования

<?
// Оплатим полностью или хотя бы частично заказ номер 21 со счета пользователя

$arOrder = CSaleOrder::GetByID(21);

$withdrawSum = CSaleUserAccount::Withdraw(
        $arOrder["USER_ID"],
        $arOrder["PRICE"],
        $arOrder["CURRENCY"],
        $arOrder["ID"]
    );

if ($withdrawSum > 0)
{
    $arFields = array(
            "SUM_PAID" => $withdrawSum,
            "USER_ID" => $arOrder["USER_ID"]
        );
    CSaleOrder::Update($arOrder["ID"], $arFields);

    if ($withdrawSum == $arOrder["PRICE"])
        CSaleOrder::PayOrder($arOrder["ID"], "Y", False, False);
}
?>


Класс CSaleUserCards

Методы класса

Метод | Описание
Delete | Метод удаляет информацию о пластиковой карте пользователя.
GetByID | Метод возвращает параметры пластиковой карты с кодом ID.
Add | Метод сохраняет информацию о новой пластиковой карте пользователя.
Update | Метод изменяет информацию о новой пластиковой карте пользователя.
GetList | Функция возвращает результат выборки записей пластиковых карт в соответствии со своими параметрами.
CryptData | Метод изменяет шифрует и расшифровывает номер пластиковой карты.
CheckPassword | Метод проверяет, установлен ли пароль для шифрации номеров карт.
IdentifyCardType | Метод определяет тип пластиковой карты по ее номеру.


Add

CSaleUserCards::Add

int
CSaleUserCards::Add(
 array arFields
);

Метод сохраняет информацию о новой пластиковой карте пользователя.

Параметры

Параметр Описание
arFields Ассоциативный массив параметров пластиковой карты с ключами:
  • USER_ID - код пользователя;
  • SORT - индекс сортировки;
  • PAY_SYSTEM_ACTION_ID - код обработчика платежной системы;
  • CURRENCY - валюта, которую можно снимать с карты;
  • CARD_CODE - CVC2;
  • CARD_TYPE - тип карты;
  • CARD_NUM - номер карты;
  • CARD_EXP_MONTH - месяц окончания действия карты;
  • CARD_EXP_YEAR - год окончания действия карты;
  • DESCRIPTION - краткое описание;
  • SUM_MIN - минимальная сумма, которую можно снять с карты за раз;
  • SUM_MAX - максимальная сумма, которую можно снять с карты за раз;
  • SUM_CURRENCY - валюта минимальной и максимальной сумм;
  • LAST_STATUS - статус последнего использования карты;
  • LAST_STATUS_CODE - код статуса последнего использования карты;
  • LAST_STATUS_DESCRIPTION - описание статуса последнего использования карты;
  • LAST_STATUS_MESSAGE - сообщение платежной системы;
  • LAST_SUM - последняя снятая с карты сумма;
  • LAST_CURRENCY - валюта последней снятой с карты суммы;
  • ACTIVE - флаг активности;
  • LAST_DATE - дата последнего использования карты.

Замечание
Перед добавлением записи номер карты должен быть зашифрован методом CSaleUserCards::CryptData.

Возвращаемые значения

Метод возвращает код добавленной записи или false в случае ошибки.

Пример использования

<?
// Сохраним новую карту текущего пользователя

if (CSaleUserCards::CheckPassword())
{
    $arFields = array(
            "USER_ID" => $USER->GetID(),
            "ACTIVE" => "Y",
            "SORT" => "100",
            "PAY_SYSTEM_ACTION_ID" => 11,
            "CURRENCY" => "USD",
            "CARD_TYPE" =>
                CSaleUserCards::IdentifyCardType("4111111111111"),
            "CARD_NUM" =>
                CSaleUserCards::CryptData("4111111111111", "E"),
            "CARD_EXP_MONTH" => 11,
            "CARD_EXP_YEAR" => 2007,
            "DESCRIPTION" => false,
            "CARD_CODE" => "123",
            "SUM_MIN" => False,
            "SUM_MAX" => False,
            "SUM_CURRENCY" => False
        );

    $UserCardID = CSaleUserCards::Add($arFields);
}
?>


CheckPassword

CSaleUserCards::CheckPassword

bool
CSaleUserCards::CheckPassword();

Метод проверяет, установлен ли пароль для шифрации номеров карт.

Параметры функции

Без параметров.

Возвращаемые значения

Метод возвращает true, если пароль установлен, и false в противном случае.


CryptData

CSaleUserCards::CryptData

string
CSaleUserCards::CryptData(
 string data,
 string type
);

Метод изменяет шифрует и расшифровывает номер пластиковой карты.

Параметры функции

Параметр | Описание
data | Шифруемые (расшифровываемые) данные.
type | Для шифрования данных значение "E", для расшифровки - "D"

Замечание

Перед сохранением номера карты в базу его необходимо шифровать, а при выборке из базы - расшифровывать.

Возвращаемые значения

Метод возвращает результат шифрования (расшифровывания).


Delete

CSaleUserCards::Delete

bool
CSaleUserCards::Delete(
 int ID
);

Метод удаляет информацию о пластиковой карте пользователя.

Параметры функции

Параметр | Описание
ID | Код удаляемой информации о карте.

Возвращаемые значения

Метод возвращает true в случае успешного удаления и false в случае ошибки.


GetByID

CSaleUserCards::GetByID

array
CSaleUserCards::GetByID(
 int ID
);

Метод возвращает параметры пластиковой карты с кодом ID

Параметры функции

Параметр | Описание
ID | Код пластиковой карты.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров пластиковой карты с ключами:

  • ID - код пластиковой карты;
  • USER_ID - код пользователя;
  • SORT - индекс сортировки;
  • PAY_SYSTEM_ACTION_ID - код обработчика платежной системы;
  • CURRENCY - валюта, которую можно снимать с карты;
  • CARD_CODE - CVC2;
  • CARD_TYPE - тип карты;
  • CARD_NUM - номер карты;
  • CARD_EXP_MONTH - месяц окончания действия карты;
  • CARD_EXP_YEAR - год окончания действия карты;
  • DESCRIPTION - краткое описание;
  • SUM_MIN - минимальная сумма, которую можно снять с карты за раз;
  • SUM_MAX - максимальная сумма, которую можно снять с карты за раз;
  • SUM_CURRENCY - валюта минимальной и максимальной сумм;
  • LAST_STATUS - статус последнего использования карты;
  • LAST_STATUS_CODE - код статуса последнего использования карты;
  • LAST_STATUS_DESCRIPTION - описание статуса последнего использования карты;
  • LAST_STATUS_MESSAGE - сообщение платежной системы;
  • LAST_SUM - последняя снятая с карты сумма;
  • LAST_CURRENCY - валюта последней снятой с карты суммы;
  • ACTIVE - флаг активности;
  • TIMESTAMP_X - дата изменения;
  • LAST_DATE - дата последнего использования карты.


GetList

CSaleUserCards::GetList

CDBResult
CSaleUserCards::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле карт, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи карт. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле карт.

Пример фильтра:
array("USER_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_ID (код пользователя) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи карт. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле карт. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров карт.

  • ID - код пластиковой карты;
  • USER_ID - код пользователя;
  • SORT - индекс сортировки;
  • PAY_SYSTEM_ACTION_ID - код обработчика платежной системы;
  • CURRENCY - валюта, которую можно снимать с карты;
  • CARD_CODE - CVC2;
  • CARD_TYPE - тип карты;
  • CARD_NUM - номер карты;
  • CARD_EXP_MONTH - месяц окончания действия карты;
  • CARD_EXP_YEAR - год окончания действия карты;
  • DESCRIPTION - краткое описание;
  • SUM_MIN - минимальная сумма, которую можно снять с карты за раз;
  • SUM_MAX - максимальная сумма, которую можно снять с карты за раз;
  • SUM_CURRENCY - валюта минимальной и максимальной сумм;
  • LAST_STATUS - статус последнего использования карты;
  • LAST_STATUS_CODE - код статуса последнего использования карты;
  • LAST_STATUS_DESCRIPTION - описание статуса последнего использования карты;
  • LAST_STATUS_MESSAGE - сообщение платежной системы;
  • LAST_SUM - последняя снятая с карты сумма;
  • LAST_CURRENCY - валюта последней снятой с карты суммы;
  • ACTIVE - флаг активности;
  • TIMESTAMP_X - дата изменения;
  • LAST_DATE - дата последнего использования карты.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


IdentifyCardType

CSaleUserCards::IdentifyCardType

string
CSaleUserCards::IdentifyCardType(
 string ccNum
);

Метод определяет тип пластиковой карты по ее номеру.

Параметры функции

Параметр | Описание
ccNum | Номер карты.

Возвращаемые значения

Метод возвращает тип карты.

Пример использования

<?
// Сохраним новую карту текущего пользователя

if (CSaleUserCards::CheckPassword())
{
    $arFields = array(
            "USER_ID" => $USER->GetID(),
            "ACTIVE" => "Y",
            "SORT" => "100",
            "PAY_SYSTEM_ACTION_ID" => 11,
            "CURRENCY" => "USD",
            "CARD_TYPE" => CSaleUserCards::IdentifyCardType("4111111111111"),
            "CARD_NUM" => CSaleUserCards::CryptData("4111111111111", "E"),
            "CARD_EXP_MONTH" => 11,
            "CARD_EXP_YEAR" => 2007,
            "DESCRIPTION" => False,
            "CARD_CODE" => "123",
            "SUM_MIN" => False,
            "SUM_MAX" => False,
            "SUM_CURRENCY" => False
        );

    $UserCardID = CSaleUserCards::Add($arFields);
}
?>


Update

CSaleUserCards::Update

int
CSaleUserCards::Update(
 int ID,
 array arFields
);

Метод изменяет информацию о новой пластиковой карте пользователя.

Параметры функции

Параметр | Описание
ID | Код изменяемой записи.
arFields Ассоциативный массив новых параметров пластиковой карты с ключами:
  • USER_ID - код пользователя;
  • SORT - индекс сортировки;
  • PAY_SYSTEM_ACTION_ID - код обработчика платежной системы;
  • CURRENCY - валюта, которую можно снимать с карты;
  • CARD_CODE - CVC2;
  • CARD_TYPE - тип карты;
  • CARD_NUM - номер карты;
  • CARD_EXP_MONTH - месяц окончания действия карты;
  • CARD_EXP_YEAR - год окончания действия карты;
  • DESCRIPTION - краткое описание;
  • SUM_MIN - минимальная сумма, которую можно снять с карты за раз;
  • SUM_MAX - максимальная сумма, которую можно снять с карты за раз;
  • SUM_CURRENCY - валюта минимальной и максимальной сумм;
  • LAST_STATUS - статус последнего использования карты;
  • LAST_STATUS_CODE - код статуса последнего использования карты;
  • LAST_STATUS_DESCRIPTION - описание статуса последнего использования карты;
  • LAST_STATUS_MESSAGE - сообщение платежной системы;
  • LAST_SUM - последняя снятая с карты сумма;
  • LAST_CURRENCY - валюта последней снятой с карты суммы;
  • ACTIVE - флаг активности;
  • LAST_DATE - дата последнего использования карты.

Замечание
Если меняется номер карты, то перед добавлением записи этот номер должен быть зашифрован методом CSaleUserCards::CryptData.

Возвращаемые значения

Метод возвращает код обновленной записи или false в случае ошибки.


Класс CSaleUserTransact

Методы класса

Метод | Описание
Delete | Метод удаляет транзакцию с кодом ID.
GetByID | Метод возвращает параметры транзакции с кодом ID.
Add | Метод добавляет новую транзакцию с параметрами из массива arFields.
Update | Метод изменяет параметры транзакции в соответствии с параметрами из массива arFields.
GetList | Функция возвращает результат выборки записей транзакций в соответствии со своими параметрами.


Add

CSaleUserTransact::Add

int
CSaleUserTransact::Add(
 array arFields
);

Метод добавляет новую транзакцию с параметрами из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой транзакции с ключами:
  • USER_ID - код пользователя;
  • AMOUNT - сумма;
  • CURRENCY - валюта суммы;
  • DEBIT - "Y", если занесение денег на счет, и "N", если списание денег со счета;
  • DESCRIPTION - описание;
  • ORDER_ID - код заказа, если транзакция относится к заказу;
  • EMPLOYEE_ID - код пользователя, осуществивщего транзакцию;
  • TRANSACT_DATE - дата транзакции.

Возвращаемые значения

Метод возвращает код вставленной транзакции или false в случае ошибки.


Delete

CSaleUserTransact::Delete

bool
CSaleUserTransact::Delete(
 int ID
);

Метод удаляет транзакцию с кодом ID.

Параметры функции

-
Параметр | Описание
ID | Номер транзакции.

Возвращаемые значения

Метод возвращает true в случае успешного удаления и false - в противном случае.


GetByID

CSaleUserTransact::GetByID

array
CSaleUserTransact::GetByID(
 int ID
);

Метод возвращает параметры транзакции с кодом ID.

Параметры функции

Параметр | Описание
ID | Номер транзакции.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров транзакции с ключами:

  • ID - код транзакции;
  • USER_ID - код пользователя;
  • AMOUNT - сумма;
  • CURRENCY - валюта суммы;
  • DEBIT - "Y", если занесение денег на счет, и "N", если списание денег со счета;
  • DESCRIPTION - описание;
  • ORDER_ID - код заказа, если транзакция относится к заказу;
  • EMPLOYEE_ID - код пользователя, осуществившего транзакцию;
  • TIMESTAMP_X - дата последнего изменения записи;
  • TRANSACT_DATE - дата транзакции.


GetList

CSaleUserTransact::GetList

CDBResult
CSaleUserTransact::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей транзакций в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле транзакций, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи транзакций. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле транзакций.

Пример фильтра:
array("USER_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле USER_ID (код пользователя) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи транзакций. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле транзакций. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов параметров транзакций:

  • ID - код транзакции;
  • USER_ID - код пользователя;
  • AMOUNT - сумма;
  • CURRENCY - валюта суммы;
  • DEBIT - "Y", если занесение денег на счет, и "N", если списание денег со счета;
  • DESCRIPTION - описание;
  • ORDER_ID - код заказа, если транзакция относится к заказу;
  • EMPLOYEE_ID - код пользователя, осуществившего транзакцию;
  • TIMESTAMP_X - дата последнего изменения записи;
  • TRANSACT_DATE - дата транзакции;
  • USER_LOGIN - логин пользователя;
  • USER_ACTIVE - флаг активности пользователя;
  • USER_NAME - имя пользователя;
  • USER_LAST_NAME - фамилия пользователя;
  • USER_EMAIL - E-Mail пользователя.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


Update

CSaleUserTransact::Update

int
CSaleUserTransact::Update(
 int ID,
 array arFields
);

Метод изменяет параметры транзакции в соответствии с параметрами из массива arFields.

Параметры функции

Параметр | Описание
ID | Код изменяемой транзакции.
arFields Ассоциативный массив новых параметров новой транзакции с ключами:
  • USER_ID - код пользователя;
  • AMOUNT - сумма;
  • CURRENCY - валюта суммы;
  • DEBIT - "Y", если занесение денег на счет, и "N", если списание денег со счета;
  • DESCRIPTION - описание;
  • ORDER_ID - код заказа, если транзакция относится к заказу;
  • EMPLOYEE_ID - код пользователя, осуществившего транзакцию;
  • TRANSACT_DATE - дата транзакции.

Возвращаемые значения

Метод возвращает код измененной транзакции или false в случае ошибки.


SaleFormatCurrency

Функции

  • SaleFormatCurrency


SaleFormatCurrency

string
SaleFormatCurrency(
 float fSum,
 string strCurrency
);

Функция форматирует сумму fSum в соответствии с правилами форматирования для валюты strCurrency на текущем языке.

Параметры функции

Параметр | Описание
fSum | Денежная сумма, которую нужно сформатировать.
strCurrency | Валюта, по правилам которой нужно производить форматирование.

Возвращаемые значения

Возвращает отформатированную строку.

Пример использования

<?
echo SaleFormatCurrency(11800.95, "USD");
?>


Информация для разработчиков

Модуль информационных блоков - мощный и в то же время гибкий механизм для хранения и выборки информации различными способами. API модуля состоит из нескольких высокоуровневых функций для выборки данных в публичном разделе сайта и набора классов с низкоуровневыми методами для более специализированной работы.

Перед использованием модуля необходимо проверить установлен ли он и подключить его при помощи конструкции:

<?
if(CModule::IncludeModule("iblock"))
{
   //здесь можно использовать функции и классы модуля
}
?>

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

Вся работа с датами через API (вставка, выборка, фильтры и т.п.) производится в формате текущего сайта или, если в административной части, в формате текущего языка.

Публичные функции и возвращаемые значения

Метод | Описание
GetIBlockList | Возвращает список информационных блоков по фильтру.
GetIBlock | Возвращает информационный блок по заданному коду.
GetIBlockElementListEx | Возвращает список элементов по фильтру.
GetIBlockElementList | Возвращает список элементов из определённого информационного блока.
GetIBlockElement | Возвращает элемент по заданному коду.
GetIBlockSectionList | Возвращает список папок из определённого информационного блока.
GetIBlockSection | Возвращает раздел по заданному коду.

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

Классы модуля информационных блоков

Метод | Описание
CIBlockType | Типы информационных блоков.
CIBlock | Информационные блоки.
CIBlockProperty | Свойства элементов.
CIBlockPropertyEnum | Варианты значений для свойств типа "список".
CIBlockSection | Разделы информационных блоков.
CIBlockElement | Элементы и их значения свойств.
CIBlockResult | Вспомогательный класс для работы с объектами результатов выборок.
_CIBElement | Вспомогательный класс для работы с объектом выборки элемента.


Структура таблиц модуля информационных блоков

Поля таблиц

Типы информационных блоков

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID типа информационных блоков. Уникален. | String(50) | Да |
SECTIONS | Флаг (Y/N). Разделяются ли элементы блока этого типа по разделам. Обязателен. По умолчанию - "Y". | Char(1) | Да | Y
EDIT_FILE_BEFORE | Полный путь к файлу-обработчику массива полей элемента перед сохранением на странице редактирования элемента. | String(255) | Нет |
EDIT_FILE_AFTER | Полный путь к файлу-обработчику вывода интерфейса редактирования элемента. | String(255) | Нет |
IN_RSS | Блоки данного типа экспортировать в RSS (Y|N). | Char(1) | Да | N
SORT | Порядок сортировки типа | Int | Да | 500

Языкозависимые параметры типов информационных блоков

Поле | Описание | Тип | Обяз. | Умолч.
IBLOCK_TYPE_ID | ID типа блока. | String(50) | Да |
LID | Код языка параметров. | Char(2) | Да |
NAME | Название типа информационных блоков. | String(100) | Да |
SECTION_NAME | Название разделов информационных блоков (если элементы блока этого типа классифицируются по разделам). | String(100) | Нет |
ELEMENT_NAME | Название элементов информационных блоков. | String(100) | Да |

Информационные блоки

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID информационного блока. | Int | Да
CODE | Мнемонический идентификатор. | String(50) | Нет
EXTERNAL_ID или XML_ID
Внешний код. String(255) Нет
IBLOCK_TYPE_ID | Код типа информационных блоков. | String(50) | Да
TIMESTAMP_X | Дата последнего изменения параметров блока. | Datetime | Да | Текущее.
NAME | Название. | String(255) | Да
ACTIVE | Флаг активности (Y|N) | Char(1) | Да | Y
SORT | Индекс сортировки. | Int | Да | 500
LIST_PAGE_URL | Шаблон URL-а к странице для публичного просмотра списка элементов информационного блока. | String(255) | Нет
SECTION_PAGE_URL | Шаблон URL-а к странице для просмотра раздела. | String(255) | Нет
DETAIL_PAGE_URL | Шаблон URL-а странице для детального просмотра элемента. | String(255) | Нет
PICTURE | Код картинки в таблице файлов. | Int | Нет
DESCRIPTION | Описание. | Text | Нет
DESCRIPTION_TYPE | Тип описания (text/html) | Char(4) | Да | text
RSS_ACTIVE | Разрешен экспорт в RSSдинамически (Y|N). | Char(1) | Да | Y
RSS_TTL | Время жизни RSS и интервал между генерациями файлов RSS (при включенном RSS_FILE_ACTIVE или RSS_YANDEX_ACTIVE) (часов). | Int | Да | 24
RSS_FILE_ACTIVE | Прегенерировать выгрузку в файл. | Char(1) | Да | N
RSS_FILE_LIMIT | Количество экспортируемых в RSS файл элементов (при включенном RSS_FILE_ACTIVE) | Int | Нет
RSS_FILE_DAYS | За сколько последних дней экспортировать в RSS файл. (при включенном RSS_FILE_ACTIVE). -1 без ограничения по дням. | Int | Нет
RSS_YANDEX_ACTIVE | Экспортировать в RSS файл в формате для yandex | Char(1) | Да | N
INDEX_ELEMENT | Индексировать для поиска элементы информационного блока. | Char(1) | Да | Y
INDEX_SECTION | Индексировать для поиска разделы информационного блока. | Char(1) | Да | N
WORKFLOW
Инфоблок участвует в документообороте (Y|N).
Char(1)
Да
Y
SECTION_CHOOSER | Флаг выбора интерфейса отображения привязки элемента к разделам (D|L|P). | Char(1) | Нет
VERSION | Флаг хранения значений свойств элементов инфоблока (1 - в общей таблице | 2 - в отдельной). | Int | Да | 1
EDIT_FILE_BEFORE | Полный путь к файлу-обработчику массива полей элемента перед сохранением на странице редактирования элемента. | String(255) | Нет
EDIT_FILE_AFTER
Полный путь к файлу-обработчику вывода интерфейса редактирования элемента.
String(255) Нет

Группы (разделы) информационных блоков

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID группы информационного блока. | Int | Да |
CODE | Мнемонический идентификатор. | String(255) | Нет |
EXTERNAL_ID или XML_ID | Внешний код. | String(255) | Нет |
IBLOCK_ID | ID информационного блока. | Int | Да |
IBLOCK_SECTION_ID | ID группы родителя, если не задан то группа корневая. | Int | Нет |
TIMESTAMP_X | Дата последнего изменения параметров группы. | Datetime | Да | Текущая.
SORT | Порядок сортировки (среди групп внутри одной группы-родителя). | Int | Да | 500
NAME | Наименование группы. | String(255) | Да |
ACTIVE | Флаг активности (Y|N) | Char(1) | Да | Y
GLOBAL_ACTIVE | Флаг активности, учитывая активность вышележащих (родительских) групп (Y|N). Вычисляется автоматически (не может быть изменен вручную). | Char(1) | - | -
PICTURE | Код картинки в таблице файлов. | Int | Нет |
DESCRIPTION | Описание группы. | Text | Нет |
DESCRIPTION_TYPE | Тип описания группы (text/html). | Char(4) | Да | text
LEFT_MARGIN | Левая граница группы. Вычисляется автоматически (не устанавливается вручную). | Int | - | -
RIGHT_MARGIN | Правая граница группы. Вычисляется автоматически (не устанавливается вручную). | Int | - | -
DEPTH_LEVEL | Уровень вложенности группы. Вычисляется автоматически (не устанавливается вручную). | Int | - | -
SEARCHABLE_CONTENT | Содержимое для поиска при фильтрации групп. Вычисляется автоматически. Складывается из полей NAME и DESCRIPTION (без html тэгов, если DESCRIPTION_TYPE установлен в html). | Text | - | -
SECTION_PAGE_URL | Шаблон URL-а к странице для детального просмотра раздела. Определяется из параметров информационного блока. Изменяется автоматически. | String(255) | - | -
MODIFIED_BY | Код пользователя, в последний раз изменившего элемент. | Int | Да | Текущий пользователь.
DATE_CREATE | Дата создания элемента. | Datetime | Да | Текущее
CREATED_BY | Код пользователя, создавшего элемент. | Int | Да | Текущий пользователь.
DETAIL_PICTURE | Код картинки в таблице файлов для детального просмотра. | Int | Нет | -

Элементы

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID элемента. | Int | Да |
CODE | Мнемонический идентификатор. | String(255) | Нет |
EXTERNAL_ID или XML_ID | Внешний идентификатор. | String(255) | Нет |
NAME | Название элемента. | String(255) | Да |
IBLOCK_ID | ID информационного блока. | Int | Да |
IBLOCK_SECTION_ID | ID группы. Если не задан, то элемент не привязан к группе. Если элемент привязан к нескольким группам, то в этом поле ID одной из групп. | Int | Нет |
ACTIVE | Флаг активности (Y|N). | Char(1) | Да | Y
DATE_ACTIVE_FROM | Дата начала действия элемента. | Datetime | Нет |
DATE_ACTIVE_TO | Дата окончания действия элемента. | Datetime | Нет |
SORT | Порядок сортировки элементов между собой (в пределах одной группы-родителя). | Int | Да | 500
PREVIEW_PICTURE | Код картинки в таблице файлов для предварительного просмотра (анонса). | Int | Нет |
PREVIEW_TEXT | Предварительное описание (анонс). | Text | Нет |
PREVIEW_TEXT_TYPE | Тип предварительного описания (text/html). | Char(4) | Да | text
DETAIL_PICTURE | Код картинки в таблице файлов для детального просмотра. | Int | Нет |
DETAIL_TEXT | Детальное описание | Text | Нет |
DETAIL_TEXT_TYPE | Тип детального описания (text/html). | Char(4) | Да | text
SEARCHABLE_CONTENT | Содержимое для поиска при фильтрации групп. Вычисляется автоматически. Складывается из полей NAME и DESCRIPTION (без html тэгов, если DESCRIPTION_TYPE установлен в html). | Text | - | -
DATE_CREATE | Дата создания элемента. | Datetime | Да | Текущее.
CREATED_BY | Код пользователя, создавшего элемент. | Int | Да | Текущий пользователь.
CREATED_USER_NAME | Имя пользователя, создавшего элемент. (доступен только для чтения). |  |  |
TIMESTAMP_X | Время последнего изменения полей элемента. | Datetime | Да | Текущее.
MODIFIED_BY | Код пользователя, в последний раз изменившего элемент. | Int | Да | Текущий пользователь.
USER_NAME | Имя пользователя, в последний раз изменившего элемент. (доступен только для чтения). |  |  |
LANG_DIR | Путь к папке сайта. Определяется из параметров информационного блока. Изменяется автоматически. (доступен только для чтения). | String(255) | - | -
LIST_PAGE_URL | Шаблон URL-а к странице для публичного просмотра списка элементов информационного блока. Определяется из параметров информационного блока. Изменяется автоматически. (доступен только для чтения). | String(255) | - | -
DETAIL_PAGE_URL | Шаблон URL-а к странице для детального просмотра элемента. Определяется из параметров информационного блока. Изменяется автоматически. (доступен только для чтения). | String(255) | - | -
SHOW_COUNTER | Количество показов элемента (изменяется при вызове функции CIBlockElement::CounterInc). | Int | Нет |
SHOW_COUNTER_START | Дата первого показа элемента (изменяется при вызове функции CIBlockElement::CounterInc). | Datetime | Нет |
WF_COMMENTS | Комментарий администратора документооборота. | Text | Нет |
WF_STATUS_ID | Код статуса элемента в документообороте. | Int | Да | 1
LOCK_STATUS | Текущее состояние блокированности на редактирование элемента. Может принимать значения: red - заблокирован, green - доступен для редактирования, yellow - заблокирован текущим пользователем. | String | - |
TAGS | Теги элемента. Используются для построения облака тегов модулем Поиска. | String(255) | Нет |

Свойства

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID свойства. | Int | Да |
CODE | Мнемонический код свойства. | String(50) | Нет |
XML_ID | Внешний код свойства. | String (100) | Нет |
IBLOCK_ID | Код информационного блока. | Int | Да |
NAME | Название свойства. | String(100) | Да |
ACTIVE | Активность свойства (Y|N). | Char(1) | Да | Y
SORT | Индекс сортировки. | Int | Да | 500
PROPERTY_TYPE | Тип свойства. Возможные значения: S - строка, N - число, F - файл, L - список, E - привязка к элементам, G - привязка к группам. | Char(1) | Да | S
MULTIPLE | Множественность (Y|N). | Char(1) | Да | N
TIMESTAMP_X | Время последнего изменения свойства. | Datetime | Да | Текущее.
DEFAULT_VALUE | Значение свойства по умолчанию (кроме свойства типа список L). | String(255) | Нет |
ROW_COUNT | Количество строк в ячейке ввода значения свойства. | Int | Да | 1
COL_COUNT | Количество столбцов в ячейке ввода значения свойства. | Int | Да | 30
LIST_TYPE | Тип для свойства список (L). Может быть "L" - выпадающий список или "C" - флажки. | Char(1) | Да | L
MULTIPLE_CNT | Количество строк в выпадающем списке для свойств типа "список". | Int | Нет |
FILE_TYPE | Список допустимых расширений для свойств файл "F"(через запятую). | Char(200) | Нет |
SEARCHABLE | Индексировать значения данного свойства. | Char(1) | Да | N
FILTRABLE | Выводить поля для фильтрации по данному свойству на странице списка элементов в административном разделе. | Char(1) | Да | N
LINK_IBLOCK_ID | Для свойств типа привязки к элементам и группам задает код информационного блока с элементами/группами которого и будут связано значение. | Int | Нет |
WITH_DESCRIPTION | Признак наличия у значения свойства дополнительного поля описания. Только для типов S - строка, N - число и F - файл (Y|N). | Char(1) | Нет |
VERSION | Флаг хранения значений свойств элементов инфоблока (1 - в общей таблице | 2 - в отдельной). (доступен только для чтения). | Int | Да | 1
USER_TYPE | Идентификатор пользовательского типа свойства. | String(255) | Нет |

Варианты значений свойств типа "список"

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID значения варианта свойства. | int | Да |
PROPERTY_ID | Код свойства. | int | Да |
VALUE | Значение варианта свойства. | string(255) | Да |
DEF | Значение по умолчанию (Y|N). | char(1) | Нет | N
SORT | Порядок сортировки варианта | int | Нет | 500
EXTERNAL_ID или XML_ID | Внешний код варианта свойства. | string(200) | Да | Автоматический уникальный идентификатор

Значения cвойств

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID значения свойства. | Int | Да |
IBLOCK_PROPERTY_ID | Код свойства. | Int | Да |
IBLOCK_ELEMENT_ID | Код элемента. | Int | Да |
VALUE | Значение свойства. | Text | Да |
VALUE_TYPE | Тип значения свойства (text/html). | Char(4) | Да | text
DESCRIPTION | Дополнительное поле описания | String(255) | Нет |


Пользовательские формы редактирования элементов

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

Рассмотрим в качестве примера форму редактирования статьи информационного издания. Для нашего издания необходимы поля:
  • заголовок статьи;
  • текст анонса;
  • картинка для анонса;
  • текст статьи;
  • большая картинка;
  • время выхода статьи;
  • автор;
  • статус документооборота для утверждения редактором;
  • список разделов для привязки.
Процесс создания и настройки информационных блоков подробно описан в документации. Поэтому лишь рассмотрим отсутствующие и лишние, по сравнению со стандартной формой редактирования, элементы:
  • множество лишних полей (сортировка, дата окончания показа, ...);
  • необходимо изменить порядок полей редактирования;
  • было бы удобнее, если при вводе только большой картинки автоматически из нее создавалась картинка для анонса;
  • необходимо чтобы поле со статьей тоже было обязательным (вместе с названием);
  • при публикации новости автоматически записывать время в поле с датой новости.

Для начала возьмем оригинальный код страницы /bitrix/modules/iblock/admin/iblock_element_edit.php, а именно, ту ее часть, которая настраивается:

<form method="POST"
      action="iblock_element_edit.php?type=<?
          echo $type?>&lang=<?
          echo LANG?>&IBLOCK_ID=<?
          echo $IBLOCK_ID?>&<?
          echo GetFilterParams("filter_");?>#tb" ENCTYPE="multipart/form-data"
      name="form_element">
<?echo GetFilterHiddens("filter_");?>
<input type="hidden" name="Update" value="Y">
<input type="hidden" name="from" value="<?echo htmlspecialchars($from)?>">
<input type="hidden" name="WF" value="<?echo htmlspecialchars($WF)?>">
<input type="hidden" name="return_url" value="<?echo $return_url?>">
<input type="hidden" name="ID" value="<?echo $ID?>">
<input type="hidden"
       name="IBLOCK_SECTION_ID" value="<?echo IntVal($IBLOCK_SECTION_ID)?>">
<table border="0" cellspacing="1" cellpadding="3"
       class="edittable" width="100%">
    <?if ($WF=="Y" || $view=="Y"):?>
    <tr>
        <td valign="top"
            align="right"><font
            class="tablefieldtext"><?=GetMessage("IBLOCK_WF_STATUS")?></font></td>
        <td valign="top"
            nowrap><font class="tablebodytext">
        <?echo SelectBox("WF_STATUS_ID",
                         CWorkflowStatus::GetDropDownList("N", "desc"), "",
                         $str_WF_STATUS_ID);?></font></td>
    </tr>
    <?endif;?>
    <?
    if($ID>0):
        $p = CIblockElement::GetByID($ID);
        $pr = $p->ExtractFields("prn_");

        if(CModule::IncludeModule("workflow")):
            if(strlen($pr["DATE_CREATE"])>0):
            ?>
                <tr>
                    <td valign="top" align="right"><font
                        class="tablefieldtext"><?echo
                        GetMessage("IBLOCK_CREATED")?></font></td>
                    <td valign="top"><font
                        class="tablebodytext"><?echo $pr["DATE_CREATE"]?><?
                    if (intval($pr["CREATED_BY"])>0):
                    ?>&nbsp;&nbsp;&nbsp;[<a
                        class="tablebodylink"
                        href="user_edit.php?lang=<?
                            =LANG?>&ID=<?=$pr["CREATED_BY"]?>"><?
                        echo $pr["CREATED_BY"]?></a>]&nbsp;<?
                            =htmlspecialcharsex($pr["CREATED_USER_NAME"])?><?
                    endif;
                    ?></font></td>
                </tr>
            <?endif;?>
            <tr>
                <td valign="top"
                    align="right"><font
                    class="tablefieldtext"><?echo
                    GetMessage("IBLOCK_LAST_UPDATE")?></font></td>
                <td valign="top"><font
                    class="tablebodytext"><?echo $str_TIMESTAMP_X?><?
                if (intval($str_MODIFIED_BY)>0):
                ?>&nbsp;&nbsp;&nbsp;[<a class="tablebodylink"
                    href="user_edit.php?lang=<?
                        =LANG?>&ID=<?=$str_MODIFIED_BY?>"><?
                    echo $str_MODIFIED_BY?></a>]&nbsp;<?=$str_USER_NAME?><?
                endif;
                ?></font></td>
            </tr>
        <?endif?>
        <?if($WF=="Y" && strlen($prn_WF_DATE_LOCK)>0):?>
        <tr>
            <td valign="top" align="right" nowrap><font
                class="tablefieldtext"><?echo
                GetMessage("IBLOCK_DATE_LOCK")?></font></td>
            <td valign="top" nowrap><font
                class="tablebodytext"><?echo $prn_WF_DATE_LOCK?><?
            if (intval($prn_WF_LOCKED_BY)>0):
            ?>&nbsp;&nbsp;&nbsp;[<a class="tablebodylink"
                href="user_edit.php?lang=<?=lang?>&id=<?
                    =$prn_WF_LOCKED_BY?>"><?
                    echo $prn_WF_LOCKED_BY?></a>]&nbsp;<?
                    =$prn_LOCKED_USER_NAME?><?
            endif;
            ?></font></td>
        </tr>
        <?endif;?>
    <?endif;?>
    <tr>
        <td valign="top" width="50%" align="right"><font
            class="tablefieldtext"><?
            echo GetMessage("IBLOCK_ACTIVE")?></font></td>
        <td valign="top" width="50%"><input
            type="checkbox" name="ACTIVE"
            value="Y"<?if($str_ACTIVE=="Y")echo " checked"?>></td>
    </tr>
    <tr>
        <td valign="top" align="right"><font
            class="tablefieldtext"><?
            echo GetMessage("IBLOCK_ACTIVE_PERIOD")?>(<?
            echo CLang::GetDateFormat("SHORT");?>)</font></td>
        <td valign="top"><font class="tablebodytext">
            <?echo CalendarPeriod("ACTIVE_FROM",
                                  $str_ACTIVE_FROM,
                                  "ACTIVE_TO",
                                  $str_ACTIVE_TO,
                                  "form_element",
                                  "N",
                                  "class=\"typeselect\"",
                                  "class=\"typeinput\"", "19")?>
        </font>
        </td>
    </tr>
    <?if($arIBTYPE["SECTIONS"]=="Y"):?>
    <tr>
        <td valign="top" align="right"><font
            class="tablefieldtext"><?
            echo GetMessage("IBLOCK_SECTION")?></font></td>
        <td valign="top" align="left">
        <?$l = CIBlockSection::GetTreeList(Array("IBLOCK_ID"=>$IBLOCK_ID));?>
        <select name="IBLOCK_SECTION[]" size="14" multiple class="typeselect">
            <option value="0"<?
                    if (is_array($str_IBLOCK_ELEMENT_SECTION) &&
                        in_array(0, $str_IBLOCK_ELEMENT_SECTION))
                        echo " selected"?>>
                    <?echo GetMessage("IBLOCK_CONTENT")?></option>
        <?
            while($l->ExtractFields("l_")):
                ?><option value="<?echo $l_ID?>"<?
                   if (is_array($str_IBLOCK_ELEMENT_SECTION) &&
                       in_array($l_ID, $str_IBLOCK_ELEMENT_SECTION))
                       echo " selected"?>>
                   <?echo str_repeat(" . ", $l_DEPTH_LEVEL)?>
                   <?echo $l_NAME?></option><?
            endwhile;
        ?>
        </select>
        </td>
    </tr>
    <?endif?>
    <tr>
        <td valign="top" align="right"><font
            class="tablefieldtext"><font
            class="required">*</font><?
            echo GetMessage("IBLOCK_NAME")?></font></td>
        <td valign="top">
            <input type="text" name="NAME" size="50"
                   maxlength="255" class="typeinput"
                   value="<?echo $str_NAME?>">
        </td>
    </tr>
    <tr>
        <td valign="top" align="right"><font
            class="tablefieldtext"><?
            echo GetMessage("IBLOCK_SORT")?></font></td>
        <td valign="top">
            <input type="text" name="SORT"
                   size="7" class="typeinput"
                   maxlength="10" value="<?echo $str_SORT?>">
        </td>
    </tr>
    <?if(COption::GetOptionString("iblock", "show_xml_id", "N")=="Y"):?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext"><?echo GetMessage("IBLOCK_EXTERNAL_CODE")?></font></td>
        <td valign="top">
            <input type="text" size="20" name="XML_ID" maxlength="255" class="typeinput" value="<?echo $str_XML_ID?>">
        </td>
    </tr>
    <?endif?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext"><?echo GetMessage("IBLOCK_CODE")?></font></td>

        <td valign="top">
            <input type="text" size="20" name="CODE" maxlength="255" class="typeinput" value="<?echo $str_CODE?>">
        </td>
    </tr>
    <?if(count($PROP)>0):?>
    <tr>
        <td valign="top" align="center" colspan="2"
            class="tablehead"><font
            class="tableheadtext"><b><?
            echo GetMessage("IBLOCK_ELEMENT_PROP_VALUE");?></b></font></td>
    </tr>
    <?
    foreach($PROP as $prop_code=>$prop_fields):
        $prop_values = $prop_fields["VALUE"];
    ?>
    <tr>
        <td valign="top" align="right"><font
            class="tablefieldtext"><?
            echo htmlspecialcharsex($prop_fields["NAME"])?>:</font></td>
        <td valign="top">
        <font class="tablebodytext"><?
             _ShowPropertyField('PROP['.$prop_fields["ID"].']',
                                $prop_fields,
                                $prop_values,
                                ((!$bVarsFromForm) &&
                                ($ID<=0)), $bVarsFromForm);?></font>
    </td>
    </tr>
    <?endforeach;?>
    <?endif?>

    <tr>
        <td valign="top" align="center" colspan="2"
            class="tablehead" nowrap><font
            class="tableheadtext"><b><?
            echo GetMessage("IBLOCK_ELEMENT_PREVIEW")?></b></font></td>
    </tr>
    <tr>
        <td valign="top" align="right"
            class="tablebody" nowrap><font
            class="tablefieldtext"><?echo GetMessage("IBLOCK_PICTURE")?></font></td>
        <td valign="top" align="left" class="tablebody"><font class="tablebodytext">
            <?echo CFile::InputFile("PREVIEW_PICTURE",
                                    20, $str_PREVIEW_PICTURE, false, 0,
                                    "IMAGE", "class=\"typefile\"", 40);?><br>
            <?echo CFile::ShowImage($str_PREVIEW_PICTURE, 200, 200, "border=0", "", true)?>
            </font>
        </td>
    </tr>

    <?if (ereg('(MSIE|Internet Explorer) ([0-9]).([0-9])+',
               $_SERVER['HTTP_USER_AGENT'],
               $version) &&
          IntVal($version[2]) >= 5 &&
          COption::GetOptionString("iblock",
                                   "use_htmledit",
                                   "Y") == "Y" &&
          CModule::IncludeModule("fileman")):?>
    <tr>
        <td valign="top" colspan="2">
            <?CFileMan::AddHTMLEditorFrame("PREVIEW_TEXT",
                                           $str_PREVIEW_TEXT,
                                           "PREVIEW_TEXT_TYPE",
                                           $str_PREVIEW_TEXT_TYPE, 300,
                    "N",
                    0,
                    "",
                    "",
                    $arIBlock["LID"]
                    );?>
        </td>
    </tr>
    <?else:?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext"><?echo GetMessage("IBLOCK_DESC_TYPE")?></font></td>
        <td valign="top">
            <font class="tablebodytext">
                <input type="radio"
                       name="PREVIEW_TEXT_TYPE"
                       value="text"<?
                 if ($str_PREVIEW_TEXT_TYPE != "html")
                     echo " checked"?>>
                 <?echo GetMessage("IBLOCK_DESC_TYPE_TEXT")?> /
                 <input type="radio" name="PREVIEW_TEXT_TYPE"
                        value="html"<?
                  if ($str_PREVIEW_TEXT_TYPE=="html")
                      echo " checked"?>> <?echo GetMessage("IBLOCK_DESC_TYPE_HTML")?>
            </font>
        </td>
    </tr>
    <tr>
        <td valign="top" align="center"colspan="2" width="100%">
            <textarea cols="110" class="typearea"
                      rows="10" name="PREVIEW_TEXT"
                      wrap="virtual"><?echo $str_PREVIEW_TEXT?></textarea>
        </td>
    </tr>
    <?endif?>
    <tr>
        <td valign="top" align="center" colspan="2"
            class="tablehead" nowrap><font
            class="tableheadtext"><b><?
            echo GetMessage("IBLOCK_ELEMENT_DETAIL")?></b></font></td>
    </tr>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext">
            <?echo GetMessage("IBLOCK_PICTURE")?></font></td>
        <td valign="top"><font class="tablebodytext">
            <?echo CFile::InputFile("DETAIL_PICTURE",
                                    20, $str_DETAIL_PICTURE, false, 0,
                                    "IMAGE", "class=\"typefile\"", 40);?><br>
            <?echo CFile::ShowImage($str_DETAIL_PICTURE, 200, 200, "border=0", "", true)?>
            </font>
        </td>
    </tr>
    <?if (ereg('(MSIE|Internet Explorer) ([0-9]).([0-9])+',
               $_SERVER['HTTP_USER_AGENT'],
               $version) && IntVal($version[2])>=5 &&
          COption::GetOptionString("iblock",
                                   "use_htmledit",
                                   "Y") == "Y" &&
          CModule::IncludeModule("fileman")):?>
    <tr>
        <td valign="top" colspan="2">
            <?CFileMan::AddHTMLEditorFrame("DETAIL_TEXT",
                                           $str_DETAIL_TEXT,
                                           "DETAIL_TEXT_TYPE",
                                           $str_DETAIL_TEXT_TYPE,
                                           440,
                     "N",
                     0,
                     "",
                     "",
                     $arIBlock["LID"]
                     );?>
        </td>
    </tr>
    <?else:?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext"><?echo GetMessage("IBLOCK_DESC_TYPE")?></font></td>
        <td valign="top">
            <font class="tablebodytext">
                <input type="radio" name="DETAIL_TEXT_TYPE"
                       value="text"
                <?if ($str_DETAIL_TEXT_TYPE!="html")
                      echo " checked"?>>
                <?echo GetMessage("IBLOCK_DESC_TYPE_TEXT")?> /
                <input type="radio" name="DETAIL_TEXT_TYPE"
                       value="html"
                <?if ($str_DETAIL_TEXT_TYPE=="html")
                      echo " checked"?>>
                <?echo GetMessage("IBLOCK_DESC_TYPE_HTML")?>
            </font>
        </td>
    </tr>
    <tr>
        <td valign="top" align="center" colspan="2">
            <textarea cols="110" rows="20"
                      class="typearea" name="DETAIL_TEXT"
                      wrap="virtual"><?echo $str_DETAIL_TEXT?></textarea>
        </td>
    </tr>
    <?endif?>
    <?if (CModule::IncludeModule("workflow")):?>
    <tr>
        <td class="tablehead" align="center"
            colspan="2"><font
            class="tableheadtext"><b><?=GetMessage("IBLOCK_COMMENTS")?></b></font></td>
    </tr>
    <tr>
        <td valign="top" align="center" colspan="2">
            <textarea name="WF_COMMENTS" class="typearea" cols="110" rows="10"><?echo $str_WF_COMMENTS?></textarea></td>
    </tr>
    <?endif?>
    <?
    if ($view!="Y" && CModule::IncludeModule("catalog") && CCatalog::GetByID($IBLOCK_ID))
    {
        include($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/catalog/admin/templates/product_edit.php");
    }
    ?>
</table>
<br>
<input <?if ($view=="Y" ||
             $prn_LOCK_STATUS=="red")
             echo "disabled";?>
       type="submit" class="button"
       name="save"
       value="<?echo (($ID > 0)?GetMessage('IBLOCK_SAVE'):GetMessage('IBLOCK_ADD'))?>">
&nbsp;
<input <?if ($view=="Y" || $prn_LOCK_STATUS=="red")
             echo "disabled";?>
       class="button"
       type="submit"
       name="apply"
       value="<?echo GetMessage('IBLOCK_APPLY')?>">
&nbsp;
<input <?if ($view=="Y" || $prn_LOCK_STATUS=="red")
             echo "disabled";?>
       type="submit"
       class="button"
       name="dontsave"
       value="<? echo GetMessage("IBLOCK_DONT_SAVE") ?>">
&nbsp;
<input type="reset" value="<?echo GetMessage('IBLOCK_RESET');?>" class="button">
</form>

Сохраним этот скрипт в файл, например, в /bitrix/php_interface/include/iblock_element_edit.php, создадим там же файл /bitrix/php_interface/include/iblock_element_edit_before_save.php - в нем будет находиться скрипт, отвечающий за обработку во время сохранения элемента. Теперь в настройках модуля информационных блоков необходимо для типа указать пути к этим файлам в поля "Файл для редактирования элемента, позволяющий модифицировать поля перед сохранением" и "Файл с формой редактирования элемента".

Это была подготовительная часть, перейдем к изменению внешнего вида формы. Удалим лишние поля и переверстаем страницу /bitrix/php_interface/include/iblock_element_edit.php под наши нужды. После всех изменений получился следующий код:

<form method="POST" action="iblock_element_edit.php?type=<?echo $type?>
 &lang=<?echo LANG?>&IBLOCK_ID=<?echo $IBLOCK_ID?>&<?
 echo GetFilterParams("filter_");?>#tb" ENCTYPE="multipart/form-data" name="form_element">
<?echo GetFilterHiddens("filter_");?>
<input type="hidden" name="Update" value="Y">
<input type="hidden" name="from" value="<?echo htmlspecialchars($from)?>">
<input type="hidden" name="WF" value="<?echo htmlspecialchars($WF)?>">
<input type="hidden" name="return_url" value="<?echo $return_url?>">
<input type="hidden" name="ID" value="<?echo $ID?>">
<input type="hidden" name="IBLOCK_SECTION_ID" value="<?echo IntVal($IBLOCK_SECTION_ID)?>">
<table border="0" cellspacing="1" cellpadding="3" class="edittable" width="100%">
    <?
    $prop_code = "AUTHOR";
    $prop_fields = $PROP[$prop_code];
    $prop_values = $prop_fields["VALUE"];
    ?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext"><?echo htmlspecialcharsex($prop_fields["NAME"])?>:</font></td>
        <td valign="top">
        <font class="tablebodytext"><?
              _ShowPropertyField('PROP['.$prop_fields["ID"].']',
                                 $prop_fields, $prop_values, ((!$bVarsFromForm) && ($ID<=0)), $bVarsFromForm);?></font>
    </td>
    </tr>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext">Дата (<?echo CLang::GetDateFormat("SHORT");?>)</font></td>
        <td valign="top"><font class="tablebodytext">
            <?echo CalendarDate("ACTIVE_FROM", $str_ACTIVE_FROM, "form_element", "20", "class=\"typeinput\"")?>
        </font>
        </td>
    </tr>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext"><font class="required">*</font>Заголовок</font></td>
        <td valign="top">
            <textarea name="NAME" cols="50" rows="5" class="typearea"><?echo $str_NAME?></textarea>
        </td>
    </tr>
    <tr>
        <td valign="top" align="center" colspan="2" class="tablehead" nowrap><font class="tableheadtext"><b>Анонс</b></font></td>
    </tr>
    <?if (ereg('(MSIE|Internet Explorer) ([0-9]).([0-9])+',
               $_SERVER['HTTP_USER_AGENT'],
               $version) &&
          IntVal($version[2])>=5 &&
          COption::GetOptionString("iblock", "use_htmledit", "Y")=="Y" &&
          CModule::IncludeModule("fileman")):?>
    <tr>
        <td valign="top" colspan="2">
            <?CFileMan::AddHTMLEditorFrame("PREVIEW_TEXT",
                                           $str_PREVIEW_TEXT,
                                           "PREVIEW_TEXT_TYPE",
                                           $str_PREVIEW_TEXT_TYPE, 300
                       "N",
                    0,
                    "",
                    "",
                    arIBlock["LID"]
                    );?>
        </td>
    </tr>
    <?else:?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext">Тип анонса:</font></td>
        <td valign="top">
            <font class="tablebodytext">
                <input type="radio"
                       name="PREVIEW_TEXT_TYPE"
                       value="text"<?
                       if ($str_PREVIEW_TEXT_TYPE!="html")
                           echo " checked"?>> Текст /
                       <input type="radio"
                              name="PREVIEW_TEXT_TYPE"
                              value="html"<?
                              if ($str_PREVIEW_TEXT_TYPE=="html")
                                  echo " checked"?>> HTML
            </font>
        </td>
    </tr>
    <tr>
        <td valign="top" align="center"colspan="2" width="100%">
            <textarea cols="110" class="typearea" rows="10" name="PREVIEW_TEXT" wrap="virtual"><?echo $str_PREVIEW_TEXT?></textarea>
        </td>
    </tr>
    <?endif?>
    <tr>
        <td valign="top" align="center" colspan="2" class="tablehead" nowrap><font class="tableheadtext"><b>Статья</b></font></td>
    </tr>
    <?if (ereg('(MSIE|Internet Explorer) ([0-9]).([0-9])+',
               $_SERVER['HTTP_USER_AGENT'],
               $version) && IntVal($version[2])>=5 &&
          COption::GetOptionString("iblock",
                                   "use_htmledit",
                                   "Y") == "Y" &&
          CModule::IncludeModule("fileman")):?>
    <tr>
        <td valign="top" colspan="2">
            <?CFileMan::AddHTMLEditorFrame("DETAIL_TEXT",
                $str_DETAIL_TEXT,
                "DETAIL_TEXT_TYPE",
                $str_DETAIL_TEXT_TYPE,
                440,
                "N",
                0,
                "",
                "",
                $arIBlock["LID"]
                )>
        </td>
    </tr>
    <?else:?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext">Тип текста статьи:</font></td>
        <td valign="top">
            <font class="tablebodytext">
                <input type="radio" name="DETAIL_TEXT_TYPE"
                       value="text"<?
                       if ($str_DETAIL_TEXT_TYPE!="html")
                           echo " checked"?>> Текст /
                       <input type="radio" name="DETAIL_TEXT_TYPE"
                              value="html"<?if($str_DETAIL_TEXT_TYPE=="html")echo " checked"?>> HTML
            </font>
        </td>
    </tr>
    <tr>
        <td valign="top" align="center" colspan="2">
            <textarea cols="110" rows="20" class="typearea" name="DETAIL_TEXT" wrap="virtual"><?echo $str_DETAIL_TEXT?></textarea>
        </td>
    </tr>
    <?endif?>
<tr>
        <td valign="top" align="right"><font class="tablefieldtext">Большая картинка</font></td>
        <td valign="top"><font class="tablebodytext">
            <?echo CFile::InputFile("DETAIL_PICTURE", 20, $str_DETAIL_PICTURE, false, 0, "IMAGE", "class=\"typefile\"", 40);?><br>
            <?echo CFile::ShowImage($str_DETAIL_PICTURE, 200, 200, "border=0", "", true)?>
            </font>
        </td>
    </tr>
    <tr>
        <td valign="top" align="right" class="tablebody" nowrap><font class="tablefieldtext">Картинка в списке:</font></td>
        <td valign="top" align="left" class="tablebody"><font class="tablebodytext">
            <input type="checkbox" name="MAKE_PREVIEW_PICTURE" value="Y" onClick="document.getElementById('PREVIEW_PICTURE').disabled=this.checked;">Создать из большой картинки<br>
            <?echo CFile::InputFile("PREVIEW_PICTURE", 20, $str_PREVIEW_PICTURE, false, 0, "IMAGE", "class=\"typefile\"", 40);?><br>
            <?echo CFile::ShowImage($str_PREVIEW_PICTURE, 200, 200, "border=0", "", true)?>
            </font>
        </td>
    </tr>
    <?if($arIBTYPE["SECTIONS"]=="Y"):?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext">Разделы:</font></td>
        <td valign="top" align="left">
        <?$l = CIBlockSection::GetTreeList(Array("IBLOCK_ID"=>$IBLOCK_ID));?>
        <select name="IBLOCK_SECTION[]" size="14" multiple class="typeselect">
            <option value="0"<?if(is_array($str_IBLOCK_ELEMENT_SECTION) && in_array(0, $str_IBLOCK_ELEMENT_SECTION))echo " selected"?>>Не привязан к разделу</option>
        <?
            while($l->ExtractFields("l_")):
                ?><option value="<?echo $l_ID?>"
                  <?if (is_array($str_IBLOCK_ELEMENT_SECTION) &&
                        in_array($l_ID, $str_IBLOCK_ELEMENT_SECTION))
                        echo " selected"?>>
                  <?echo str_repeat(" . ", $l_DEPTH_LEVEL)?><?echo $l_NAME?></option><?
            endwhile;
        ?>
        </select>
        </td>
    </tr>
    <?endif?>
    <tr>
        <td valign="top" align="center" colspan="2" class="tablehead"><font class="tableheadtext"><b>Активность и документооборот</b></font></td>
    </tr>
    <?if ($WF=="Y" || $view=="Y"):?>
    <tr>
        <td valign="top" align="right"><font class="tablefieldtext">Статус:</font></td>
        <td valign="top" nowrap><font class="tablebodytext">
        <?echo SelectBox("WF_STATUS_ID", CWorkflowStatus::GetDropDownList("N", "desc"), "", $str_WF_STATUS_ID);?></font></td>
    </tr>
    <?endif;?>
    <?
    if($ID>0):
        $p = CIblockElement::GetByID($ID);
        $pr = $p->ExtractFields("prn_");

        if(CModule::IncludeModule("workflow")):
            if(strlen($pr["DATE_CREATE"])>0):
            ?>
                <tr>
                    <td valign="top" align="right"><font class="tablefieldtext">Создана:</font></td>
                    <td valign="top"><font class="tablebodytext"><?echo $pr["DATE_CREATE"]?><?
                    if (intval($pr["CREATED_BY"])>0):
                    ?>&nbsp;&nbsp;&nbsp;[<a class="tablebodylink" href="user_edit.php?lang=<?=lang?>&id=<?=$pr["created_by"]?>"><?echo $pr["CREATED_BY"]?></a>]&nbsp;<?=htmlspecialcharsex($pr["CREATED_USER_NAME"])?><?
                    endif;
                    ?></font></td>
                </tr>
            <?endif;?>
            <tr>
                <td valign="top" align="right"><font class="tablefieldtext">Изменена:</font></td>
                <td valign="top"><font class="tablebodytext"><?echo $str_TIMESTAMP_X?><?
                if (intval($str_MODIFIED_BY)>0):
                ?>&nbsp;&nbsp;&nbsp;[<a class="tablebodylink" href="user_edit.php?lang=<?=lang?>&id=<?=$str_modified_by?>"><?echo $str_MODIFIED_BY?></a>]&nbsp;<?=$str_USER_NAME?><?
                endif;
                ?></font></td>
            </tr>
        <?endif?>
        <?if($WF=="Y" && strlen($prn_WF_DATE_LOCK)>0):?>
        <tr>
            <td valign="top" align="right" nowrap><font class="tablefieldtext">Заблокирована:</font></td>
            <td valign="top" nowrap><font class="tablebodytext"><?echo $prn_WF_DATE_LOCK?><?
            if (intval($prn_WF_LOCKED_BY)>0):
            ?>&nbsp;&nbsp;&nbsp;[<a class="tablebodylink" href="user_edit.php?lang=<?=lang?>&id=<?=$prn_wf_locked_by?>"><?echo $prn_WF_LOCKED_BY?></a>]&nbsp;<?=$prn_LOCKED_USER_NAME?><?
            endif;
            ?></font></td>
        </tr>
        <?endif;?>
    <?endif;?>
    <?if (CModule::IncludeModule("workflow")):?>
    <tr>
        <td valign="top" align="center" colspan="2">
            <textarea name="WF_COMMENTS" class="typearea" cols="110" rows="10"><?echo $str_WF_COMMENTS?></textarea></td>
    </tr>
    <?endif?>
</table>
<br>
<input <?if ($view=="Y" || $prn_LOCK_STATUS=="red") echo "disabled";?> type="submit" class="button" name="save" value="<?echo (($ID > 0)?"Изменить":"Добавить")?>">
&nbsp;
<input <?if ($view=="Y" || $prn_LOCK_STATUS=="red") echo "disabled";?> class="button" type="submit" name="apply" value="Применить">
&nbsp;
<input <?if ($view=="Y" || $prn_LOCK_STATUS=="red") echo "disabled";?> type="submit" class="button" name="dontsave" value="Выйти без сохранения">
</form>

Внешний вид готов, теперь приступим к странице-обработчику перед сохранением. Чтобы как-то повлиять на сохраняемые поля необходимо модифицировать одноименные поля в массивах $_POST и $_FILES, значения всех свойств необходимо модифицировать в массиве $PROP.

Для проверки что текст статьи введен используем следующее условие:

if (strlen($_POST['DETAIL_TEXT'])<=0)
    $error = new _CIBlockError(2, 'DESCRIPTION_REQUIRED', 'Введите текст статьи');

Конструктор объекта _CIBlockError принимает три параметра: степень серьезности ошибки, произвольный идентификатор и текст ошибки. Если на странице редактирования определить переменную $error со значением этого объекта, то сохранения внесённых изменений не произойдет. Для того чтобы значения, пришедшие из формы, не потерялись, после инициализации переменной $error также инициализируйте переменную $bVarsFromForm=true. Переменная $bVarsFromForm как раз указывает, что значения в полях необходимо показывать те, которые пришли из формы.

Для автоматической установки даты новости в момент публикации переопределим поле $_POST["ACTIVE_FROM"]:

if ($_POST["WF_STATUS_ID"]==1 && strlen($_POST["ACTIVE_FROM"])<=0)
{
    $_POST["ACTIVE_FROM"] = date("d.m.Y H:i:s");
}

В данном случае мы фиксированно считаем что формат даты для языка в котором мы работаем DD.MM.YYYY HH:MI:SS, если у вас формат другой, то необходимо обработать его.

Для автоматического создания маленькой картинки на основе большой воспользуемся функцией BXIBlockAfterSave. Если ее определить до сохранения элемента, то она автоматически будет вызвана после успешного сохранения элемента. Определим ее в начале файла /bitrix/php_interface/include/iblock_element_edit_before_save.php:

<?
function BXIBlockAfterSave($arFields)
{
    if($_POST['MAKE_PREVIEW_PICTURE']=='Y')
    {
        $dbr = CIBlockElement::GetByID($arFields['ID']);
        if(($ar = $dbr->Fetch()) && $ar['DETAIL_PICTURE']>0)
        {
            $img_path = $_SERVER['DOCUMENT_ROOT'].CFile::GetPath($ar['DETAIL_PICTURE']);
            $width = 200;
            $height = 200;
            list($width_orig, $height_orig) = getimagesize($img_path);
            if($width && ($width_orig < $height_orig))
               $width = ($height / $height_orig) * $width_orig;
            else
               $height = ($width / $width_orig) * $height_orig;
            $image_p = imagecreatetruecolor($width, $height);
            $image = imagecreatefromjpeg($img_path);
            imagecopyresized($image_p, $image, 0, 0, 0, 0,
                             $width, $height, $width_orig, $height_orig);
            $new_img_path = tempnam("/tmp", "FOO").".jpg";
            imagejpeg($image_p, $new_img_path);
            $be = new CIBlockElement();
            $be->Update($arFields['ID'],
                        Array('PREVIEW_PICTURE' => CFile::MakeFileArray($new_img_path)),
                        false);
            @unlink($new_img_path);
        }
    }
}
?>

В вышеприведенном скрипте если установлен специальный флажок, то на основе большой картинки будет создана маленькая и эта картинка будет подставлена в поле для маленькой картинки. Пример работает только с картинками в формате JPG.

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

function BXIBlockAfterSave($arFields)
{
    if($arFields['WF_STATUS_ID']==1)
    {
        BXClearCache(true, "/ru/main_page/");
        BXClearCache(true, "/ru/detail/".$arFields['ID']."/");
    }
}

Вот и все. Теперь у нас есть форма полностью настроенная для наших нужд. Иногда бывает необходимо выполнить изменения совсем другого характера, например, форма ввода и изменения одновременно несколько картинок, в этом случае необходимо просто создать свою новую страницу и добавить ее в административное меню. В заключении приведем полный код страницы /bitrix/php_interface/include/iblock_element_edit_before_save.php:

<?
if($REQUEST_METHOD=="POST" && strlen($Update)>0 && $view!="Y" && (!$error) && empty($dontsave) && strlen($_POST['DETAIL_TEXT'])<=0)
    $error = new _CIBlockError(2, "DESCRIPTION_REQUIRED", "Введите текст статьи");
elseif($_POST["WF_STATUS_ID"] == 1 && strlen($_POST["ACTIVE_FROM"]) <= 0)
    $_POST["ACTIVE_FROM"] = date("d.m.Y H:i:s");

function BXIBlockAfterSave($arFields)
{
    if($_POST['MAKE_PREVIEW_PICTURE']=='Y')
    {
        $dbr = CIBlockElement::GetByID($arFields['ID']);
        if(($ar = $dbr->Fetch()) && $ar['DETAIL_PICTURE']>0)
        {
            $img_path = $_SERVER['DOCUMENT_ROOT'].CFile::GetPath($ar['DETAIL_PICTURE']);
            $width = 200;
            $height = 200;
            list($width_orig, $height_orig) = getimagesize($img_path);
            if($width && ($width_orig < $height_orig))
               $width = ($height / $height_orig) * $width_orig;
            else
               $height = ($width / $width_orig) * $height_orig;
            $image_p = imagecreatetruecolor($width, $height);
            $image = imagecreatefromjpeg($img_path);
            imagecopyresized($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);
            $new_img_path = tempnam("/tmp", "FOO").".jpg";
            imagejpeg($image_p, $new_img_path);
            $be = new CIBlockElement();
            $be->Update($arFields['ID'], Array('PREVIEW_PICTURE'=>CFile::MakeFileArray($new_img_path)), false);
            @unlink($new_img_path);
            die($new_img_path);
        }
    }

    if($arFields['WF_STATUS_ID']==1)
    {
        BXClearCache(true, "/ru/main_page/");
        BXClearCache(true, "/ru/detail/".$arFields['ID']."/");
    }
}
?>


Типы фильтрации

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

Типы:

  • (пустой) - для строковых полей означает поиск по маске (в маске: "%" - произвольное число любых символов, "_" - один произвольный символ), для полей с нестроковыми типами поиск "равно".
<?
// найти элементы у которых название начинается на "#"
$res = CIBlockElement::GetList(Array(), Array("NAME"=>"#%"));

// найти элементы с идентификатором 100
$res = CIBlockElement::GetList(Array(), Array("ID"=>"100"));
?>
  • "!" - для строк выражение не попадающее под маску, или не равно (для остальных типов полей).
<?
// найти элементы у которых название не начинается на "#"
$res = CIBlockElement::GetList(Array(), Array("!NAME"=>"#%"));
?>
  • "?" - с применением логики, работает только для строковых свойств.
<?
// найти элементы у которых название содержит "One" или "Two"
$res = CIBlockElement::GetList(Array(), Array("?NAME"=>"One | Two"));
?>
  • "<" - меньше;
  • "<=" - меньше либо равно;
  • ">" - больше;
  • ">=" - больше либо равно.
<?
// найти элементы у которых название начинается на "A"
$res = CIBlockElement::GetList(Array(), Array(">=NAME"=>"A", "<NAME"=>"B"));

// найти элементы с идентификатором большим 100
$res = CIBlockElement::GetList(Array(), Array(">ID"=>"100"));
?>
  • "=" - равно;
  • "!=" - не равно.
<?
// найти элементы у которых название равно "ELEMENT%1"
$res = CIBlockElement::GetList(Array(), Array("=NAME"=>"ELEMENT%1"));
?>
  • "%" - подстрока;
  • "!%" - не подстрока.
<?
// найти элементы у которых в названии есть символ процента "%"
$res = CIBlockElement::GetList(Array(), Array("%NAME"=>"%"));
?>
  • "><" - между;
  • "!><" - не между.

В качестве аргумента данные типы фильтров принимает массив вида Array("значение ОТ", "значение ДО")

<?
// найти элементы у которых название начинается между "A" и "B" или между "D" и "E"
$res = CIBlockElement::GetList(Array(), Array("><NAME"=>Array(Array("A", "B"), Array("D", "E"))));

// найти элементы, у которых дата начала активности не в периоде 2003 года
$res = CIBlockElement::GetList(Array(),
                               Array("!><DATE_ACTIVE_FROM"=>
                                     Array(date($DB->DateFormatToPHP(CLang::GetDateFormat("FULL")),
                                                mktime(0,0,0,1,1,2003)),
                                           date($DB->DateFormatToPHP(CLang::GetDateFormat("FULL")),
                                                mktime(0,0,0,1,1,2004)))));
?>


RSS

RSS - формат, предназначенный для обмена информацией (прежде всего новостями) между сайтами. Формат RSS является диалектом XML. Получить полную информацию по формату RSS 2.0 можно по адресу http://backend.userland.com/rss.

Терминология

Канал
Информационный блок в RSS формате.
Сайт-сервер
Сайт, который экспортирует (отдает) информацию в формате RSS.
Сайт-клиент
Сайт, который импортирует (принимает) информацию в формате RSS.
Кеширование
Временное хранение информации, полученной с сайта-сервера, на сайте-клиенте для ускорения повторного доступа к ней.
Узел (элемент) канала
Элемент информационного блока (например, новость или товар) в RSS формате.

Экспорт в RSS

Существует три способа экспорта содержимого информационного блока в формат RSS

Динамическая ("на лету") генерация RSS файла по запросу сайта-клиента.

Для включения этого способа необходимо на сайте-сервере поставить флаг Разрешен экспорт в RSS динамически в настройках информационного блока и установить в поле Действительно (часов) время, через которое сайт-клиент должен будет перезапрашивать данные с сайта-сервера (между перезапросами сайт-клиент будет выводить данные из кеша).

Для доступа к RSS файлу сайт-клиент должен запросить скрипт /bitrix/rss.php с сайта-сервера с параметрами ID, LANG, TYPE и LIMIT.

Параметры запроса
Параметр | Описание
ID | Код информационного блока или символьный код инфоблока.
LANG | Сайт информационного блока.
TYPE | Тип информационного блока.
LIMIT | Сколько элементов информационного блока выдавать.

Пример запроса
http://www.1c-bitrix.ru/bitrix/rss.php?ID=3&LANG=ru&TYPE=news&LIMIT=3

Прегенерация RSS файла

Для включения этого способа необходимо на сайте-сервере поставить флаг Разрешен экспорт в RSS файл в настройках информационного блока и установить поля Количество экспортируемых в RSS файл элементов (ограничивает максимальное количество экспортируемых в файл элементов, -1 для отсутствия ограничений) и За сколько последних дней экспортировать в RSS файл (ограничивает экспортируемые в файл элементы заданным количеством последних дней по началу периода активности элемента, -1 для отсутствия ограничений).

RSS будет генерироваться с периодичностью, заданной в поле Действительно (часов), и сохраняться в файл с именем типа iblock_rss_<ID блока>.xml в каталог, заданный в настройках модуля информационных блоков.

Для доступа к RSS файлу сайт-клиент должен запросить файл http://<сайт-сервер>/<путь из настроек модуля информационных блоков>/iblock_rss_<ID блока>.xml.

Примеры запроса
http://www.1c-bitrix.ru/upload/iblock_rss_3.xml

Прегенерация RSS файла в Yandex-формате.

Этот формат служит для отправки новостей службе Яндекс.Новости и отличается от предыдущих форматов наличием дополнительной ветки, содержащей полный текст элемента информационного блока. Для включения этого способа необходимо на сайте-сервере поставить флаг Разрешен экспорт в RSS файл в формате yandex в настройках информационного блока. В этом случае элементы информационного блока выбираются за последние два дня без ограничения количества.

RSS будет генерироваться с периодичностью, заданной в поле Действительно (часов), и сохраняться в файл с именем типа yandex_rss_<ID блока>.xml в каталог, заданный в настройках модуля информационных блоков.

Для доступа к RSS файлу сайт-клиент должен запросить файл http://<сайт-сервер>/<путь из настроек модуля информационных блоков>/yandex_rss_<ID блока>.xml.

Пример запроса
http://www.1c-bitrix.ru/upload/yandex_rss_3.xml

Структура элемента канала в RSS файле

По умолчанию при генерации RSS узел <item> строится следующим образом:

<item>
  <title>Поле Название элемента информационного блока</title>
  <link>Поле URL страницы детального просмотра информационного блока</link>
  <description>Поле Описание для анонса элемента информационного блока, если оно заполнено. Иначе поле Описание для детального просмотра элемента информационного блока.</description>
  <pubDate>Поле Период активности элемента информационного блока.</pubDate>
  <enclosure url="Адрес изображения, загруженого в поле Описание для анонса элемента информационного блока." length="Размер файла изображения" type="Тип файла изображения" width="Ширина файла изображения" height="Высота файла изображения"/>
  <yandex:full-text>Только в Yandex-формате. Поле Описание для детального просмотра элемента информационного блока.</yandex:full-text>
</item>

Изменить генерацию можно на странице редактирования информационного блока в разделе Привязка полей для выгрузки в RSS. Поля RSS могут принимать любые текстовые значения. Кроме того можно использовать параметры, которые при генерации будут заменены на реальные данные. Параметры записываются в виде #ИМЯ#. В качестве имени параметра могут быть использованы коды свойств, а так же следующие значения:

  • NAME - заголовок элемента информационного блока;
  • DETAIL_PAGE_URL - адрес страницы с детальной информацией об элементе;
  • PREVIEW_TEXT - описание для анонса;
  • DETAIL_TEXT - описание для детального просмотра;
  • ACTIVE_FROM - начало периода активности/

Импорт из RSS

Для получения информации на сайте-клиенте следует воспользоваться методом GetNewsEx класса CIBlockRSS. Метод GetNews также доступен, но не рекомендуется к использованию как устаревший.

array
CIBlockRSS::GetNewsEx(
 SITE,
 PORT,
 PATH,
 QUERY_STR
);

Функция возвращает канал из кэша (если он не устарел) или с сайта-сервера.

Параметры запроса

SITE | Адрес сайта-сервера. Например, "www.bitrix.ru".
PORT | Порт сайта-сервера. Например, 80.
PATH | Путь к скрипту, генерирующему RSS на сайте-сервере. Например, "/bitrix/rss.php".
QUERY_STR | Строка запроса, если она необходима. Например, ID=3&LANG=ru&TYPE=news&LIMIT=5. Обратите внимание, что строка запроса должна строиться на основании спецификации HTTP.

Возвращаемое значение

Функция возвращает массив, содержащий данные запрошеного RSS файла.

Примеры использования

<?
CModule::IncludeModule("iblock");
$arRes = CIBlockRSS::GetNewsEx("www.bitrix.ru", 80, "/bitrix/rss.php", "ID=3&LANG=ru&TYPE=news&LIMIT=5");
$arRes = CIBlockRSS::FormatArray($arRes);

echo $arRes["title"];          // Название канала/блока
echo $arRes["link"];           // Ссылка на сайт-сервер
echo $arRes["description"];    // Описание канала/блока
echo $arRes["lastBuildDate"];  // Дата генерации файла на сайте-сервере
echo $arRes["ttl"];            // Через сколько часов обновить с сайта-сервера

echo $arRes["image"]["title"];   // Заголовок изображения блока/канала, если есть
echo $arRes["image"]["url"];     // Ссылка на файл изображения блока/канала, если есть
echo $arRes["image"]["width"];   // Ширина изображения блока/канала, если есть
echo $arRes["image"]["height"];  // Высота изображения блока/канала, если есть

echo $arRes["item"][0]["title"];       // Заголовок первой новости
echo $arRes["item"][1]["title"];       // Заголовок второй новости
echo $arRes["item"][1]["link"];        // Ссылка на вторую новость
echo $arRes["item"][1]["description"]; // Описание второй новости
echo $arRes["item"][1]["pubDate"];     // Дата публикации второй новости
echo $arRes["item"][1]["enclosure"]["url"];     // Ссылка на файл-вложение второй новости
echo $arRes["item"][1]["enclosure"]["length"];  // Размер файла-вложения второй новости
echo $arRes["item"][1]["enclosure"]["type"];    // MIME тип файла-вложения второй новости
echo $arRes["item"][1]["enclosure"]["width"];   // Ширина файла-вложения картинки
echo $arRes["item"][1]["enclosure"]["height"];  // Высота файла-вложения картинки

?>

<?
CModule::IncludeModule("iblock");
$arRes = CIBlockRSS::GetNewsEx("www.bitrix.ru", 80, "/bitrix/rss.php", "ID=demo&LANG=ru&TYPE=news&LIMIT=5");
$arRes = CIBlockRSS::FormatArray($arRes);
?>
<b><?echo $arRes["title"] ?></b><br>

<table cellpadding="2" cellspacing="0" border="0" width="80%">
  <?for ($i = 0; $i < count($arRes["item"]); $i++):?>
  <tr>
    <td width="100%">
      <font class="date">
        <?echo $arRes["item"][$i]["pubDate"]?>
      </font>&nbsp;|&nbsp;
      <?if (strlen($arRes["item"][$i]["link"])>0):?>
        <a href="<?echo $arRes["item"][$i]["link"]?>" class="zag">
      <?endif;?>
      <?echo $arRes["item"][$i]["title"]?>
      <?if (strlen($arRes["item"][$i]["link"])>0):?>
        </a>
      <?endif;?>
      <br>
    </td>
  </tr>
  <tr>
    <td valign="top" width="100%">
      <?if (strlen($arRes["item"][$i]["enclosure"]["url"])>0):?>
        <table cellpadding="0" cellspacing="0" border="0" align="left">
          <tr>
            <td valign="top">
              <img src="<?echo $arRes["item"][$i]["enclosure"]["url"] ?>" width="<?echo $arRes["item"][$i]["enclosure"]["width"] ?>" height="<?echo $arRes["item"][$i]["enclosure"]["height"]?>" border="0">
            </td>
          </tr>
        </table>
      <?endif;?>
      <font class="text">
        <?echo $arRes["item"][$i]["description"];?>
        <br>
      </font>
    </td>
  </tr>
  <?endfor;?>
</table>


Режим хранения свойств в отдельных таблицах

Инфоблоки 2.0

  • Режим хранения свойств в отдельных таблицах


Режим хранения свойств в отдельных таблицах

Введение

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

  1. При выборке элементов можно сразу получать значения свойств, т.к. количество присоединяемых таблиц в запросе не увеличивается с каждым свойством, а всегда равно единице.
  2. Фильтрация по значениям свойств происходит аналогично (за исключением множественных).
  3. Выборка значений множественных свойств теперь не приводит к декартовому произведению результата запроса - значения свойств передаются в виде массива.
  4. Для комбинированных фильтров по не множественным (в дальнейшем назовем их единичными) свойствам появилась возможность ручного создания составных индексов БД для ускорения операций выборки.
  5. Для инфоблоков с хранением значений свойств в выделенных таблицах нет возможности "сквозной" выборки элементов, когда в фильтре указывается тип инфоблока и символьный код свойства. В фильтре необходимо указывать IBLOCK_ID.

Важным является полная совместимость API. Т.е. техника использования инфоблоков, свойств, элементов и их значений не изменилась. Изменилась методика - например, теперь нет необходимости в дополнительном запросе CIBlockElement::GetProperty при выборе значений свойств функцией CIBlockElement::GetList.

Уровень информационного блока.

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

При редактировании инфоблока доступна ссылка на "конвертер" между типами хранения. Пользоваться им надо с большой осторожностью, т.к. продолжительность процесса конвертации зависит от общего объема значений свойств инфоблока. В течение всего процесса инфоблок находится в несогласованном состоянии (часть значений перенесена, а часть нет). На тестовой конфигурации для MySQL версии скорость была порядка 1500 элементов за 20-ти секундный шаг.

В классе CIBlockResult переопределён метод Fetch. В нем происходит кэширование значений множественных свойств элемента, участвующих в выборке. Для этих же свойств типа "список" выбираются пары ID=>VALUE из справочника списков.

В API добавлен новый параметр "VERSION" в массиве полей $arFields метода CIBlock::Add. Его значения: 1 - для общего хранения и 2 - для выделенного (нового).

Уровень свойств информационного блока.

Для свойств инфоблока в административном разделе изменений нет.

При редактировании свойств (смена признака множественности или типа свойства) для свойств в выделенном хранилище выполняются дополнительные операции по управлению таблицами. Такие как удаление/добавление колонок, вставка/обновление или удаление большого количества записей. Без настоятельной необходимости лучше избегать этого. Наилучшей методикой будет менять тип или множественность одного свойства за один раз. Причем для единичных свойств предпочтительнее сначала сделать его множественным а потом сменить тип, а для множественных наоборот - сначала тип, и уже потом делать его единичным.

Уровень элементов информационного блока.

Главные изменения коснулись использования метода GetList. Все они были перечислены во введении.

При вставке элемента вставляется и соответствующая запись в таблицу хранения значений свойств элемента.

Уровень значений свойств элементов информационного блока.

Для значений единичных свойств инфоблока с выделенным хранилищем ID - "синтетический". Он состоит из ID элемента и ID свойства, разделенных двоеточием.

При обновлении множественных свойств происходит сброс кеша этих значений.

Значения свойств хранятся в 2-х таблицах (описание таблиц и их структуры имеет справочный характер и могут меняться в следующих версиях):

  • b_iblock_element_prop_mNN - для множественных. Имеет ту же самую структуру, что и b_iblock_element_property;
  • b_iblock_element_prop_sNN - для единичных. Имеет поле IBLOCK_ELEMENT_ID - ID элемента инфоблока которому принадлежат свойства:
    • PROPERTY_XX - хранит значения единичного свойства XX или кэш значений для множественного свойства;
    • DESCRIPTION_XX - хранит описание для единичного свойства

Как достичь наибольшей эффективности при использовании новых инфоблоков?

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

Например: если раньше шаблон кода был примерно таким:

<?
//Определяем массив нужных полей элемента
$arSelect = array(
    "ID",
    "IBLOCK_ID",
    "IBLOCK_SECTION_ID",
    "NAME",
    "PREVIEW_PICTURE",
    "DETAIL_PICTURE",
    "DETAIL_PAGE_URL",
);
//Получаем список элементов. (+1 запрос)
if($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, false, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER), $ELEMENT_COUNT, $arFilter, $arSelect))
{
    //Инициализация постраничного вывода.
    $rsElements->NavStart($ELEMENT_COUNT);
    $count = intval($rsElements->SelectedRowsCount());
    if ($count>0)
    {
        //Для каждого элемента:
        while ($obElement = $rsElements->GetNextElement())
        {
            $arElement = $obElement->GetFields();
            //Получаем его свойства. (+1 запрос)
            $arProperty = $obElement->GetProperties();
            //Ниже можно пользоваться значениями свойств.
            //Например:
            echo $arProperty["SOURCE"],"<br>";
            //и т.д. и т.п.
        }
    }
}
?>

Теперь, после преобразования в новый тип хранения, стало возможным избавится от запросов в цикле:

<?
//Определяем массив нужных полей элемента
$arSelect = array(
    "ID",
    "IBLOCK_ID",
    "IBLOCK_SECTION_ID",
    "NAME",
    "PREVIEW_PICTURE",
    "DETAIL_PICTURE",
    "DETAIL_PAGE_URL",
    "PROPERTY_SOURCE", //Выбираем нужное нам свойство
    // И все другие какие могут понадобится
    // непосредственно в списке
);
//Получаем список элементов. (+1 запрос)
if($rsElements = GetIBlockElementListEx($IBLOCK_TYPE, false, false, array($ELEMENT_SORT_FIELD => $ELEMENT_SORT_ORDER), Array("nPageSize"=>$ELEMENT_COUNT), $arFilter, $arSelect))
{
    //Инициализация постраничного вывода.
    $rsElements->NavStart($ELEMENT_COUNT);
    if($obElement = $rsElements->GetNextElement())
    {
        //Для каждого элемента:
        do
        {
            $arElement = $obElement->GetFields();
            //Ниже можно пользоваться значениями свойств.
            //Например:
            echo $arElement["PROPERTY_SOURCE"],"<br>";
            //и т.д. и т.п.
        }
        while ($obElement = $rsElements->GetNextElement())
    }
}
?>


Классы

CIBlockElement - класс для работы с элементами информационных блоков.

Метод | Описание
GetList | Возвращает список элементов по фильтру.
GetByID | Возвращает элемент по его ID.
GetElementGroups | Возвращает группы, которым принадлежит элемент, по его коду.
GetProperty | Получение свойств злемента.
Add | Добавляет новый элемент.
Update | Изменяет элемент.
Delete | Удаляет элемент из информационного блока.
SetElementSection | Привязывает элемент информационного блока к группам.
SetPropertyValues | Сохраняет свойства элемента информационного блока.
SetPropertyValueCode | Изменяет значение свойства элемента.
UpdateSearch | Индексирует указанный элемент в модуле поиска.

CIBlockSection - класс для работы с группами информационных блоков.

Метод | Описание
GetList | Возвращает список групп по фильтру.
GetByID | Возвращает группу по ID.
Add | Добавляет в информационный блок новую группу.
Update | Изменяет группу.
Delete | Удаляет группу информационного блока.

CIBlock - класс для работы с информационными блоками.

Метод | Описание
ShowPanel | Добавляет кнопки для управления блоками, группами и элементами в верхнюю панель.
SetPermission | Устанавливает права доступа на информационный блок.
GetProperties | Возвращает свойства информационного блока.
GetGroupPermissions | Возвращает все права доступа для информационного блока.
GetPermission | Определяет право доступа для текущего пользователя.
GetList | Возвращает список информационных блоков по фильтру.
GetByID | Возвращает информационный блок по его ID.
Add | Добавляет новый информационный блок.
Update | Изменяет информационный блок.
Delete | Удаляет информационный блок.

CIBlockProperty - класс для работы со свойствами информационных блоков.

Метод | Описание
GetList | Возвращает список свойств по фильтру.
GetByID | Возвращает свойство по его ID.
Add | Добавляет новое свойство.
Update | Изменяет параметры свойства.
Delete | Удаляет свойства.
GetPropertyEnum | Начинает перечисление свойств.
UpdateEnum | Обновляет информацию в массиве результатов перечисления свойства.

CIBlockPropertyEnum - класс для работы с вариантами значений для свойств типа "список".

Метод | Описание
GetList | Возвращает список вариантов по фильтру.
Add | Добавляет новый вариант.
Update | Изменяет вариант.
Delete | Удаляет вариант свойства.

CIBlockType - класс для работы с типами информационных блоков.

Метод | Описание
GetList | Возвращает список типов по фильтру.
GetByID | Возвращает тип по его ID.
Add | Добавляет новый тип.
Update | Изменяет параметры типа.
Delete | Удаляет тип блока.

CIBlockResult - вспомогательный класс для работы с объектами результатов выборок.

Метод | Описание
GetNext | Возвращает массив полей из выборки.
GetNextElement | Возвращает объект _CIBElement из выборки.

_CIBElement - вспомогательный класс для работы с объектом выборки элемента .

Метод | Описание
GetFields | Возвращает поля элемента.
GetProperty | Возвращает значение свойства элемента.
GetProperties | Возвращает значения нескольких свойств элемента.
GetGroups | Возвращает список разделов, к которым привязан элемент.


CIBlock

CIBlock - класс для работы с информационными блоками

Методы класса

Метод | Описание
GetList | Возвращает список информационных блоков по фильтру.
GetSite | Возвращаке список сайтов для информационного блока.
GetByID | Возвращает информационный блок по его ID.
GetProperties | Возвращает свойства информационного блока.
GetPermission | Определяет право доступа для текущего пользователя.
Add | Добавляет новый информационный блок.
Update | Изменяет информационный блок.
Delete | Удаляет информационный блок.
SetPermission | Устанавливает права доступа на информационный блок.
GetGroupPermissions | Возвращает все права доступа для информационного блока.
ShowPanel | Добавляет кнопки для управления блоками, группами и элементами в верхнюю панель.


Add

CIBlock::Add

int
CIBlock::Add(
 array arFields
);

Метод добавляет новый информационный блок.

Параметры функции

Параметр Описание
arFields Массив Array("поле"=>"значение", ...). Содержит значения всех полей информационного блока.
Дополнительно в поле SITE_ID должен находиться массив идентификаторов сайтов, к которым привязан добавляемый информационный блок.
Кроме того, с помощью поля "GROUP_ID", значением которого должен быть массив соответствий кодов групп правам доступа, можно установить права для разных групп на доступ к информационному блоку(см. CIBlock::SetPermission()).

Возвращаемое значение

Метод возвращает код добавленного информационного блока, если добавление прошло успешно, при возникновении ошибки функция вернет false, а в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

См. также

  • CIBlock::Update
  • Поля информационного блока

Примеры использования

<?
$arPICTURE = $_FILES["PICTURE"];
$ib = new CIBlock;
$arFields = Array(
  "ACTIVE" => $ACTIVE,
  "NAME" => $NAME,
  "CODE" => $CODE,
  "LIST_PAGE_URL" => $LIST_PAGE_URL,
  "DETAIL_PAGE_URL" => $DETAIL_PAGE_URL,
  "IBLOCK_TYPE_ID" => $type,
  "SITE_ID" => Array("en", "de"),
  "SORT" => $SORT,
  "PICTURE" => $arPICTURE,
  "DESCRIPTION" => $DESCRIPTION,
  "DESCRIPTION_TYPE" => $DESCRIPTION_TYPE,
  "GROUP_ID" => Array("2"=>"D", "3"=>"R")
  );
if ($ID > 0)
  $res = $ib->Update($ID, $arFields);
else
{
  $ID = $ib->Add($arFields);
  $res = ($ID>0);
}
?>


Delete

CIBlock::Delete

bool
CIBlock::Delete(
 int ID
);

Функция удаляет информационный блок.

Параметры функции

Параметр | Описание
ID | Код информационного блока.

Возвращаемое значение

Возвращается true в случае успешного удаления и false - в противном случае.

Примеры использования

<?
if($USER->IsAdmin())
{
    $DB->StartTransaction();
    if(!CIBlock::Delete($iblock_id))
    {
        $strWarning .= GetMessage("IBLOCK_DELETE_ERROR");
        $DB->Rollback();
    }
    else
        $DB->Commit();
}
?>


GetByID

CIBlock::GetByID

CDBResult
CIBlock::GetByID(
 int ID
);

Возвращает информационный блок по его коду ID.

Параметры функции

Параметр | Описание
ID | Код информационного блока.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля результата

Примеры использования

<?
$res = CIBlock::GetByID($_GET["BID"]);
if($ar_res = $res->GetNext())
  echo $ar_res['NAME'];
?>


GetGroupPermissions

CIBlock::GetGroupPermissions

array
CIBlock::GetGroupPermissions(
 int ID
);

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

Параметры функции

Параметр | Описание
ID | Код информационного блока.

Возвращаемое значение

Массив прав вида Array("ID группы"=>"Право доступа"[, ...]). Право доступа может принимать значение: "D" - запрещён, "R" - чтение, "U" - изменение через документооборот, "W" - изменение, "X" - полный доступ (изменение + право изменять права доступа).

См. также

  • GetPermission

Примеры использования

<?
// выбор списка пользователей, имеющих право доступа на чтение инфоблока $IBLOCK_ID
$gr_res = CIBlock::GetGroupPermissions($IBLOCK_ID);
$res = Array(1);
foreach($gr_res as $group_id=>$perm)
if($perm>"R")
   $res[] = $group_id;
$res = CUser::GetList($by="NAME", $order="ASC", Array("GROUP_MULTI"=>$res));
?>


GetList

CIBlock::GetList

CDBResult
CIBlock::GetList(
 array arOrder = Array("SORT"=>"ASC"),
 array arFilter = Array(),
 bool bIncCnt = false
);

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

Параметры функции

Параметр | Описание
arOrder Массив для сортировки результата. Содержит пары "поле сортировки"=>"направление сортировки". Поле для сортировки может принимать значения:
  • id - код раздела;
  • iblock_type - тип раздела;
  • name - название раздела;
  • active - активность;
  • sort - индекс сортировки;
  • element_cnt - количество элементов (только если bIncCnt = true);
  • timestamp_x - дата последнего изменения.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ACTIVE - фильтр по активности (Y|N);
  • NAME - по названию (можно искать по шаблону [%_]);
  • EXTERNAL_ID, XML_ID - по внешнему коду;
  • SITE_ID - по сайту;
  • TYPE - по типу раздела;
  • CODE - по мнемоническому коду;
  • ID - по коду;
  • CNT_ACTIVE - только если bIncCnt = true. Если значение Y, то при подсчете элементов будут учитываться только активные элементы, при любом другом значении все элементы;
  • CNT_ALL - только если bIncCnt = true. Если значение Y, то при подсчете элементов будут учитываться и те элементы, которые ещё не были опубликованы. При любом другом значении все элементы;
  • MIN_PERMISSION - фильтр по правам доступа, по умолчанию принимает R (уровень доступа Чтение).
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно
Все фильтруемые поля кроме могут содержать перед названием тип проверки фильтра.
"значения фильтра" - одиночное значение или массив.

Необязательное. По умолчанию записи не фильтруются.
bIncCnt | Возвращать ли количество элементов в информационном блоке в поле ELEMENT_CNT. Не обязательный параметр, по умолчанию равен false.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля CIBlock

Примеры использования

<?
// выберем все активные информационные блоки для текущего сайта типа catalog
// у которых мнемонический код не my_products, со счетчиком активных элементов.
$res = CIBlock::GetList(
    Array(),
    Array(
        'TYPE'=>'catalog',
        'SITE_ID'=>SITE_ID,
        'ACTIVE'=>'Y',
        "CNT_ACTIVE"=>"Y",
        "!CODE"=>'my_products'
    ), true
);
while($ar_res = $res->Fetch())
{
    echo $ar_res['NAME'].': '.$ar_res['ELEMENT_CNT'];
}
?>


GetPermission

CIBlock::GetPermission

string
CIBlock::GetPermission(
 int IBLOCK_ID
);

Возвращает право доступа к информационному блоку IBLOCK_ID для текущего пользователя.

Параметры функции

Параметр | Описание
IBLOCK_ID | Код информационного блока.

Возвращаемое значение

Символ права доступа: "D" - запрещён, "R" - чтение, "U" - изменение через документооборот, "W" - изменение, "X" - полный доступ (изменение + право изменять права доступа).

См. также

  • GetGroupPermissions

Примеры использования

<?
$iblock_permission = CIBlock::GetPermission($id);
if($iblock_permission<"X")
        return false;
?>


GetProperties

CIBlock::GetProperties

CDBResult
CIBlock::GetProperties(
 int iblock_id,
 array arOrder=Array(),
 array arFilter=Array()
);
Возвращает свойства информационного блока iblock_id с возможностью сортировки и дополнительной фильтрации.

Параметры функции

Параметр | Описание
iblock_id | Код информационного блока.
arOrder | Массив для сортировки результата. Содержит пары "поле сортировки"=>"направление сортировки". Поля сортировки см. CIBlockProperty::GetList().
arFilter | Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемые поля и их значения смотрите в CIBlockProperty::GetList().

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • Поля свойств
  • CIBlockProperty::GetList()

Примеры использования

<?
$res = CIBlock::GetProperties($IBLOCK_ID, Array(), Array("CODE"=>"SRC"));
if($res_arr = $res->Fetch())
    $SrcPropID = $res_arr["ID"];
else
{
    $arFields = Array(
        "NAME" 			=> "Источник импорта",
        "ACTIVE" 		=> "Y",
        "SORT" 			=> "1000",
        "DEFAULT_VALUE" => "",
        "CODE" 			=> "SRC",
        "ROW_COUNT" 	=> "1",
        "COL_COUNT" 	=> "10",
        "MULTIPLE"	 	=> "N",
        "MULTIPLE_CNT" 	=> "",
        "PROPERTY_TYPE"	=> "S",
        "LIST_TYPE" 	=> "L",
        "IBLOCK_ID" 	=> $IBLOCK_ID
        );
    $ibp = new CIBlockProperty;
    $SrcPropID = $ibp->Add($arFields);
    if(IntVal($SrcPropID)<=0)
        $strWarning .= $ibp->LAST_ERROR."<br>";
}
?>


SetPermission

CIBlock::SetPermission

CIBlock::SetPermission(
 int IBLOCK_ID,
 array arPERMISSIONS
);

Функция устанавливает права доступа arPERMISSIONS для информационного блока IBLOCK_ID.

Параметры функции

Параметр | Описание
IBLOCK_ID | Код информационного блока.
arPERMISSIONS | Массив вида Array("код группы"=>"право доступа", ....), где право доступа: D - доступ запрещён, R - чтение, U - редактирование через документооборот, W - запись, X - полный доступ (запись + назначение прав доступа на данный инфоблок).

См. также

  • CIBlock::GetPermission()
  • CIBlock::Update()

Примеры использования

<?
CIBlock::SetPermission($IBLOCK_ID, Array("2"=>"R", "3"=>"W"));
?>


ShowPanel

CIBlock::ShowPanel

CIBlock::ShowPanel(
 int IBLOCK_ID = 0,
 int ELEMENT_ID = 0,
 int SECTION_ID = 0,
 string TYPE_ID = "news"
);

Добавляет в административную панель кнопки для быстрого перехода к редактированию объектов модуля информационных блоков, с учётом прав доступа.

Параметры функции

Параметр | Описание
IBLOCK_ID | Код информационного блока. если задан (больше нуля), то в панель добавляются кнопки на изменение параметров этого информационного блока, на добавление в него разделов и элементов.
ELEMENT_ID | Код элемента информационного блока. если задан (больше нуля), то в панель добавляются кнопки на редактирование этого элемента и просмотр его истории изменений (при установленном модуле документооборота).
SECTION_ID | Код раздела информационного блока. если задан (больше нуля), то в панель добавляются кнопки на изменение свойств этого раздела.
TYPE_ID | Тип информационного блока. если задан, то в панель добавляется кнопка добавления нового информационного блока.

Примечание

Если задан ELEMENT_ID, но не определён IBLOCK_ID, то функция автоматически установит его .

См. также

  • CMain::ShowPanel()

Примеры использования

<?
$IBLOCK_TYPE = 'catalog';
if(CModule::IncludeModule('iblock')):
    if($arIBlockElement = GetIBlockElement($_GET['ID'], $IBLOCK_TYPE)):
        CIBlock::ShowPanel($arIBlockElement['IBLOCK_ID'], $_GET['ID'], 0, $IBLOCK_TYPE);
        $APPLICATION->SetTitle($arIBlockElement['NAME']);
        $APPLICATION->AddChainItem($arIBlockElement['IBLOCK_NAME'], $arIBlockElement['LIST_PAGE_URL']);
        ?>
        <?=$arIBlockElement['NAME']?><br>
        <?=$arIBlockElement['DETAIL_TEXT']?>
        <?
    endif;
endif;
?>


Update

CIBlock::Update

bool
CIBlock::Update(
 int ID,
 array arFields
);

Функция изменяет параметры информационного блока с кодом ID.

Параметры функции

Параметр | Описание
ID | ID изменяемой записи.
arFields Массив Array("поле"=>"значение", ...). Содержит значения всех полей информационного блока.
Дополнительно в поле SITE_ID должен находиться массив идентификаторов сайтов, к которым привязан изменяемый информационный блок.
Кроме того, с помощью поля "GROUP_ID", значением которого должен быть массив соответствий кодов групп правам доступа, можно установить права для разных групп на доступ к информационному блоку(см. CIBlock::SetPermission()).

Возвращаемое значение

Функция возвращает true если изменение прошло успешно, при возникновении ошибки функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CIBlock::Add
  • Поля информационного блока

Примеры использования

<?
$arPICTURE = $_FILES["PICTURE"];
$ib = new CIBlock;
$arFields = Array(
  "ACTIVE" => $ACTIVE,
  "NAME" => $NAME,
  "CODE" => $CODE,
  "LIST_PAGE_URL" => $LIST_PAGE_URL,
  "DETAIL_PAGE_URL" => $DETAIL_PAGE_URL,
  "IBLOCK_TYPE_ID" => $type,
  "SITE_ID" => Array("en", "de"),
  "SORT" => $SORT,
  "PICTURE" => $arPICTURE,
  "DESCRIPTION" => $DESCRIPTION,
  "DESCRIPTION_TYPE" => $DESCRIPTION_TYPE,
  "GROUP_ID" => Array("2"=>"D", "3"=>"R")
  );
if ($ID > 0)
  $res = $ib->Update($ID, $arFields);
else
{
  $ID = $ib->Add($arFields);
  $res = ($ID>0);
}
?>


CIBlockElement

CIBlockElement - класс для работы с элементами информационных блоков.

Методы класса

Метод | Описание
GetList | Возвращает список элементов по фильтру.
GetByID | Возвращает элемент по его ID.
GetElementGroups | Возвращает группы, которым принадлежит элемент, по его коду.
GetProperty | Получение свойств злемента.
Add | Добавляет новый элемент.
Update | Изменяет элемент.
Delete | Удаляет элемент из информационного блока.
SetElementSection | Привязывает элемент информационного блока к группам.
SetPropertyValues | Сохраняет свойства элемента информационного блока.
SetPropertyValueCode | Изменяет значение свойства элемента.
UpdateSearch | Индексирует указанный элемент в модуле поиска.
CounterInc | Увеличивает счетчик показов элемента.


Add

CIBlockElement::Add

int
CIBlockElement::Add(
 array arFields,
 bool bWorkFlow = false,
 bool bUpdateSearch = true
);
Метод добавляет новый элемент информационного блока.

Параметры функции

Параметр | Описание
arFields | Массив вида Array("поле"=>"значение", ...), содержащий значения полей элемента инфоблоков и дополнительно может содержать поле "PROPERTY_VALUES" - массив со всеми значениями свойств элемента в виде массива Array("код свойства"=>"значение свойства"). Где "код свойства" - числовой или мнемонический код свойства, "значение свойства" - одиночное значение, либо массив значений если свойство множественное. Дополнительно для сохранения значения свойств см: CIBlockElement::SetPropertyValues(), CIBlockElement::SetPropertyValueCode()
bWorkFlow | Вставка в режиме документооборота. Если true и модуль документооборота установлен, то данное добавление будет учтено в журнале изменения элемента. Не обязательный параметр, по умолчанию вставка в режиме документооборота отключена.
bUpdateSearch | Индексировать элемент для поиска. Для повышения производительности можно отключать этот параметр во время серии добавлений элементов, а после вставки переиндексировать поиск. Не обязательный параметр, по умолчанию элемент после добавления будет проиндексирован в поиске.

Возвращаемое значение

Метод возвращает код добавленного элемента инфоблока, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

См. также

  • CIBlockElement::Update
  • CIBlockElement::SetPropertyValues()
  • CIBlockElement::SetPropertyValueCode()

Примеры использования

<?
$el = new CIBlockElement;

$PROP = array();
$PROP[12] = "Белый";  // свойству с кодом 12 присваиваем значение "Белый"
$PROP[3] = 38;        // свойству с кодом 3 присваиваем значение 38

$arLoadProductArray = Array(
  "MODIFIED_BY"    => $USER->GetID(), // элемент изменен текущим пользователем
  "IBLOCK_SECTION" => false,          // элемент лежит в корне раздела
  "IBLOCK_ID"      => 18,
  "PROPERTY_VALUES"=> $PROP,
  "NAME"           => "Элемент",
  "ACTIVE"         => "Y",            // активен
  "PREVIEW_TEXT"   => "текст для списка элементов",
  "DETAIL_TEXT"    => "текст для детального просмотра",
  "DETAIL_PICTURE" => CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/image.gif")
  );

if($PRODUCT_ID = $el->Add($arLoadProductArray))
  echo "New ID: ".$PRODUCT_ID;
else
  echo "Error: ".$el->LAST_ERROR;
?>


CounterInc

CIBlockElement::CounterInc

CIBlockElement::CounterInc(
 int ID
);
Увеличивает счетчик просмотров элемента с кодом ID. При увеличении учитывается уникальность просмотров данного элемента в одной сессии.

Параметры функции

Параметр | Описание
ID | Код элемента.

Примеры использования

<?
if(CModule::IncludeModule("iblock"))
    CIBlockElement::CounterInc($ID);
?>


Delete

CIBlockElement::Delete

bool
CIBlockElement::Delete(
 int ID
);

Функция удаляет элемент информационного блока.

Параметры функции

Параметр | Описание
ID | Код элемента.

Возвращаемое значение

Возвращается true в случае успешного удаления, в противном случае функция вернет false.

Примеры использования

<?
if(CIBlock::GetPermission($IBLOCK_ID)>='W')
{
    $DB->StartTransaction();
    if(!CIBlockElement::Delete($ELEMENT_ID))
    {
        $strWarning .= 'Error!';
        $DB->Rollback();
    }
    else
        $DB->Commit();
}
?>


GetByID

CIBlockElement::GetByID

CIBlockResult
CIBlockElement::GetByID(
 int ID
);

Возвращает параметры элемента с кодом ID.

Параметры функции

Параметр | Описание
ID | ID элемента.

Возвращаемое значение

Возвращается объект CIBlockResult с полями элемента информационного блока.

Примечание

Функция не проверяет чтобы элемент с кодом ID был опубликован и не являлся записью из истории. Для выборки только опубликованных элементов воспользуйтесь функциeй CIBlockElement::GetList().

См. также

  • CDBResult
  • CIBlockResult
  • Поля элемента информационного блока
  • CIBlockElement::GetList()

Примеры использования

<?
$res = CIBlockElement::GetByID($_GET["PID"]);
if($ar_res = $res->GetNext())
  echo $ar_res['NAME'];
?>


GetElementGroups

CIBlockElement::GetElementGroups

CDBResult
CIBlockElement::GetElementGroups(
 int ID
);

Возвращает группы, которым принадлежит элемент, по его коду ID.

Параметры функции

Параметр | Описание
ID | ID элемента.

Возвращаемое значение

Возвращается объект CDBResult с полями разделов.

См. также

  • CDBResult
  • Поля раздела
  • CIBlockElement::SetElementSectio n()

Примеры использования

<?
$db_old_groups = CIBlockElement::GetElementGroups($ELEMENT_ID);
$ar_new_groups = Array($NEW_GROUP_ID);
while($ar_group = $db_old_groups->Fetch())
    $ar_new_groups[] = $ar_group["ID"];
CIBlockElement::SetElementSection($ELEMENT_ID, $ar_new_groups);
?>


GetList

CIBlockElement::GetList

CIBlockResult
CIBlockElement::GetList(
 array arOrder = Array("SORT"=>"ASC"),
 array arFilter = Array(),
 mixed arGroupBy = false,
 mixed arNavStartParams = false,
 array arSelectFields = Array()
);

Возвращает список элементов по фильтру arFilter.

Примечание: внутренние ограничения Oracle и MSSQL не позволяют использовать DISTINCT при фильтрации по полям типа blob, поскольку фильтрация по нескольким значениям множественного свойства может дать дублирование.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где by - поле для сортировки, может принимать значения:
  • id - ID элемента;
  • sort - индекс сортировки;
  • timestamp_x - дата изменения;
  • name - название;
  • active_from - начало периода действия элемента;
  • active_to - окончание периода действия элемента;
  • status - код статуса элемента в документообороте;
  • code - мнемонический код элемента;
  • iblock_id - числовой код информационного блока;
  • modified_by - код последнего изменившего пользователя;
  • active - признак активности элемента;
  • show_counter - количество показов элемента (учитывается функцией CIBlockElement::CounterInc);
  • show_counter_start - время первого показа элемента (учитывается функцией CIBlockElement::CounterInc);
  • shows - усредненное количество показов (количество показов / продолжительность показа);
  • rand - случайный порядок;
  • property_<PROPERTY_CODE> - по значению свойства с числовым или мнемоническим кодом PROPERTY_CODE (например, PROPERTY_123 или PROPERTY_NEWS_SOURCE);
  • catalog_<CATALOG_FIELD>_<PRICE_TYPE> - по полю CATALOG_FIELD (может быть PRICE - цена или CURRENCY - валюта) из цены с типом PRICE_TYPE (например, catalog_PRICE_1 или CATALOG_CURRENCY_3);
  • order - порядок сортировки, может принимать значения:
    • asc - по возрастанию;
    • desc - по убыванию;
    Необязательный. По умолчанию равен Array("sort"=>"asc")
arFilter Массив вида array("фильтруемое поле"=>"значения фильтра" [, ...]). "фильтруемое поле" может принимать значения:
  • ID - по числовому коду;
  • ACTIVE - фильтр по активности (Y|N); передача пустого значения ("ACTIVE"=>"") выводит все элементы без учета их состояния;
  • NAME - по названию (можно искать по шаблону [%_]);
  • CODE - по мнемоническому идентификатору (можно искать по шаблону [%_]);
  • EXTERNAL_ID - по внешнему коду (можно искать по шаблону [%_]);
  • PREVIEW_TEXT - по анонсу (можно искать по шаблону [%_]);
  • PREVIEW_TEXT_TYPE - по типу анонса (html|text);
  • PREVIEW_PICTURE - коду картинки для анонса;
  • DETAIL_TEXT - по детальному описанию (можно искать по шаблону [%_]);
  • DETAIL_TEXT_TYPE - по типу детальному описания (html|text);
  • DETAIL_PICTURE - по коду детальной картинки;
  • CHECK_PERMISSIONS - если установлен в "Y", то в выборке будет осуществляться проверка прав доступа к информационным блокам. По умолчанию права доступа не проверяются.
  • MIN_PERMISSION - минимальный уровень доступа, будет обработан только если CHECK_PERMISSIONS установлен в "Y". По умолчанию "R". Список прав доступа см. в CIBlock::SetPermission().
  • SEARCHABLE_CONTENT - по содержимому для поиска. Включает в себя название, описание для анонса и детальное описание (можно искать по шаблону [%_]);
  • SORT - по сортировке;
  • TIMESTAMP_X - по времени изменения (можно искать по шаблону [%_]);
  • MODIFIED_USER_ID - по коду пользователя, изменившего элемент;
  • DATE_CREATE - по времени создания;
  • CREATED_BY - по коду пользователя, добавившего элемент;
  • DATE_ACTIVE_FROM - по дате начала активности;
  • DATE_ACTIVE_TO - по дате окончания активности;
  • ACTIVE_DATE - непустое значение задействует фильтр по датам активности (DATE_ACTIVE_FROM и DATE_ACTIVE_TO). Если значение не установлено (""), фильтрация по датам активности не производится;
  • IBLOCK_ID - по коду информационного блока;
  • IBLOCK_CODE - по мнемоническому коду информационного блока (можно искать по шаблону [%_]);
  • IBLOCK_SITE_ID - по сайту;
  • IBLOCK_TYPE - по типу информационного блока (можно искать по шаблону [%_]);
  • IBLOCK_ACTIVE - по активности информационного блока(Y|N);
  • SECTION_ID - по родительской группе;
  • INCLUDE_SUBSECTIONS - если задан фильтр по родительским группам SECTION_ID, то будут также выбраны элементы находящиеся в подгруппах этих групп;
  • SHOW_COUNTER - по количеству показов;
  • SHOW_COUNTER_START - по времени первого показа;
  • WF_COMMENTS - по комментарию документооборота (можно искать по шаблону [%_]);
  • WF_STATUS_ID - по коду статуса документооборота;
  • SHOW_HISTORY - если установлен в значение "Y", то вместе с элементами будут выводится и их архив (история), по умолчанию выводятся только опубликованные элементы;
  • SHOW_NEW - если SHOW_HISTORY не установлен или не равен Y и SHOW_NEW=Y, то будут показываться ещё неопубликованные элементы вместе с опубликованными;
  • WF_PARENT_ELEMENT_ID - по коду элемента-родителя в документообороте для выборки истории изменений;
  • WF_NEW - флаг что элемент ещё ни разу не был опубликован (Y|N);
  • WF_LOCK_STATUS - статус заблокированности элемента в документооборте (red|green|yellow);
  • PROPERTY_<код свойства> - фильтр по значениям свойств (можно искать по шаблону [%_]);
  • PROPERTY_<код свойства>_VALUE - фильтр по значениям списка для свойств типа "список" (можно искать по шаблону [%_]), поиск будет осуществляться по строковому значению списка, а не по идентификатору;
  • CATALOG_<CATALOG_FIELD>_<PRICE_TYPE> - по полю CATALOG_FIELD из цены типа PRICE_TYPE (ID типа цены), где CATALOG_FIELD может быть: PRICE - цена, CURRENCY - валюта.
Перед названием фильтруемого поля можно указать тип проверки фильтра:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно
Значения фильтра - одиночное значение или массив значений.

Необязательное. По умолчанию записи не фильтруются.
arGroupBy Массив полей для группировки элемента. Если поля указаны, то выборка по ним группируется, а в результат добавляется поле CNT - количество сгруппированных элементов. Если указать в качестве arGroupBy пустой массив, то функция вернет количество элементов CNT по фильтру. Группировать можно по полям элемента, а также по значениям его свойств. Для этого в качестве одного из полей группировки необходимо указать PROPERTY_<PROPERTY_CODE>, где PROPERTY_CODE - мнемонический код.
Необязательное. По умолчанию false - записи не группируются.
arNavStartParams Параметры для постраничной навигации и ограничения количества выводимых элементов. массив вида "Название параметра"=>"Значение", где название параметра
"nTopCount" - ограничить количество сверху
"bShowAll" - разрешить вывести все элементы при постраничной навигации
"iNumPage" - номер страницы при постраничной навигации
"nPageSize" - количество элементов на странице при постраничной навигации

Необязательное. По умолчанию false - не ограничивать выводимые элементы.
arSelectFields Массив возвращаемых полей элемента. Список полей элемента, а также можно сразу выводить значения его свойств. Обязательно должно быть использовано поле IBLOCK_ID, иначе не будет работать корректно. Кроме того, также в качестве одного из полей необходимо указать PROPERTY_<PROPERTY_CODE>, где PROPERTY_CODE - ID или мнемонический код. В результате будет выведены значения свойств элемента в виде полей PROPERTY_<PROPERTY_CODE>_VALUE - значение; PROPERTY_<PROPERTY_CODE>_ID - код значения у элемента; PROPERTY_<PROPERTY_CODE>_ENUM_ID - код значения (для свойств типа список)
При установленном модуле торгового каталога можно выводить и цены элемента. Для этого в качестве одного из полей необходимо указать CATALOG_GROUP_<PROPERTY_CODE>, где PROPERTY_CODE - ID типа цены.

По умолчанию выводить все поля.

Примечание: если в массиве используются свойство, являющееся множественным, то для элементов, где используются несколько значений этого свойства, будет возвращено несколько записей вместо одной. Для решения этой проблемы инфоблоки нужно перевести в "инфоблоки+", в этом случае для свойства будет отдаваться массив значений. Либо можно не указывать свойства в параметрах выборки, а получать их значения на каждом шаге перебора выборки с помощью _CIBElement::GetProperties().

Рассмотрим несколько частных случаев фильтрации:

  • $arFilter = array("PROPERTY_CML2_SCAN_CODE") =>false - используется, чтобы выбрать все элементы с незаполненными свойствами;
  • $arFilter = array("PROPERTY_CML2_SCAN_CODE") =>"" - используется, чтобы выбрать все элементы;
  • $arFilter = array("PROPERTY_CML2_SCAN_CODE") =>qwe - при фильтрации элементов проверяется точное совпадение с заданными свойствами;
  • $arFilter = array("?PROPERTY_CML2_SCAN_CODE") =>we" - при фильтрации элементов проверяется наличие заданной подстроки свойствах.
  • $arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>false - используется, чтобы выбрать только элементы с заполненными свойствами;
  • $arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>"" - используется, чтобы выбрать все элементы;
  • $arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>qwe - при фильтрации элементов проверяется точное совпадение с заданными свойствами;
  • $arFilter = array("!?PROPERTY_CML2_SCAN_CODE") =>we - при фильтрации элементов проверяется наличие заданной подстроки свойствах.

Возвращаемое значение

Возвращается объект CIBlockResult.

См. также

  • CDBResult
  • Поля элементов

    Примеры использования

    <?
$arSelect = Array("ID", "NAME", "DATE_ACTIVE_FROM");
$arFilter = Array("IBLOCK_ID"=>IntVal($yvalue), "ACTIVE_DATE"=>"Y", "ACTIVE"=>"Y");
$res = CIBlockElement::GetList(Array(), $arFilter, false, Array("nPageSize"=>50), $arSelect);
while($ob = $res->GetNextElement())
{
  $arFields = $ob->GetFields();
  print_r($arFields);
}
?>
    <?
// выборка активных элементов из информационного блока $yvalue,
// у которых установлено значение свойства с мнемоническим кодом SRC
// и дата начала автивности старше 1 января 2003 года
// выбранные элементы будут сгруппированы по дате активности
$arFilter = Array(
   "IBLOCK_ID"=>IntVal($yvalue),
   ">DATE_ACTIVE_FROM"=>date($DB->DateFormatToPHP(CLang::GetDateFormat("SHORT")), mktime(0,0,0,1,1,2003)),
   "ACTIVE"=>"Y",
   "!PROPERTY_SRC"=>false
   );
$res = CIBlockElement::GetList(Array("SORT"=>"ASC", "PROPERTY_PRIORITY"=>"ASC"), $arFilter, Array("DATE_ACTIVE_FROM"));
while($ar_fields = $res->GetNext())
{
  echo $ar_fields["DATE_ACTIVE_FROM"].": ".$ar_fields["CNT"]."<br>";
}
?>


GetProperty

CIBlockElement::GetProperty

CDBResult
CIBlockElement::GetProperty(
 int iblock_id,
 int element_id,
 string by = "sort",
 string order = "asc",
 array arFilter = Array()
);

Функция возвращает значения свойств для злемента element_id.

Параметры функции

Параметр | Описание
iblock_id | Код раздела.
element_id | Код элемента.
by | Поле для сортировки результата. Может принимать одно из следующих значений id - по ключу, name - по имени свойства, active - по активности свойства, sort - по индексу сортировки свойства. Не обязательный параметр, по умолчанию равен sort.
order | Направление сортировки. Может принимать одно из следующих значений asc - по возрастанию, desc - по убыванию. Не обязательный параметр, по умолчанию равен asc.
arFilter | Массив вида array("фильтруемое поле"=>"значения фильтра" [, ...]) "фильтруемое поле" может принимать значения: ACTIVE - активность (Y/N), NAME - название свойства, ID - код свойства, ACTIVE - активность (Y|N), PROPERTY_TYPE - тип свойства, CODE - мнемонический код свойства, EMPTY - пустота свойства. Не обязательный параметр, по умолчанию равен array().

Возвращаемое значение

Возвращается объект CDBResult, содержащий поля свойств и поля со значениями:
PROPERTY_VALUE_ID - код значения свойства,
VALUE - значение свойства,
DESCRIPTION - описание значения свойства,
VALUE_ENUM - код значения свойства типа "список".

См. также

  • CDBResult
  • Поля свойств

Примеры использования

<?
$db_props = CIBlockElement::GetProperty($PRODUCT_IBLOCK_ID, $PRODUCT_ID, "sort", "asc", Array("CODE"=>"FORUM_TOPIC_ID"));
if($ar_props = $db_props->Fetch())
    $FORUM_TOPIC_ID = IntVal($ar_props["VALUE"]);
else
    $FORUM_TOPIC_ID = false;
?>


SetElementSection

CIBlockElement::SetElementSection

CIBlockElement::SetElementSection(
 int ID,
 array arSections
);
Функция привязывает элемент информационного блока к группам.

Параметры функции

Параметр | Описание
ID | Код (ID) элемента.
arSections | Массив кодов групп, к которым принадлежит указанный элемент.

См. также

  • CIBlockElement:: GetElementGroups()

Примеры использования

<?
$ID = 18;  // код элемента
$arSects = array(1, 5, 7); // массив кодов групп
CIBlockElement::SetElementSection($ID, $arSects);
?>


SetPropertyValueCode

CIBlockElement::SetPropertyValueCode

bool
CIBlockElement::SetPropertyValueCode(
 int ELEMENT_ID,
 string PROPERTY_CODE,
 string PROPERTY_VALUE
);
Функция изменяет значение свойства элемента информационного блока.

Параметры функции

Параметр | Описание
ELEMENT_ID | Код элемента, значение свойства которого изменяется.
PROPERTY_CODE | Мнемонический или числовой код свойства, которое изменяется.
PROPERTY_VALUE | Значение свойства (одиночное или множественное в виде массива значений).

См. также

  • CIBlockElement::Update
  • CIBlockElement::SetPropertyValues

Примеры использования

<?
$arFile = CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/images/add_basket.gif");
CIBlockElement::SetPropertyValueCode($ELEMENT_ID, "picture", $arFile);
?>


SetPropertyValues

CIBlockElement::SetPropertyValues

CIBlockElement::SetPropertyValues(
 int ELEMENT_ID,
 int IBLOCK_ID,
 array PROPERTY_VALUES,
 string PROPERTY_CODE = false
);
Функция сохраняет значения всех свойств элемента информационного блока.

Параметры функции

Параметр | Описание
ELEMENT_ID | Код элемента, значения свойств которого необходимо установить.
IBLOCK_ID | Код информационного блока.
PROPERTY_VALUES | Массив значений свойств, в котором коду свойства ставится в соответствие значение свойства. Если PROPERTY_CODE установлен, то должен содержать одно или массив всех значений свойства (множественное) для заданного элемента. Если PROPERTY_CODE равен false, то PROPERTY_VALUES должен быть вида Array("код свойства1"=>"значения свойства1", ....), где "код свойства" - числовой или мнемонический код свойства, "значения свойства" - одно или массив всех значений свойства (множественное). При этом массив PROPERTY_VALUES должен содержать полный набор значений свойств для данного элемента, т.е. если в нем будет остутствовать одно из свойств, то все его значения для данного элемента будут удалены.
PROPERTY_CODE | Код изменяемого свойства. Если этот параметр отличен от false, то изменяется только свойство с таким кодом. Не обязательный параметр, по умолчанию равен false.

См. также

  • CIBlockElement::Update
  • CIBlockElement::SetPropertyValueCode

Примеры использования

<?
$ELEMENT_ID = 18;  // код элемента
$PROPERTY_CODE = "PROP1";  // код свойства
$PROPERTY_VALUE = "Синий";  // значение свойства

// Установим новое значение для данного свойства данного элемента
$strSql =
  "SELECT BE.IBLOCK_ID ".
  "FROM b_iblock_element BE ".
  "WHERE BE.ID = ".IntVal($ELEMENT_ID);
$dbr = $DB->Query($strSql);
if ($dbr_arr = $dbr->Fetch())
{
  $IBLOCK_ID = $dbr_arr["IBLOCK_ID"];
  CIBlockElement::SetPropertyValues($ELEMENT_ID, $IBLOCK_ID, $PROPERTY_VALUE, $PROPERTY_CODE);
}
?>


Update

CIBlockElement::Update

bool
CIBlockElement::Update(
 int ID,
 array arFields,
 bool bWorkFlow = false,
 bool bUpdateSearch = true
);

Метод изменяет параметры элемента с кодом ID.

Параметры функции

Параметр | Описание
ID | ID изменяемой записи.
arFields | Массив вида Array("поле"=>"значение", ...), содержащий значения полей элемента инфоблоков и дополнительно может содержать поле "PROPERTY_VALUES" - массив со всеми значениями свойств элемента в виде массива Array("код свойства"=>"значение свойства"). Где "код свойства" - числовой или мнемонический код свойства, "значение свойства" - одиночное значение, либо массив значений (если свойство множественное). Если массив PROPERTY_VALUES задан, то он должен содержать полный набор значений свойств для данного элемента, т.е. если в нем будет отсутствовать одно из свойств, то все его значения для данного элемента будут удалены. Дополнительно для сохранения значения свойств см: CIBlockElement::SetPropertyValues(), CIBlockElement::SetPropertyValueCode()
bWorkFlow | Изменение в режиме документооборота. Если true и модуль документооборота установлен, то данное изменение будет учтено в журнале изменений элемента. Не обязательный параметр, по умолчанию изменение в режиме документооборота отключена. Примечание: в режиме документооборота можно передавать значения не всех свойств в PROPERTY_VALUES, а только необходимых.
bUpdateSearch | Индексировать элемент для поиска. Для повышения производительности можно отключать этот параметр во время серии изменений элементов, а после их окончания переиндексировать поиск. Не обязательный параметр, по умолчанию элемент после изменения будет автоматически проиндексирован в поиске.

Возвращаемое значение

Метод возвращает true если изменение прошло успешно, при возникновении ошибки метод вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CIBlockElement::Add

Примеры использования

<?
$el = new CIBlockElement;

$PROP = array();
$PROP[12] = "Белый";  // свойству с кодом 12 присваиваем значение "Белый"
$PROP[3] = 38;        // свойству с кодом 3 присваиваем значение 38

$arLoadProductArray = Array(
  "MODIFIED_BY"    => $USER->GetID(), // элемент изменен текущим пользователем
  "IBLOCK_SECTION" => false,          // элемент лежит в корне раздела
  "IBLOCK_ID"      => 18,
  "PROPERTY_VALUES"=> $PROP,
  "NAME"           => "Элемент",
  "ACTIVE"         => "Y",            // активен
  "PREVIEW_TEXT"   => "текст для списка элементов",
  "DETAIL_TEXT"    => "текст для детального просмотра",
  "DETAIL_PICTURE" => CFile::MakeFileArray($_SERVER["DOCUMENT_ROOT"]."/image.gif")
  );

$PRODUCT_ID = 2;  // изменяем элемент с кодом (ID) 2
$res = $el->Update($PRODUCT_ID, $arLoadProductArray);
?>


UpdateSearch

CIBlockElement::UpdateSearch

CIBlockElement::UpdateSearch(
 int ID,
 bool bOverWrite = false
);
Индексирует элемент с кодом ID в модуле поиска.

Параметры функции

Параметр | Описание
ID | Код элемента.
bOverWrite | Переиндексировать ли элемент, если дата его изменения не изменилась.


CIBlockProperty

CIBlockProperty - класс для работы со свойствами информационных разделов.

Методы класса

Метод | Описание
GetList | Возвращает список свойств по фильтру.
GetByID | Возвращает свойство по его ID.
Add | Добавляет новое свойство.
Update | Изменяет параметры свойства.
Delete | Удаляет свойства.
GetPropertyEnum | Начинает перечисление свойств.
UpdateEnum | Обновляет информацию в массиве результатов перечисления свойства.


Add

CIBlockProperty::Add

int
CIBlockProperty::Add(
 array fields
);

Функция добавляет новое свойство.

Параметры функции

Параметр | Описание
fields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей свойства. Кроме того, с помощью поля "VALUES", значением которого должен быть массив структуры array(array("VALUE"=>"значение", "DEF"=>"по умолчанию (Y/N)", "SORT"=>"индекс сортировки"),...), можно установить варианты выбора для свойств типа "список" (подробнее смотрите метод CIBlockProperty::UpdateEnum()).

Возвращаемое значение

Функция возвращает код добавленного свойства, если добавление прошло успешно, при возникновении ошибки функция вернет false, а в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

См. также

  • CIBlockProperty::Update
  • Поля свойства

Примеры использования

<?
$arFields = Array(
  "NAME" => "Цвет",
  "ACTIVE" => "Y",
  "SORT" => "100",
  "CODE" => "color",
  "PROPERTY_TYPE" => "L",
  "IBLOCK_ID" => 11
  );

$arFields["VALUES"][0] = Array(
  "VALUE" => "Красный",
  "DEF" => "N",
  "SORT" => "100"
}

$arFields["VALUES"][1] = Array(
  "VALUE" => "Желтый",
  "DEF" => "N",
  "SORT" => "200"
}

$arFields["VALUES"][2] = Array(
  "VALUE" => "Зеленый",
  "DEF" => "Y",
  "SORT" => "300"
}

$ibp = new CIBlockProperty;
$PropID = $ibp->Add($arFields);
?>


Delete

CIBlockProperty::Delete

bool
CIBlockProperty::Delete(
 int ID
);

Функция удаляет свойство.

Параметры функции

Параметр | Описание
ID | Код свойства.

Возвращаемое значение

В случае успешного удаления возвращается true, иначе - false.


GetByID

CIBlockProperty::GetByID

CDBResult
CIBlockProperty::GetByID(
 mixed ID,
 int IBLOCK_ID = false,
 string IBLOCK_CODE = false
);

Возвращает свойство по его коду ID.

Параметры функции

Параметр | Описание
ID | Числовой или мнемонический код свойства.
IBLOCK_ID | Код информационного блока. Используется для уточнения свойства если его ID задано мнемоническим кодом и с таким мнемоническим кодом свойства присутствует в нескольких информационных блоках.
IBLOCK_CODE | Мнемонический код информационного блока. Используется для уточнения свойства если его ID задано мнемоническим кодом и с таким мнемоническим кодом свойства присутствует в нескольких информационных блоках.

Возвращаемое значение

Возвращается объект CDBResult.

Примечание

Если заданы оба значения IBLOCK_ID и IBLOCK_CODE, то будет производиться попытка найти свойство в одном из них (логика "или").

См. также

  • CDBResult
  • Поля свойства

Примеры использования

<?
$res = CIBlockProperty::GetByID("SRC", false, "company_news");
if($ar_res = $res->GetNext())
  echo $ar_res['NAME'];
?>


GetList

CIBlockProperty::GetList

CDBResult
CIBlockProperty::GetList(
 array arOrder = Array(),
 array arFilter = Array()
);

Возвращает список свойств по фильтру arFilter отсортированные в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки, имеющий вид by1=>order1[,by2=>order2 [, ..]], где: by - поле сортировки, может принимать значения:
  • id - код;
  • block_id - код информационного блока, которому принадлежит свойство; name - название;
  • active - активность;
  • sort - индекс сортировки;
  • timestamp_x - дата последнего изменения
  • searchable - по признаку участия значения свойства в поиске;
  • filtrable - по признаку участия свойства в фильре на странице списка элементов;
  • order - порядок сортировки, может принимать значения:
    • asc - по возрастанию;
    • desc - по убыванию;
arFilter Массив вида array("фильтруемое поле"=>"значение" [, ...]) . Фильтруемое поле может принимать значения:
  • ACTIVE - фильтр по активности (Y|N);
  • CODE - по мнемоническому коду(по шаблону [%_]);
  • NAME - по названию свойства (по шаблону [%_]);
  • EXTERNAL_ID - по внешнему коду(по шаблону [%_]). Возможно использование отрицания, указав !EXTERNAL_ID;
  • PROPERTY_TYPE - по типу свойства;
  • SEARCHABLE - по признаку участия значения свойства в поиске;
  • FILTRABLE - по признаку участия свойства в фильре на странице списка элементов;
  • IBLOCK_ID - по коду информационного блока, которому принадлежит свойство;
  • ID - по коду.
Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля свойства

Примеры использования

<?
$IBLOCK_ID = 11;
$properties = CIBlockProperty::GetList(Array("sort"=>"asc", "name"=>"asc"), Array("ACTIVE"=>"Y", "IBLOCK_ID"=>$IBLOCK_ID));
while ($prop_fields = $properties->GetNext())
{
  echo $prop_fields["ID"]." - ".$prop_fields["NAME"]."<br>";
}
?>


GetPropertyEnum

CIBlockProperty::GetPropertyEnum

CDBResult
CIBlockProperty::GetPropertyEnum(
 mixed PROP_ID,
 array arOrder = Array("SORT"=>"asc"),
 array arFilter = Array()
)

Возвращает варианты для значения свойства PROP_ID типа "список" отсортированные в порядке arOrder и отфильтрованные по arFilter.

Параметры функции

Параметр | Описание
PROP_ID | Числовой или мнемонический код свойства.
arOrder Массив для сортировки, имеющий вид by1=>order1[, by2=>order2 [, ..]], где
by - поле сортировки, может принимать значения:
id - код;
value - значение,
sort - поле сортировки,
order - порядок сортировки, может принимать значения:
asc - по возрастанию;
desc - по убыванию;
arFilter Массив вида array("фильтруемое поле"=>"значение" [, ...])
"фильтруемое поле" может принимать значения:
VALUE - по значению варианта свойства (можно искать по шаблону [%_]);
IBLOCK_ID - по коду информационного блока, которому принадлежит свойство;
ID - по коду значения варианта свойства;
Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult, содержащий записи полей вариантов свойства.

См. также

  • Поля вариантов свойства
  • CIBlockPropertyEnum::GetList()

Примеры использования

<?
$db_enum_list = CIBlockProperty::GetPropertyEnum("IMPORTANT_NEWS", Array(), Array("IBLOCK_ID"=>$BID, "VALUE"=>"Yes"));
if($ar_enum_list = $db_enum_list->GetNext())
{
  $db_important_news = CIBlockElement::GetList(Array(), Array("IBLOCK_ID"=>$BID, "PROPERTY"=>array("IMPORTANT_NEWS"=>$ar_enum_list["ID"])));
}
?>


Update

CIBlockProperty::Update

bool
CIBlockProperty::Update(
 int ID,
 array arFields
);

Функция изменяет параметры свойства с кодом ID.

Параметры функции

Параметр | Описание
ID | ID изменяемой записи.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей изменяемого свойства. Кроме того, с помощью поля "VALUES", значением которого должен быть массив вида Array(Array("VALUE"=>"значение", "DEF"=>"по умолчанию (Y/N)", "SORT"=>"индекс сортировки"),...), можно установить варианты выбора для свойств типа "список" (подробнее смотрите метод CIBlockProperty::UpdateEnum()).

Возвращаемое значение

Функция возвращает true если изменение прошло успешно, при возникновении ошибки функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CIBlockProperty::Add
  • Поля свойства

Примеры использования

<?
$arFields = Array(
  "NAME" => "Цвет",
  "ACTIVE" => "Y",
  "SORT" => "100",
  "CODE" => "color",
  "PROPERTY_TYPE" => "L",
  "IBLOCK_ID" => 11
  );

$arFields["VALUES"][0] = Array(
  "VALUE" => "Красный",
  "DEF" => "N",
  "SORT" => "100"
}

$arFields["VALUES"][1] = Array(
  "VALUE" => "Желтый",
  "DEF" => "N",
  "SORT" => "200"
}

$arFields["VALUES"][2] = Array(
  "VALUE" => "Зеленый",
  "DEF" => "Y",
  "SORT" => "300"
}

$ibp = new CIBlockProperty;
if(!$ibp->Update($ID, $arFields))
    echo $ibp->LAST_ERROR;
?


UpdateEnum

CIBlockProperty::UpdateEnum

CIBlockProperty::UpdateEnum(
 int ID,
 array arVALUES
);

Функция устанавливает значения перечислений свойства типа "список".

Параметры функции

Параметр | Описание
ID | Код свойства.
arVALUES | Массив всех значений в формате Array("код существующего значения"=>"массив полей значения", ..., "массив полей нового значения", ...). Где массив полей имеет вид: Array("VALUE"=>"значение"[, "SORT"=>"порядок сортировки"][, "DEF"=>"является значением по умолчанию (Y|N)"]).

Примечание

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

См. также

  • Поля значений свойства типа "список "
  • CIBlockPropetyEnum::Update()
  • CIBlockPropetyEnum::Add()

Примеры использования

<?
$cnt = 0;
$ar_all_values = Array();
$db_enum_list = CIBlockProperty::GetPropertyEnum($PROP_ID, Array('SORT'=>'ASC'));
while($ar_enum = $db_enum_list->Fetch())
{
    $cnt++;
    $ar_all_values[$ar_enum['ID']] = Array('SORT'=>$cnt, 'VALUE'=>$ar_enum['VALUE']);
}

CIBlockPropertyEnum::UpdateEnum($PROP_ID, $ar_all_values);
?>


CIBlockPropertyEnum

CIBlockPropertyEnum - класс для работы со вариантами значений свойств типа "список".

Методы класса

Метод | Описание
GetList | Возвращает список вариантов свойств по фильтру.
Add | Добавляет новый вариант свойства.
Update | Изменяет вариант свойства.
Delete | Удаляет вариант свойства.


Add

CIBlockPropertyEnum::Add

int
CIBlockPropertyEnum::Add(
 array fields
);

Функция добавляет новый вариант значения свойства типа "список".

Параметры функции

Параметр | Описание
fields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей варианта значения свойства.

Возвращаемое значение

Функция возвращает код добавленного свойства, если добавление прошло успешно, при возникновении ошибки функция вернет false.

См. также

  • CIBlockPropertyEnum::Update
  • Поля вариантов значения свойств типа "список"

Примеры использования

<?
$ibpenum = new CIBlockPropertyEnum;
if($PropID = $ibpenum->Add(Array('PROPERTY_ID'=>$PROPERTY_ID, 'VALUE'=>'New Enum 1')))
 echo 'New ID:'.$PropID;
?>


Delete

CIBlockPropertyEnum::Delete

bool
CIBlockPropertyEnum::Delete(
 int ID
);

Функция удаляет вариант значения свойства типа "список".

Параметры функции

Параметр | Описание
ID | Код варианта значения свойства.

Возвращаемое значение

В случае успешного удаления возвращается true, иначе - false.


GetList

CIBlockPropertyEnum::GetList

CDBResult
CIBlockPropertyEnum::GetList(
 array arOrder = Array("SORT"=>"ASC", "VALUE"=>"ASC"),
 array arFilter = Array()
);

Возвращает список вариантов значений свойств типа "список" по фильтру arFilter отсортированные в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки, имеющий вид by1=>order1[, by2=>order2 [, ..]], где
by - поле сортировки, может принимать значения:
id - код варианта значения;
value - значение варианта;
sort - индекс сортировки варианта;
external_id - внешний код варианта значения;
def - по признаку "значение по умолчанию";
property_id - код свойства;
property_sort - индекс сортировки свойства;
property_code - мнемонический код свойства;
order - порядок сортировки, может принимать значения:
asc - по возрастанию;
desc - по убыванию;
arFilter Массив вида array("фильтруемое поле"=>"значение" [, ...])
"фильтруемое поле" может принимать значения:
VALUE - по значению (по шаблону [%_]);
ID - по коду значения варианта свойства;
SORT - по индексу сортировки варианта свойства;
DEF - по параметру "значение по умолчанию" (Y|N);
EXTERNAL_ID - по внешнему коду(по шаблону [%_]);
CODE - по мнемоническому коду свойства (по шаблону [%_]);
PROPERTY_ID - по числовому или мнемоническому коду свойства;
IBLOCK_ID - фильтр по коду информационного блока, которому принадлежит свойство;
Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля варианта значений свойства типа "список"

Примеры использования

<?
$property_enums = CIBlockPropertyEnum::GetList(Array("DEF"=>"DESC", "SORT"=>"ASC"), Array("IBLOCK_ID"=>$IBLOCK_ID, "CODE"=>"COLORS"));
while($enum_fields = $property_enums->GetNext())
{
  echo $enum_fields["ID"]." - ".$enum_fields["VALUE"]."<br>";
}
?>


Update

CIBlockPropertyEnum::Update

bool
CIBlockPropertyEnum::Update(
 int ID,
 array arFields
);

Функция изменяет параметры варианта свойства с кодом ID.

Параметры функции

Параметр | Описание
ID | ID изменяемой записи.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей варианта значения свойства.

Возвращаемое значение

Функция возвращает true если изменение прошло успешно, при возникновении ошибки метод вернет false.

См. также

  • CIBlockPropertyEnum::Add
  • Поля свойства

Примеры использования

<?
$ibpenum = new CIBlockPropertyEnum;
$ibpenum->Update($PROPERTY_ENUM_ID, Array('VALUE'=>'Enum 1'));
?>


CIBlockResult

CIBlockResult - вспомогательный класс для работы с объектами результатов выборок, наследуется от класса CDBResult и содержит все его параметры и методы. Объекты данного класса возвращают функции: CIBlockElement::GetList, CIBlockElement::GetByID, GetIBlockElementList и GetIBlockElementListEx. Использование методов этого объекта позволяет более гибко и эффективно работать с элементами информационных блоков.

Методы класса

Метод | Описание
GetNext | Возвращает из выборки список полей элемента, с замененными ссылками в полях DETAIL_PAGE_URL и LIST_PAGE_URL.
GetNextElement | Возвращает объект _CIBElement элемента из выборки.


GetNext

CIBlockResult::GetNext

mixed
CIBlockResult::GetNext();

Возвращает массив значений полей приведенный в HTML безопасный вид. Также в полях DETAIL_PAGE_URL и LIST_PAGE_URL заменяются шаблоны вида #IBLOCK_ID# и т.п. на их реальные значения, в результате чего в этих полях будут ссылки на страницу детального просмотра и страницу списка элементов.

Возвращаемое значение

Метод возвращает массив с полями элемента информационного блока вида Array("поле"=>"преобразованное значение" [, ...]) и передвигает курсор на следующую запись.
Если достигнута последняя запись (или в результате нет ни одной записи) функция вернет false.

См. также

  • CDBResult
  • CIBlockResult::GetNextElement()
  • Поля элемента информационного блока
  • CIBlockElement::GetList()

Примеры использования

<?
$res = CIBlockElement::GetByID($_GET["PID"]);
if($ar_res = $res->GetNext())
  echo '<a href="'.$ar_res['detail_page_url'].'">'.$ar_res['name'].'</a>';
?>


GetNextElement

CIBlockResult::GetNextElement

_CIBElement
CIBlockResult::GetNextElement();

Метод возвращает из выборки объект _CIBElement.

Возвращаемое значение

Метод возвращает из выборки объект _CIBElement, и передвигает курсор на следующую запись.
Если достигнута последняя запись (или в результате нет ни одной записи) функция вернет false.

См. также

  • _CIBElement
  • CIBlockResult::GetNext()
  • CIBlockElement::GetList()

Примеры использования

<?
$res = CIBlockElement::GetByID($_GET["PID"]);
if($obRes = $res->GetNextElement())
{
  $ar_res = $obRes->GetFields();
  echo $ar_res['NAME'];
}
?>


CIBlockSection

CIBlockSection - класс для работы с разделами (группами) информационных блоков.

Методы класса

Метод | Описание
GetList | Возвращает список разделов по фильтру.
GetByID | Возвращает параметры раздела по его коду ID.
Add | Добавляет в информационный блок новый раздел.
Update | Изменяет параметры существующего раздела.
Delete | Удаляет раздел из информационного блока.
GetCount | Возвращает количество подразделов.
GetSectionElementsCount | Возвращает количество элементов в разделе.
GetTreeList | Возвращает разделы отсортированные в порядке "полностью развернутого дерева"
GetNavChain | Возвращает путь от заданного раздела до корневого.
ReSort | Пересчет левой и правой границ.


Add

CIBlockSection::Add

int
Add(
 array arFields,
 bool bResort = true,
 bool bUpdateSearch = true
);

Метод добавляет новый раздел в информационный блок.

Параметры функции

Параметр | Описание
arFields | Массив вида Array("поле"=>"значение", ...), содержащий значения полей раздела инфоблоков.
bResort | Флаг, указывающий пересчитывать ли правую и левую границы после изменения (поля LEFT_MARGIN и RIGHT_MARGIN). Установите значение в false, если необходимо выполнить серию добавлений, в этом случае для повышения производительности можно установить параметр в false, а после всех изменений вызвать метод CIBlockSection::ReSort()
bUpdateSearch | Флаг, указывающий, что раздел должен быть проиндексирован для поиска сразу же после сохранения.

Возвращаемое значение

Метод возвращает код добавленного раздела блока, если добавление прошло успешно. При возникновении ошибки функция вернет false, а в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

См. также

  • CIBlockSection::Update

Примеры использования

<?
$bs = new CIBlockSection;
$arFields = Array(
  "ACTIVE" => $ACTIVE,
  "IBLOCK_SECTION_ID" => $IBLOCK_SECTION_ID,
  "IBLOCK_ID" => $IBLOCK_ID,
  "NAME" => $NAME,
  "SORT" => $SORT,
  "PICTURE" => $_FILES["PICTURE"],
  "DESCRIPTION" => $DESCRIPTION,
  "DESCRIPTION_TYPE" => $DESCRIPTION_TYPE
  );

if($ID > 0)
{
  $res = $bs->Update($ID, $arFields);
}
else
{
  $ID = $bs->Add($arFields);
  $res = ($ID>0);
}

if(!$res)
  echo $bs->LAST_ERROR;
?>


Delete

CIBlockSection::Delete

bool
CIBlockSection::Delete(
 int ID
);

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

Параметры функции

Параметр | Описание
ID | Код раздела.

Возвращаемое значение

Возвращается true в случае успешного удаления, иначе возвращается false.

Примеры использования

<?
if(CIBlock::GetPermission($IBLOCK_ID)>='W')
{
    $DB->StartTransaction();
    if(!CIBlockSection::Delete($SECTION_ID))
    {
        $strWarning .= 'Error.';
        $DB->Rollback();
    }
    else
        $DB->Commit();
}
?>


GetByID

CIBlockSection::GetByID

CDBResult
GetByID(
 int ID
);

Возвращает параметры раздела по его коду ID.

Параметры функции

Параметр | Описание
ID | Код раздела.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля раздела

Примеры использования

<?
$res = CIBlockSection::GetByID($_GET["GID"]);
if($ar_res = $res->GetNext())
  echo $ar_res['NAME'];
?>


GetCount

CIBlockSection::GetCount

int
CIBlockSection::GetCount(
 array arFilter = Array()
);

Возвращает количество разделов, удовлетворяющих фильтру arFilter.

Параметры функции

Параметр Описание
arFilter Массив вида array("фильтруемое поле"=>"значение" [, ...])
"фильтруемое поле" может принимать значения:
ACTIVE - фильтр по активности (Y|N);
GLOBAL_ACTIVE - фильтр по активности, учитывая активность вышележащих разделов (Y|N);
NAME - по названию (можно искать по шаблону [%_]);
CODE - по мнемоническому коду (по шаблону [%_]);
EXTERNAL_ID - по внешнему коду (по шаблону [%_]);
SECTION_ID - по коду раздела-родителя;
DEPTH_LEVEL - по уровню вложенности;
LEFT_BORDER, RIGHT_BORDER - по левой и правой границе (поля LEFT_MARGIN и RIGHT_MARGIN, см. примечание);
ID - по коду раздела;
IBLOCK_ID - по коду родительского информационного блока;
IBLOCK_ACTIVE - по активности родительского информационного блока;
IBLOCK_NAME - по названию информационного блока (по шаблону [%_]);
IBLOCK_TYPE - по типу информационного блока;
IBLOCK_CODE - по мнемоническому коду информационного блока (по шаблону [%_]);
IBLOCK_EXTERNAL_ID - по внешнему коду информационного блока (по шаблону [%_]);

Перед названием фильтруемого поля можно указать тип фильтрации:
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

"значения фильтра" одиночное значение или массив.

Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Число - количество разделов.

См. также

  • CIBlockSection::GetList()

Примеры использования

<?
    $arFilter = Array(
        "IBLOCK_ID"=>$IBLOCK_ID,
        "SECTION_ID"=>$f_ID
        );

    echo CIBlockSection::GetCount($arFilter);
?>


GetList

CIBlockSection::GetList

CDBResult
CIBlockSection::GetList(
 array arOrder = Array("SORT"=>"ASC"),
 array arFilter = Array(),
 bool bIncCnt = false
);

Возвращает список разделов, отсортированных в порядке arOrder по фильтру arFilter.

Параметры функции

Параметр Описание
arOrder Массив для сортировки, имеющий вид by1=>order1[, by2=>order2 [, ..]], где by1, ... - поле сортировки, может принимать значения:
  • id - код группы;
  • section - код родительской группы;
  • name - название группы;
  • active - активности группы;
  • left_margin - левая граница;
  • depth_level - глубина вложенности;
  • sort - индекс сортировки;
  • element_cnt - количество элементов в группе, работает только если bIncCnt = true;
  • timestamp_x - по времени последнего изменения.
order1, ... - порядок сортировки, может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию.
arFilter Массив вида array("фильтруемое поле"=>"значение" [, ...]). Фильтруемое поле может принимать значения:
  • ACTIVE - фильтр по активности (Y|N);
  • GLOBAL_ACTIVE - фильтр по активности, учитывая активность вышележащих разделов (Y|N);
  • NAME - по названию (можно искать по шаблону [%_]);
  • CODE - по мнемоническому коду (по шаблону [%_]);
  • EXTERNAL_ID - по внешнему коду (по шаблону [%_]);
  • SECTION_ID - по коду раздела-родителя;
  • DEPTH_LEVEL - по уровню вложенности;
  • LEFT_BORDER, RIGHT_BORDER - по левой и правой границе (поля LEFT_MARGIN и RIGHT_MARGIN, см. примечание);
  • ID - по коду раздела;
  • IBLOCK_ID - по коду родительского информационного блока;
  • IBLOCK_ACTIVE - по активности родительского информационного блока;
  • IBLOCK_NAME - по названию информационного блока (по шаблону [%_]);
  • IBLOCK_TYPE - по типу информационного блока;
  • IBLOCK_CODE - по мнемоническому коду информационного блока (по шаблону [%_]);
  • IBLOCK_EXTERNAL_ID - по внешнему коду информационного блока (по шаблону [%_]);
  • PROPERTY - по значениям свойств внутрилежащих элементов, PROPERTY - массив вида Array("код свойства"=>"значение", ...).
Все фильтруемые поля могут содержать перед названием тип проверки фильтра.

Значения фильтра одиночное значение или массив.

Необязательное. По умолчанию записи не фильтруются.
bIncCnt Возвращать ли поле ELEMENT_CNT - количество элементов в разделе.

Необязательный параметр, по умолчанию равен false.

Возвращаемое значение

Возвращается объект CDBResult

Примечание

Поле для сортировки left_margin, так называемая "сквозная" сортировка, высчитывается на основании поля sort, уровня вложенности и сортировкой верхнего уровня. Отличие полей sort и left_margin в том, что sort указывается пользователем, для сортировки разделов между собой в пределах одного раздела-родителя, а вычисляемое left_margin предназначено для сортировки во всем информационном блоке.

См. также

  • CDBResult
  • Поля раздела информационного блока

Примеры использования

<?
$arIBTYPE = CIBlockType::GetByIDLang($type, LANGUAGE_ID);
if($arIBTYPE!==false)
{
  // выборка только активных разделов из инфоблока $IBLOCK_ID, в которых есть элементы
  // со значением свойства SRC, начинающееся с https://
  $arFilter = Array('IBLOCK_ID'=>$IBLOCK_ID, 'GLOBAL_ACTIVE'=>'Y', 'PROPERTY'=>Array('SRC'=>'https://%'));
  $db_list = CIBlockSection::GetList(Array($by=>$order), $arFilter, true);
  $db_list->NavStart(20);
  echo $db_list->NavPrint($arIBTYPE["SECTION_NAME"]);
  while($ar_result = $db_list->GetNext())
  {
    echo $ar_result['ID'].' '.$ar_result['NAME'].': '.$ar_result['ELEMENT_CNT'].'<br>';
  }
  echo $db_list->NavPrint($arIBTYPE["SECTION_NAME"]);
}
?>


GetNavChain

CIBlockSection::GetNavChain

CDBResult
CIBlockSection::GetNavChain(
 int IBLOCK_ID,
 int SECTION_ID
);
Функция возвращает путь по дереву от корня до раздела SECTION_ID.

Параметры функции

Параметр | Описание
IBLOCK_ID | Код информационного блока, служит для проверки что раздел SECTION_ID, находится в заданном информационном блоке. Если значение IBLOCK_ID ноль, то проверка не будет выполнена и код информационного блока не будет учитываться.
SECTION_ID | Код раздела информационного раздела, путь до которого будет выбран.

Возвращаемое значение

Возвращается объект CDBResult с полями раздела информационного блока.

См. также

  • CDBResult
  • Поля раздела информационного блока

Примеры использования

<?
$nav = CIBlockSection::GetNavChain(false, $SECTION_ID);
while($nav->ExtractFields("nav_")):
?> &raquo;
  <?if($SECTION_ID == $nav_ID):?>
    <?echo $nav_NAME?>
  <?else:?>
    <a class="navchain" href="<?=$application->getcurpage()?>?iblock_id=<?=$iblock_id?>&section_id=<?=$nav_id?>#tb"><?echo $nav_NAME?></a>
  <?endif?>
<?endwhile;?>


GetSectionElementsCount

CIBlockSection::GetSectionElementsCount

int
CIBlockSection::GetSectionElementsCount(
 int ID,
 array arFilter = Array()
);

Функция считает количество элементов внутри раздела ID, учитывая фильтр arFilter.

Параметры функции

Параметр | Описание
ID | Код раздела.
arFilter | Массив вида Array("фильтруемое поле"=>"значение", ...), где фильтруемое поле может принимать значения: CNT_ACTIVE - активные элементы (Y|N), CNT_ALL - учитывать ещё не опубликованные элементы (если установлен модуль документооборота), PROPERTY - массив для фильтрации элементов по значениям свойств, вида Array("код свойства"=>"значение", ...),

Примечание

Функция устаревшая, для получения количества рекомендуется использовать функцию CIBlockElement::GetList() с установленным параметром для группировки.

См. также

  • CIBlockElement::GetList()


GetTreeList

CIBlockSection::GetTreeList

CDBResult
CIBlockSection::GetTreeList(
 array arFilter=Array()
);

Функция возвращает список разделов, отсортированный в порядке "полного развернутого дерева". По сути является оберткой функции CIBlockSection::GetList() с предустановленным параметром сортировки:

CIBlockSection::GetList(Array("left_margin"=>"asc"), $arFilter);

См. также

  • CIBlockSection::GetList()


Resort

CIBlockSection::Resort

CIBlockSection::Resort(
 int IBLOCK_ID
);

Функция пересчитывает параметры левой и правой границ для всех разделов информационного блока IBLOCK_ID. Должна использоваться после применения серии добавлений или изменений разделов при помощи функций CIBlockSection::Add() или CIBlockSection::Update() c отключенным параметром bReSort, в целях повышения производительности.

Параметры функции

Параметр | Описание
IBLOCK_ID | код информационного блока.

См. также

  • CIBlockSection::Add()
  • CIBlockSection::Update()

    Примеры использования

    <?
$obSect = new CIBlockSection;
for($i=0; $i<100; $i++)
{
  $obSect->Add(Array('NAME'=>'Section #'.$i, 'IBLOCK_ID'=>$IBLOCK_ID), false);
}

CIBlockSection::ReSort($IBLOCK_ID);
?>


Update

CIBlockSection::Update

bool
CIBlockSection::Update(
 int ID,
 array arFields,
 bool bResort = true,
 bool bUpdateSearch = true
);

Метод изменяет параметры раздела с кодом ID.

Параметры функции

Параметр | Описание
ID | Код изменяемой записи.
arFields | Массив вида Array("поле"=>"значение", ...), содержащий значения полей раздела инфоблоков.
bResort | Флаг, указывающий пересчитывать ли правую и левую границы после изменения (поля LEFT_MARGIN и RIGHT_MARGIN). Установите значение в false, в случае если поля которые влияют на значения границ не изменяются или необходимо выполнить серию изменений, в последнем случае для повышения производительности можно установить параметр в false, а после всех изменений вызвать метод CIBlockSection::ReSort()
bUpdateSearch | Флаг, указывающий, что раздел должен быть проиндексирован для поиска сразу же после сохранения.

Возвращаемое значение

Метод возвращает true если изменение прошло успешно, при возникновении ошибки функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CIBlockSection::Add

Примеры использования

<?
$bs = new CIBlockSection;

$arPICTURE = $_FILES["PICTURE"];
$arPICTURE["MODULE_ID"] = "iblock";

$arFields = Array(
  "ACTIVE" => $ACTIVE,
  "IBLOCK_SECTION_ID" => $IBLOCK_SECTION_ID,
  "IBLOCK_ID" => $IBLOCK_ID,
  "NAME" => $NAME,
  "SORT" => $SORT,
  "PICTURE" => $arPICTURE,
  "DESCRIPTION" => $DESCRIPTION,
  "DESCRIPTION_TYPE" => $DESCRIPTION_TYPE
  );

if($ID > 0)
{
  $res = $bs->Update($ID, $arFields);
}
else
{
  $ID = $bs->Add($arFields);
  $res = ($ID>0);
}
?>


CIBlockType

CIBlockType - класс для работы с типами информационных блоков.

Методы класса

Метод | Описание
GetList | Возвращает список типов по фильтру.
GetByID | Возвращает тип по идентификатору.
GetByIDLang | Возвращает настройки типа для заданного языка.
Add | Добавляет новый тип информационных блоков.
Update | Изменяет тип.
Delete | Удаляет тип информационных блоков.


Add

CIBlockType::Add

bool
CIBlockType::Add(
 array arFields
);

Метод добавляет новый тип информационных блоков. Этот метод не может быть использован как статическая функция. В случае ошибки в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

Параметры метода

Параметр | Описание
arFields | Массив поле=>значение... Содержит значения полей типа информационных блоков. В элементе массива arFields["LANG"] должен содержаться массив языковых свойств типа.

Возвращаемое значение

true, если тип успешно добавлен или false в противном случае.

См. также

  • CIBlockType::Update()
  • Поля типа информационных блоков

Примеры использования

<?
$arFields = Array(
    'ID'=>'catalog',
    'SECTIONS'=>'Y',
    'IN_RSS'=>'N',
    'SORT'=>100,
    'LANG'=>Array(
        'en'=>Array(
            'NAME'=>'Catalog',
            'SECTION_NAME'=>'Sections',
            'ELEMENT_NAME'=>'Products'
            )
        )
    );

$obBlocktype = new CIBlockType;
$DB->StartTransaction();
$res = $obBlocktype->Add($arFields);
if(!$res)
{
   $DB->Rollback();
   echo 'Error: '.$obBlocktype->LAST_ERROR.'<br>';
}
else
   $DB->Commit();
?>


Delete

CIBlockType::Delete

bool
CIBlockType::Delete(
 string ID
);

Функция удаляет тип информационных блоков по его коду ID.

Параметры функции

Параметр | Описание
ID | Код типа.

Возвращаемое значение

Возвращается true в случае успешного удаления, иначе возвращает false.

Примеры использования

<?
$DB->StartTransaction();
if(!CIBlockType::Delete('catalog'))
{
    $DB->Rollback();
    echo 'Delete error!';
}
$DB->Commit();
?>


GetByID

CIBlockType::GetByID

CDBResult
CIBlockType::GetByID(
 string ID
);

Возвращает тип информационных блоков по его коду ID.

Параметры функции

Параметр | Описание
ID | Код типа.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля CIBlockType


GetByIDLang

CIBlockType::GetByIDLang

mixed
CIBlockType::GetByIDLang(
 string ID,
 string LANGUAGE_ID,
 bool bFindAny = true
);

Метод возвращает языковые настройки типа информационных блоков по его коду ID, для языка LANGUAGE_ID. Если для языка LANGUAGE_ID нет настроек и параметр bFindAny установлен в true, функция вернет настройки типа для языка по умолчанию.

Параметры функции

Параметр | Описание
ID | Код типа.

Возвращаемое значение

Если языковые настройки найдены, то метод возвратит массив полей типа информационных блоков, в противном случае метод вернет false.

См. также

  • Поля CIBlockType

Примеры использования

<?
$db_iblock_type = CIBlockType::GetList();
while($ar_iblock_type = $db_iblock_type->Fetch())
{
   if($arIBType = CIBlockType::GetByIDLang($ar_iblock_type["ID"], LANG))
   {
      echo htmlspecialcharsex($arIBType["NAME"])."<br>";
   }
}
?>


GetList

CIBlockType::GetList

CDBResult
CIBlockType::GetList(
 array arOrder = Array("SORT"=>"ASC"),
 array arFilter = Array()
);

Возвращает список типов информационных блоков по фильтру arFilter с сортировкой arOrder.

Параметры функции

Параметр | Описание
arOrder | Массив полей для сортировки, содержащий пары "поле сортировки"=>"направление сортировки". Поля сортировки могут принимать значения id - код типа; sort - индекс сортировки;
arFilter | Массив вида array("фильтруемое поле"=>"значение" [, ...]) может принимать значения ID - по коду типа; Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля CIBlockType

Примеры использования

<?
$db_iblock_type = CIBlockType::GetList();
while($ar_iblock_type = $db_iblock_type->Fetch())
{
   if($arIBType = CIBlockType::GetByIDLang($ar_iblock_type["ID"], LANG))
   {
      echo htmlspecialcharsex($arIBType["NAME"])."<br>";
   }
}
?>


Update

CIBlockType::Update

bool
CIBlockType::Update(
 string ID,
 array arFields
);

Функция изменяет параметры типа информационных блоков с кодом ID.

Параметры функции

Параметр | Описание
ID | Код изменяемой записи.
arFields | Массив поле=>значение... Содержит значения полей типа информационных блоков. В элементе массива arFields["LANG"] должен содержаться массив языковых свойств типа.

Возвращаемое значение

Функция возвращает true если изменение прошло успешно, при возникновении ошибки функция вернет false, а в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CIBlockType::Add()
  • Поля типа информационных блоков

Примеры использования

<?
$arFields = Array(
    'SECTIONS'=>'Y',
    'IN_RSS'=>'N',
    'SORT'=>100,
    'LANG'=>Array(
        'en'=>Array(
            'NAME'=>'Catalog',
            'SECTION_NAME'=>'Sections',
            'ELEMENT_NAME'=>'Products'
            )
        )
    );

$obBlocktype = new CIBlockType;
$DB->StartTransaction();
$res = $obBlocktype->Update('catalog', $arFields);
if(!$res)
{
   $DB->Rollback();
   echo 'Error: '.$obBlocktype->LAST_ERROR.'<br>';
}
else
   $DB->Commit();
?>


_CIBElement

_CIBElement - вспомогательный класс для работы с объектами, которые возвращает CIBlockResult::GetNextElement. Для получения различных характеристик элемента рекомендуется использовать именно этот класс, т.к. использование методов этого объекта позволяет более гибко и эффективно работать с элементами информационных блоков.

Методы класса

Метод | Описание
GetFields | Возвращает массив полей элемента, с замененными ссылками в полях DETAIL_PAGE_URL и LIST_PAGE_URL.
GetProperties | Возвращает все или некоторые значения свойств элемента.
GetProperty | Возвращает значения свойства элемента.
GetGroups | Возвращает группы, к которым привязан элемент.


GetFields

array
_CIBElement::GetFields();

Возвращает массив значений полей приведенный в HTML безопасный вид. Также в полях DETAIL_PAGE_URL и LIST_PAGE_URL заменяются шаблоны вида #IBLOCK_ID# и т.п. на их реальные значения, в результате чего в этих полях будут ссылки на страницу детального просмотра и страницу списка элементов.

Возвращаемое значение

Метод возвращает массив с полями элемента информационного блока вида Array("поле"=>"преобразованное значение" [, ...]).

См. также

  • CIBlockResult::GetNext()
  • Поля элемента информационного блока
  • CIBlockElement::GetList()

Примеры использования

<?
$res = CIBlockElement::GetByID($_GET["PID"]);
if($obRes = $res->GetNextElement())
{
  $ar_res = $obRes->GetFields();
  echo '<a href="'.$ar_res['detail_page_url'].'">'.$ar_res['name'].'</a>';
}
?>


GetGroups

CDBResult
_CIBElement::GetGroups();

Возвращает группы, которым принадлежит текущий элемент.

Возвращаемое значение

Возвращается объект CDBResult с полями разделов.

См. также

  • CDBResult
  • Поля раздела
  • CIBlockElement::GetElementGroups

Примеры использования

<?
$res = CIBlockElement::GetByID($_GET["PID"]);
if($obRes = $res->GetNextElement())
{
  $ar_res = $obRes->GetGroups();
  print_r($ar_res);
}
?>


GetProperties

array
_CIBElement::GetProperties(
   arOrder = Array("sort" => "asc"),
   arFilter = Array()
);

Метод возвращает значения свойств текущего элемента информационного блока .

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
id - по ключу,
name - по имени свойства,
active - по активности свойства,
sort - по индексу сортировки свойства.
order - порядок сортировки, может принимать значения
asc - по возрастанию,
desc - по убыванию.
arFilter Массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения:
NAME - название свойства;
ID - код свойства;
ACTIVE - активность свойства (Y|N), по умолчанию выводятся только активные свойства, если необходимо вывести все значения, то установите ACTIVE в пустое значение;
PROPERTY_TYPE - тип свойства;
CODE - мнемонический код свойства;
EMPTY - пустота значения свойства (Y|N). По умолчанию выводятся все свойства и имеющие непустые значения и без значений.
Не обязательный параметр, по умолчанию равен array().

Возвращаемое значение

Метод возвращает массив значений свойств, где:
  • в качестве индексов массива "Символьный код свойства" (задается в настройках информационного блока) или, если символьный код свойства не указан, то уникальный числовой ID свойства.
  • значением массива будет массив полей свойства и дополнительно поля со значениями свойства:
    "VALUE" => "значение свойства или массив значений свойств, если свойство множественное",
    "VALUE_ENUM_ID" => "код варианта значения для свойства типа "Список" (массив или единичное значение)",
    "DESCRIPTION" => "описание значения свойства (массив или единичное значение)",
    "PROPERTY_VALUE_ID" => "код значения свойства (массив или единичное значение)"

    См. также

    • _CIBElement::GetProperties()
    • CIBlockElement::GetProperty()

    Примеры использования

    <?
    include($_SERVER['DOCUMENT_ROOT'].'/bitrix/header.php');
    if(CModule::IncludeModule('iblock'))
    {
        $dbEl = CIBlockElement::GetList(Array(), Array("IBLOCK_TYPE"=>"catalog", "IBLOCK_ID"=>11));
        if($obEl = $dbEl->GetNextElement())
        {
            $props = $obEl->GetProperties();
            echo "<pre>";
            print_r($props);
            echo "</pre>";
        }
    }
    ?>
    <?include($_SERVER['DOCUMENT_ROOT'].'/bitrix/footer.php');?>
    Вывод примера:

Array
(
    [27] => Array
        (
            [ID] => 27
            [TIMESTAMP_X] => 20041222191551
            [IBLOCK_ID] => 11
            [NAME] => Battery
            [ACTIVE] => Y
            [SORT] => 500
            [CODE] =>
            [DEFAULT_VALUE] =>
            [PROPERTY_TYPE] => L
            [ROW_COUNT] => 1
            [COL_COUNT] => 30
            [LIST_TYPE] => L
            [MULTIPLE] => Y
            [XML_ID] =>
            [FILE_TYPE] =>
            [MULTIPLE_CNT] => 5
            [TMP_ID] =>
            [WITH_DESCRIPTION] =>
            [LINK_IBLOCK_ID] => 0
            [VALUE_TYPE] => text
            [VALUE_ENUM] => Li-Mon
            [VALUE] => Array
                (
                    [0] => Li-Test
                    [1] => Li-NEW
                    [2] => Li-Mon
                )

            [~VALUE] => Array
                (
                    [0] => Li-Test
                    [1] => Li-NEW
                    [2] => Li-Mon
                )

            [DESCRIPTION] => Array
                (
                    [0] =>
                    [1] =>
                    [2] =>
                )

            [~DESCRIPTION] => Array
                (
                    [0] =>
                    [1] =>
                    [2] =>
                )

            [PROPERTY_VALUE_ID] => Array
                (
                    [0] => 53860
                    [1] => 53861
                    [2] => 53862
                )

            [VALUE_ENUM_ID] => Array
                (
                    [0] => 18
                    [1] => 19
                    [2] => 20
                )

            [~NAME] => Battery
            [~DEFAULT_VALUE] =>
        )

    [28] => Array
        (
            [ID] => 28
            [TIMESTAMP_X] => 20041222191551
            [IBLOCK_ID] => 11
            [NAME] => Screen
            [ACTIVE] => Y
            [SORT] => 500
            [CODE] =>
            [DEFAULT_VALUE] =>
            [PROPERTY_TYPE] => S
            [ROW_COUNT] => 1
            [COL_COUNT] => 30
            [LIST_TYPE] => L
            [MULTIPLE] => Y
            [XML_ID] =>
            [FILE_TYPE] =>
            [MULTIPLE_CNT] => 5
            [TMP_ID] =>
            [WITH_DESCRIPTION] =>
            [LINK_IBLOCK_ID] => 0
            [VALUE_TYPE] =>
            [VALUE_ENUM] =>
            [VALUE] => Color
            [~VALUE] => Color
            [DESCRIPTION] =>
            [~DESCRIPTION] =>
            [PROPERTY_VALUE_ID] => 32862
            [~NAME] => Screen
            [~DEFAULT_VALUE] =>
        )

    [29] => Array
        (
            [ID] => 29
            [TIMESTAMP_X] => 20041222191551
            [IBLOCK_ID] => 11
            [NAME] => PropertyX
            [ACTIVE] => Y
            [SORT] => 500
            [CODE] =>
            [DEFAULT_VALUE] =>
            [PROPERTY_TYPE] => N
            [ROW_COUNT] => 1
            [COL_COUNT] => 30
            [LIST_TYPE] => L
            [MULTIPLE] => Y
            [XML_ID] =>
            [FILE_TYPE] =>
            [MULTIPLE_CNT] => 5
            [TMP_ID] =>
            [WITH_DESCRIPTION] =>
            [LINK_IBLOCK_ID] => 0
            [VALUE_TYPE] =>
            [VALUE_ENUM] =>
            [VALUE] =>
            [~VALUE] =>
            [DESCRIPTION] =>
            [~DESCRIPTION] =>
            [PROPERTY_VALUE_ID] =>
            [~NAME] => PropertyX
            [~DEFAULT_VALUE] =>
        )
    [FORUM_TOPIC_ID] => Array
        (
            [ID] => 383
            [TIMESTAMP_X] => 20041223132810
            [IBLOCK_ID] => 11
            [NAME] => FORUM_TOPIC_ID
            [ACTIVE] => Y
            [SORT] => 500
            [CODE] => FORUM_TOPIC_ID
            [DEFAULT_VALUE] =>
            [PROPERTY_TYPE] => N
            [ROW_COUNT] => 1
            [COL_COUNT] => 30
            [LIST_TYPE] => L
            [MULTIPLE] => N
            [XML_ID] =>
            [FILE_TYPE] =>
            [MULTIPLE_CNT] => 5
            [TMP_ID] =>
            [WITH_DESCRIPTION] =>
            [LINK_IBLOCK_ID] => 0
            [VALUE_TYPE] =>
            [VALUE_ENUM] =>
            [VALUE] =>
            [~VALUE] =>
            [DESCRIPTION] =>
            [~DESCRIPTION] =>
            [PROPERTY_VALUE_ID] =>
            [~NAME] => FORUM_TOPIC_ID
            [~DEFAULT_VALUE] =>
        )
    [386] => Array
        (
            [ID] => 386
            [TIMESTAMP_X] => 20050119162457
            [IBLOCK_ID] => 11
            [NAME] => Photo
            [ACTIVE] => Y
            [SORT] => 500
            [CODE] =>
            [DEFAULT_VALUE] =>
            [PROPERTY_TYPE] => F
            [ROW_COUNT] => 1
            [COL_COUNT] => 30
            [LIST_TYPE] => L
            [MULTIPLE] => N
            [XML_ID] =>
            [FILE_TYPE] =>
            [MULTIPLE_CNT] => 5
            [TMP_ID] =>
            [WITH_DESCRIPTION] => Y
            [LINK_IBLOCK_ID] => 0
            [VALUE_TYPE] => text
            [VALUE_ENUM] =>
            [VALUE] => 2309
            [~VALUE] => 2309
            [DESCRIPTION] => HP
            [~DESCRIPTION] => HP
            [PROPERTY_VALUE_ID] => 53863
            [~NAME] => Photo
            [~DEFAULT_VALUE] =>
        )
)


GetProperty

array
_CIBElement::GetProperty(
   mixed ID
);

Метод возвращает параметры свойства ID и его значения для текущего элемента информационного блока.

Параметры функции

Параметр | Описание
ID | Числовой или мнемонический код свойства.

Возвращаемое значение

Метод возвращает массив полей свойства и дополнительно поля со значениями свойства:
VALUE => значение свойства или массив значений свойств, если свойство множественное,
VALUE_ENUM_ID => код варианта значения для свойства типа "Список" (массив или единичное значение),
DESCRIPTION => описание значения свойства (массив или единичное значение),
PROPERTY_VALUE_ID => код значения свойства (массив или единичное значение).

См. также

  • CIBlockElement::GetProperty()
  • _CIBElement::GetProperties()

Примеры использования

<?
$res = CIBlockElement::GetByID($_GET["PID"]);
if($obRes = $res->GetNextElement())
{
  $ar_res = $obRes->GetProperty("PHOTOS");
  print_r($ar_res);
}
?>
Вывод примера:

Array
(
    [ID] => 388
    [TIMESTAMP_X] => 20050119162457
    [IBLOCK_ID] => 11
    [NAME] => Photos with description
    [ACTIVE] => Y
    [SORT] => 500
    [CODE] =>
    [DEFAULT_VALUE] =>
    [PROPERTY_TYPE] => F
    [ROW_COUNT] => 1
    [COL_COUNT] => 30
    [LIST_TYPE] => L
    [MULTIPLE] => Y
    [XML_ID] =>
    [FILE_TYPE] =>
    [MULTIPLE_CNT] => 5
    [TMP_ID] =>
    [WITH_DESCRIPTION] => Y
    [LINK_IBLOCK_ID] => 0
    [VALUE_TYPE] => text
    [VALUE_ENUM] =>
    [VALUE] => Array
        (
            [0] => 2311
        )

    [~VALUE] => Array
        (
            [0] => 2311
        )

    [DESCRIPTION] => Array
        (
            [0] => Descr
        )

    [~DESCRIPTION] => Array
        (
            [0] => Descr
        )

    [PROPERTY_VALUE_ID] => Array
        (
            [0] => 53865
        )

    [~NAME] => Photos with description
    [~DEFAULT_VALUE] =>
)


События

Событие | Описание
OnBeforeIBlockAdd | Вызывается перед добавлением информационного блока.
OnAfterIBlockAdd | Вызывается после добавления информационного блока.
OnBeforeIBlockUpdate | Вызывается перед изменением информационного блока.
OnAfterIBlockUpdate | Вызывается после изменения информационного блока.
OnBeforeIBlockDelete | Вызывается перед удалением информационного блока.
OnIBlockDelete | Вызывается при удалении информационного блока.
OnBeforeIBlockPropertyAdd | Вызывается перед добавлением свойства.
OnAfterIBlockPropertyAdd | Вызывается после добавления свойства.
OnBeforeIBlockPropertyUpdate | Вызывается перед изменением свойства.
OnAfterIBlockPropertyUpdate | Вызывается после изменения свойства.
OnBeforeIBlockPropertyDelete | Вызывается перед удалением свойства.
OnBeforeIBlockSectionAdd | Вызывается перед добавлением раздела.
OnAfterIBlockSectionAdd | Вызывается после добавления раздела.
OnBeforeIBlockSectionUpdate | Вызывается перед изменением раздела.
OnAfterIBlockSectionUpdate | Вызывается после изменения раздела.
OnBeforeIBlockSectionDelete | Вызывается перед удалением раздела.
OnBeforeIBlockElementAdd | Вызывается перед добавлением элемента.
OnAfterIBlockElementAdd | Вызывается после добавления элемента.
OnBeforeIBlockElementUpdate | Вызывается перед изменением элемента.
OnAfterIBlockElementUpdate | Вызывается после изменения элемента.
OnBeforeIBlockElementDelete | Вызывается перед удалением элемента.
OnIBlockElementDelete | Вызывается при удалении элемента информационного блока.


OnAfterIBlockAdd

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockAdd" вызывается после попытки добавления нового информационного блока методом CIBlock::Add.

Параметры

Параметр | Описание
arFields | Массив полей нового информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlock::Add и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockAdd"
  • CIBlock::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockAdd", Array("MyClass", "OnAfterIBlockAddHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockAdd"
    function OnAfterIBlockAddHandler(&$arFields)
    {
        if($arFields["ID"]>0)
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." добавлена.");
        else
            AddMessage2Log("Ошибка добавления записи (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockElementAdd

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockElementAdd" вызывается после попытки добавления нового элемента информационного блока методом CIBlockElement::Add.

Параметры

Параметр | Описание
arFields | Массив полей нового элемента информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlockElement::Add и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockElementAdd"
  • CIBlockElement::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockElementAdd", Array("MyClass", "OnAfterIBlockElementAddHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockElementAdd"
    function OnAfterIBlockElementAddHandler(&$arFields)
    {
        if($arFields["ID"]>0)
             AddMessage2Log("Запись с кодом ".$arFields["ID"]." добавлена.");
        else
             AddMessage2Log("Ошибка добавления записи (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockElementUpdate

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockElementUpdate" вызывается после попытки изменения элемента информационного блока методом CIBlockElement::Update.

Параметры

Параметр | Описание
arFields | Массив полей изменяемого элемента информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlockElement::Update и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockElementUpdate"
  • CIBlockElement::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockElementUpdate", Array("MyClass", "OnAfterIBlockElementUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockElementUpdate"
    function OnAfterIBlockElementUpdateHandler(&$arFields)
    {
        if($arFields["RESULT"])
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." изменена.");
        else
            AddMessage2Log("Ошибка изменения записи ".$arFields["ID"]." (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockPropertyAdd

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockPropertyAdd" вызывается после попытки добавления нового свойства информационного блока методом CIBlockProperty::Add.

Параметры

Параметр | Описание
arFields | Массив полей нового свойства информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlockProperty::Add и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockPropertyAdd"
  • CIBlockProperty::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockPropertyAdd", Array("MyClass", "OnAfterIBlockPropertyAddHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockPropertyAdd"
    function OnAfterIBlockPropertyAddHandler(&$arFields)
    {
        if($arFields["ID"]>0)
             AddMessage2Log("Запись с кодом ".$arFields["ID"]." добавлена.");
        else
             AddMessage2Log("Ошибка добавления записи (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockPropertyUpdate

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockPropertyUpdate" вызывается после попытки изменения свойства информационного блока методом CIBlockProperty::Update.

Параметры

Параметр | Описание
arFields | Массив полей изменяемого свойства информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlockProperty::Update и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockPropertyUpdate"
  • CIBlockProperty::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockPropertyUpdate", Array("MyClass", "OnAfterIBlockPropertyUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockPropertyUpdate"
    function OnAfterIBlockPropertyUpdateHandler(&$arFields)
    {
        if($arFields["RESULT"])
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." изменена.");
        else
            AddMessage2Log("Ошибка изменения записи ".$arFields["ID"]." (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockSectionAdd

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockSectionAdd" вызывается после попытки добавления нового раздела информационного блока методом CIBlockSection::Add.

Параметры

Параметр | Описание
arFields | Массив полей нового раздела информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlockSection::Add и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockSectionAdd"
  • CIBlockSection::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockSectionAdd", Array("MyClass", "OnAfterIBlockSectionAddHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockSectionAdd"
    function OnAfterIBlockSectionAddHandler(&$arFields)
    {
        if($arFields["ID"]>0)
             AddMessage2Log("Запись с кодом ".$arFields["ID"]." добавлена.");
        else
             AddMessage2Log("Ошибка добавления записи (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockSectionUpdate

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockSectionUpdate" вызывается после попытки изменения раздела информационного блока методом CIBlockSection::Update.

Параметры

Параметр | Описание
arFields | Массив полей изменяемого раздела информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlockSection::Update и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockSectionUpdate"
  • CIBlockSection::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockSectionUpdate", Array("MyClass", "OnAfterIBlockSectionUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockSectionUpdate"
    function OnAfterIBlockSectionUpdateHandler(&$arFields)
    {
        if($arFields["RESULT"])
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." изменена.");
        else
            AddMessage2Log("Ошибка изменения записи ".$arFields["ID"]." (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnAfterIBlockUpdate

функция-обработчик(
 array &arFields
);
Событие "OnAfterIBlockUpdate" вызывается после попытки изменения информационного блока методом CIBlock::Update.

Параметры

Параметр | Описание
arFields | Массив полей изменяемого информационного блока. Дополнительно, в элементе массива с индексом "RESULT" содержится результат работы (возвращаемое значение) метода CIBlock::Update и, в случае ошибки, элемент с индексом "RESULT_MESSAGE" будет содержать текст ошибки.

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

См. также

  • Событие "OnBeforeIBlockUpdate"
  • CIBlock::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnAfterIBlockUpdate", Array("MyClass", "OnAfterIBlockUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnAfterIBlockUpdate"
    function OnAfterIBlockUpdateHandler(&$arFields)
    {
        if($arFields["RESULT"])
            AddMessage2Log("Запись с кодом ".$arFields["ID"]." изменена.");
        else
            AddMessage2Log("Ошибка изменения записи ".$arFields["ID"]." (".$arFields["RESULT_MESSAGE"].").");
    }
}
?>


OnBeforeIBlockAdd

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlock::Add до вставки информационного блока, и может быть использовано для отмены вставки или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей нового информационного блока.

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

Возвращаемое значение

Для отмены добавления и прекращении выполнения метода CIBlock::Add необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockAdd"
  • CIBlock::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockAdd", Array("MyClass", "OnBeforeIBlockAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockAdd"
    function OnBeforeIBlockAddHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код.");
            return false;
        }
    }
}
?>


OnBeforeIBlockDelete

bool
функция-обработчик(
   int ID
);

Вызывается перед удалением информационного блока.

Параметры

Параметр | Описание
ID | ID информационного блока.

Возвращаемое значение

Обработчик должен вернуть false в случае если необходимо отменить удаление информационного блока.

Примеры использования

<?
// Подключаем к событию обработчик
RegisterModuleDependences("iblock",
                          "OnBeforeIBlockDelete",
                          "catalog",
                          "CCatalog",
                          "OnIBlockDelete");

// Реализуем обработчик
class CCatalog
{
  * * *

  function OnBeforeIBlockDelete($ID)
  {
    return false;
  }
}

// Теперь нельзя удалить информационный блок.
?>


OnBeforeIBlockElementAdd

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlockElement::Add до вставки информационного блока, и может быть использовано для отмены вставки или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей нового элемента информационного блока.

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

Возвращаемое значение

Для отмены добавления и прекращении выполнения метода CIBlockElement::Add необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockElementAdd"
  • CIBlockElement::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockElementAdd", Array("MyClass", "OnBeforeIBlockElementAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockElementAdd"
    function OnBeforeIBlockElementAddHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код.");
            return false;
        }
    }
}
?>


OnBeforeIBlockElementDelete

bool
функция-обработчик(
 int ID
);
Событие "OnBeforeIBlockElementDelete" вызывается перед удалением элемента методом CIBlockElement::Delete. Как правило задачи обработчика данного события - разрешить или запретить удаление.

Параметры

Параметр | Описание
ID | ID удаляемого элемента.

Возвращаемое значение

Для отмены удаления элемента и прекращении выполнения метода CIBlockElement::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • CIBlockElement::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockElementDelete", Array("MyClass", "OnBeforeIBlockElementDeleteHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockElementDelete"
    function OnBeforeIBlockElementDeleteHandler($ID)
    {
        if($ID==1)
        {
            global $APPLICATION;
            $APPLICATION->throwException("элемент с ID=1 нельзя удалить.");
            return false;
        }
    }
}
?>


OnBeforeIBlockElementUpdate

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlockElement::Update до изменения элемента информационного блока, и может быть использовано для отмены изменения или для переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей изменяемого элемента информационного блока.

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

Возвращаемое значение

Для отмены изменения и прекращении выполнения метода CIBlockElement::Update необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockElementUpdate"
  • CIBlockElement::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockElementUpdate", Array("MyClass", "OnBeforeIBlockElementUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockElementUpdate"
    function OnBeforeIBlockElementUpdateHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код. (ID:".$arFields["ID"].")");
            return false;
        }
    }
}
?>


OnBeforeIBlockPropertyAdd

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlockProperty::Add до вставки информационного блока, и может быть использовано для отмены вставки или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей нового свойства информационного блока.

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

Возвращаемое значение

Для отмены добавления и прекращении выполнения метода CIBlockProperty::Add необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockPropertyAdd"
  • CIBlockProperty::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockPropertyAdd", Array("MyClass", "OnBeforeIBlockPropertyAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockPropertyAdd"
    function OnBeforeIBlockPropertyAddHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код.");
            return false;
        }
    }
}
?>


OnBeforeIBlockPropertyDelete

bool
функция-обработчик(
 int ID
);
Событие "OnBeforeIBlockPropertyDelete" вызывается перед удалением свойства методом CIBlockProperty::Delete. Как правило задачи обработчика данного события - разрешить или запретить удаление.

Параметры

Параметр | Описание
ID | ID удаляемого свойства.

Возвращаемое значение

Для отмены удаления свойства и прекращении выполнения метода CIBlockProperty::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • CIBlockProperty::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockPropertyDelete", Array("MyClass", "OnBeforeIBlockPropertyDeleteHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockPropertyDelete"
    function OnBeforeIBlockPropertyDeleteHandler($ID)
    {
        if($ID==1)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Свойство с ID=1 нельзя удалить.");
            return false;
        }
    }
}
?>


OnBeforeIBlockPropertyUpdate

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlockProperty::Update до изменения свойства информационного блока, и может быть использовано для отмены изменения или для переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей изменяемого свойства информационного блока.

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

Возвращаемое значение

Для отмены изменения и прекращении выполнения метода CIBlockProperty::Update необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockPropertyUpdate"
  • CIBlockProperty::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockPropertyUpdate", Array("MyClass", "OnBeforeIBlockPropertyUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockPropertyUpdate"
    function OnBeforeIBlockPropertyUpdateHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код. (ID:".$arFields["ID"].")");
            return false;
        }
    }
}
?>


OnBeforeIBlockSectionAdd

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlockSection::Add до вставки информационного блока, и может быть использовано для отмены вставки или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей нового раздела информационного блока.

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

Возвращаемое значение

Для отмены добавления и прекращении выполнения метода CIBlockSection::Add необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockSectionAdd"
  • CIBlockSection::Add
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockSectionAdd", Array("MyClass", "OnBeforeIBlockSectionAddHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockSectionAdd"
    function OnBeforeIBlockSectionAddHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код.");
            return false;
        }
    }
}
?>


OnBeforeIBlockSectionDelete

bool
функция-обработчик(
 int ID
);
Событие "OnBeforeIBlockSectionDelete" вызывается перед удалением раздела методом CIBlockSection::Delete. Как правило задачи обработчика данного события - разрешить или запретить удаление.

Параметры

Параметр | Описание
ID | ID удаляемого раздела.

Возвращаемое значение

Для отмены удаления раздела и прекращении выполнения метода CIBlockSection::Delete необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • CIBlockSection::Delete
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockSectionDelete", Array("MyClass", "OnBeforeIBlockSectionDeleteHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockSectionDelete"
    function OnBeforeIBlockSectionDeleteHandler($ID)
    {
        if($ID==1)
        {
            global $APPLICATION;
            $APPLICATION->throwException("раздел с ID=1 нельзя удалить.");
            return false;
        }
    }
}
?>


OnBeforeIBlockSectionUpdate

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlockSection::Update до изменения раздела информационного блока, и может быть использовано для отмены изменения или для переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей изменяемого раздела информационного блока.

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

Возвращаемое значение

Для отмены изменения и прекращении выполнения метода CIBlockSection::Update необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockSectionUpdate"
  • CIBlockSection::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockSectionUpdate", Array("MyClass", "OnBeforeIBlockSectionUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockSectionUpdate"
    function OnBeforeIBlockSectionUpdateHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код. (ID:".$arFields["ID"].")");
            return false;
        }
    }
}
?>


OnBeforeIBlockUpdate

bool функция-обработчик(
   array &arParams
);
Событие вызывается в методе CIBlock::Update до изменения информационного блока, и может быть использовано для отмены изменения или переопределения некоторых полей.

Параметры

Параметр | Описание
arParams | Массив полей изменяемого информационного блока.

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

Возвращаемое значение

Для отмены изменения и прекращении выполнения метода CIBlock::Update необходимо в функции-обработчике создать исключение методом $APPLICATION->ThrowException() и вернуть false.

См. также

  • Событие "OnAfterIBlockUpdate"
  • CIBlock::Update
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("iblock", "OnBeforeIBlockUpdate", Array("MyClass", "OnBeforeIBlockUpdateHandler"));

class MyClass
{
    // создаем обработчик события "OnBeforeIBlockUpdate"
    function OnBeforeIBlockUpdateHandler(&$arFields)
    {
        if(strlen($arFields["CODE"])<=0)
        {
            global $APPLICATION;
            $APPLICATION->throwException("Введите мнемонический код. (ID:".$arFields["ID"].")");
            return false;
        }
    }
}
?>


OnIBlockDelete

функция-обработчик(
   int ID
);

Вызывается в момент удаления информационного блока.

Параметры

Параметр | Описание
ID | ID информационного блока.

Примеры использования

<?
// Подключаем к событию обработчик
RegisterModuleDependences("iblock",
                          "OnIBlockDelete",
                          "catalog",
                          "CCatalog",
                          "OnIBlockDelete");

// Реализуем обработчик
class CCatalog
{
  * * *

  function OnIBlockDelete($ID)
  {
    return CCatalog::Delete($ID);
  }
}

// Теперь при удалении блока будет вызываться обработчик
?>


OnIBlockElementDelete

функция-обработчик(
   int ID
);

Вызывается в момент удаления элемента информационного блока.

Параметры

Параметр | Описание
ID | ID элемента информационного блока.

Примеры использования

<?
// Подключаем к событию обработчик
RegisterModuleDependences("iblock",
                          "OnIBlockElementDelete",
                          "catalog",
                          "CCatalogProduct",
                          "OnIBlockElementDelete");

// Реализуем обработчик
class CCatalogProduct
{
  * * *

  function OnIBlockElementDelete($PRODUCT_ID)
  {
    global $DB;
    echo "Удаляем...";
    return True;
  }
}

// Теперь при удалении элемента будет вызываться обработчик
?>


Функции для использования в публичной части

Метод | Описание
GetIBlockList | Возвращает список информационных блоков по фильтру.
GetIBlock | Возвращает информационный блок по заданному коду.
GetIBlockElementListEx | Возвращает список элементов по фильтру.
GetIBlockElementList | Возвращает список элементов из определённого информационного блока.
GetIBlockElement | Возвращает элемент по заданному коду.
GetIBlockSectionList | Возвращает список папок из определённого информационного блока.
GetIBlockSection | Возвращает раздел по заданному коду.


GetIBlock

array
GetIBlock(
 string ID,
 type = ""
);

Функция возвращает информационный блок по коду ID.

Параметры функции

Параметр | Описание
ID | ID информационного блока.
type | Тип информационного блока. Устанавливается в настройках модуля. Если задан, то при выборке проверяется чтобы информационный блок соответствовал этому типу. Необязательный. По умолчанию на информационный блок не накладываются ограничения по типу.

Возвращаемое значение

Функция возвращает массив полей информационного блока. Все возвращаемые поля преобразованы в "HTML безопасный" вид, а в полях (LIST_PAGE_URL - списка элементов и DETAIL_PAGE_URL - детального просмотра) с шаблонами для URL-ов заменены параметры #SITE_DIR# и #IBLOCK_ID#.
Если заданным параметрам не найден информационный блок, функция вернет false.

Примечание

Функция вернет поля информационного блока только в том случае, если информационный блок активен и привязан к текущему сайту.

См. также

  • Поля информационных блоков

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

$APPLICATION->SetTitle("Продукты");

// проверим установлен ли модуль и получим блок с кодом $BID и типом catalog
if(CModule::IncludeModule("iblock") && ($arIBlock = GetIBlock($_GET["BID"], "catalog")))
{
   // сделаем заголовок страницы таким же как название инф. блока
   $APPLICATION->SetTitle($arIBlock["NAME"]);
   //добавим название в навигационную цепочку
   $APPLICATION->AddChainItem($arIBlock["NAME"], $arIBlock["LIST_PAGE_URL"]);

   //работаем дальше с информационным блоком
   // ....
}
else
   ShowError("Информационный блок не найден.");

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


GetIBlockElement

array
GetIBlockElement(
 int ID,
 string type = ""
);

Функция возвращает информационный элемент с кодом ID.

Параметры функции

Параметр | Описание
ID | ID элемента.
type | Тип элемента. Устанавливается в настройках модуля. Если задан, то при выборке проверяется чтобы элемент соответствовал этому типу. Необязательный. По умолчанию на элемент не накладываются ограничения по типу.

Возвращаемое значение

Функция возвращает массив полей информационного элемента и дополнительно следующие поля:
IBLOCK_NAME - название информационного блока;
PROPERTIES - массив значений свойств, имеющий в качестве индексов "Символьный код свойства" (задается в настройках информационного блока) или, если код не задан, то уникальное ID свойства. Значением каждого свойства будет массив вида:
Array(
"NAME"=>"название свойства",
"DEFAULT_VALUE"=>"значение свойства по умолчанию",
"VALUE"=>"значение свойства или массив значений свойств, если свойство множественное",
"VALUE_ENUM_ID"=>"Код значения свойства типа <Список>"
) .
Если заданным параметрам не найден элемент, функция вернет false.
Выборка элемента происходит только из активных элементов инфоблока, неактивный элемент выбран быть не может.

Примечание

Все возвращаемые поля преобразованы в "HTML безопасный" вид, а в полях (LIST_PAGE_URL - списка элементов и DETAIL_PAGE_URL - детального просмотра) с шаблонами URL-ов к страницам будут заменены параметры #SITE_DIR#, #IBLOCK_ID#, #EXTERNAL_ID# и #ID#.

См. также

  • Поля информационного элемента

Примеры использования

<?
require($_SERVER['DOCUMENT_ROOT'].'/bitrix/header.php');

$APPLICATION->SetTitle('Карточка товара');

// подключим модуль и выберем элемент ID типа product
$arIBlockElement = false;
if(CModule::IncludeModule('iblock') && ($arIBlockElement = GetIBlockElement($ID, 'product')))
{
   // В заголовок страницы вставим название элемента
   $APPLICATION->SetTitle($arIBlockElement['NAME']);
   // В навигационную цепочку вставим название и ссылку на текущий информационный блок
   $APPLICATION->AddChainItem($arIBlockElement['IBLOCK_NAME'], 'products.php?ID='.$arIBlockElement['IBLOCK_ID']);

   // выведем детальную картинку
   echo ShowImage($arIBlockElement['DETAIL_PICTURE'], 150, 150, 'border="0"', '', true);
   // выведем детальное описание
   echo $arIBlockElement['DETAIL_TEXT'].'<br>';
   // выведем значение свойства с кодом PRICE
   echo $arIBlockElement['PROPERTIES']['PRICE']['VALUE'].'<br>';

   // вывeдем оставшиеся свойсва
   $arProps = $arIBlockElement['PROPERTIES'];
   foreach($arProps as $property_code=>$arValue)
   {
      // если это свойство с кодом PRICE или значение свойства не введено - пропустим
      if($property_code=='PRICE'
            || (!is_array($arValue['VALUE']) && strlen($arValue['VALUE'])<=0)
            || (is_array($arValue['VALUE']) && count($arValue['VALUE'])<=0)
            )
         continue;

      // выведем пару "Название: значение"
      if(!is_array($arValue['VALUE']))
         echo $arValue['NAME'].": ".$arValue['VALUE'];
      else
      {
         echo $arValue['NAME'].': ';
         foreach($arValue['VALUE'] as $val)
         {
            echo $val.'<br>';
         }
      }
   }
}
else
   echo ShowError('Новость не найдена');

require($_SERVER["DOCUMENT_ROOT"].'/bitrix/footer.php");
?>


GetIBlockElementList

CIBlockResult
GetIBlockElementList(
 int iblock_id,
 int section_id = false,
 array order = Array("SORT"=>"ASC"),
 int cnt = 0,
 array arFilter = Array()
);

Функция возвращает активные элементы из информационного блока iblock_id.

Параметры функции

Параметр | Описание
iblock_id | ID информационного блока из которого будут выбраны элементы.
section_id ID раздела, из которой требуется получить элементы. Для получения элементов из корня информационного блока (не привязанные ни к одному разделу) установите параметр section_id = 0.

Необязательный. По умолчанию (false) выбираются все записи без ограничения по папкам.
order Порядок сортировки - массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где by - поле для сортировки, может принимать значения:
  • sort - индекс сортировки;
  • timestamp_x - дата изменения;
  • name - название;
  • id - ID элемента;
  • active_from - начало периода действия элемента;
  • active_to - окончание периода действия элемента;
  • order - порядок сортировки сортировки, может принимать значения:
    • asc - по возрастанию;
    • desc - по убыванию.
    Необязательный. По умолчанию равен Array("sort"=>"asc")
Полный список полей сортировки и дополнительную информацию смотрите в CIBlockElement::GetList()
cnt Максимальное количество записей, которые вернет функция.
Необязательный. По умолчанию выбираются все записи.
arFilter Дополнительный фильтр по произвольным полям вида Array("Фильтруемое поле"=>"Значение", ...).
Фильтруемое поле может принимать значения:
  • ID - по коду;
  • ACTIVE - фильтр по активности (Y|N); передача пустого значения ("ACTIVE"=>"") выводит все элементы без учета их состояния;
  • NAME - по имени и фамилии (можно искать по шаблону [%_]);
  • PREVIEW_TEXT - по имени и фамилии (можно искать по шаблону [%_]);
  • DETAIL_TEXT - по детальному описанию (можно искать по шаблону [%_]);
  • SEARCHABLE_CONTENT - по содержимому для поиска. Включает в себя название, описание для анонса и детальное описание (можно искать по шаблону [%_]);
  • CODE - по мнемоническому идентификатору (можно искать по шаблону [%_]);
  • SORT - по сортировке;
  • EXTERNAL_ID - по внешнему коду (можно искать по шаблону [%_]);
  • TIMESTAMP_X - по времени изменения;
  • DATE_CREATE - по времени создания;
  • DATE_ACTIVE_FROM - по дате начала активности;
  • DATE_ACTIVE_TO - по дате окончанию активности;
  • ACTIVE_DATE - непустое значение задействует фильтр по датам активности (DATE_ACTIVE_FROM и DATE_ACTIVE_TO). Если значение не установлено (""), фильтрация по датам активности не производится;
  • IBLOCK_ID - по коду информационного блока;
  • IBLOCK_CODE - по мнемоническому коду информационного блока (можно искать по шаблону [%_]);
  • IBLOCK_LID - по языку (можно искать по шаблону [%_]);
  • IBLOCK_TYPE - по типу блока (можно искать по шаблону [%_]);
  • IBLOCK_ACTIVE - по активности блока (можно искать по шаблону [%_]);
  • SECTION_ID - по родительскому разделу;
  • PROPERTY_<код свойства> - фильтр по значениям свойств (можно искать по шаблону [%_]), для свойств типа "список", поиск будет осуществляться не по значению перечисления, а по его идентификатору;
  • PROPERTY_<код свойства>_VALUE - фильтр по значениям списка для свойств типа "список" (можно искать по шаблону [%_]), поиск будет осуществляться по строковому значению списка, а не по идентификатору;
  • CATALOG_<CATALOG_FIELD>_<PRICE_TYPE> - по полю CATALOG_FIELD из цены типа PRICE_TYPE (ID типа цены), где CATALOG_FIELD может быть: PRICE - цена, CURRENCY - валюта.
Все фильтруемые поля (кроме SECTION_ID и ACTIVE_DATE) могут содержать перед названием тип проверки фильтра, а поля SECTION_ID и ACTIVE_DATE могут содержать перед названием тип проверки фильтра "!" - не равно.

Значения фильтра - одиночное значение или массив.

Необязательный. По умолчанию - пустой массив.
Полный список полей фильтра и дополнительную информацию смотрите в CIBlockElement::GetList().

Возвращаемое значение

Функция возвращает объект класса CIBlockResult с активными элементами (у которых установлен флаг "Активен", выполняется условие периода активности и находящиеся в активных информационных блоках для текущего сайта).

Примечание

При работе с результатом рекомендуется применять метод класса CDBResult::GetNext(), результатом которого будет массив с полями элемента информационного блока. Все поля при этом будут преобразованы в "HTML безопасный" вид, а в полях с шаблонами URL-ов к страницам (LIST_PAGE_URL - списка элементов и DETAIL_PAGE_URL - детального просмотра) будут заменены параметры #SITE_DIR#, #IBLOCK_ID#, #EXTERNAL_ID# и #ID#. Если результат пуст или достигнут конец выборки CDBResult::GetNext() вернет false. Также можно воспользоваться любыми другими методами класса CDBResult, но при этом в полях LIST_PAGE_URL и DETAIL_PAGE_URL будут оригинальные (как они введены в форме редактирования информационного блока) шаблоны URL-ов, а не с замененными параметрами #SITE_DIR#, #IBLOCK_ID#, #EXTERNAL_ID# и #ID#.

См. также

  • Поля элементов информационного блока
  • Функция GetIBlockElementListEx

Примеры использования

<?
if(CModule::IncludeModule("iblock"))
{
   // выберем 10 элементов из папки $ID информационного блока $BID
   $items = GetIBlockElementList($_GET['BID'], $_GET['ID'], Array("SORT"=>"ASC"), 10);
   $items->NavPrint("Товары");
   while($arItem = $items->GetNext())
   {
      echo $arItem["NAME"]."<br>";
      echo $arItem["PREVIEW_TEXT"]."<br>";
   }
   $items->NavPrint("Товары");
}
?>


GetIBlockElementListEx

CIBlockResult
GetIBlockElementListEx (
 string type,
 mixed TypesInc = Array(),
 mixed TypesExc = Array(),
 array Order = Array("SORT"=>"ASC"),
 int cnt = 0,
 array arFilter = Array(),
 array arSelect = Array(),
 mixed arGroupBy = false
);

Функция возвращает активные для текущего сайта элементы из информационных блоков типа type.

Параметры функции

Параметр | Описание
type | Тип информационных блоков из которых выбираются элементы.
TypesInc Фильтр для включения по ID и(или) мнемоническому коду информационного блока. В качестве параметра может быть как единичное значение (ID или мнемонический код информационного блока), так и массив (array) таких значений.
Необязательный. По умолчанию включаются все элементы из информационных блоков типа type без дополнительной фильтрации.
Пример: "product_news"
TypesExc Фильтр для исключения по ID и(или) мнемоническому коду информационного блока. В качестве параметра может быть как единичное значение (ID или мнемонический код информационного блока), так и массив (array) таких значений.
Необязательный. По умолчанию выбираются все элементы из информационных блоков типа type без исключений.
Пример: Array("company_news", "product_news", 22)
Order Порядок сортировки - массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где by - поле для сортировки, может принимать значения:
  • sort - индекс сортировки;
  • timestamp_x - дата изменения;
  • name - название;
  • id - ID элемента;
  • active_from - начало периода действия элемента;
  • active_to - окончание периода действия элемента;
  • order - порядок сортировки сортировки, может принимать значения:
    • asc - по возрастанию;
    • desc - по убыванию.
    Необязательный. По умолчанию равен Array("sort"=>"asc")
Полный список полей сортировки и дополнительную информацию смотрите в CIBlockElement::GetList()
cnt Максимальное количество записей, которые вернет функция.
Необязательный. По умолчанию выбираются все записи.
arFilter Дополнительный фильтр по произвольным полям вида Array("Фильтруемое поле"=>"Значение", ...).
Фильтруемое поле может принимать значения:
  • ID - по коду;
  • ACTIVE - фильтр по активности (Y|N); передача пустого значения ("ACTIVE"=>"") выводит все элементы без учета их состояния;
  • NAME - по имени и фамилии (можно искать по шаблону [%_]);
  • PREVIEW_TEXT - по имени и фамилии (можно искать по шаблону [%_]);
  • DETAIL_TEXT - по детальному описанию (можно искать по шаблону [%_]);
  • SEARCHABLE_CONTENT - по содержимому для поиска. Включает в себя название, описание для анонса и детальное описание (можно искать по шаблону [%_]);
  • CODE - по мнемоническому идентификатору (можно искать по шаблону [%_]);
  • SORT - по сортировке;
  • EXTERNAL_ID - по внешнему коду (можно искать по шаблону [%_]);
  • TIMESTAMP_X - по времени изменения;
  • DATE_CREATE - по времени создания;
  • DATE_ACTIVE_FROM - по дате начала активности;
  • DATE_ACTIVE_TO - по дате окончанию активности;
  • ACTIVE_DATE - непустое значение задействует фильтр по датам активности (DATE_ACTIVE_FROM и DATE_ACTIVE_TO). Если значение не установлено (""), фильтрация по датам активности не производится;
  • IBLOCK_ID - по коду информационного блока;
  • IBLOCK_CODE - по мнемоническому коду информационного блока (можно искать по шаблону [%_]);
  • IBLOCK_LID - по языку (можно искать по шаблону [%_]);
  • IBLOCK_TYPE - по типу блока (можно искать по шаблону [%_]);
  • IBLOCK_ACTIVE - по активности блока (можно искать по шаблону [%_]);
  • SECTION_ID - по родительскому разделу;
  • PROPERTY_<код свойства> - фильтр по значениям свойств (можно искать по шаблону [%_]), для свойств типа "список", поиск будет осуществляться не по значению перечисления, а по его идентификатору;
  • PROPERTY_<код свойства>_VALUE - фильтр по значениям списка для свойств типа "список" (можно искать по шаблону [%_]), поиск будет осуществляться по строковому значению списка, а не по идентификатору;
  • CATALOG_<CATALOG_FIELD>_<PRICE_TYPE> - по полю CATALOG_FIELD из цены типа PRICE_TYPE (ID типа цены), где CATALOG_FIELD может быть: PRICE - цена, CURRENCY - валюта.
Все фильтруемые поля (кроме SECTION_ID и ACTIVE_DATE) могут содержать перед названием тип проверки фильтра, а поля SECTION_ID и ACTIVE_DATE могут содержать перед названием тип проверки фильтра "!" - не равно.

Значения фильтра - одиночное значение или массив.

Необязательный. По умолчанию - пустой массив.
Полный список полей фильтра и дополнительную информацию смотрите в CIBlockElement::GetList().
arSelect Массив возвращаемых полей элемента. Список полей элемента, а также можно сразу выводить значения его свойств. Для этого в качестве одного из полей необходимо указать PROPERTY_<PROPERTY_CODE>, где PROPERTY_CODE - ID или мнемонический код. В результате будет выведены значения свойств элемена в виде полей:
  • PROPERTY_<PROPERTY_CODE>_VALUE - значение;
  • PROPERTY_<PROPERTY_CODE>_ID - код значения у элемента;
  • PROPERTY_<PROPERTY_CODE>_ENUM_ID - код значения (для свойств типа список).
При установленном модуле торгового каталога можно выводить и цены элемента. Для этого в качестве одного из полей необходимо указать CATALOG_GROUP_<PROPERTY_CODE>, где PROPERTY_CODE - ID типа цены.

По умолчанию выводятся все поля элемента.
arGroupBy Массив полей для группировки элемента.

Если поля указаны, то выборка по ним группируется, а в результат добавляется поле CNT - количество сгруппированных элементов.

Если указать в качестве arGroupBy пустой массив, то функция вернет количество элементов CNT по заданному фильтру.

Группировать можно по полям элемента, а также по значениям его свойств. Для этого в качестве одного из полей группировки необходимо указать PROPERTY_<PROPERTY_CODE>, где PROPERTY_CODE - ID или мнемонический код свойства.

Необязательное. По умолчанию false - записи не группируются.

Возвращаемое значение

Функция возвращает объект класса CIBlockResult с активными элементами (у которых установлен флаг "Активен", выполняется условие периода активности и находящиеся в активных информационных блоках для текущего сайта).

Примечание

При работе с результатом рекомендуется применять метод класса CDBResult::GetNext(), результатом которого будет массив с полями элемента информационного блока. Все поля при этом будут преобразованы в "HTML безопасный" вид, а в полях с шаблонами URL-ов к страницам (LIST_PAGE_URL - списка элементов и DETAIL_PAGE_URL - детального просмотра) будут заменены параметры #SITE_DIR#, #IBLOCK_ID#, #EXTERNAL_ID# и #ID#. Если результат пуст или достигнут конец выборки CDBResult::GetNext() вернет false. Также можно воспользоваться любыми другими методами класса CDBResult, но при этом в полях LIST_PAGE_URL и DETAIL_PAGE_URL будут оригинальные (как они введены в форме редактирования информационного блока) шаблоны URL-ов, а не с замененными параметрами #SITE_DIR#, #IBLOCK_ID#, #EXTERNAL_ID# и #ID#.

См. также

  • CIBlockElement::GetList()
  • Поля элементов информационного блока
  • Функция GetIBlockElementList

Примеры использования

<?
if(CModule::IncludeModule("iblock"))
{
   // выберем 15 элементов типа "news" из информационного блока "company_news"
   $items = GetIBlockElementListEx("news", "company_news", Array(),
              Array("DATE_ACTIVE_FROM"=>"DESC", "SORT"=>"ASC", "NAME" => "ASC"), 15);

   // постраничная навигация
   $items->NavPrint("Новости компании");
   // цикл по всем новостям
   while($arItem = $items->GetNext())
   {
     // выведем ссылку на страницу с детальным просмотром
      echo "<a href='".$arItem["DETAIL_PAGE_URL"]."'>".$arItem["NAME"]."</a>";
     // выведем дату
      echo $arItem["DATE_ACTIVE_FROM"]."<br>";
     // выведем картинку для анонса, с ссылкой на детальный просмотр
      echo ShowImage($arItem["PREVIEW_PICTURE"], 100, 100,
                     "border='0'", $arItem["DETAIL_PAGE_URL"]);
     // выведем анонс
      echo $arItem["PREVIEW_TEXT"]."<hr>";
   }
   $items->NavPrint("Новости компании");
}
?>

<?
// Например, если необходимо вывести новости за сегодняшнюю дату (DATE_ACTIVE_FROM >= сегодня):
$items = GetIBlockElementListEx("news", Array(), Array(),
                                Array("SORT"=>"ASC", "ID" => "DESC"), 15,
                                Array(">=DATE_ACTIVE_FROM"=>
                                      date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")))));

// если необходимо вывести все вчерашние новости, т.е.
// (DATE_ACTIVE_FROM >= вчера && DATE_ACTIVE_FROM < сегодня):
$items = GetIBlockElementListEx("news", Array(), Array(),
                                Array("SORT"=>"ASC", "ID" => "DESC"), 15,
                                Array(">=DATE_ACTIVE_FROM"=>
                                      date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")),
                                                                mktime(0,0,0,date("m"),date("d")-1,date("Y"))),
                                      "<DATE_ACTIVE_FROM"=>
                                      date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")),
                                                                mktime(0,0,0,date("m"),date("d"),date("Y")))));

// если необходимо вывести все новости за 1 января 2003г., т.е.
// (DATE_ACTIVE_FROM >= 01.01.2003 && DATE_ACTIVE_FROM < 02.01.2003):
$items = GetIBlockElementListEx("news", Array(), Array(),
                                Array("SORT"=>"ASC", "ID" => "DESC"), 15,
                                Array(">=DATE_ACTIVE_FROM"=>
                                      date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")),
                                                                mktime(0,0,0,1,1,2003)),
                                      "<DATE_ACTIVE_FROM"=>
                                      date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")),
                                                                mktime(0,0,0,1,2,2003))));
?>


GetIBlockList

CDBResult
GetIBlockList (
 string type,
 mixed TypesInc = array(),
 mixed TypesExc = array(),
 array Order = array("SORT"=>"ASC"),
 int cnt = 0
);

Функция возвращает активные для текущего сайта информационные блоки типа type.

Параметры функции

Параметр | Описание
type | Тип информационных блоков.
TypesInc Фильтр для включения по ID и(или) мнемоническому коду информационного блока. В качестве параметра может быть как единичное значение (ID или мнемонический код информационного блока), так и массив (array) таких значений.
Необязательный. По умолчанию включаются все записи типа type без дополнительной фильтрации.
Пример: "product_news"
TypesExc Фильтр для исключения по ID и(или) мнемоническому коду информационного блока. В качестве параметра может быть как единичное значение (ID или мнемонический код информационного блока), так и массив (array) таких значений.
Необязательный. По умолчанию выбираются все записи типа type без исключений.
Пример: Array("company_news", "product_news", 22)
Order Сортировка - массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где by - поле для сортировки, может принимать значения:
id - сортировка по ID информационных блоков;
sort - индекс сортировки;
timestamp_x - дата изменения;
name - название;
order - порядок сортировки сортировки, может принимать значения:
asc - по возрастанию;
desc - по убыванию;
Необязательный. По умолчанию равен Array("sort"=>"asc") - по возрастанию индекса сортировки.
cnt Максимальное количество записей, которые вернет функция.
Необязательный. По умолчанию выбираются все записи.

Возвращаемое значение

Функция возвращает объект класса CDBResult с активными (у которых установлен флаг "Активен") информационными блоками для текущего сайта, т.е. того на котором происходит вызов функции.

Примечание

При работе с результатом рекомендуется применять метод класса CDBResult::GetNext(), результатом которого будет массив с полями информационного блока. Все поля при этом будут преобразованы в "HTML безопасный" вид, а в полях с шаблонами URL-ов к страницам (LIST_PAGE_URL - списка элементов и DETAIL_PAGE_URL - детального просмотра) будут заменены параметры #SITE_DIR# и #IBLOCK_ID#. Если результат пуст или достигнут конец выборки CDBResult::GetNext() вернет false.
Можно пользоваться любыми методами класса CDBResult, но при этом в полях LIST_PAGE_URL и DETAIL_PAGE_URL будут оригинальные значения шаблонов URL-ов (как они введены в форме редактирования информационного блока), а не с замененными параметрами #SITE_DIR# и #IBLOCK_ID#.

См. также

  • Поля информационных блоков

Примеры использования

<?
if(CModule::IncludeModule("iblock"))
{
   //выбираем все информационные блоки типа "catalog"
   $iblocks = GetIBlockList("catalog");
   while($arIBlock = $iblocks->GetNext()) //цикл по всем блокам
   {
      // здесь мы НЕ используем функцию htmlspecialchars($arIBlock["NAME"]),
      // т.к. метод GetNext() делает это за нас
      echo "Название: ".$arIBlock["NAME"]."<br>";
   }
}

?>
<?
if(CModule::IncludeModule("iblock"))
{
   // выберем 5 информационных блоков типа "news", отсортированных по названию,
   // кроме тех, у которых мнемонический код "company_news"
   $iblocks = GetIBlockList(
               "news",
               Array(),
               "company_news",
               Array("name"=>"asc"),
               5
               );

   while($arIBlock = $iblocks->GetNext()): // цикл по информационным блокам
   ?>
       // ставим ссылку на страницу со списком новостей
       <a href="<?echo $arIBlock["LIST_PAGE_URL"]?>"><?echo $arIBlock["NAME"]?></a><br>
       <?
       // выберем 5 последних новостей для каждого информационного блока
       $items = GetIBlockElementList(
                   $arIBlock["ID"],
                   false,
                   Array("ACTIVE_FROM"=>"desc", "sort"=>"asc"),
                   5
                   );
       while($arItem = $items->GetNext())
       {
            //дальше показ новостей
       }
   endwhile;
}
?>


GetIBlockSection

array
GetIBlockSection(
 int ID,
 string type = ""
);

Функция возвращает раздел информационного блока.

Параметры функции

Параметр | Описание
ID | ID раздела.
type | Тип информационного блока, в котором размещён раздел. Устанавливается в настройках модуля. Если задан, то при выборке проверяется чтобы раздел соответствовал этому типу. Необязательный. По умолчанию на раздел не накладываются ограничения по типу.

Возвращаемое значение

Функция возвращает массив полей раздела информационного блока и поле IBLOCK_NAME - название информационного блока. Все возвращаемые поля преобразованы в "HTML безопасный" вид.
Если по заданным параметрам раздел не найден, функция вернет false.

Примечание

Функция вернет поля раздела информационного блока только в том случае, если раздел "активен" и находится в информационный блоке, который также "активен" и привязан к текущему сайту.

См. также

  • Поля раздела иформационного блока

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

$APPLICATION->SetTitle("Просмотр раздела");

// подключим модуль и выберем раздел ID типа product
if(CModule::IncludeModule("iblock") && ($arIBlockSection = GetIBlockSection($_GET['ID'], 'product')))
{
   // В заголовок страницы вставим название раздела
   $APPLICATION->SetTitle($arIBlockSection["NAME"]);
   // В навигационную цепочку вставим название и ссылку на текущий информационный блок
   $APPLICATION->AddChainItem($arIBlockSection["IBLOCK_NAME"], "products.php?ID=".$arIBlockElement["IBLOCK_ID"]);
   // выведем картинку
   echo ShowImage($arIBlockSection["PICTURE"], 150, 150, "border='0'", "", true);
   // выведем детальное описание
   echo $arIBlockSection["DESCRIPTION"]."<br>";
}
else
   echo ShowError("Раздел не найден");

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


GetIBlockSectionList

CDBResult
GetIBlockSectionList (
 int iblock_id,
 int section_id = false,
 array order = Array("LEFT_MARGIN"=>"ASC"),
 int cnt = 0,
 array arFilter = Array()
);

Функция возвращает активные разделы из информационного блока iblock_id.

Параметры функции

Параметр | Описание
iblock_id | ID информационного блока из которого будут выбраны разделы.
section_id ID папки-родителя. Для получения корневых разделов информационного блока установите параметр section_id = 0.
Необязательный. По умолчанию (false) выбираются все записи без ограничения по разделу-родителю.
order Массив вида Array(order1=>by1[, order2=>by2 [, ..]]), где order - поле для сортировки, может принимать значения:
  • sort - индекс сортировки;
  • timestamp_x - дата изменения;
  • name - название;
  • id - ID папки;
  • left_margin - поле обозначающее "сквозную" сортировку (см. Примечание);
  • depth_level - уровень вложенности папки;
  • by - порядок сортировки сортировки, может принимать значения:
    • asc - по возрастанию;
    • desc - по убыванию.
    Необязательный. По умолчанию равен Array("left_margin"=>"asc").
Полный список полей сортировки и дополнительную информацию смотрите в CIBlockSection::GetList()
cnt Максимальное количество записей, которые вернет функция.
Необязательный. По умолчанию выбираются все записи.
arFilter Дополнительный фильтр - массив вида array("фильтруемое поле"=>"значение" [, ...])
Может принимать значения:
  • ACTIVE - фильтр по активности (Y|N);
  • GLOBAL_ACTIVE - фильтр по активности, учитывая активность вышележащих разделов (Y|N);
  • NAME - по названию (можно искать по шаблону [%_]);
  • CODE - по мнемоническому коду (по шаблону [%_]);
  • EXTERNAL_ID - по внешнему коду (по шаблону [%_]);
  • IBLOCK_ID - по коду информационного блока;
  • DEPTH_LEVEL - по уровню вложенности;
  • SECTION_ID - по разделу-родителю;
  • LEFT_BORDER, RIGHT_BORDER - по левой и правой границе (поля LEFT_MARGIN и RIGHT_MARGIN, см. примечание);
  • ID - по коду;
  • PROPERTY - по значениям свойств внутрилежащих элементов, PROPERTY - массив вида Array("код свойства"=>"значение", ...).
Необязательное. По умолчанию записи не фильтруются дополнительно.

Все фильтруемые поля могут содержать перед названием тип проверки фильтра.

Полный список параметров фильтра и дополнительную информацию смотрите в CIBlockSection::GetList()

Возвращаемое значение

Функция возвращает объект класса CDBResult с активными разделами (находящиеся в активных информационных блоках (у которых установлен флаг "Активен"), и которые лежат внутри активных разделов).

Примечание

1. При работе с результатом рекомендуется применять метод класса CDBResult::GetNext(), результатом которого будет массив с полями раздела. Все поля при этом будут преобразованы в "HTML безопасный" вид. Если результат пуст или достигнут конец выборки CDBResult::GetNext() функция вернет false.

2. Поле для сортировки left_margin, так называемая "сквозная" сортировка, высчитывается на основании поля sort, уровня вложенности и сортировкой верхнего уровня. Отличие полей sort и left_margin в том, что sort указывается пользователем, для сортировки разделов между собой в пределах одного раздела-родителя, а вычисляемое left_margin предназначено для сортировки во всем информационном блоке.

См. также

  • Поля разделов информационных блоков

Примеры использования

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

$APPLICATION->SetTitle("Каталог");

if(CModule::IncludeModule("iblock"))
{
   // если $ID не задан или это не число, тогда
   // $ID будет =0, выбираем корневые разделы
   $ID = IntVal($_GET['ID']);
   // выберем папки из информационного блока $BID и раздела $ID
   $items = GetIBlockSectionList($_GET['BID'], $ID, Array("sort"=>"asc"), 10);
   while($arItem = $items->GetNext())
   {
      echo '<a href="catalog.php?bid='.
           urlencode($_get['bid']).
           '&id='.$aritem['id'].'">'.$aritem["name"].'</a><br>';
      echo $arItem["DESCRIPTION"]."<br>";
   }
}
else
   ShowError("Модуль не установлен");

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");
?>


Информация для разработчиков

Перед использованием модуля необходимо проверить, установлен ли он, и подключить его при помощи конструкции:

<?
if (CModule::IncludeModule("learning"))
{
   //здесь можно использовать функции модуля
}
?>


Структура таблиц модуля обучения

Поля таблиц

Учебные курсы

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор учебного курса. | Int | Да |
TIMESTAMP_X | Время последнего изменения курса. | Datetime |  | Текущее
ACTIVE | Флаг активности (Y|N). | Char(1) | Да | Y
CODE | Мнемонический идентификатор. | String(50) |  |
NAME | Название курса. | String(255) | Да |
SORT | Индекс сортировки. | Int | Да | 500
PREVIEW_PICTURE | Код картинки в таблице файлов для предварительного просмотра (анонса). | Int |  |
PREVIEW_TEXT | Предварительное описание (анонс). | Text |  |
PREVIEW_TEXT_TYPE | Тип предварительного описания (text/html). | String(4) | Да | Text
DESCRIPTION | Описание. | Text |  |
DESCRIPTION_TYPE | Тип описания (text/html). | String(4) | Да | Text
ACTIVE_FROM | Дата начала активности курса. | Datetime |  |
ACTIVE_TO | Дата окончания активности курса. | Datetime |  |

Главы

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор главы. | Int | Да |
TIMESTAMP_X | Время последнего изменения главы. | Datetime |  | Текущее
ACTIVE | Флаг активности (Y|N). | Char(1) | Да | Y
COURSE_ID | Идентификатор учебного курса. | Int | Да |
CHAPTER_ID | Идентификатор главы-родителя, если не задан, то глава корневая. | Int |  |
NAME | Название главы. | String(255) | Да |
CODE | Мнемонический идентификатор. | String(50) |  |
SORT | Индекс сортировки. | Int | Да | 500
PREVIEW_PICTURE | Код картинки в таблице файлов для предварительного просмотра (анонса). | Int |  |
PREVIEW_TEXT | Предварительное описание (анонс). | Text |  |
PREVIEW_TEXT_TYPE | Тип предварительного описания (text/html). | String(4) | Да | Text
DETAIL_PICTURE | Код картинки в таблице файлов для детального просмотра. | Int |  |
DETAIL_TEXT | Детальное описание. | Text |  |
DETAIL_TEXT_TYPE | Тип детального описания (text/html). | String(4) | Да | Text

Уроки

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор урока. | Int | Да |
TIMESTAMP_X | Время последнего изменения урока. | Datetime |  | Текущее
DATE_CREATE | Дата создания урока. | Datetime | Да | Текущая
CREATED_BY | Код пользователя, создавшего урок. | Int | Да | Текущий пользователь
ACTIVE | Флаг активности (Y|N). | Char(1) | Да | Y
COURSE_ID | Идентификатор учебного курса. | Int | Да |
CHAPTER_ID | Идентификатор главы. Если не задан, то урок не привязан к главе. | Int |  |
NAME | Название урока. | String(255) | Да |
SORT | Индекс сортировки. | Int | Да | 500
PREVIEW_PICTURE | Код картинки в таблице файлов для предварительного просмотра (анонса). | Int |  |
PREVIEW_TEXT | Предварительное описание (анонс). | Text |  |
PREVIEW_TEXT_TYPE | Тип предварительного описания (text/html). | String(4) | Да | Text
DETAIL_PICTURE | Код картинки в таблице файлов для детального просмотра. | Int |  |
DETAIL_TEXT | Детальное описание. | Text |  |
DETAIL_TEXT_TYPE | Тип детального описания (text/html). | String(4) | Да | Text

Вопросы

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор вопроса. | Int | Да |
TIMESTAMP_X | Время последнего изменения вопроса. | Datetime |  | Текущее
ACTIVE | Флаг активности (Y|N). | Char(1) | Да | Y
LESSON_ID | Идентификатор урока. | Int | Да |
QUESTION_TYPE | Тип вопроса. S - одиночный выбор, M - множественный выбор. | Char(1) | Да | S
NAME | Название вопроса. | String(255) | Да |
SORT | Индекс сортировки. | Int | Да | 500
DESCRIPTION | Описание. | Text |  |
DESCRIPTION_TYPE | Тип описания (text/html). | String(4) | Да | Text
FILE_ID | Код картинки/файла в таблице файлов. | Int |  |
SELF | Вопрос для самопроверки (Y/N). | Char(1) | Да | Y
POINT | Количество баллов. | Int | Да | 10

Варианты ответов на вопросы

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор ответа. | Int | Да |
QUESTION_ID | Идентификатор вопроса. | Int | Да |
SORT | Индекс сортировки. | Int | Да | 10
ANSWER | Вариант ответа. | Text | Да |
CORRECT | Правильность ответа (Y/N). | Char(1) | Да |
FEEDBACK | Комментарий к ответу. | Text |  |

Тесты
Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор теста. | Int | Да
COURSE_ID | Идентификатор учебного курса. | Int | Да
TIMESTAMP_X | Время последнего изменения теста. | Datetime | Текущее
SORT | Индекс сортировки. | Int | Да | 500
ACTIVE | Флаг активности (Y|N). | Char(1) | Да | Y
NAME | Название теста. | String(255) | Да
DESCRIPTION | Описание. | Text
DESCRIPTION_TYPE | Тип описания (text/html). | String(4) | Да | Text
ATTEMPT_LIMIT | Количество попыток прохождения теста. 0 - неограниченное количество. | Int | Да
TIME_LIMIT | Ограничение времени прохождения теста в минутах. 0 - без ограничения. | Int
COMPLETED_SCORE | Процент правильных ответов при автоматической проверке результатов теста. | Int
QUESTIONS_FROM В тесте участвуют вопросы из:
  • A - со всего курса,
  • C - с каждой главы,
  • L - с каждого урока.
 Char(1) Да A
QUESTIONS_AMOUNT | Количество вопросов в тесте. | Int | Да
RANDOM_QUESTIONS | Случайный порядок вопросов (Y/N). | Char(1) | Да | Y
RANDOM_ANSWERS | Случайный порядок ответов (Y/N). | Char(1) | Да | Y
APPROVED | Автоматическая проверка результатов (Y/N). | Char(1) | Да | Y
INCLUDE_SELF_TEST | Включать вопросы для самопроверки (Y/N). | Char(1) | Да | N
PASSAGE_TYPE Тип прохождения теста:
  • 0 - запретить переход к следующему вопросу без ответа на текущий вопрос, пользователь не может изменять свои ответы;
  • 1 - разрешить переход к следующему вопросу без ответа на текущий вопрос, пользователь не может изменять свои ответы;
  • 3 - разрешить переход к следующему вопросу без ответа на текущий вопрос, пользователь может изменять свои ответы.
 Char(1) Да 0

Попытки прохождения теста

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор попытки. | Int | Да |
TEST_ID | Идентификатор теста. | Int | Да |
STUDENT_ID | Код пользователя, проходящего тест. | Int | Да |
DATE_START | Дата начала прохождения теста. | Datetime | Да | Текущая
DATE_END | Дата завершения теста. | Datetime |  |
STATUS | Статус попытки. B - тестирование началось, D - тест прерван, F - тест закончен. | Char(1) | Да | B
SCORE | Сумма баллов. | Int |  |
MAX_SCORE | Максимально возможная сумма баллов. | Int |  | Автоматически
QUESTIONS | Количество вопросов в попытке. | Int |  | Автоматически

План тестирования

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор результата. | Int | Да |
ATTEMPT_ID | Идентификатор попытки. | Int | Да |
QUESTION_ID | Идентификатор вопроса. | Int | Да |
RESPONSE | Ответ учащегося. | Text |  |
POINT | Баллы. | Int | Да |
ANSWERED | Вопрос отвечен (Y/N). | Char(1) | Да | N
CORRECT | Отвечен правильно (Y/N). | Char(1) | Да | N

Журнал

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор записи в журнале. | Int | Да |
STUDENT_ID | Код пользователя, проходящего тест. | Int | Да |
TEST_ID | Идентификатор теста. | Int | Да |
RESULT | Итоговая сумма баллов. | Int |  |
MAX_RESULT | Максимально возможная итоговая сумма баллов. | Int |  | Автоматически
COMPLETED | Тест пройден (Y/N). | Char(1) | Да | N
ATTEMPTS | Количество попыток прохождения теста. | Int. |  | Автоматически

Сертификаты

Поле | Описание | Тип | Обяз. | Умолч.
ID | Идентификатор сертификата. | Int | Да |
STUDENT_ID | Код пользователя. | Int | Да |
COURSE_ID | Идентификатор учебного курса. | Int | Да |
TIMESTAMP_X | Дата изменения сертификата. | Datetime |  | Текущее
DATE_CREATE | Дата создания сертификата. | Datetime |  |
ACTIVE | Активность сертификата (Y/N). | Char(1) | Да | Y
SORT | Индекс сортировки. | Int | Да | 500
FROM_ONLINE | Сертификат получен через Online-обучение (Y/N). | Char(1) | Да | Y
PUBLIC_PROFILE | Публиковать сертификат в профиле (Y/N). | Char(1) | Да | Y
SUMMARY | Сумма баллов, набранных за прохождение всех тестов курса. | Int | Да |
MAX_SUMMARY | Максимально возможная сумма баллов за прохождение всех тестов курса. | Int | Да | Автоматически

Профиль студента

Поле | Описание | Тип | Обяз. | Умолч.
USER_ID | Код пользователя. | Int | Да |
TRANSCRIPT | Числовой случайный идентификатор. | Int | Да | Автоматически
PUBLIC_PROFILE | Профиль доступен публично (Y/N). | Char(1) | Да | N
RESUME | Резюме студента | Text |  |


Классы модуля обучения

Следующие PHP классы используются в модуле обучения.

Классы

Класс | Описание
CCourse | Класс для работы с курсами.
CChapter | Класс для работы с главами.
CLesson | Класс для работы с уроками.
CLQuestion | Класс для работы с вопросами.
CLAnswer | Класс для работы с ответами.
CTest | Класс для работы с тестами.
CTestAttempt | Класс для работы с попытками прохождения теста.
CTestResult | Класс для работы с планом тестирования.
CGradeBook | Класс для работы с журналом.
CCertification | Класс для работы с сертификатами.
CStudent | Класс для работы c профилем студента.
CCoursePackage | Класс для экспорта курса.
CCourseImport | Класс для импорта курса.


Класс CCertification

CCertification - класс для работы с сертификатами студентов.
Метод | Описание
GetList | Возвращает список сертификатов по фильтру.
GetByID | Возвращает сертификат по идентификатору.
Add | Добавляет новый сертификат.
Update | Изменят параметры сертификата.
Delete | Удаляет сертификат.
IsCourseCompleted | Проверяет, пройден ли курс.
Certificate | Добавляет или изменяет сертификат, если курс был пройден.


Add

CCertification::Add

int
CCertification::Add(
 array arFields
);

Метод добавляет новый сертификат.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей сертификата. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленного сертификата, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CCertification::Update
  • Поля

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $STUDENT_ID = 3;

    $arFields = Array(
        "ACTIVE" => "Y",
        "COURSE_ID" => $COURSE_ID,
        "STUDENT_ID" => $STUDENT_ID,
        "SUMMARY" => 300,
        "MAX_SUMMARY" => 300
    );

    $certificate = new CCertification;
    $ID = $certificate->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }
}
?>


Certificate

CCertification::Certificate

bool

  CCertification::Certificate(
 int STUDENT_ID,
 int COURSE_ID
);

Добавляет или изменяет сертификат, если курс был пройден.

Параметры функции

Параметр | Описание
STUDENT_ID | Идентификатор студента.
COURSE_ID | Идентификатор курса.

Возвращаемое значение

Метод возвращает true, если сертификация прошла успешно, иначе - false.

См. также

  • CCertification::Add
  • CCertification::Update
  • CTest::GetList
  • CGradeBook::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $STUDENT_ID = 1;
    $COURSE_ID = 92;

    $done = CCertification::Certificate($STUDENT_ID, $COURSE_ID);

    if ($done)
        echo "Success!";
    else
        echo "Course is not completed";
}
?>


Delete

CCertification::Delete

bool
CCertification::Delete(
 int ID
);

Метод удаляет сертификат с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сертификата.

Возвращаемое значение

Метод возвращает true в случае успешного удаления сертификата, в противном случае возвращает false.

См. также

  • CCertification::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $CERTIFICATE_ID = 19;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CCertification::Delete($CERTIFICATE_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CCertification::GetByID

CDBResult

  CCertification::GetByID(
 int ID
);

Возвращает сертификат по идентификатору ID. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
ID | Идентификатор сертификата.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля сертификата
  • CCertification::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $CERTIFICATE_ID = 13;

    $res = CCertification::GetByID($CERTIFICATE_ID);

    if ($arCertificate = $res->GetNext())
    {
        echo "Course: ".$arCertificate["COURSE_NAME"].
             " User: ".$arCertificate["USER_NAME"].
             " Score: ".$arCertificate["SUMMARY"];
    }
}
?>


GetList

CCertification::GetList

CDBResult

  CCertification::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array()
);

Возвращает список сертификатов по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор сертификата;
  • STUDENT_ID - идентификатор студента ;
  • COURSE_ID - идентификатор курса;
  • SUMMARY - cумма баллов, набранных за прохождение всех тестов курса;
  • MAX_SUMMARY - максимально возможная сумма баллов за прохождение всех тестов курса;
  • SORT - индекс сортировки;
  • ACTIVE - фильтр по активности (Y|N);
  • FROM_ONLINE - сертификат получен через online-обучение (Y/N);
  • PUBLIC_PROFILE - публиковать сертификат в профиле (Y/N);
  • DATE_CREATE - дата создания сертификата;
  • TIMESTAMP_X - дата изменения студента.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию идентификатора сертификата.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор сертификата;
  • STUDENT_ID - идентификатор студента ;
  • COURSE_ID - идентификатор курса;
  • SUMMARY - cумма баллов, набранных за прохождение всех тестов курса;
  • MAX_SUMMARY - максимально возможная сумма баллов за прохождение всех тестов курса;
  • SORT - индекс сортировки;
  • ACTIVE - фильтр по активности (Y|N);
  • FROM_ONLINE - сертификат получен через online-обучение (Y/N);
  • PUBLIC_PROFILE - публиковать сертификат в профиле (Y/N);
  • DATE_CREATE - дата создания сертификата;
  • TIMESTAMP_X - дата изменения студента.
  • USER - пользователь (возможны сложные условия по полям пользователя ID, LOGIN, NAME, LAST_NAME);
  • MIN_PERMISSION - минимальный уровень доступа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CCertification::GetByID
  • Поля сертификата

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 100;
    $res = CCertification::GetList(
        Array("SUMMARY" => "DESC", "SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID)
    );

    while ($arCertification = $res->GetNext())
    {
        echo "User:".$arCertification["USER_NAME"].
             "; Course name: ".$arCertification["COURSE_NAME"]."<br>";
    }
}
?>
<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 100;
    $res = CCertification::GetList(
        Array("SUMMARY" => "DESC", "SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "CHECK_PERMISSIONS" => "N")
    );

    while ($arCertification = $res->GetNext())
    {
        echo "User:".$arCertification["USER_NAME"].
             "; Course name: ".$arCertification["COURSE_NAME"]."<br>";
    }
}
?>


IsCourseCompleted

CCertification::IsCourseCompleted

bool
CCertification::IsCourseCompleted(
 int STUDENT_ID,
 int COURSE_ID
);

Проверяет, пройден ли курс. Курс считается пройденным, если пройдены все его тесты.

Параметры функции

Параметр | Описание
STUDENT_ID | Идентификатор студента.
COURSE_ID | Идентификатор курса.

Возвращаемое значение

Метод возвращает true, если курс пройден, иначе - false.

См. также

  • CGradeBook::GetList
  • CTest::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $STUDENT_ID = 1;
    $COURSE_ID = 92;

    $done = CCertification::IsCourseCompleted($STUDENT_ID, $COURSE_ID);

    if ($done)
        echo "Course completed";
    else
        echo "Course is not completed";

}
?>


Update

CCertification::Update

bool
CCertification::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры сертификата с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор сертификата.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей сертификата. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернет false. При возникновении ошибки в исключениях будет содержаться текст ошибки

См. также

  • Поля
  • CCertification::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $CERTIFICATE_ID = 15;

    $arFields = Array(
        "ACTIVE" => "N",
        "SUMMARY" => 290,
        "MAX_SUMMARY" => 555
    );

    $certificate = new CCertification;
    $success =  $certificate->Update($CERTIFICATE_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }
}
?>


Класс CChapter

CChapter - класс для работы с главами.
Метод | Описание
GetList | Возвращает список глав по фильтру.
GetByID | Возвращает главу по ее идентификатору.
Add | Добавляет новую главу.
Update | Изменяет параметры главы.
Delete | Удаляет главу.
GetCount | Возвращает количество подразделов.
GetTreeList | Возвращает разделы отсортированные в порядке "полностью развернутого дерева".
GetNavChain | Возвращает путь от заданного раздела до корневого.


Add

CChapter::Add

int
CChapter::Add(
 array arFields
);

Метод добавляет новую главу.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей главы. Обязательные поля должны быть заполнены.

Возвращаемое значение

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

См. также

  • CChapter::Update
  • Поля главы

Примеры использования

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $arFields = Array(
        "COURSE_ID" => $COURSE_ID,
        "ACTIVE" => "Y",
        "NAME" => "Chapter 1",
        "SORT" => "100",
        "DETAIL_TEXT" => "In this chapter ...",
    );

    $chapter = new CChapter;
    $ID = $chapter->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Delete

CChapter::Delete

bool
CChapter::Delete(
 int ID
);

Метод удаляет главу с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор главы.

Возвращаемое значение

Метод возвращает true в случае успешного удаления главы, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $CHAPTER_ID = 300;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CChapter::Delete($CHAPTER_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CChapter::GetByID

CDBResult
CChapter::GetByID(
 int ID
);

Возвращает главу по ее коду ID.

Параметры функции

Параметр | Описание
ID | Идентификатор главы.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля главы
  • CChapter::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $CHAPTER_ID = 97;

    $res = CChapter::GetByID($CHAPTER_ID);

    if ($arChapter = $res->GetNext())
    {
        echo "Name: ".$arChapter["NAME"];
    }
}

?>


GetCount

CChapter::GetCount

int
CChapter::GetCount(
 array arFilter = Array()
);

Возвращает количество глав по заданному фильтру.

Параметры функции

Параметр | Описание
arFilter | Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Описание фильтра см. в CChapter::GetList

Возвращаемое значение

Число - количество глав.

См. также

  • CChapter::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $cnt = CChapter::GetCount(Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID));

    echo "Number of chapters: ".$cnt;
}

?>

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $cnt = CChapter::GetCount(Array("CHECK_PERMISSIONS" => "N", "COURSE_ID" => $COURSE_ID));

    echo "Number of chapters: ".$cnt;
}

?>


GetList

CChapter::GetList

CDBResult
CChapter::GetList(
 array arOrder = Array("TIMESTAMP_X"=>"DESC"),
 array arFilter = Array(),
 bool bIncCnt = false
);

Возвращает список глав по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор главы;
  • NAME - название главы;
  • ACTIVE - активность главы;
  • SORT - индекс сортировки;
  • TIMESTAMP_X - дата изменения главы.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию даты изменения главы.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор главы;
  • NAME - название главы (можно искать по шаблону [%_]);
  • SORT - индекс сортировки;
  • CODE - мнемоническое имя главы (можно искать по шаблону [%_]);
  • ACTIVE - фильтр по активности (Y|N);
  • TIMESTAMP_X - дата изменения главы;
  • CHAPTER_ID - идентификатор главы. Для получения списка родительских глав установите это поле в значение пусто;
  • COURSE_ID - идентификатор курса;
  • DETAIL_TEXT - детальное описание (можно искать по шаблону [%_]);
  • PREVIEW_TEXT - предварительное описание (можно искать по шаблону [%_]);
  • MIN_PERMISSION - минимальный уровень доcтупа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются;
  • CNT_ACTIVE - считать количество только активных уроков. Работает, если bIncCnt установлено в значение true.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
bIncCnt | Возвращать ли количество уроков главы в поле ELEMENT_CNT. Не обязательный параметр, по умолчанию равен false.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CChapter::GetByID
  • Поля главы

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $res = CChapter::GetList(
        Array("SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID, "CNT_ACTIVE" => "Y"),
        true
    );

    while ($arChapter = $res->GetNext())
    {
        echo "Chapter name: ".$arChapter["NAME"]."<br>";
        echo "Active lessons: ".$arChapter["ELEMENT_CNT"]."<br><br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $res = CChapter::GetList(
        Array("SORT"=>"ASC"),
        Array("?NAME" => "Site")
    );

    while ($arChapter = $res->GetNext())
    {
        echo "Chapter name: ".$arChapter["NAME"]."<br>";
    }
}
?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $res = CChapter::GetList(
        Array("NAME" => "ASC", "SORT"=>"ASC"),
        Array("COURSE_ID" => $COURSE_ID)
    );

    while ($arChapter = $res->GetNext())
    {
        echo "Chapter name: ".$arChapter["NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $res = CChapter::GetList(
        Array("TIMESTAMP_X" => "ASC", "SORT"=>"ASC"),
        Array("CHECK_PERMISSIONS" => "N", "CHAPTER_ID" => "", "COURSE_ID" => $COURSE_ID)
    );

    while ($arChapter = $res->GetNext())
    {
        echo "Chapter name: ".$arChapter["NAME"]."<br>";
    }
}

?>


GetNavChain

CChapter::GetNavChain

CDBResult
CChapter::GetNavChain(
 int COURSE_ID,
 int CHAPTER_ID
);

Функция возвращает путь по дереву от корня до главы CHAPTER_ID.

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.
CHAPTER_ID | Идентификатор главы.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CChapter::GetList
  • CChapter::GetByID
  • Поля главы

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{

    $COURSE_ID = 90;
    $CHAPTER_ID = 116;

    $nav = CChapter::GetNavChain($COURSE_ID, $CHAPTER_ID);
    $i = 1;
    while($arChain = $nav->GetNext())
    {
        if ($i > 1) echo " -> ";
        echo $arChain["NAME"];
        $i++;
    }

    /*
    The above example will output something similar to:

    Chapter 1 -> Chapter 1.1 -> Chapter 1.1.3 -> Chapter 1.1.2
    $CHAPTER_ID - ID of Chapter 1.1.2;
    */
}
?>


GetTreeList

CChapter::GetTreeList

CDBResult
CChapter::GetTreeList(
 int COURSE_ID
);

Метод возвращает список глав, отсортированный в порядке "полного развернутого дерева".

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CChapter::GetByID
  • CChapter::GetList
  • CCourse::GetCourseContent
  • Поля главы

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $res = CChapter::GetTreeList($COURSE_ID = 105);

    while ($arChapter = $res->GetNext())
    {
        echo str_repeat("&nbsp;&nbsp;&nbsp;&nbsp;", $arChapter["DEPTH_LEVEL"]);
        echo "+".$arChapter["NAME"]."<br>";
    }

    /*
    The above example will output something similar to:
    +Chapter 1
      +Chapter 1.1
      +Chapter 1.2
    +Chapter 2
    +Chapter 3
      +Chapter 3.1
        +Chapter 3.1.1
    */
}
?>


Update

CChapter::Update

bool
CChapter::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры главы с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор главы.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей главы. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернет false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля главы
  • CChapter::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $CHAPTER_ID = 299;

    $arFields = Array(
        "ACTIVE" => "N",
        "NAME" => "New name of Chapter 1",
        "SORT" => "555",
    );

    $chapter = new CChapter;
    $success = $chapter->Update($CHAPTER_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Класс CCourse

CCourse - класс для работы с учебными курсами.
Метод | Описание
GetList | Возвращает список курсов по фильтру.
GetByID | Возвращает курс по идентификатору.
Add | Добавляет новый курс.
Update | Изменяет параметры курса.
Delete | Удаляет курс.
SetPermission | Устанавливает права доступа на курс.
GetPermission | Определяет право доступа для текущего пользователя.
GetGroupPermissions | Возвращает все права доступа для курса.
IsHaveCourse | Определяет, имеет ли текущий пользователь право доступа хотя бы к одному курсу.
GetSite | Возвращает список сайтов для курса.
GetCourseContent | Возвращает список глав и уроков ("дерево" курса).
TimeToStr | Переводит количество секунд в текст.


Add

CCourse::Add

int
CCourse::Add(
 array arFields
);

Метод добавляет новый курс.

Параметры функции

Параметр Описание
arFields Массив Array("поле"=>"значение", ...). Содержит значения всех полей курса. Обязательные поля должны быть заполнены.
Дополнительно в поле SITE_ID должен находиться массив идентификаторов сайтов, к которым привязан добавляемый курс.
Кроме того, с помощью поля "GROUP_ID", значением которого должен быть массив соответствий кодов групп правам доступа, можно установить права для разных групп на доступ к курсу (см. CCourse::SetPermission).

Возвращаемое значение

Метод возвращает идентификатор добавленного курса, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CCourse::Update
  • Поля курса

Примеры использования

<?

if (CModule::IncludeModule("learning"))
{
    $arFields = Array(
        "ACTIVE" => "Y",
        "NAME" => "My First Course",
        "SITE_ID" => Array("ru", "en"), //Sites
        "GROUP_ID" => Array("2" => "R"), //Permissions: Everyone can read my course
        "SORT" => "100",
        "DESCRIPTION" => "It's my first e-Learning course",
        "DESCRIPTION_TYPE" => "text",
    );

    $course = new CCourse;
    $ID = $course->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();

    }

}
?>


Delete

CCourse::Delete

bool
CCourse::Delete(
 int ID
);

Метод удаляет курс с идентификатором ID.

Примечание

Если есть сертификаты, полученные за указанный курс, метод возвратит false.

Параметры функции

Параметр | Описание
ID | Идентификатор курса.

Возвращаемое значение

Метод возвращает true в случае успешного удаления курса, в противном случае возвращает false.

Примеры использования

<?

if (CModule::IncludeModule("learning"))
{

    $ID = 109;//Course ID

    if($USER->IsAdmin())
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if(!CCourse::Delete($ID))
            $DB->Rollback();
        else
            $DB->Commit();
    }

}

?>


GetByID

CCourse::GetByID

CDBResult
CCourse::GetByID(
 int ID
);

Возвращает поля курса по его коду ID. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
ID | Идентификатор курса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля курса
  • CCourse::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $course = CCourse::GetByID($COURSE_ID);
    if ($arCourse = $course->GetNext())
    {
        echo $arCourse["NAME"];
    }
}
?>


GetCourseContent

CCourse::GetCourseContent

CDBResult
CCourse::GetCourseContent(
 int COURSE_ID,
 array arAddSelectFileds = Array("DETAIL_TEXT", "DETAIL_TEXT_TYPE", "DETAIL_PICTURE")
);

Возвращает список активных глав и уроков, отсортированный по возрастанию индекса сортировки.

Примечание

Возвращаемый список содержит одноименные поля глав и уроков. Обязательные поля списка: ID - идентификатор урока или главы; NAME - название; CHAPTER_ID - идентификатор родительской главы; SORT - индекс сортировки; DEPTH_LEVEL - уровень вложенности; TYPE - тип ("LE" - урок, "CH" - глава). Для вывода остальных полей используйте массив arAddSelectFileds. Метод предназначен для вывода "дерева" курса. Если поля "DETAIL_TEXT", "DETAIL_TEXT_TYPE", "DETAIL_PICTURE" не используются - рекомендуется arAddSelectFileds оставлять пустым (arAddSelectFileds = Array()).

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.
arAddSelectFileds Массив дополнительных полей. Допустимые поля:
PREVIEW_TEXT - Предварительное описание (анонс);
PREVIEW_TEXT_TYPE - Тип предварительного описания (text/html);
PREVIEW_PICTURE - Код картинки в таблице файлов для предварительного просмотра (анонса);
DETAIL_TEXT_TYPE - Тип детального описания (text/html);
DETAIL_PICTURE - Код картинки в таблице файлов для детального просмотра;
DETAIL_TEXT - Детальное описание;
По умолчанию массив arAddSelectFileds = Array("DETAIL_TEXT", "DETAIL_TEXT_TYPE", "DETAIL_PICTURE");

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • Поля урока
  • Поля главы
  • CDBResult
  • CLesson::GetList
  • CChapter::GetList
  • CChapter::GetTreeList

    Примеры использования

    <?
if (CModule::IncludeModule("learning"))
{
    $res = CCourse::GetCourseContent($COURSE_ID = 105, Array());

    while ($arContent = $res->GetNext())
    {
        echo str_repeat("&nbsp;&nbsp;&nbsp;&nbsp;", $arContent["DEPTH_LEVEL"]);
        echo ($arContent["TYPE"]=="CH" ? "+": "-").$arContent["NAME"]."<br>";
    }

    /*
    The above example will output something similar to:

    +Chapter 1
      +Chapter 1.1
        -Lesson 1.1.1
      +Chapter 1.2
    +Chapter 2
      -Lesson 2
    +Chapter 3
      +Chapter 3.1
        -Lesson 3.1.1
        -Lesson 3.1.2
        +Chapter 3.1.1

    */

}

?>


GetGroupPermissions

CCourse::GetGroupPermissions

array
CCourse::GetGroupPermissions(
 int COURSE_ID
);

Возвращает права доступа к учебному курсу с идентификатором COURSE_ID для всех групп пользователей.

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.

Возвращаемое значение

Массив прав вида Array("ID группы"=>"Право доступа"[, ...]). Право доступа может принимать значение: "D" - запрещён, "R" - чтение, "W" - изменение, "X" - полный доступ (изменение + право изменять права доступа).

См. также

  • CCourse::GetPermission

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $arPerm = CCourse::GetGroupPermissions($COURSE = 8);
    print_r($arPerm);

    /*
    The above example will output something similar to:

    Array
    (
        [2] => R
        [22] => W
    )
    */
}

?>


GetList

CCourse::GetList

CDBResult
CCourse::GetList(
 array arOrder = Array("TIMESTAMP_X"=>"DESC"),
 array arFilter = Array(),
 bool bIncCnt = false
);

Возвращает список курсов по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор курса;
  • NAME - название курса;
  • ACTIVE - активность курса;
  • SORT - индекс сортировки;
  • TIMESTAMP_X - дата изменения курса.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию даты изменения курса.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор курса;
  • NAME - название курса (можно искать по шаблону [%_]);
  • SORT - индекс сортировки;
  • CODE - мнемоническое имя курса (можно искать по шаблону [%_]);
  • DESCRIPTION - описание курса (можно искать по шаблону [%_]);
  • ACTIVE - фильтр по активности (Y|N);
  • SITE_ID - идентификатор сайта;
  • TIMESTAMP_X - дата изменения курса;
  • ACTIVE_FROM - дата начала активности с учётом пустого значения;
  • ACTIVE_TO - дата окончания активности с учётом пустого значения;
  • DATE_ACTIVE_FROM - дата начала активности без учета пустого значения;
  • DATE_ACTIVE_TO - дата окончания активности без учета пустого значения;
  • ACTIVE_DATE - непустое значение задействует фильтр по датам активности (ACTIVE_FROM и ACTIVE_TO). Если значение не установлено (""), фильтрация по датам активности не производится;
  • MIN_PERMISSION - минимальный уровень доcтупа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются;
  • CNT_ACTIVE - считать количество только активных уроков. Работает, если bIncCnt установлено в значение true.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.
bIncCnt | Возвращать ли количество уроков курса в поле ELEMENT_CNT. Не обязательный параметр, по умолчанию равен false.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CCourse::GetByID
  • Поля курса

Примеры использования

lt;?
if (CModule::IncludeModule("learning"))
{
    $res = CCourse::GetList(
        Array("SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "CNT_ACTIVE" => "Y"),
        $bIncCnt = true
    );

    while ($arCourse = $res->GetNext())
    {
        echo "Course name: ".$arCourse["NAME"]."<br>";
        echo "Active lessons: ".$arCourse["ELEMENT_CNT"]."<br><br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $res = CCourse::GetList(
        Array("SORT"=>"ASC"),
        Array("?NAME" => "Site")
    );

    while ($arCourse = $res->GetNext())
    {
        echo "Course name: ".$arCourse["NAME"]."<br>";
    }
}
?>

<?

if (CModule::IncludeModule("learning"))
{
    $res = CCourse::GetList(
        Array("NAME" => "ASC", "SORT"=>"ASC"),
        Array("CHECK_PERMISSIONS" => "N")
    );

    while ($arCourse = $res->GetNext())
    {
        echo "Course name: ".$arCourse["NAME"]."<br>";
    }
}

?>

<?
if(CModule::IncludeModule("learning")):

    $res = CCourse::GetList(Array("SORT" => "DESC"), Array("ACTIVE" => "Y", "ACTIVE_DATE" => "Y", "SITE_ID" => LANG));

    while ($arElement = $res->GetNext()):?>

        <font class="text">
        <?if ($arElement["PREVIEW_PICTURE"]):?>
            <table cellpadding="0" cellspacing="0" border="0" align="left">

                <tr>
                    <td><?echo ShowImage($arElement["PREVIEW_PICTURE"], 200, 200, "hspace='0' vspace='2' align='left' border='0'", "", true);?></td>
                    <td valign="top" width="0%"><img src="/bitrix/images/1.gif" width="10" height="1"></td>

                </tr>
            </table>
        <?endif;?>
        <a target="blank_" href="<?=$COURSE_URL?>?COURSE_ID=<?=$arElement["ID"]?>"><?=$arElement["NAME"]?></a>

        <?=(strlen($arElement["PREVIEW_TEXT"])>0 ? "<br>".$arElement["PREVIEW_TEXT"]: "")?>
        </font><br clear="all"><br>

    <?endwhile?>
<?endif?>
?>


GetPermission

CCourse::GetPermission

string
CCourse::GetPermission(
 int COURSE_ID
);

Возвращает право доступа к учебному курсу с идентификатором COURSE_ID для текущего пользователя.

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.

Возвращаемое значение

Символ права доступа: "D" - запрещён, "R" - чтение, "W" - изменение, "X" - полный доступ (изменение + право изменять права доступа).

См. также

  • CCourse::SetPermission
  • CCourse::GetGroupPermissions

Примеры использования

<?
$permission = CIBlock::GetPermission($id);
if ($permission<"X")
    return false;
?>


GetSite

CCourse::GetSite

CDBResult
CCourse::GetSite(
 int COURSE_ID
);

Возвращает список сайтов для учебного курса с идентификатором COURSE_ID.

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult

Примеры использования

<?

if (CModule::IncludeModule("learning"))
{

    $ID = 106;//Course ID

    $arSite = Array();
    $db_SITE_ID = CCourse::GetSite($ID);
    while($ar_SITE_ID = $db_SITE_ID->Fetch())
        $arSite[] = $ar_SITE_ID["LID"];

}

?>


IsHaveCourse

CCourse::IsHaveCourse

bool
CCourse::IsHaveCourse(
 string MIN_PERMISSION = "W"
);

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

Параметры функции

Параметр | Описание
MIN_PERMISSION | Минимальное право доступа. По умолчанию "W" - запись.

Возвращаемое значение

Метод возвращает true, если пользователь имеет доступ хотя бы к одному курсу, в противном случае - false.

См. также

  • CCourse::GetList

    Примеры использования

    <?
if (CCourse::IsHaveCourse($MIN_PERMISSION = "W"))
{
  echo "You are a teacher!";
}
else
{
  echo "Access denied!";
}
?>


SetPermission

CCourse::SetPermission

CCourse::SetPermission(
 int COURSE_ID,
 array arPERMISSIONS
);

Функция устанавливает права доступа arPERMISSIONS для учебного курса с идентификатором COURSE_ID.

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.
arPERMISSIONS массив вида Array("код группы"=>"право доступа", ....),
где право доступа:
  • D - доступ запрещён;
  • R - чтение;
  • W - запись;
  • X - полный доступ (запись + назначение прав доступа на данный курс).

См. также

  • CCourse::GetPermission
  • CCourse::Update()

Примеры использования

<?
CCourse::SetPermission($COURSE_ID, Array("2"=>"R", "3"=>"W"));
?>


TimeToStr

CCourse::TimeToStr

string
CCourse::TimeToStr(
 int seconds
);

Возвращает количество дней, часов, минут и секунд в виде строки, содержащихся в seconds.

Параметры функции

Параметр | Описание
seconds | Количество секунд.

Возвращаемое значение

Метод возвращает строку вида "DDдн. HHч. MMмин. SSсек.".

Примеры использования

<?

if (CModule::IncludeModule("learning"))
{
    $seconds = 56789;
    $time = CCourse::TimeToStr($seconds);
    echo $time; //print 15 ч. 46 мин. 29 сек.
}

?>


Update

CCourse::Update

bool
CCourse::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры курса с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор изменяемого курса.
arFields Массив Array("поле"=>"значение", ...). Содержит значения всех полей курса. Обязательные поля должны быть заполнены.
Дополнительно в поле SITE_ID должен находиться массив идентификаторов сайтов, к которым привязан добавляемый курс.
Кроме того, с помощью поля "GROUP_ID", значением которого должен быть массив соответствий кодов групп правам доступа, можно установить права для разных групп на доступ к курсу (см. CCourse::SetPermission).

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернет false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля курса
  • CCourse::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $arFields = Array(
        "ACTIVE" => "Y",
        "NAME" => "New name",
        "SITE_ID" => Array("en"), //Sites
    );

    $ID = 1;//Course ID

    $course = new CCourse;
    $success = $course->Update($ID, $arFields);

    if($success)
    {
        echo "Ok!";

    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Класс CCourseImport

CCourseImport - класс для импорта курса.
Метод | Описание
CCourseImport | (конструктор) инициализирует импортируемый курс.
ImportPackage | Импортирует курс.


CCourseImport

CCourseImport::CCourseImport

bool
CCourseImport::CCourseImport(
 string PACKAGE_DIR,
 array arSITE_ID
);

Конструктор класса CCourseImport. Инициализирует импортируемый курс.

Параметры функции

Параметр | Описание
PACKAGE_DIR | Путь к директории (относительно корня сайта) с архивом курса.
arSITE_ID | Массив идентификаторов сайтов, к которым будет привязан импортируемый курс.

Примечание

Если инициализация прошла неудачно, в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CCourseImport::ImportPackage

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    if ($USER->IsAdmin())
    {
        @set_time_limit(0);
        $package = new CCourseImport($PACKAGE_DIR = "/upload/mypackage/", Array("ru", "en"));

        if (strlen($package->LAST_ERROR) > 0)
        {
            echo "Error: ".$package->LAST_ERROR;
        }
        else
        {
            $success = $package->ImportPackage();

            if (!$success)
                echo "Error: ".$package->LAST_ERROR;
            else
                echo "Ok!";
        }
    }
}
?>


ImportPackage

CCourseImport::ImportPackage

bool
CCourseImport::ImportPackage();

Метод импортирует курс.

Параметры функции

Нет параметров.

Возвращаемое значение

Метод возвращает true, если создание курса прошло успешно. При возникновении ошибки метод вернёт false, а в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

См. также

  • CCourseImport::CCourseImport

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    if ($USER->IsAdmin())
    {
        @set_time_limit(0);
        $package = new CCourseImport($PACKAGE_DIR = "/upload/mypackage/", Array("ru", "en"));

        if (strlen($package->LAST_ERROR) > 0)
        {
            echo "Error: ".$package->LAST_ERROR;
        }
        else
        {
            $success = $package->ImportPackage();

            if (!$success)
                echo "Error: ".$package->LAST_ERROR;
            else
                echo "Ok!";
        }
    }
}
?>


Класс CCoursePackage

CCoursePackage - класс для экспорта курса.
Метод | Описание
CCoursePackage | (конструктор) инициализирует экспортируемый курс.
CreateManifest | Возвращает манифест (в xml-формате) архива.
CreatePackage | Создает архив с учебным курсом.


CCoursePackage

CCoursePackage::CCoursePackage

bool
CCoursePackage::CCoursePackage(
 int COURSE_ID
);

Конструктор класса CCoursePackage инициализирует экспортируемый курс.

Параметры функции

Параметр | Описание
COURSE_ID | Идентификатор курса.

Примечание

Если инициализация прошла неудачно, в свойстве LAST_ERROR объекта будет содержаться текст ошибки.

См. также

  • CCoursePackage::CreatePackage
  • CCoursePackage::CreateManifest

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $package = new CCoursePackage($COURSE_ID);

        if (strlen($package->LAST_ERROR) > 0)
        {
            echo "Error: ".$package->LAST_ERROR;
        }
        else
        {
            $success = $package->CreatePackage($PACKAGE_DIR = "/upload/mypackage/");

            if (!$success)
                echo "Error: ".$package->LAST_ERROR;
            else
                echo "Ok!";
        }

    }
}

?>


CreateManifest

CCoursePackage::CreateManifest

string
CCoursePackage::CreateManifest();

Возвращает манифест (в xml-формате) архива учебного курса.

Параметры функции

Нет параметров.

Возвращаемое значение

Метод возвращает строку - содержимое файла imsmanifest.xml архива учебного курса.

См. также

  • CCoursePackage::CCoursePackage
  • CCoursePackage::CreatePackage

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $package = new CCoursePackage($COURSE_ID);

        if (strlen($package->LAST_ERROR) > 0)
        {
            echo "Error: ".$package->LAST_ERROR;
        }
        else
        {
            echo htmlspecialchars($package->CreateManifest());
        }

    }
}

?>


CreatePackage

CCoursePackage::CreatePackage

bool
CCoursePackage::CreatePackage(
 int PACKAGE_DIR
);

Создает архив с учебным курсом.

Параметры функции

Параметр | Описание
PACKAGE_DIR | Путь (относительно корня сайта) к директории, куда будет скопирован архив курса.

Возвращаемое значение

Метод возвращает true, если создание архива прошло успешно. При возникновении ошибки метод вернет false, а в свойстве объекта LAST_ERROR будет содержаться текст ошибки.

См. также

  • CCoursePackage::CCoursePackage
  • CCoursePackage::CreateManifest

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $package = new CCoursePackage($COURSE_ID);

        if (strlen($package->LAST_ERROR) > 0)
        {
            echo "Error: ".$package->LAST_ERROR;
        }
        else
        {
            $success = $package->CreatePackage($PACKAGE_DIR = "/upload/mypackage/");

            if (!$success)
                echo "Error: ".$package->LAST_ERROR;
            else
                echo "Ok!";
        }

    }
}

?>


Класс CGradeBook

CGradeBook - класс для работы с журналом.
Метод | Описание
GetList | Возвращает список записей журнала по фильтру.
GetByID | Возвращает запись по идентификатору.
Add | Добавляет новую запись в журнал.
Update | Изменяет параметры записи в журнале.
Delete | Удаляет запись из журнала.


Add

CGradeBook::Add

int
CGradeBook::Add(
 array arFields
);

Метод добавляет новую запись в журнал.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей журнала. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленной записи в журнал, если добавление прошло успешно. При возникновении ошибки метод вернёт false, а в исключениях будут содержаться ошибки.

См. также

  • CGradeBook::Update
  • Поля журнала

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 32;
    $STUDENT_ID = 3;

    $arFields = Array(

        "TEST_ID" => $TEST_ID,
        "STUDENT_ID" => $STUDENT_ID,
        "RESULT" => 300,
        "MAX_RESULT" => 300
    );

    $gradebook = new CGradeBook;
    $ID = $gradebook->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }
}
?>


Delete

CGradeBook::Delete

bool
CGradeBook::Delete(
 int ID
);

Метод удаляет запись в журнале с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор записи.

Возвращаемое значение

Метод возвращает true в случае успешного удаления записи, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $RECORD_ID = 96;

    @set_time_limit(0);
    $DB->StartTransaction();
    if (!CGradeBook::Delete($RECORD_ID))
    {
        echo "Error!";
        $DB->Rollback();
    }
    else
        $DB->Commit();

}
?>


GetByID

CGradeBook::GetByID

CDBResult
CGradeBook::GetByID(
 int ID
);

Возвращает запись журнала по идентификатору ID. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
ID | Идентификатор записи в журнале.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля журнала
  • CGradeBook::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $RECORD_ID = 95;

    $res = CGradeBook::GetByID($RECORD_ID);

    if ($arGradeBook = $res->GetNext())
    {
        echo "Test: ".$arGradeBook["TEST_NAME"]." User: ".$arGradeBook["USER_NAME"]." Score: ".$arGradeBook["RESULT"];
    }
}

?>


GetList

CGradeBook::GetList

CDBResult
CGradeBook::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array()
);

Возвращает список записей журнала по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор записи;
  • TEST_ID - идентификатор теста;
  • STUDENT_ID - идентификатор студента ;
  • RESULT - количество баллов;
  • MAX_RESULT - максимальное количество баллов;
  • COMPLETED - тест пройден;
  • USER_NAME - имя студента;
  • TEST_NAME - название теста.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию идентификатора записи журнала.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор записи;
  • TEST_ID - идентификатор теста;
  • STUDENT_ID - идентификатор студента;
  • RESULT - количество баллов;
  • MAX_RESULT - максимальное количество баллов;
  • COMPLETED - тест пройден (Y|N);
  • USER - пользователь (возможны сложные условия по полям пользователя ID, LOGIN, NAME, LAST_NAME);
  • MIN_PERMISSION - минимальный уровень доcтупа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CGradeBook::GetByID
  • Поля журнала

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 45;
    $res = CGradebook::GetList(
        Array("ID" => "ASC"),
        Array("TEST_ID" => $TEST_ID)
    );

    while ($arGradebook = $res->GetNext())
    {
        echo "Student: ".$arGradebook["USER_NAME"]."; Test name: ".$arGradebook["TEST_NAME"]."; Completed: ".$arGradebook["COMPLETED"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 45;
    $STUDENT_ID = 3;

    $res = CGradebook::GetList(
        Array("ID" => "ASC"),
        Array("CHECK_PERMISSIONS" => "N", "TEST_ID" => $TEST_ID, "STUDENT_ID" => $STUDENT_ID)
    );

    while ($arGradebook = $res->GetNext())
    {
        echo "Student: ".$arGradebook["USER_NAME"]."; Test name: ".$arGradebook["TEST_NAME"]."; Completed: ".$arGradebook["COMPLETED"]."<br>";
    }

}

?>


Update

CGradeBook::Update

bool
CGradeBook::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры записи в журнале с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор записи в журнале.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей журнала. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернет false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля журнала
  • CGradeBook::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $RECORD_ID = 96;

    $arFields = Array(
        "RESULT" => 250,
        "MAX_RESULT" => 300
    );

    $gradebook = new CGradeBook;
    $success = $gradebook->Update($RECORD_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }
}
?>


Класс CLAnswer

CLAnswer - класс для работы с ответами вопроса.
Метод | Описание
GetList | Возвращает список ответов по фильтру.
GetByID | Возвращает ответ по идентификатору.
Add | Добавляет новый ответ.
Update | Изменяет параметры ответа.
Delete | Удаляет ответ.


Add

CLAnswer::Add

int
CLAnswer::Add(
 array arFields
);

Метод добавляет новый ответ на вопрос.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей ответа. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленного ответа, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CLAnswer::Update
  • Поля ответа

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 289;

    $arFields = Array(
        "ANSWER" => "Another answer",
        "QUESTION_ID" => $QUESTION_ID,
    );

    $answer = new CLAnswer;
    $ID = $answer->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Delete

CLAnswer::Delete

bool
CLAnswer::Delete(
 int ID
);

Метод удаляет ответ с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор ответа.

Возвращаемое значение

Метод возвращает true в случае успешного удаления ответа, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $ANSWER_ID = 1553;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CLAnswer::Delete($ANSWER_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CLAnswer::GetByID

CDBResult
CLAnswer::GetByID(
 int ID
);

Возвращает ответ по его коду ID.

Параметры функции

Параметр | Описание
ID | Идентификатор ответа.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля ответа
  • CLAnswer::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ANSWER_ID = 573;

    $res = CLAnswer::GetByID($ANSWER_ID);

    if ($arAnswer = $res->GetNext())
    {
        echo "Name: ".$arAnswer["ANSWER"];
    }
}
?>


GetList

CLAnswer::GetList

CDBResult
CLAnswer::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array()
);

Возвращает список ответов по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор ответа;
  • SORT - индекс сортировки;
  • CORRECT - правильность ответа;
  • ANSWER - текст ответа;
  • RAND - случайный порядок;
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию идентификатора ответа.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор ответа;
  • SORT - индекс сортировки;
  • QUESTION_ID - идентификатор вопроса;
  • ANSWER - текст ответа (можно искать по шаблону [%_]);
  • CORRECT - правильность ответа (Y|N);
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CLAnswer::GetByID
  • Поля ответа

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 290;
    $res = CLAnswer::GetList(
        Array("SORT"=>"DESC"),
        Array("QUESTION_ID" => $QUESTION_ID)
    );

    while ($arAnswer = $res->GetNext())
    {
        echo "Answer name: ".$arAnswer["ANSWER"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 290;

    $res = CLAnswer::GetList(
        Array("SORT"=>"ASC"),
        Array("QUESTION_ID" => $QUESTION_ID, "?ANSWER" => "sys")
    );

    while ($arAnswer = $res->GetNext())
    {
        echo "Answer name: ".$arAnswer["ANSWER"]."<br>";
    }
}
?>

<?

if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 290;

    $res = CLAnswer::GetList(
        Array(),
        Array("QUESTION_ID" => $QUESTION_ID, "CORRECT" => "Y")
    );

    while ($arAnswer = $res->GetNext())
    {
        echo "Answer name: ".$arAnswer["ANSWER"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 290;

    $res = CLAnswer::GetList(
        Array("TIMESTAMP_X" => "ASC", "SORT"=>"ASC"),
        Array("QUESTION_ID" => $QUESTION_ID)
    );

    while ($arAnswer = $res->GetNext())
    {
        echo "Answer name: ".$arAnswer["ANSWER"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 290;

    $res = CLAnswer::GetList(
        Array("RAND"=>""),
        Array("QUESTION_ID" => $QUESTION_ID)
    );

    while ($arAnswer = $res->GetNext())
    {
        echo "Answer name: ".$arAnswer["ANSWER"]."<br>";
    }
}

?>


Update

CLAnswer::Update

bool
CLAnswer::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры ответа с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор ответа.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей ответа. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернет false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля ответа
  • CLAnswer::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ANSWER_ID = 1553;

    $arFields = Array(
        "ANSWER" => "New answer name",
        "SORT" => "1",
    );

    $answer = new CLAnswer;
    $success = $answer->Update($ANSWER_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Класс CLesson

CLesson - класс для работы с уроками.
Метод | Описание
GetList | Возвращает список уроков по фильтру.
GetByID | Возвращает урок по идентификатору.
Add | Добавляет новый урок.
Update | Изменяет параметры урока.
Delete | Удаляет урок.


Add

CLesson::Add

int
CLesson::Add(
 array arFields
);

Метод добавляет новый урок.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей урока. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленного урока, если добавление прошло успешно. При возникновении ошибки метод вернёт false, а в исключениях будут содержаться ошибки.

См. также

  • CLesson::Update
  • Поля урока

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $arFields = Array(
        "ACTIVE" => "Y",
        "COURSE_ID" => $COURSE_ID,
        "NAME" => "Lesson 1",
        "SORT" => "1",
        "DETAIL_TEXT" => "It my first lesson ...",
    );

    $lesson = new CLesson;
    $ID = $lesson->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Delete

CLesson::Delete

bool
CLesson::Delete(
 int ID
);

Метод удаляет урок с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор урока.

Возвращаемое значение

Метод возвращает true в случае успешного удаления урока, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $LESSON_ID = 732;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CLesson::Delete($LESSON_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CLesson::GetByID

CDBResult
CLesson::GetByID(
 int ID
);

Возвращает урок по его коду ID. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
ID | Идентификатор урока.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля урока
  • CLesson::GetList

    Примеры использования

    <?
if (CModule::IncludeModule("learning"))
{
    $LESSON_ID = 651;

    $res = CLesson::GetByID($LESSON_ID);

    if ($arLesson = $res->GetNext())
    {
        echo "Name: ".$arLesson["NAME"];
    }
}
?>


GetList

CLesson::GetList

CDBResult
CLesson::GetList(
 array arOrder = Array("TIMESTAMP_X"=>"DESC"),
 array arFilter = Array()
);

Возвращает список уроков по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор урока;
  • NAME - название урока;
  • ACTIVE - активность урока;
  • SORT - индекс сортировки;
  • TIMESTAMP_X - дата изменения урока.
  • CREATED_BY - код пользователя, создавшего урок.
  • CHAPTER_NAME - название главы, в .
  • DATE_CREATE - дата создания урока.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию даты изменения урока.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор урока;
  • NAME - название урока (можно искать по шаблону [%_]);
  • SORT - индекс сортировки;
  • ACTIVE - фильтр по активности (Y|N);
  • TIMESTAMP_X - дата изменения урока;
  • DATE_CREATE - дата создания урока;
  • CHAPTER_ID - идентификатор главы. Для получения списка родительских глав установите это поле в значение пусто;
  • COURSE_ID - идентификатор курса;
  • CREATED_BY - код пользователя, создавшего урок;
  • DETAIL_TEXT - детальное описание (можно искать по шаблону [%_]);
  • PREVIEW_TEXT - предварительное описание (можно искать по шаблону [%_]);
  • MIN_PERMISSION - минимальный уровень доcтупа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CLesson::GetByID
  • Поля урока

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 8;
    $res = CLesson::GetList(
        Array("SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID)
    );

    while ($arLesson = $res->GetNext())
    {
        echo "Lesson name: ".$arLesson["NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $res = CLesson::GetList(
        Array("SORT"=>"ASC"),
        Array("?NAME" => "Site")
    );

    while ($arLesson = $res->GetNext())
    {
        echo "Lesson name: ".$arLesson["NAME"]."<br>";
    }
}
?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 8;

    $res = CLesson::GetList(
        Array("NAME" => "ASC", "SORT"=>"ASC"),
        Array("CHECK_PERMISSIONS" => "N", "COURSE_ID" => $COURSE_ID)
    );

    while ($arLesson = $res->GetNext())
    {
        echo "Lesson name: ".$arLesson["NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 8;

    $res = CLesson::GetList(
        Array("NAME" => "ASC", "SORT"=>"ASC"),
        Array("CHECK_PERMISSIONS" => "N", "CHAPTER_ID" => "", "COURSE_ID" => $COURSE_ID)
    );

    while ($arLesson = $res->GetNext())
    {
        echo "Lesson name: ".$arLesson["NAME"]."<br>";
    }
}

?>


Update

CLesson::Update

bool
CLesson::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры урока с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор урока.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей урока. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернёт false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля урока
  • CLesson::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $LESSON_ID = 732;

    $arFields = Array(
        "ACTIVE" => "N",
        "NAME" => "New name of Lesson 1",
        "SORT" => "555",
    );

    $lesson = new CLesson;
    $success = $lesson->Update($LESSON_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Класс CLQuestion

CLQuestion - класс для работы с вопросами.
Метод | Описание
GetList | Возвращает список вопросов по фильтру.
GetByID | Возвращает вопрос по идентификатору.
Add | Добавляет новый вопрос.
Update | Изменяет параметры вопроса.
Delete | Удаляет вопрос.
GetCount | Возвращает количество вопросов.


Add

CLQuestion::Add

int
CLQuestion::Add(
 array arFields
);

Метод добавляет новый вопрос.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей вопроса. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленного вопроса, если добавление прошло успешно. При возникновении ошибки метод вернет false, а в исключениях будут содержаться ошибки.

См. также

  • CLQuestion::Update
  • Поля вопроса

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $LESSON_ID = 431;

    $arFields = Array(
        "ACTIVE" => "Y",
        "LESSON_ID" => $LESSON_ID,
        "NAME" => "Lesson 1",
        "SORT" => "1",
        "NAME" => "Let us assume that there are several sites in the system.
        Is it possible to assign users permissions on access to viewing statistics individually for each site?"
    );

    $question = new CLQuestion;
    $ID = $question->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Delete

CLQuestion::Delete

bool
CLQuestion::Delete(
 int ID
);

Метод удаляет вопрос с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор вопроса.

Возвращаемое значение

Метод возвращает true в случае успешного удаления вопроса, в противном случае возвращает false.

См. также

  • CLQuestion::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $QUESTION_ID = 600;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CLQuestion::Delete($QUESTION_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CLQuestion::GetByID

CDBResult
CLQuestion::GetByID(
 int ID
);

Возвращает вопрос по идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор вопроса.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля вопроса
  • CLQuestion::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 289;

    $res = CLQuestion::GetByID($QUESTION_ID);

    if ($arQuestion = $res->GetNext())
    {
        echo "Name: ".$arQuestion["NAME"];
    }
}
?>


GetCount

CLQuestion::GetCount

int
CLQuestion::GetCount(
 array arFilter = Array()
);

Метод возвращает количество вопросов по заданному фильтру.

Параметры функции

Параметр | Описание
arFilter | Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Описание фильтра см. в CLQuestion::GetList. По умолчанию вопросы не фильтруются.

Возвращаемое значение

Число - количество вопросов.

См. также

  • CLQuestion::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $cnt = CLQuestion::GetCount(Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID));

    echo "Number of questions: ".$cnt;
}

?>

<?
if (CModule::IncludeModule("learning"))
{
    $LESSON_ID = 426;

    $cnt = CLQuestion::GetCount(Array("LESSON_ID" => $LESSON_ID));

    echo "Number of questions: ".$cnt;
}

?>


GetList

CLQuestion::GetList

CDBResult
CLQuestion::GetList(
 array arOrder = Array("TIMESTAMP_X"=>"DESC"),
 array arFilter = Array()
);

Возвращает список вопросов по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор вопроса;
  • NAME - название вопроса;
  • ACTIVE - активность вопроса;
  • SORT - индекс сортировки;
  • SELF - вопрос для самопроверки;
  • POINT - баллы;
  • TYPE - тип вопроса;
  • TIMESTAMP_X - дата изменения вопроса.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию даты изменения вопроса.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор вопроса;
  • NAME - название вопроса (можно искать по шаблону [%_]);
  • SORT - индекс сортировки;
  • ACTIVE - фильтр по активности (Y|N);
  • LESSON_ID - идентификатор урока;
  • POINT - баллы;
  • COURSE_ID - идентификатор курса;
  • QUESTION_TYPE - тип вопроса (S - одиночный выбор, M - множественный выбор);
  • SELF - вопрос для самопроверки (Y|N).
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CLQuestion::GetByID
  • Поля вопроса

Примеры использования

<?

if (CModule::IncludeModule("learning"))
{
    $LESSON_ID = 426;

    $res = CLQuestion::GetList(
        Array("TIMESTAMP_X" => "ASC", "SORT"=>"ASC"),
        Array("LESSON_ID" => $LESSON_ID)
    );

    while ($arQuestion = $res->GetNext())
    {
        echo "Question name: ".$arQuestion["NAME"]."<br>";
    }
}

?>

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $res = CLQuestion::GetList(
        Array("SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID)
    );

    while ($arQuestion = $res->GetNext())
    {
        echo "Question name: ".$arQuestion["NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $res = CLQuestion::GetList(
        Array("SORT"=>"ASC"),
        Array("?NAME" => "Site")
    );

    while ($arQuestion = $res->GetNext())
    {
        echo "Question name: ".$arQuestion["NAME"]."<br>";
    }
}
?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $res = CLQuestion::GetList(
        Array("NAME" => "ASC", "SORT"=>"ASC"),
        Array("COURSE_ID" => $COURSE_ID, "!SELF" => "Y")
    );

    while ($arQuestion = $res->GetNext())
    {
        echo "Question name: ".$arQuestion["NAME"]."<br>";
    }
}

?>


Update

CLQuestion::Update

bool
CLQuestion::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры вопроса с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор вопроса.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей вопроса. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернёт false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля вопроса
  • CLQuestion::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $QUESTION_ID = 600;

    $arFields = Array(
        "ACTIVE" => "N",
        "NAME" => "New name of question",
        "SORT" => "555",
    );

    $question = new CLQuestion;
    $success = $question->Update($QUESTION_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Класс CStudent

CStudent - класс для работы с учетными записями студентов.
Метод | Описание
GetList | Возвращает список учетных записей студентов.
GetByID | Возвращает учетную запись по идентификатору.
Add | Добавляет новую учетную запись.
Update | Изменяет параметры учетной записи.
Delete | Удаляет учетную запись.
GenerateTranscipt | Возвращает случайный числовой идентификатор.


Add

CStudent::Add

int
CStudent::Add(
 array arFields
);

Метод добавляет новую учетную запись студента.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей учётной записи студента. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленной учетной записи студента (равный коду пользователя), если добавление прошло успешно. При возникновении ошибки метод вернёт false, а в исключениях будут содержаться ошибки.

См. также

  • CStudent::Update
  • Поля учетной записи студента

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $arFields = Array(
        "USER_ID" => 151,
        "RESUME" => "My resume"
    );

    $student = new CStudent;
    $ID = $student->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Delete

CStudent::Delete

bool
CStudent::Delete(
 int USER_ID
);

Метод удаляет учётную запись студента с кодом пользователя USER_ID.

Параметры функции

Параметр | Описание
USER_ID | Код пользователя.

Возвращаемое значение

Метод возвращает true в случае успешного удаления учётной записи студента, в противном случае возвращает false.

См. также

  • CStudent::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $USER_ID = 3;
    if ($USER->IsAdmin())
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CStudent::Delete($USER_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GenerateTranscipt

CStudent::GenerateTranscipt

int
CStudent::GenerateTranscipt(
 int TranscriptLength = 8
);

Возвращает случайный числовой идентификатор.

Параметры функции

Параметр | Описание
TranscriptLength | Длина числового идентификатора. По умолчанию равна 8.

Возвращаемое значение

Случайное число.

См. также

  • CStudent::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    echo CStudent::GenerateTranscipt();
}
?>


GetByID

CStudent::GetByID

CDBResult
CStudent::GetByID(
 int USER_ID
);

Возвращает возвращает учётную запись студента по коду пользователя USER_ID.

Параметры функции

Параметр | Описание
USER_ID | Код пользователя.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля учетной записи студента
  • CStudent::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $USER_ID = 3;

    $res = CStudent::GetByID($USER_ID);

    if ($arStudent = $res->GetNext())
    {
        echo "CP: ".$arStudent["RESUME"];
    }
}
?>


GetList

CStudent::GetList

CDBResult
CStudent::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array()
);

Возвращает список учётных записей студентов по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • USER_ID - Код пользователя;
  • PUBLIC_PROFILE - профиль доступен публично (Y/N);
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию коду пользователя.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • USER_ID - Код пользователя;
  • PUBLIC_PROFILE - профиль доступен публично (Y/N);
  • TRANSCRIPT - числовой случайный идентификатор;
  • RESUME - резюме студента (можно искать по шаблону [%_]);
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CStudent::GetByID
  • Поля студента

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $USER_ID = 1; $TRANSCRIPT = 46785643;
    $res = CStudent::GetList(Array(), Array("USER_ID" => $USER_ID, "TRANSCRIPT" => $TRANSCRIPT));

    while ($arProfile = $res->GetNext())
    {
        echo $arProfile["RESUME"];
    }
}
?>


Update

CStudent::Update

bool
CStudent::Update(
 int   USER_ID,
 array arFields
);

Метод изменяет параметры учётной записи студента с идентификатором ID.

Параметры функции

Параметр | Описание
USER_ID | Код пользователя.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей учетной записи студента. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернёт false. При возникновении ошибки в исключениях будет содержаться текст ошибки

См. также

  • Поля учетной записи студента
  • CStudent::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $USER_ID = 151;

    $arFields = Array(
        "RESUME" => "My new CP",
    );

    $student = new CStudent;
    $success = $student->Update($USER_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Класс CTest

CTest - класс для работы с тестами.
Метод | Описание
GetList | Возвращает список тестов по фильтру.
GetByID | Возвращает тест по идентификатору.
Add | Добавляет новый тест.
Update | Изменяет параметры теста.
Delete | Удаляет тест.
GetCount | Возвращает количество тестов по фильтру.


Add

CTest::Add

int
CTest::Add(
 array arFields
);

Метод добавляет новый тест.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей теста. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленного теста, если добавление прошло успешно. При возникновении ошибки метод вернёт false, а в исключениях будут содержаться ошибки.

См. также

  • CTest::Update
  • Поля теста

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{

    $COURSE_ID = 97;

    $arFields = Array(
        "COURSE_ID" => $COURSE_ID,
        "NAME" => "New test!",
        "INCLUDE_SELF_TEST" => "Y"
    );

    $test = new CTest;
    $ID = $test->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Delete

CTest::Delete

bool
CTest::Delete(
 int ID
);

Метод удаляет тест с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор теста.

Возвращаемое значение

Метод возвращает true в случае успешного удаления теста, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{

    $TEST_ID = 99;
    $COURSE_ID = 97;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CTest::Delete($TEST_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CTest::GetByID

CDBResult
CTest::GetByID(
 int ID
);

Возвращает тест по идентификатору ID. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
ID | Идентификатор теста.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля теста
  • CTest::GetList

    Примеры использования

    <?
if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 32;

    $res = CTest::GetByID($TEST_ID);

    if ($arTest = $res->GetNext())
    {
        echo "Test name: ".$arTest["NAME"];
    }
}
?>


GetCount

CTest::GetCount

int
CTest::GetCount(
 array arFilter = Array()
);

Возвращает количество тестов по заданному фильтру.

Параметры функции

Параметр | Описание
arFilter | Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Описание фильтра см. в CTest::GetList. По умолчанию тесты не фильтруются.

Возвращаемое значение

Число - количество тестов.

См. также

  • CTest::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $cnt = CTest::GetCount(Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID));

    echo "Number of tests: ".$cnt;
}

?>

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $cnt = CTest::GetCount(Array("CHECK_PERMISSIONS" => "N", "COURSE_ID" => $COURSE_ID));

    echo "Number of tests: ".$cnt;
}

?>


GetList

CTest::GetList

CDBResult
CTest::GetList(
 array arOrder = Array("TIMESTAMP_X"=>"DESC"),
 array arFilter = Array()
);

Возвращает список тестов по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор теста;
  • SORT - индекс сортировки;
  • NAME - название теста;
  • SORT - индекс сортировки;
  • TIMESTAMP_X - даты изменения теста;
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию даты изменения теста.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор теста;
  • SORT - индекс сортировки;
  • COURSE_ID - идентификатор курса;
  • ATTEMPT_LIMIT - количество попыток;
  • TIME_LIMIT - ограничение времени прохождения теста (в минутах);
  • NAME - название теста (можно искать по шаблону [%_]);
  • DESCRIPTION - описание теста (можно искать по шаблону [%_]);
  • ACTIVE - фильтр по активности (Y|N);
  • APPROVED - автоматическая проверка результатов (Y|N);
  • INCLUDE_SELF_TEST - включать вопросы для самопроверки (Y|N);
  • RANDOM_QUESTIONS - случайный порядок вопросов (Y|N);
  • RANDOM_ANSWERS - случайный порядок ответов (Y|N);
  • QUESTIONS_FROM - в тесте участвуют вопросы (A - со всего курса, C - с каждой главы, L - с каждого урока);
  • PASSAGE_TYPE - Тип прохождения теста. 0 - запретить переход к следующему вопросу без ответа на текущий вопрос, пользователь не может изменять свои ответы; 1 - разрешить переход к следующему вопросу без ответа на текущий вопрос, пользователь не может изменять свои ответы; 3 - разрешить переход к следующему вопросу без ответа на текущий вопрос, пользователь может изменять свои ответы.
  • MIN_PERMISSION - минимальный уровень доcтупа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CTest::GetByID
  • Поля теста

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;
    $res = CTest::GetList(
        Array("SORT"=>"ASC"),
        Array("ACTIVE" => "Y", "COURSE_ID" => $COURSE_ID)
    );

    while ($arTest = $res->GetNext())
    {
        echo "Test name: ".$arTest["NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $res = CTest::GetList(
        Array("SORT"=>"ASC"),
        Array("?NAME" => "Site")
    );

    while ($arTest = $res->GetNext())
    {
        echo "Test name: ".$arTest["NAME"]."<br>";
    }
}
?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $res = CTest::GetList(
        Array("NAME" => "ASC", "SORT"=>"ASC"),
        Array("COURSE_ID" => $COURSE_ID, "APPROVED" => "Y")
    );

    while ($arTest = $res->GetNext())
    {
        echo "Test name: ".$arTest["NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 97;

    $res = CTest::GetList(
        Array("TIMESTAMP_X" => "ASC", "SORT"=>"ASC"),
        Array("CHECK_PERMISSIONS" => "N", "COURSE_ID" => $COURSE_ID)
    );

    while ($arTest = $res->GetNext())
    {
        echo "Test name: ".$arTest["NAME"]."<br>";
    }
}

?>


Update

CTest::Update

bool
CTest::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры теста с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор теста.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей теста. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернет false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля теста
  • CTest::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{

    $TEST_ID = 99;

    $arFields = Array(
        "NAME" => "New name",
        "INCLUDE_SELF_TEST" => "N",
        "QUESTIONS_AMOUNT" => 5
    );

    $test = new CTest;
    $success = $test->Update($TEST_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}

?>


Класс CTestAttempt

CTestAttempt - класс для работы с попытками.
Метод | Описание
GetList | Возвращает список попыток по фильтру.
GetByID | Возвращает попытку по идентификатору.
Add | Добавляет новую попытку.
Update | Изменяет параметры попытки.
Delete | Удаляет попытку.
GetCount | Возвращает количество попыток.
AttemptFinished | Переводит попытку в статус "Закончена" и пересчитывает набранные баллы.
IsTestCompleted | Проверяет, пройден ли тест.
CreateAttemptQuestions | Создает план вопросов для указанной попытки.


Add

CTestAttempt::Add

int
CTestAttempt::Add(
 array arFields
);

Метод добавляет новую попытку.

Параметры функции

Параметр | Описание
Параметр | Массив Array("поле"=>"значение", ...). Содержит значения всех полей попытки. Обязательные поля должны быть заполнены.

Возвращаемое значение

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

См. также

  • CTestAttempt::Update
  • Поля попытки

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 32;
    $STUDENT_ID = 3;

    $arFields = Array(
        "TEST_ID" => $TEST_ID,
        "STUDENT_ID" => $STUDENT_ID,
        "STATUS" => "B"
    );

    $attempt = new CTestAttempt;
    $ID = $attempt->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


AttemptFinished

CTestAttempt::AttemptFinished

bool
CTestAttempt::AttemptFinished(
 int ATTEMPT_ID
);

Переводит попытку в статус "Закончена" и пересчитывает набранные баллы.

Параметры функции

Параметр | Описание
ATTEMPT_ID | Идентификатор попытки.

Возвращаемое значение

Метод возвращает true, если операция выполнилась успешно, иначе false.

См. также

  • CTestAttempt::Update

Примеры использования

if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 23;
    $oTestAttempt = new CTestAttempt;
    $success = $oTestAttempt->AttemptFinished($ATTEMPT_ID);
    if ($success)
        echo "Attempt has been finished";
    else
        echo "Error!";
}


CreateAttemptQuestions

CTestAttempt::CreateAttemptQuestions

bool
CTestAttempt::CreateAttemptQuestions(
 int ATTEMPT_ID
);

Создаёт план вопросов для указанной попытки.

Параметры функции

Параметр | Описание
ATTEMPT_ID | Идентификатор попытки.

Возвращаемое значение

Метод возвращает true, если создание плана вопросов прошло успешно. При возникновении ошибки метод вернёт false, а в исключениях будут содержаться ошибки.

См. также

  • CTestResult::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 563;

    $success = CTestAttempt::CreateAttemptQuestions($ATTEMPT_ID);

    if($success)
    {
        echo "Questions have been created.";
    }
    else
    {
        if($ex = $APPLICATION->GetException())
            echo "Error: ".$ex->GetString();
    }

}
?>


Delete

CTestAttempt::Delete

bool
CTestAttempt::Delete(
 int ID
);

Метод удаляет попытку с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор попытки.

Возвращаемое значение

Метод возвращает true в случае успешного удаления попытки, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $COURSE_ID = 83;
    $ATTEMPT_ID = 596;

    if (CCourse::GetPermission($COURSE_ID) >= 'W')
    {
        @set_time_limit(0);
        $DB->StartTransaction();
        if (!CTestAttempt::Delete($ATTEMPT_ID))
        {
            echo "Error!";
            $DB->Rollback();
        }
        else
            $DB->Commit();
    }
}
?>


GetByID

CTestAttempt::GetByID

CDBResult
CTestAttempt::GetByID(
 int ID
);

Возвращает попытку по идентификатору ID. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр | Описание
ID | Идентификатор попытки.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля попытки
  • CTestAttempt::GetList

    Примеры использования

    <?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 590;

    $res = CTestAttempt::GetByID($ATTEMPT_ID);

    if ($arAttempt = $res->GetNext())
    {
        echo "Test name: ".$arAttempt["TEST_NAME"];
        echo "Date start: ".$arAttempt["DATE_START"];
    }
}
?>


GetCount

CTestAttempt::GetCount

int
CTestAttempt::GetCount(
 int TEST_ID
 int STUDENT_ID
);

Возвращает количество попыток студента для указанного теста.

Параметры функции

Параметр | Описание
TEST_ID | Идентификатор теста.
STUDENT_ID | Идентификатор студента.

Возвращаемое значение

Число - количество попыток.

См. также

  • CTestAttempt::GetList

    Примеры использования

    <?
if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 33;
    $STUDENT_ID = 165;

    $cnt = CTestAttempt::GetCount($TEST_ID, $STUDENT_ID);

    echo "Number of attempts:".$cnt;

}
?>


GetList

CTestAttempt::GetList

CDBResult
CTestAttempt::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array()
);

Возвращает список попыток по фильтру arFilter, отсортированный в порядке arOrder. Учитываются права доступа текущего пользователя.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор попытки;
  • TEST_ID - идентификатор теста;
  • STUDENT_ID - идентификатор студента ;
  • DATE_START - дата начала попытки;
  • DATE_END - дата окончания попытки;
  • STATUS - статус попытки;
  • SCORE - количество баллов;
  • MAX_SCORE - максимальное количество баллов;
  • COMPLETED - тест пройден;
  • QUESTIONS - количество вопросов;
  • USER_NAME - имя студента ;
  • TEST_NAME - название теста.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию идентификатора попытки.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор попытки;
  • TEST_ID - идентификатор теста;
  • STUDENT_ID - идентификатор студента;
  • SCORE - количество баллов;
  • MAX_SCORE - максимальное количество баллов;
  • QUESTIONS - количество вопросов;
  • STATUS - статус попытки (B - тестирование началось, D - тест прерван, F - тест закончен.);
  • COMPLETED - тест пройден (Y|N);
  • DATE_START - дата начала попытки;
  • DATE_END - дата окончания попытки;
  • USER - пользователь (возможны сложные условия по полям пользователя ID, LOGIN, NAME, LAST_NAME);
  • MIN_PERMISSION - минимальный уровень доcтупа. По умолчанию "R". Список прав доступа см. в CCourse::SetPermission.
  • CHECK_PERMISSIONS - проверять уровень доступа. Если установлено значение "N" - права доступа не проверяются.
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CTestAttempt::GetByID
  • Поля попытки

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 45;
    $res = CTestAttempt::GetList(
        Array("ID" => "ASC"),
        Array("TEST_ID" => $TEST_ID)
    );

    while ($arAttempt = $res->GetNext())
    {
        echo "Attempt ID:".$arAttempt["ID"]."; Date start: ".$arAttempt["DATE_START"]."; Test name: ".$arAttempt["TEST_NAME"]."<br>";
    }
}

?>

<?

if (CModule::IncludeModule("learning"))
{
    $TEST_ID = 45;
    $STUDENT_ID = 3;

    $res = CTestAttempt::GetList(
        Array("SCORE" => "DESC"),
        Array("CHECK_PERMISSIONS" => "N", "TEST_ID" => $TEST_ID, "STUDENT_ID" => $STUDENT_ID)
    );

    while ($arAttempt = $res->GetNext())
    {
        echo "Attempt ID:".$arAttempt["ID"]."; Date start: ".$arAttempt["DATE_START"]."; Test name: ".$arAttempt["TEST_NAME"]."<br>";
    }
}

?>


IsTestCompleted

CTestAttempt::IsTestCompleted

bool
CTestAttempt::IsTestCompleted(
 int ATTEMPT_ID
 int PERCENT
);

Проверяет, пройден ли тест.

Параметры функции

Параметр | Описание
ATTEMPT_ID | Идентификатор попытки.
PERCENT | Количество процентов, необходимых для прохождения теста.

Возвращаемое значение

Метод возвращает true, если тест пройден, иначе - false.

См. также

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 563;
    $PERCENT = 30;

    $complete = CTestAttempt::IsTestCompleted($ATTEMPT_ID, $PERCENT);

    if ($complete)
        echo "Test has been completed";
    else
        echo "Try again";
}
?>


Update

CTestAttempt::Update

bool
CTestAttempt::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры попытки с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор попытки
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей попытки. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернёт false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля попытки
  • CTestAttempt::Add

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 596;

    $arFields = Array(
        "STATUS" => "F",
        "DATE_END" => ConvertTimeStamp(false,"FULL")
    );

    $attempt = new CTestAttempt;
    $ID = $attempt->Update($ATTEMPT_ID, $arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Класс CTestResult

CTestResult - класс для работы с планом тестирования.
Метод | Описание
GetList | Возвращает список вопросов плана тестирования.
GetByID | Возвращает вопрос плана тестирования по идентификатору.
Add | Добавляет новый вопрос плана тестирования.
Update | Изменяет параметры вопроса плана тестирования.
AddResponse | Сохраняет ответ учащегося и устанавливает, отвечен ли вопрос правильно.
Delete | Удаляет вопрос плана тестирования.
GetCount | Возвращает количество вопросов плана тестирования для указанной попытки.
GetProgress | Возвращает количество отвеченных и неотвеченных вопросов плана тестирования.


Add

CTestResult::Add

int
CTestResult::Add(
 array arFields
);

Метод добавляет новый вопрос плана тестирования.

Параметры функции

Параметр | Описание
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей плана тестирования. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает идентификатор добавленного вопроса плана тестирования, если добавление прошло успешно. При возникновении ошибки метод вернёт false, а в исключениях будут содержаться ошибки.

См. также

  • CTestAttempt::CreateAttemptQuestions
  • CTestResult::Update
  • CTestResult::AddResponse
  • Поля плана тестирования

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 588;
    $QUESTION_ID = 128;

    $arFields = Array(
        "ATTEMPT_ID" => $ATTEMPT_ID,
        "QUESTION_ID" => $QUESTION_ID
    );

    $plan = new CTestResult;
    $ID = $plan->Add($arFields);
    $success = ($ID>0);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


AddResponse

CTestResult::AddResponse

bool
CTestResult::AddResponse(
 int TEST_RESULT_ID
 mixed RESPONSE
);

Сохраняет ответ учащегося и устанавливает, отвечен ли вопрос правильно.

Параметры функции

Параметр | Описание
TEST_RESULT_ID | Идентификатор вопроса в плане тестирования.
RESPONSE | Идентификатор или массив идентификаторов ответов на вопрос.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернёт false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • CTestResult::Update

Примеры использования

if (CModule::IncludeModule("learning"))
{
    $TEST_TESULT_ID = 2962;
    $RESPONSE = 186; /* or Array(186,187); */

    $res = CTestResult::AddResponse($TEST_RESULT_ID, $RESPONSE);
    if($res)
     echo "Response has been added ";
    else
     echo "Error";
}


Delete

CTestResult::Delete

bool
CTestResult::Delete(
 int ID
);

Метод удаляет вопрос плана тестирования с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор вопроса в плане тестирования.

Возвращаемое значение

Метод возвращает true в случае успешного удаления результата тестирования, в противном случае возвращает false.

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_RESULT_ID = 2967;

    @set_time_limit(0);
    $DB->StartTransaction();
    if (!CTestResult::Delete($TEST_RESULT_ID))
    {
        echo "Error!";
        $DB->Rollback();
    }
    else
        $DB->Commit();

}
?>


GetByID

CTestResult::GetByID

CDBResult
CTestResult::GetByID(
 int ID
);

Возвращает вопрос плана тестирования по идентификатору ID.

Параметры функции

Параметр | Описание
ID | Идентификатор вопроса в плане тестирования.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • Поля плана тестирования
  • CTestResult::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_RESULT_ID = 2894;

    $res = CTestResult::GetByID($TEST_RESULT_ID);

    if ($arResult = $res->GetNext())
    {
        echo " Question name: ".$arResult["QUESTION_NAME"];
        echo " Answered: ".$arResult["ANSWERED"];
        echo " Point: ".$arResult["POINT"];
    }
}
?>


GetCount

CTestResult::GetCount

int
CTestResult::GetCount(
 int ATTEMPT_ID
);

Возвращает количество вопросов плана тестирования для указанной попытки.

Параметры функции

Параметр | Описание
ATTEMPT_ID | Идентификатор попытки.

Возвращаемое значение

Число - количество вопросов плана тестирования.

См. также

  • CTestResult::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 588;

    $cnt = CTestResult::GetCount($ATTEMPT_ID);

    echo "Number of questions:".$cnt;

}
?>


GetList

CTestResult::GetList

CDBResult
CTestResult::GetList(
 array arOrder = Array("ID"=>"DESC"),
 array arFilter = Array()
);

Возвращает список вопросов плана тестирования по фильтру arFilter, отсортированный в порядке arOrder.

Параметры функции

Параметр Описание
arOrder Массив для сортировки результата. Массив вида array("поле сортировки"=>"направление сортировки" [, ...]).
Поле для сортировки может принимать значения:
  • ID - идентификатор вопроса в плане тестирования;
  • ATTEMPT_ID - идентификатор попытки;
  • QUESTION_ID - идентификатор вопроса;
  • POINT - количество баллов;
  • ANSWERED - вопрос отвечен (Y|N);
  • CORRECT - вопрос правильно отвечен (Y|N);
  • QUESTION_NAME - название вопроса;
  • RAND - случайный порядок.
Направление сортировки может принимать значения:
  • asc - по возрастанию;
  • desc - по убыванию;
Необязательный. По умолчанию фильтруется по убыванию идентификатора вопроса в плане тестирования.
arFilter Массив вида array("фильтруемое поле"=>"значение фильтра" [, ...]). Фильтруемое поле может принимать значения:
  • ID - идентификатор вопроса в плане тестирования;
  • ATTEMPT_ID - идентификатор попытки;
  • QUESTION_ID - идентификатор вопроса;
  • POINT - количество баллов;
  • RESPONSE - ответ учащегося (можно искать по шаблону [%_]);
  • QUESTION_NAME - название вопроса (можно искать по шаблону [%_]);
  • ANSWERED - вопрос отвечен (Y|N);
  • CORRECT - вопрос правильно отвечен (Y|N).
Перед названием фильтруемого поля может указать тип фильтрации:
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно

"значения фильтра" - одиночное значение или массив.

Необязательный. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult.

См. также

  • CDBResult
  • CTestResult::GetByID
  • Поля плана тестирования

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 590;
    $res = CTestResult::GetList(
        Array("ID" => "ASC"),
        Array("ANSWERED" => "N", "ATTEMPT_ID" => $ATTEMPT_ID)
    );

    while ($arQuestionPlan = $res->GetNext())
    {
        echo "Question ID: ".$arQuestionPlan["QUESTION_ID"].
             "; Correct answer: ".$arQuestionPlan["CORRECT"].
             "; Question name:".$arQuestionPlan["QUESTION_NAME"]."<br>";
    }
}
?>


GetProgress

CTestResult::GetProgress

array
CTestResult::GetProgress(
 int ATTEMPT_ID
);

Возвращает количество отвеченных и неотвеченных вопросов плана тестирования.

Параметры функции

Параметр | Описание
ATTEMPT_ID | Идентификатор попытки.

Возвращаемое значение

Метод возвращает ассоциативный массив с ключами:

  • DONE - количество отвеченных вопросов теста.
  • TODO - количество неотвеченных вопросов теста.

См. также

  • CTestResult::GetList

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $ATTEMPT_ID = 588;

    $arStat = CTestResult::GetProgress($ATTEMPT_ID);

    echo $arStat["TODO"];
    echo $arStat["DONE"];
}
?>


Update

CTestResult::Update

bool
CTestResult::Update(
 int   ID,
 array arFields
);

Метод изменяет параметры вопроса плана тестирования с идентификатором ID.

Параметры функции

Параметр | Описание
ID | Идентификатор вопроса в плане тестирования.
arFields | Массив Array("поле"=>"значение", ...). Содержит значения всех полей плана тестирования. Обязательные поля должны быть заполнены.

Возвращаемое значение

Метод возвращает true, если изменение прошло успешно, при возникновении ошибки функция вернёт false. При возникновении ошибки в исключениях будет содержаться текст ошибки.

См. также

  • Поля плана тестирования
  • CTestResult::Add
  • CTestResult::AddResponse

Примеры использования

<?
if (CModule::IncludeModule("learning"))
{
    $TEST_TESULT_ID = 2962;

    $arFields = Array(
        "CORRECT" => "Y",
        "POINT" => "20"
    );

    $plan = new CTestResult;
    $success = $plan->Update($TEST_TESULT_ID, $arFields);

    if($success)
    {
        echo "Ok!";
    }
    else
    {
        if($e = $APPLICATION->GetException())
            echo "Error: ".$e->GetString();
    }

}
?>


Для разработчиков

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


Инсталляция

Для инсталляции модуля вам необходимо выполнить следующее:

  1. Убедитесь что версия ядра не менее чем 3.0.11 (версию ядра можно узнать в левом нижнем углу административных страниц). Инсталлятор не даст вам установить модуль, если версия ядра не соответствует требуемой.
  2. Выберете каталог сайта в котором будут располагаться файлы отображения списка опросов, формы опросов и диаграмм опросов.
  3. Введите каталог сайта в предложенное поле ввода “Каталог для опросов”. Например, каталоги, в которых будут располагаться опросы: “/vote/”.
  4. Нажмите кнопку Установить.
  5. После окончания установки зайдите в меню Группы опросов. Здесь вам необходимо создать группы опросов и придумать им символические имена.
  6. Зайдите в меню Список опросов и создайте какой – либо опрос.
  7. В публичной части сайта настройте меню "Архив опросов" к скрипту “vote_list.php” и меню "Текущий опрос" к скрипту "vote_now.php". В меню "Архив опросов" добавьте дополнительные ссылки на файлы "vote.php", "vote_result.php".

Инсталляция подразумевает создание следующих таблиц в базе:

  • b_vote_channel – таблица групп опросов
  • b_vote_channel_group – таблица связи групп опросов к группам пользователей
  • b_vote – таблица опросов
  • b_vote_question – таблица вопросов
  • b_vote_answer – таблица ответов
  • b_vote_user – таблица посетителей, участвовавших в опросах
  • b_vote_event – таблица голосований
  • b_vote_event_question – таблица вопросов на которые давались ответы в момент голосований
  • b_vote_event_answer – таблица ответов посетителей в момент голосований

Когда таблицы подготовлены, происходит копирование всех необходимых скриптов для администрирования техподдержки из каталога “\bitrix\modules\vote\install\public\ admin\” в каталог ”\bitrix\admin\”:

  • vote_channel_list.php – список групп опросов
  • vote_channel_edit.php – редактирование группы опросов
  • vote_list.php – список опросов
  • vote_edit.php – редактирование опроса
  • vote_preview.php – форма опросов
  • vote_results.php – результирующая диаграмма опроса
  • vote_question_list.php – список вопросов
  • vote_question_edit.php – редактирование вопроса
  • vote_user_list.php – список посетителей участвовавших в опросах
  • vote_user_votes.php – список голосований
  • vote_user_results.php – результат голосования

Если необходимо, то в каждом сайте происходит создание каталога, имя которого указанно в параметре “Каталог для опросов”. После этого в эти каталоги копируются файлы:

  • vote_list.php – отображает список опросов (архив)
  • vote.php – отображает форму опроса по заданному ID
  • vote_result.php – отображает результат опроса по заданному ID
  • vote_prev.php – отображает результаты предыдущего опроса заданной группы
  • vote_current.php – отображает форму текущего опроса заданной группы,
    после голосования перенаправляет на файл отображающий результат опроса
  • vote_now.php – отображает форму текущего опроса группы, если пользователь ещё не голосовал, иначе отображает результаты текущего опроса группы
  • vote_any.php – отображает форму первого попавшегося опроса по которому пользователь ещё не голосовал, если пользователь проголосовал, то перенаправляет его на файл отображающий результат данного опроса

Вышеописанные файлы будут скопированы из каталога “\bitrix\modules\vote\install\public\”. Вы можете их использовать в качестве примеров кодов для настройки модуля опросов.


Функции

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


GetAnyAccessibleVote

GetAnyAccessibleVote([lid])

Функция возвращает ID первого попавшегося опроса по которому пользователь ещё не голосовал, с учётом прав пользователя, у которого должно быть право "на участие в опросе" (>=2)

Параметры функции

Параметр | Описание
lid | Сайт группы опросов.

Примеры использования

Файл в публичной части сайта - "vote_any.php":
<?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
// Отображает форму первого попавшегося опроса по которому пользователь ещё не голосовал
// если пользователь проголосовал, то перенаправляет его на файл отображающий результат данного опроса
if (CModule::IncludeModule("vote") && $VOTING_OK=="Y")
{
    $VOTE_DIR = COption::GetOptionString("vote", "VOTE_DIR", "");
    $z = CLang::GetByID(LANG);
    $zr = $z->Fetch();
    $LANG_DIR = $zr["DIR"];
    $LANG_DIR = TrimExAll($LANG_DIR,"/");
    $VOTE_DIR = TrimExAll($VOTE_DIR,"/");
    LocalRedirect("/".$LANG_DIR."/".$VOTE_DIR."/vote_result.php?VOTE_ID=". $PUBLIC_VOTE_ID."&VOTING_OK=".$VOTING_OK);
}
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_VOTING_TITLE"));
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote"))
{
    $VID = GetAnyAccessibleVote();
    ShowVote($VID);
}
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


GetCurrentVote

GetCurrentVote(
 GROUP_SYMBOLIC_NAME, [
 lid, [
 access]]
)

Функция возвращает ID текущего опроса в группе.

Параметры функции

Параметр | Описание
GROUP_SYMBOLIC_NAME | Символическое имя группы.
lid | ID сайта. По умолчанию - текущий - константа "LANG".
access | Минимальный уровень доступа к опросу для текущего пользователя: 0 - доступ закрыт 1 - право на просмотр результатов опроса 2 - право на участие в опросе По умолчанию access = 1, т.е. для того чтобы функция GetCurrentVote возвратила ID текущего опроса группы у пользователя на данную группу должно быть, как минимум, право на просмотр результатов.

Примеры использования

<?
// возвращает форму текущего опроса для заданной группы
function ShowCurrentVote($GROUP_SYMBOLIC_NAME, $lid=LANG)
{
    $CURRENT_VOTE_ID = GetCurrentVote($GROUP_SYMBOLIC_NAME, $lid, 2);
    if (intval($CURRENT_VOTE_ID)>0) ShowVote($CURRENT_VOTE_ID);
}
?>


GetPrevVote

GetPrevVote(
 GROUP_SYMBOLIC_NAME, [
 level, [
 lid]]
);

Функция возвращает ID предыдущего опроса в группе.

Параметры функции

Параметр | Описание
GROUP_SYMBOLIC_NAME | Символическое имя группы.
level | Уровень предыдущего опроса (1 - предыдущий, 2 - пред- предыдущий и т.д.). По умолчанию - 1.
lid | ID сайта. По умолчанию - текущий.

Примеры использования

<?
// возвращает диаграмму результатов предыдущего опроса
function ShowPrevVoteResults($GROUP_SYMBOLIC_NAME, $level=1, $lid=LANG)
{
    $PREV_VOTE_ID = GetPrevVote($GROUP_SYMBOLIC_NAME, $level, $lid);
    if (intval($PREV_VOTE_ID)>0) ShowVoteResults($PREV_VOTE_ID);
}
?>


GetVoteDataByID

GetVoteDataByID(
  int VOTE_ID,
  array &arChannel,
  array &arVote,
  array &arQuestions,
  array &arAnswers,
  array &arDropDown,
  array &arMultiSelect,
  array &arGroupAnswers,
  string getGroupAnswers
)

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

Параметры функции

Параметр | Описание
VOTE_ID | ID опроса.
arChannel Массив описывающий группу заданного опроса.
Индексы массива:
  • ID - ID группы
  • SYMBOLIC_NAME - символическое имя
  • ACTIVE - флаг активности ["Y"|"N"]
  • TITLE - заголовок группы
  • LID - ID сайта
  • C_SORT - порядок сортировки
  • TIMESTAMP_X - время изменения записи в базе данных
    • arVote Массив описывающий заданный опрос.
    Индексы массива:
  • ID - ID опроса
  • CHANNEL_ID - ID группы опроса
  • C_SORT - порядок сортировки
  • ACTIVE - флаг активности ["Y"|"N"]
  • TIMESTAMP_X - время изменения записи в базе данных
  • DATE_START - время начала опроса
  • DATE_END - время окончания опроса
  • COUNTER - количество голосований по опросу
  • TITLE - заголовок опроса
  • DESCRIPTION - описание опроса
  • DESCRIPTION_TYPE - тип описания опроса ["html"|"text"]
  • IMAGE_ID - ID изображения
  • EVENT1 - идентификатор типа события - " event1"
  • EVENT2 - идентификатор типа события - " event2"
  • EVENT3 - дополнительный параметр типа события - " event3"
  • UNIQUE_TYPE - тип уникальности посетителей: 0 - не ограничено; 1 - не голосовать дважды в одной сессии; 2 - не голосовать дважды в одной сессии либо с одним cookie; 3 - не голосовать дважды в одной сессии либо с одним cookie либо с одного IP;
  • KEEP_IP_SEC - количество секунд в течении которых нельзя голосовать с одного IP
  • TEMPLATE - шаблон для показа формы опроса
  • RESULT_TEMPLATE - шаблон для показа результатов опроса
  • QUESTIONS - количество вопросов
  • LAMP - индикатор: "red" - флаг активности опроса снят либо текущая дата не попадает в интервал проведения опроса; "green" - флаг активности опроса установлен и текущая дата попадает в интервал проведения опроса.
    • arQuestions Массив состоящий из массивов каждый из которых описывает один вопрос.
    Индексы массива:
  • ID - ID вопроса
  • ACTIVE - флаг активности ["Y"|"N"]
  • C_SORT - порядок сортировки
  • QUESTION - текст вопроса
  • QUESTION_TYPE - тип текста вопроса ["html"|"text"]
  • IMAGE_ID - ID изображения
  • DIAGRAM - флаг включения вопроса в результирующую диаграмму ["Y"|"N"]
  • TEMPLATE - шаблон для показа результатов вопроса
  • TIMESTAMP_X - дата изменения записи в базе данных
    • arAnswers Массив ответов, его индексами являются ID вопросов, а значениями - список массивов, каждый из которых описывает один ответ.
    Индексы массива описывающего один ответ:
  • ID - ID ответа
  • ACTIVE - флаг активности ["Y"|"N"]
  • TIMESTAMP_X - дата изменения записи в базе данных
  • QUESTION_ID - ID вопроса
  • C_SORT - порядок сортировки
  • MESSAGE - текст сообщения который будет выдан рядом с ответом в форме опроса и в качестве ответа в диаграмме опроса
  • COUNTER - количество раз когда был выбран данный ответ
  • FIELD_TYPE - тип поля ввода: 0 - radio, 1 - checkbox, 2 - dropdown list; 3 - multiselect list, 4 - text; 5 - textarea
  • FIELD_WIDTH - ширина поля ввода
  • FIELD_HEIGHT - высота поля ввода
  • FIELD_PARAM - дополнительные параметры поля ввода: стиль, класс
  • COLOR - RGB цвета элемента диаграммы (например: #FFOOCC)
    • arDropDown Массив с всеми элементами типа "2" (dropdown list) одного вопроса. Индексом массива является ID вопроса, а значением - массив со следующими индексами:
  • REFERENCE - текст ответа
  • REFERENCE_ID - ID ответа
    • arMultiSelect Массив с всеми элементами типа "3" (multiselect list) одного вопроса. Индексом массива является ID вопроса, а значением - массив со следующими индексами:
  • REFERENCE - текст ответа
  • REFERENCE_ID - ID ответа
    • arGroupAnswers Массив описывающий варианты ответов для элементов ввода типа "4" (text) и "5" (textarea). Индексом массива является ID вопроса, а значением - список массивов со следующими индексами:
  • MESSAGE - текст ответа
  • COUNTER - количество таких ответов
    • getGroupAnswers | Флаг принимающий следующие значения: "Y" - собирать массив arGroupAnswers; "N" - собирать массив arGroupAnswers не нужно.

    Примеры использования

    <?
// возвращает форму заданного опроса с учётом прав пользователя
function ShowVote($VOTE_ID, $template1="")
{
    global $MESS, $VOTING_LAMP, $VOTING_OK, $USER_ALREADY_VOTE, $USER_GROUP_PERMISSION, $VOTE_USER_ID, $VOTE_PERMISSION;
    $VOTE_ID = GetVoteDataByID($VOTE_ID, $arChannel, $arVote, $arQuestions, $arAnswers, $arDropDown, $arMultiSelect, $arGroupAnswers, "N");
    if (intval($VOTE_ID)>0)
    {
        $perm = CVoteChannel::GetGroupPermission($arChannel["ID"]);
        if (intval($perm)>=2)
        {
            $template = (strlen($arVote["TEMPLATE"])<=0) ? "default.php" : $arVote["TEMPLATE"];
            $VOTE_PERMISSION = CVote::UserGroupPermission($arChannel["ID"]);
            require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/vote/include.php");
            @include_once (GetLangFileName($_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/lang/", "/".$template));
            $path = COption::GetOptionString("vote", "VOTE_TEMPLATE_PATH", "/bitrix/php_interface/include/vote/show/");
            if (strlen($template1)>0) $template = $template1;
            @include($_SERVER["DOCUMENT_ROOT"].$path.$template);
        }
    }
}
?>

    <?
// получаем данные по опросу
$VOTE_ID = GetVoteDataByID($PUBLIC_VOTE_ID, $arChannel, $arVote, $arQuestions, $arAnswers, $arDropDown, $arMultiSelect, $arGroupAnswers, "N", $template, $res_template);
$VOTE_ID = intval($VOTE_ID);
// если поступивший ID опроса корректный то
if ($VOTE_ID>0 && $arVote["LAMP"]=="green")
{
    ...
}
?>


GetVoteList

GetVoteList([
 GROUP_SYMBOLIC_NAME, [
 strSqlOrder]]
);

Функция возвращает выборку из базы по опросам.

Параметры функции

Параметр | Описание
GROUP_SYMBOLIC_NAME | Символическое имя группы опросов (по умолчанию функция вернет выборку опросов из всех групп).
strSqlOrder | SQL код содержащий параметры сортировки для выборки. По умолчанию: "ORDER BY C.C_SORT, C.ID, V.DATE_START desc"

Примеры использования

Файл в публичной части сайта - "vote_list.php":
<?
// Отображает список опросов (архив)
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("vote")) require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/vote/include.php");
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_LIST_TITLE"));
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote"))
{
    $votes = GetVoteList(); // список опросов
    require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/php_interface/include/vote/list/default.php"); // шаблон показа
}
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


IsUserVoted

IsUserVoted (VOTE_ID)

Функция возвращает true, если пользователь уже голосовал по заданному опросу и ему больше нельзя голосовать в соответствии с настройками опроса, в противном случае - false

Параметры функции

Параметр | Описание
VOTE_ID | ID опроса.

Примеры использования

Файл в публичной части сайта - "vote_now.php":
<?
// Отображает форму текущего опроса группы, если пользователь
// ещё не голосовал, иначе отображает результаты текущего опроса группы
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("vote"))
{
    $VID = GetCurrentVote("ANKETA");
    if ($VOTING_OK=="Y" || IsUserVoted($VID)) $ALREADY_VOTED = "Y"; else $ALREADY_VOTED = "N";
}
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_VOTING_TITLE"));
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote"))
{
    if ($ALREADY_VOTED=="Y") ShowVoteResults($VID); else ShowVote($VID);
}
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


ShowCurrentVote

ShowCurrentVote(
 GROUP_SYMBOLIC_NAME, [
 lid]
);

Функция выводит HTML-код текущего опроса группы.

Параметры функции

Параметр | Описание
GROUP_SYMBOLIC_NAME | Символическое имя группы.
lid | ID сайта. По умолчанию - текущий.

Примеры использования

Файл в публичной части сайта - "vote_current.php":
<?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
// Отображает форму текущего опроса заданной группы,
// после голосования перенаправляет на файл отображающий результат опроса
if (CModule::IncludeModule("vote") && $VOTING_OK=="Y")
{
    $VOTE_DIR = COption::GetOptionString("vote", "VOTE_DIR", "");
    $z = CLang::GetByID(LANG);
    $zr = $z->Fetch();
    $LANG_DIR = $zr["DIR"];
    $LANG_DIR = TrimExAll($LANG_DIR,"/");
    $VOTE_DIR = TrimExAll($VOTE_DIR,"/");
    LocalRedirect("/".$LANG_DIR."/".$VOTE_DIR."/vote_result.php?VOTE_ID=".$PUBLIC_VOTE_ID."&VOTING_OK=Y");
}
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_VOTING_TITLE"));
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote")) ShowCurrentVote("ANKETA");
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


ShowCurrentVoteResults

ShowCurrentVoteResults (
 GROUP_SYMBOLIC_NAME, [
 lid]
);

Функция выводит HTML-код диаграммы результатов текущего опроса группы.

Параметры функции

Параметр | Описание
GROUP_SYMBOLIC_NAME | Символическое имя группы.
lid | ID сайта. По умолчанию - текущий.


ShowPrevVoteResults

ShowPrevVoteResults (
 GROUP_SYMBOLIC_NAME, [
 level, [
 lid]]
);

Функция выводит HTML-код диаграммы результатов предыдущего опроса группы.

Параметры функции

Параметр | Описание
GROUP_SYMBOLIC_NAME | Символическое имя группы.
level | Уровень предыдущего опроса (1 - предыдущий, 2 - предпредыдущий и т.д.). По умолчанию - 1.
lid | ID сайта. По умолчанию - текущий.

Примеры использования

Файл в публичной части сайта - "vote_prev.php":
<?
// Отображает результаты предыдущего опроса заданной группы
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_PREV_VOTING_TITLE"));
$APPLICATION->AddChainItem(GetMessage("VOTE_VOTES_LIST"), "vote_list.php");
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote")) ShowPrevVoteResults("ANKETA");
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


ShowVote

ShowVote(
 VOTE_ID, [
 template]
);

Функция выводит HTML-код формы опроса.

Параметры функции

Параметр | Описание
VOTE_ID | ID опроса.
template | Имя файла - шаблона для показа опроса. По умолчанию будет использован шаблон заданный в параметрах опроса.

Примеры использования

Файл в публичной части сайта - "vote.php":
<?
// Отображает форму опроса по заданному ID
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("vote") && $VOTING_OK=="Y")
{
    $VOTE_DIR = COption::GetOptionString("vote", "VOTE_DIR", "");
    $z = CLang::GetByID(LANG);
    $zr = $z->Fetch();
    $LANG_DIR = $zr["DIR"];
    $LANG_DIR = TrimExAll($LANG_DIR,"/");
    $VOTE_DIR = TrimExAll($VOTE_DIR,"/");
    LocalRedirect("/".$LANG_DIR."/".$VOTE_DIR."/vote_result.php?VOTE_ID=".$PUBLIC_VOTE_ID."&VOTING_OK=Y");
}
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_VOTING_TITLE"));
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote")) ShowVote($VOTE_ID);
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


ShowVoteResults

ShowVoteResults(
 VOTE_ID, [
 template]
);

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

Параметры функции

Параметр | Описание
VOTE_ID | ID опроса.
template | Имя файла - шаблона для показа результатов опроса. По умолчанию будет использован шаблон заданный в параметрах опроса.

Примеры использования

Файл в публичной части сайта - "vote_result.php":
<?
// Отображает результат опроса по заданному ID
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (strlen($APPLICATION->GetTitle())<=0) $APPLICATION->SetTitle(GetMessage("VOTE_RESULTS_TITLE"));
//$APPLICATION->AddChainItem(GetMessage("VOTE_VOTES_LIST"), "vote_list.php");
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");
?><?
if (CModule::IncludeModule("vote")) ShowVoteResults($VOTE_ID);
require_once ($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>


ShowVoteResults

Подписка, рассылки

  • Классы
  • События


Классы модуля подписки и рассылки

Следующие PHP классы используются в модуле подписки и рассылки.

Классы

Класс | Описание
CPosting | Класс для работы с выпусками новостей подписки.
CRubric | Класс для работы с рубриками подписки.
CSubscription | Класс для работы с подписками на рассылки.
CPostingTemplate | Класс для работы с шаблонами.


Класс CPosting

CPosting - класс для работы с выпусками новостей подписки.

Методы класса

Метод | Описание
Add | Функция добавляет выпуск.
Delete | Функция удаляет выпуск по его идентификатору.
GetByID | Функция возвращает выпуск по его идентификатору.
GetEmails | Функция возвращает массив адресов, по которым выпуск будет отправлен.
GetGroupList | Функция возвращает выборку групп пользователей, на которые будет отправлен выпуск.
UpdateGroups | Функция изменяет информацию о привязке выпуска к группам пользователей.
GetList | Функция возвращает список выпусков по фильтру.
GetRubricList | Функция возвращает выборку рассылок, на которые будет отправлен выпуск.
UpdateRubrics | Функция изменяет информацию о привязке выпуска к рубрикам подписки.
SendMessage | Функция возвращает true при успешной отправке, false при неуспешной, "CONTINUE" при частичной отправке. При неуспешной отправке переменная LAST_ERROR класса содержит сообщение об ошибке.
Update | Функция изменяет информацию о выпуске по его идентификатору.
Lock | Функция возвращает true при успешной блокировке выпуска и false при неуспешной.
UnLock | Функция возвращает true при успешном снятии блокировки выпуска и false при неуспешном.
SaveFile | Функция добавляет вложение к выпуску сохраняя и регистрируя его в таблице файлов (b_file).
DeleteFile | Функция удаляет одно или все вложения выпуска.
GetFileList | Функция возвращает выборку вложений выпуска.
AutoSend | Функция для отправки выпуска с помощью cron'а или агента.
ChangeStatus | Функция изменяет статус выпуска.


Add

CPosting::Add

int
CPosting::Add(
 array arFields
);

Функция добавляет выпуск.

Параметры функции

Параметр | Описание
arFields | Массив со значениями полей объекта "Выпуск" Дополнительно могут быть указаны поля: RUB_ID - массив идентификаторов рассылок; GROUP_ID - массив идентификаторов групп пользователей.

Требования к полям передаваемым в arFields

  • FROM_FIELD - должно содержать правильный адрес e-mail (см. функцию check_email).
  • TO_FIELD - в случае когда поле DIRECT_SEND равно Y не должно быть пустым.
  • SUBJECT - не должно быть пустым.
  • BODY - не должно быть пустым.
  • AUTO_SEND_TIME - если задано, то должно содержать или false или дату включающую время (см. функцию CDatabase::IsDate)

Возвращаемые значения

В случае успешного добавления возвращается ID выпуска. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке (так же возбуждается исключение CMain::ThrowException).

Пример использования

$posting = new CPosting;
$arFields = Array(
    "FROM_FIELD" => $FROM_FIELD,
    "TO_FIELD" => $TO_FIELD,
    "BCC_FIELD" => $BCC_FIELD,
    "EMAIL_FILTER" => $EMAIL_FILTER,
    "SUBJECT" => $SUBJECT,
    "BODY_TYPE" => ($BODY_TYPE <> "html"? "text":"html"),
    "BODY" => $BODY,
    "DIRECT_SEND" => ($DIRECT_SEND <> "Y"? "N":"Y"),
    "CHARSET" => $CHARSET,
    "SUBSCR_FORMAT" => ($SUBSCR_FORMAT<>"html" && $SUBSCR_FORMAT<>"text"?
        false:$SUBSCR_FORMAT),
    "RUB_ID" => $RUB_ID,
    "GROUP_ID" => $GROUP_ID
);
if($STATUS <> "")
{
    if($STATUS<>"S" && $STATUS<>"E" && $STATUS<>"P")
        $STATUS = "D";
    $arFields["STATUS"] = $STATUS;
    if($STATUS == "D")
    {
        $arFields["DATE_SENT"] = false;
        $arFields["SENT_BCC"] = "";
        $arFields["ERROR_EMAIL"] = "";
    }
}
$ID = $posting->Add($arFields);
if($ID == false)
    echo $posting->LAST_ERROR;


AutoSend

CPosting::AutoSend

CPosting::AutoSend(
 int ID = false,
 bool limit = false,
 string site_id = false
);

Функция для отправки выпуска с помощью cron'а или агента.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска. Если параметр не указан или равен false, то будут отсылаться все выпуски в статусе "В процессе" время отправки которых меньше или равно текущему. В порядке возрастания времени отправки.
limit | Флажок ограничения количества отправляемых писем за один вызов. Если этот параметр указан и равен true количество писем отправляемых за один вызов данной функции ограничивается параметром "Количество писем для автоматической рассылки агентом за один запуск" в настройках модуля. При отправке выпуска с помощью агента (задан параметр ID) дополнительно ограничивается продолжительность отправки, которая определяется параметром в настройках модуля.
site_id | Идентификатор сайта. Используется при отправке автоматически сгенерированных выпусков с помощью агентов. Если этот параметр указан, то его значение сравнивается с текущим значением константы SITE_ID. Таким образом агент по отправке выполняется только в контексте сайта к которому привязана рубрика породившая выпуск. Это позволяет избежать проблемы пропуска картинок в html выпусках в случае многосайтовости организованной по второму варианту.

Возвращаемые значения

Нет.

Пример использования в сценарии PHP для cron'а

#!/usr/bin/php
<?php
//Здесь необходимо указать ваш DOCUMENT_ROOT!
$_SERVER["DOCUMENT_ROOT"] = "/opt/www/html";
$DOCUMENT_ROOT = $_SERVER["DOCUMENT_ROOT"];
define("NO_KEEP_STATISTIC", true);
define("NOT_CHECK_PERMISSIONS", true);
set_time_limit(0);
define("LANG", "ru");
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("subscribe"))
{
    $cPosting = new CPosting;
    $cPosting->AutoSend();
}
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_after.php");
?>

Пример использования в сценарии PHP для агента

<?
    CAgent::AddAgent("CPosting::AutoSend(".$ID.",true);", "subscribe", "N", 0, $post_arr["AUTO_SEND_TIME"], "Y", $post_arr["AUTO_SEND_TIME"]);
?>
<p class="notetext">Для отправки выпуска был создан агент.</p>


ChangeStatus

CPosting::ChangeStatus

bool
CPosting::ChangeStatus(
 int ID,
 string status
);

Функция изменяет статус выпуска и производит действия в соответствии с приведенной ниже таблицей.

Текущий статус | Новый статус | Действия
Черновик | В процессе | Формируется список адресов по которым будет происходить отправка.
В процессе | Остановлен | Нет.
Остановлен | В процессе | Нет.
В процессе | Отправлен с ошибками | Нет.
В процессе | Отправлен | Нет.
Отправлен с ошибками | В процессе | Список ошибочных адресов копируется в список на отправку и очищается.
Отправлен с ошибками, Отправлен, Остановлен | Черновик | Список ошибочных адресов, список на отправку и список отправленных очищаются.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
status | Новый статус выпуска. Может принимать значение: "S" (отправлен успешно),"E" (отправлен с ошибками), "P" (в процессе), "W" (остановлен), "D" (черновик).

Возвращаемые значения

Функция возвращает true при успешной смене статуса и false при неуспешной. При неуспешной смене статуса переменная LAST_ERROR класса содержит сообщение об ошибке.

Пример использования

//******************************
// Stop sending the message
//******************************
if($action=="stop" && $ID>0 && $POST_RIGHT=="W")
{
    $cPosting->ChangeStatus($ID, "W");
}


Delete

CPosting::Delete

mixed
CPosting::Delete(
 int ID
);

Функция удаляет выпуск по его идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.

Возвращаемые значения

В случае успешного удаления возвращается результат типа CDBResult. В противном случает возвращается false.

Пример использования

$res = CPosting::Delete($ID);
if(!$res)
    echo "Cannot delete the issue.";
elseif($res->AffectedRowsCount() < 1)
    echo "Already deleted.";
else
    echo "Deleted successfylly.";


DeleteFile

CPosting::DeleteFile

CPosting::DeleteFile(
 int ID,
 int file_id = false
);

Функция удаляет одно или все вложения выпуска.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
file_id | Идентификатор вложения. Если параметр не указан или равен false, то удаляются все вложения выпуска.

Возвращаемые значения

Нет.

Пример использования

    if(is_array($FILE_ID))
        foreach($FILE_ID as $file_id)
            CPosting::DeleteFile($ID, $file_id);


GetByID

CPosting::GetByID

CDBResult
CPosting::GetByID(
 int ID
);

Функция возвращает выпуск по его идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Выпуск".

Пример использования

$rsPosting = CPosting::GetByID($ID);
$arPosting = $rsPosting->Fetch();
if($arPosting)
    echo htmlspecialchars(print_r($arPosting, true));
else
    echo "Not found";


GetEmails

CPosting::GetEmails

array
CPosting::GetEmails(
 array post_arr
);

Функция возвращает массив адресов, по которым выпуск будет отправлен.

Параметры функции

Параметр | Описание
post_arr | Массив всех полей объекта "Выпуск" в виде наборов "название поля" => "значение".

Возвращаемые значения

Функция возвращает массив уникальных e-mail адресов. В который входят

  • Адреса подписчиков из рубрик выпуска, подписка которых активна и подтверждена с учетом формата подписки и фильтра адресов.
  • Адреса зарегистрированных и активных пользователей принадлежащих тем группам к которым привязан выпуск.
  • Адреса перечисленные в поле BCC_FIELD.

Пример использования

$post = CPosting::GetByID($ID);
if(($post_arr = $post->Fetch()))
    $aEmail = CPosting::GetEmails($post_arr);


GetFileList

CPosting::GetFileList

CDBResult
CPosting::GetFileList(
 int ID,
 int file_id = false
);

Функция возвращает выборку вложений выпуска.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
file_id | Идентификатор вложения. Если параметр не указан или равен false, то выбираются все вложения выпуска.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Файл": ID, FILE_SIZE, ORIGINAL_NAME, SUBDIR, FILE_NAME, CONTENT_TYPE.

Пример использования

//размер всех вложений
$attach_size = 0;
$rsFile = CPosting::GetFileList($ID);
while($arFile = $rsFile->Fetch())
    $attach_size += $arFile["FILE_SIZE"];


GetGroupList

CPosting::GetGroupList

CDBResult
CPosting::GetGroupList(
 int ID
);

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

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Группа": ID, NAME.

Пример использования

<?
//show user groups and check selected for the issue
$aPostGrp = array();
if($ID>0)
{
    $post_grp = CPosting::GetGroupList($ID);
    while($post_grp_arr = $post_grp->Fetch())
        $aPostGrp[] = $post_grp_arr["ID"];
}
$group = CGroup::GetList(($by="name"), ($order="asc"));
while($group->ExtractFields("g_")):
?>
<input type="checkbox" name="GROUP_ID[]" value="<?echo $g_ID?>"<?if(in_array($g_ID, $aPostGrp)) echo " checked"?>>
<?echo $g_NAME?><br>
<?
endwhile;
?>


GetList

CPosting::GetList

CDBResult
CPosting::GetList(
 array aSort = Array(),
 array aFilter = Array()
);

Функция возвращает список выпусков по фильтру.

Параметры функции

Параметр Описание
aSort Массив, содержащий признак сортировки в виде наборов "название поля"=>"направление".

Название поля может принимать значение:
  • ID - идентификатор выпуска;
  • TIMESTAMP - дата изменения;
  • SUBJECT - тема письма;
  • BODY_TYPE - тип текста;
  • STATUS - статус выпуска;
  • DATE_SENT - дата отправки выпуска;
  • AUTO_SEND_TIME - время автоматической отправки выпуска;
Направление сортировки может принимать значение:
  • ASC - по возрастанию;
  • DESC - по убыванию.
Пример:
array("STATUS"=>"ASC",
      "DATE_SENT"=>"DESC")
aFilter Массив, содержащий фильтр в виде наборов "название поля"=>"значение фильтра".

Название поля может принимать значение:
  • ID - идентификатор выпуска (возможны сложные условия);
  • TIMESTAMP_1 - дата изменения (начало периода);
  • TIMESTAMP_2 - дата изменения (конец периода);
  • DATE_SENT_1 - дата отправки (начало периода);
  • DATE_SENT_2 - дата отправки (конец периода);
  • AUTO_SEND_TIME_1 - дата или время автоматической отправки (начало периода);
  • AUTO_SEND_TIME_2 - дата или время автоматической отправки (конец периода);
  • STATUS - статус выпуска строкой (возможны сложные условия);
  • STATUS_ID - статус выпуска символом (возможны сложные условия);
  • SUBJECT - тема письма (возможны сложные условия);
  • FROM - поле "от кого" письма (возможны сложные условия);
  • TO - кому отправлен выпуск (возможны сложные условия);
  • BODY_TYPE - тип текста письма;
  • BODY - текст письма (возможны сложные условия).
Пример:
array("SUBJECT"=>"test | тест",
      "TO"=>"@bitrixsoft.ru")

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Выпуск", за исключением полей типа text.

Если поля фильтра содержат ошибку, то переменная LAST_ERROR класса содержит сообщение об ошибке.

Пример использования

$cPosting = new CPosting;
$arFilter = Array(
    "ID" => $find_id,
    "TIMESTAMP_1" => $find_timestamp_1,
    "TIMESTAMP_2" => $find_timestamp_2,
    "DATE_SENT_1" => $find_date_sent_1,
    "DATE_SENT_2" => $find_date_sent_2,
    "STATUS" => $find_status,
    "STATUS_ID" => $find_status_id,
    "SUBJECT" => $find_subject,
    "FROM" => $find_from,
    "TO" => $find_to,
    "BODY" => $find_body,
    "BODY_TYPE" => $find_body_type
);
$rsPosting = $cPosting->GetList(array($by=>$order), $arFilter);
$strError .= $cPosting->LAST_ERROR;

$rsPosting->NavStart(50);
echo $rsPosting->NavPrint("Issues");
while($rsPosting->NavNext(true, "f_"))
{
    //...
}


GetRubricList

CPosting::GetRubricList

CDBResult
CPosting::GetRubricList(
 int ID
);

Функция возвращает выборку рассылок, на которые будет отправлен выпуск.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Рассылка": ID, NAME, SORT, LID, ACTIVE.

Пример использования

//в какие рубрики отправлять
$aPostRub = array();
$post_rub = CPosting::GetRubricList($post_arr["ID"]);
while($post_rub_arr = $post_rub->Fetch())
    $aPostRub[] = $post_rub_arr["ID"];


Lock

CPosting::Lock

bool
CPosting::Lock(
 int ID );

Функция возвращает true при успешной блокировке выпуска и false при не успешной. Используется при автоматической отправке выпусков.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.

Возвращаемые значения

В случае успешной блокировки возвращается true. В противном случае возвращается false. Если блокировку не удалось получить из-за ошибки базы данных, то функция возвращает false и возбуждает исключение (CMain::ThrowException).

Пример использования

if(CPosting::Lock($ID)===false)
{
    if($e = $APPLICATION->GetException())
        echo "Произошла ошибка БД: ".$e->GetString();
    else
        return;
}
else
{
    //Выпуск успешно заблокирован
    //можно продолжать обработку
}


SaveFile

CPosting::SaveFile

bool
CPosting::SaveFile(
 int ID,
 array file
);

Функция добавляет вложение к выпуску сохраняя и регистрируя его в таблице файлов (b_file).

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
file Массив с данными файла формата:
Array(
    "name" => "название файла",
    "size" => "размер",
    "tmp_name" => "временный путь на сервере",
    "type" => "тип загружаемого файла");
Массив такого вида может быть взят прямо из $_FILES[имя поля]

Возвращаемые значения

В случае успешного сохранения вложения возвращается ID зарегистрированного файла. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке.

Пример использования

if (strlen($save)>0 && $REQUEST_METHOD=="POST")
{
    $file_id = CPosting::SaveFile($ID, $_FILES["FILE_TO_ATTACH"]);
    if($file_id===false)
    strError .= "Ошибка при сохранении вложения."."<br>";
}


SendMessage

CPosting::SendMessage

mixed
CPosting::SendMessage(
 int ID,
 int timeout = 0,
 int maxcount = 0
);

Функция отправляет выпуск в почтовую рассылку по адресам.

Выпуски со статусом "Успешно отправлен" повторно не отправляются. Если у выпуска установлен статус "Частично отправлен", то выпуск отправляется по оставшимся адресам.

Сначала выполняется попытка получения блокировки выпуска (см. CPosting::Lock). Если блокировку получить не удалось, то отправка считается частичной и функция возвращает "CONTINUE". Затем формируется тело письма для отправки и в цикле по адресам подписчиков осуществляется отправка выпуска с использованием php функции mail.

В режиме отправки "Персонально каждому получателю" перед вызовом mail вызываются обработчики события BeforePostingSendMail.

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

С выпуска снимается блокировка(см. CPosting::UnLock).

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
timeout | Максимальное время отправки в секундах. При превышении этого времени функция прерывает работу и устанавливает статус выпуска "Частично отправлен". Параметр имеет значение только при методе отправки "Персонально каждому получателю". Если timeout=0, то отправка производится за один шаг.
maxcount | Максимальное количество писем для отправки. При превышении этого количества функция прерывает работу и устанавливает статус выпуска "Частично отправлен". Параметр имеет значение только при методе отправки "Персонально каждому получателю". Если maxcount=0, то отправка производится за один шаг.

Возвращаемые значения

Функция возвращает true при успешной отправке, false при неуспешной, "CONTINUE" при частичной отправке. При неуспешной отправке переменная LAST_ERROR класса содержит сообщение об ошибке.

Пример использования

<?
if($action=="send" && $ID>0):
    if(($res = $cPosting->SendMessage($ID, COption::GetOptionString("subscribe", "posting_interval"))) !== false):
        if($res === "CONTINUE"):
?>
<script language="JavaScript" type="text/javascript">
<!--
function DoNext(){window.location="<?echo $APPLICATION->GetCurPage()."?ID=".$ID."&action=send&lang=".LANG."&rnd=".rand();?>";}
setTimeout('DoNext()', 2500);
//-->
</script>
<?
        else:
            $strOk = "Sent successfully.";
        endif; //$res === "CONTINUE"
    endif; //$cPosting->SendMessage
    $strError .= $cPosting->LAST_ERROR;
endif; //$action=="send"


UnLock

CPosting::UnLock

bool
CPosting::UnLock(
 int ID
);

Функция возвращает true при успешном снятии блокировки выпуска и false при неуспешном. Используется при отправке выпусков.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.

Возвращаемые значения

В случае успешного снятия блокировки возвращается true. В противном случае возвращается false.

Пример использования

CPosting::UnLock($ID);


Update

CPosting::Update

bool
CPosting::Update(
 int ID,
 array arFields
);

Функция изменяет информацию о выпуске по его идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
arFields | Массив со значениями полей объекта "Выпуск". Дополнительно могут быть указаны поля: RUB_ID - массив идентификаторов рассылок; GROUP_ID - массив идентификаторов групп пользователей.

Возвращаемые значения

В случае успешного изменения возвращается true. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке.

Пример использования

$posting = new CPosting;
$arFields = Array(
    "FROM_FIELD" => $FROM_FIELD,
    "TO_FIELD" => $TO_FIELD,
    "BCC_FIELD" => $BCC_FIELD,
    "EMAIL_FILTER" => $EMAIL_FILTER,
    "SUBJECT" => $SUBJECT,
    "BODY_TYPE" => ($BODY_TYPE <> "html"? "text":"html"),
    "BODY" => $BODY,
    "DIRECT_SEND" => ($DIRECT_SEND <> "Y"? "N":"Y"),
    "CHARSET" => $CHARSET,
    "SUBSCR_FORMAT" => ($SUBSCR_FORMAT<>"html" && $SUBSCR_FORMAT<>"text"? false:$SUBSCR_FORMAT),
    "RUB_ID" => $RUB_ID,
    "GROUP_ID" => $GROUP_ID
);
if($STATUS <> "")
{
    if($STATUS<>"S" && $STATUS<>"E" && $STATUS<>"P")
        $STATUS = "D";
    $arFields["STATUS"] = $STATUS;
    if($STATUS == "D")
    {
        $arFields["DATE_SENT"] = false;
        $arFields["SENT_BCC"] = "";
        $arFields["ERROR_EMAIL"] = "";
    }
}
if(!$posting->Update($ID, $arFields))
    $strError = $posting->LAST_ERROR;


UpdateGroups

CPosting::UpdateGroups

void
CPosting::UpdateGroups(
 int ID,
 array aGroup
);

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

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
aRubric | Массив идентификаторов групп пользователей.

Пример использования

$posting = new CPosting;
$posting->UpdateGroups($ID, array(1));


UpdateRubrics

CPosting::UpdateRubrics

void
CPosting::UpdateRubrics(
 int ID,
 array aRubric
);

Функция изменяет информацию о привязке выпуска к рубрикам подписки.

Параметры функции

Параметр | Описание
ID | Идентификатор выпуска.
aRubric | Массив идентификаторов рассылок.

Пример использования

$posting = new CPosting;
$posting->UpdateRubrics($ID, array(1, 2, 3));


Поля CPosting

CPosting::Поля CPosting

Класс CPosting использует следующие поля при работе с объектом "Выпуск".

Название поля | Описание | Тип | Обяз.
ID | Идентификатор выпуска. | int | Да.
TIMESTAMP_X | Дата модификации записи. | datetime |
STATUS | Статус выпуска. Может принимать значение: "S" (отправлен успешно), "E" (отправлен с ошибками), "P" (в процессе), "W" (остановлен), "D" (черновик). | char(1) |
DATE_SENT | Дата отправки выпуска. | datetime |
SENT_BCC | Список адресов, на которые отправлен выпуск. Адреса разделены запятыми. | text |
FROM_FIELD | Поле письма "От кого". | string(255) | Да.
TO_FIELD | Поле письма "Кому". | string(255) | Нет.
BCC_FIELD | Список адресов в поле письма "Скрытая копия". | text |
SUBJECT | Поле письма "Тема". | string(255) | Да.
BODY_TYPE | Тип текста письма ("text"/"html"). | string(4) |
BODY | Текст письма. | text | Да.
DIRECT_SEND | Отправлять персонально каждому подписчику ("Y"/"N"). | char(1) |
CHARSET | Кодировка, указываемая в заголовке письма. | string(50) |
EMAIL_FILTER | Фильтр на выборку адресов. | string(255) |
SUBSCR_FORMAT | Фильтр на формат текста. Формат указан в подписках. | string(4) |
ERROR_EMAIL | Список адресов, на которые не удалось отправить выпуск. Адреса в списке разделены запятыми. | text |
AUTO_SEND_TIME | Время для начала отправки выпуска с помощью агента или по cron'у. | datetime |
BCC_TO_SEND | Список адресов, по которым происходит отправка выпуска. Адреса в списке разделены запятыми. | text |


Класс CPostingTemplate

CPostingTemplate - класс для работы с шаблонами генерации выпусков подписки.

Методы класса

Метод | Описание
GetList | Функция возвращает список шаблонов.
GetByID | Функция возвращает шаблон по его идентификатору (относительному пути).
IsExists | Функция проверяет существование каталога шаблона.
Execute | Функция выбирает шаблон для генерации выпуска рассылки в соответствии с расписанием.
AddPosting | Функция генерации выпуска на основании шаблона.


AddPosting

CPostingTemplate::AddPosting

void
CPostingTemplate::AddPosting(
    array arRubric
);

Функция генерации выпуска на основании шаблона.

Сначала ищется и подключается языковой файл шаблона. Поиск осуществляется по пути <шаблон>>/lang/<идентификатор языка сайта к которому привязана рассылка>/template.php. Затем исполняется (подключается файл <шаблон>>/lang/template.php) шаблон. Весь вывод шаблона становится телом письма, а массив возвращаемый из него становится полями выпуска.

Если в этом массиве есть элемент FILES, к выпуску добавляются вложения. Элементами этого массива должны быть массивы формата:

Array(
    "name" => "название файла",
    "size" => "размер",
    "tmp_name" => "временный путь на сервере",
    "type" => "тип загружаемого файла");
Массив такого вида может быть сформирован с помощью функии CFile::MakeFileArray.

А если в этом массиве есть элемент DO_NOT_SEND и его значение равно "Y", то выпуск не будет отправлен. Может быть использовано для отладки генерации или премодерации автоматических выпусков.

Параметры функции

Параметр | Описание
arRubric | Массив со значениями полей объекта "Рассылка". и дополнительными полями: SITE_ID - идентификатор сайта рассылки; START_TIME - время предыдущего запуска шаблона в формате "FULL" текущего сайта; END_TIME - время текущего запуска шаблона в формате "FULL" текущего сайта.

Возвращаемые значения

Нет.

Пример использования

$rubrics = CRubric::GetList(array(), array("ID"=>$ID));
if($arRubric=$rubrics->Fetch())
{
    $arRubric["START_TIME"] = $START_TIME;
    $arRubric["END_TIME"] = $END_TIME;
    $arRubric["SITE_ID"] = $arRubric["LID"];
    CPostingTemplate::AddPosting($arRubric);
}


Execute

CPostingTemplate::Execute

string
CPostingTemplate::Execute();

Функция выбирает шаблон для генерации выпуска рассылки в соответствии с расписанием.

Сначала делается выборка всех рассылок отмеченных как активные и автоматические. Затем для каждой из них выполняется проверка на необходимость генерации выпуска. Как только найдена такая рассылка для нее вызывается функция CPostingTemplate::AddPosting и на этом функция Execute завершает свою работу.

Эта функция предназначена для вызова из сценария cron'а или агента.

Параметры функции

Функция не имеет параметров.

Возвращаемые значения

Если была найдена хотя бы одна активная и автоматическая рассылка, то возвращается строка для вызова из агента, иначе возвращается пустая строка.

Пример использования в сценарии PHP для cron'а

#!/usr/bin/php
<?php
//Здесь необходимо указать ваш DOCUMENT_ROOT!
$_SERVER["DOCUMENT_ROOT"] = "/opt/www/html";
$DOCUMENT_ROOT = $_SERVER["DOCUMENT_ROOT"];
define("NO_KEEP_STATISTIC", true);
define("NOT_CHECK_PERMISSIONS", true);
set_time_limit(0);
define("LANG", "ru");
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("subscribe"))
    CPostingTemplate::Execute();
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog_after.php");
?>


GetByID

CPostingTemplate::GetByID

array
CPostingTemplate::GetByID(
    string path = ""
);

Функция возвращает шаблон по его идентификатору (относительному пути).

Параметры функции

Параметр | Описание
path | Относительный путь к каталогу шаблона.

Возвращаемые значения

Возвращается массив формируемый в файле description.php дополненный элементом "path" равным относительному пути к каталогу шаблона.

Пример файла description.php

<?
$arTemplate =
    Array(
    "NAME"=>"Дайджест новостей",
    "DESCRIPTION"=>"Шаблон генерации дайджеста новостей."
    );
?>


GetList

CPostingTemplate::GetList

array
CPostingTemplate::GetList();

Функция возвращает список шаблонов.

Параметры функции

Функция не имеет параметров.

Возвращаемые значения

Возвращается массив относительных путей к подкаталогам каталога substr(BX_PERSONAL_ROOT, 1)."/php_interface/subscribe/templates".

Пример использования

<?
//get template directories
$arTemplates = CPostingTemplate::GetList();
foreach($arTemplates as $template_dir):
?>
    <p><?echo $template_dir?></p>
<?
endforeach;
?>


IsExists

CPostingTemplate::IsExists

bool
CPostingTemplate::IsExists(
    string path = ""
);

Функция проверяет существование каталога шаблона.

Параметры функции

Параметр | Описание
path | Относительный путь к каталогу шаблона.

Возвращаемые значения

Функция возвращает true если каталог шаблона существует и false в противном случае.

Пример использования

<?
if(!CPostingTemplate::IsExists("bitrix/php_interface/subscribe/templates/news"))
    echo "Указанный шаблон не существует.";
?>


Класс CRubric

CRubric - класс для работы с рубриками подписки.

Методы класса

Метод | Описание
Add | Функция добавляет рассылку.
Delete | Функция удаляет рассылку.
GetByID | Функция выбирает одну рассылку по ее идентификатору.
GetList | Функция возвращает список рассылок по фильтру.
GetSubscriptionCount | Функция возвращает количество подписчиков на указанную рассылку. Учитываются как подтвержденные, так и неподтвержденные подписчики.
Update | Функция модифицирует рассылку.


Add

CRubric::Add

int
CRubric::Add(
    array arFields
);

Функция добавляет рассылку. При этом если рассылка активна и является автоматической, то в случае соответствующей настроки модуля (метод генерации не cron) добляется агент для генерации выпусков.

Параметры функции

Параметр | Описание
arFields | Массив со значениями полей объекта "Рассылка".

Требования к полям передаваемым в arFields

  • NAME - не должно быть пустым.
  • LID - не должно быть пустым и должно содержать корректный идентификатор сайта.
  • DAYS_OF_MONTH - может быть пустым или должно содержать корректный список дней месяца вида (DD|DD-DD)[[,(DD|DD-DD)],...].
  • DAYS_OF_WEEK - может быть пустым или должно содержать корректный список дней недели вида DD[[,DD],...].
  • TIMES_OF_DAY - может быть пустым или должно содержать корректный список времен вида HH:MM[[,HH:MM],...].
  • TEMPLATE - может быть пустым или должно содержать корректный идентификатор шаблона.
  • LAST_EXECUTED - может быть пустым или должно содержать корректное значение времени.
  • AUTO - если задано и равно "Y", то должны быть заданы DAYS_OF_MONTH или DAYS_OF_WEEK, а также TIMES_OF_DAY и LAST_EXECUTED. И еще поле FROM_FIELD должно содержать правильный адрес e-mail (см. функцию check_email).

Возвращаемые значения

В случае успешного добавления возвращается ID рассылки. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке.

Пример использования

$rubric = new CRubric;
$arFields = Array(
    "ACTIVE" => ($ACTIVE <> "Y"? "N":"Y"),
    "NAME" => $NAME,
    "SORT" => $SORT,
    "DESCRIPTION" => $DESCRIPTION,
    "LID" => $LID
);
$ID = $rubric->Add($arFields);
if($ID == false)
    echo $rubric->LAST_ERROR;


Delete

CRubric::Delete

mixed
CRubric::Delete(
    int ID
);

Функция удаляет рассылку.

Параметры функции

Параметр | Описание
ID | Идентификатор рассылки.

Возвращаемые значения

В случае успешного удаления возвращается результат типа CDBResult. В противном случает возвращается false.

Пример использования

if (($res = CRubric::Delete($ID)) &&
     $res->AffectedRowsCount() < 1 ||
     $res == false)
    echo "Error";


GetByID

CRubric::GetByID

CDBResult
CRubric::GetByID(
    int ID
);

Функция выбирает одну рассылку по ее идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор рассылки.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Рассылка".

Пример использования

if($ID>0)
{
    $rubric = CRubric::GetByID($ID);
    if($rubric->ExtractFields("str_"))
        echo $str_NAME;
}


GetList

CRubric::GetList

CDBResult
CRubric::GetList(
    array aSort = Array(),
    array aFilter = Array()
);

Функция возвращает список рассылок по фильтру.

Параметры функции

Параметр Описание
aSort Массив, содержащий признак сортировки в виде наборов "название поля"=>"направление".

Название поля может принимать значение:
  • NAME - название рассылки;
  • LID - идентификатор сайта;
  • ACT - активность рассылки;
  • SORT - сортировка в списке;
  • ID - идентификатор рассылки;
  • AUTO - флаг генерации;
  • VISIBLE - публичность рассылки;
  • LAST_EXECUTED - время последней генерации.
Направление сортировки может принимать значение:
  • ASC - по возрастанию;
  • DESC - по убыванию.
Пример:
array("LID"=>"ASC", "NAME"=>"DESC")
aFilter Массив, содержащий фильтр в виде наборов "название поля"=>"значение фильтра".

Название поля может принимать значение:
  • LID - идентификатор сайта;
  • ACTIVE - активность рассылки;
  • AUTO - флаг генерации;
  • VISIBLE - публичность рассылки;
  • ID - идентификатор рассылки.
  • NAME - название рассылки.
Пример:
array("LID"=>SITE_ID, "ACTIVE"=>"Y")

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Рассылка".

Пример использования

<?
//get site's newsletter categories
$rub = CRubric::GetList(array("SORT"=>"ASC", "NAME"=>"ASC"), array("ACTIVE"=>"Y", "LID"=>LANG));
while($rub->ExtractFields("r_")):
?>
    <input type="checkbox" name="sf_RUB_ID[]" value="<?echo $r_ID?>"><?echo $r_NAME?><br>
<?
endwhile;
?>


GetSubscriptionCount

CRubric::GetSubscriptionCount

int
CRubric::GetSubscriptionCount(
    int ID
);

Функция возвращает количество подписчиков на указанную рассылку. Учитываются как подтвержденные, так и неподтвержденные подписчики.

Параметры функции

Параметр | Описание
ID | Идентификатор рассылки.

Возвращаемые значения

Функция возвращает целое число, равное количеству подписчиков рассылки. Если подписка с заданным идентификатором не существует, то возвращается 0.

Пример использования

<?
//get site's newsletter categories
$rub = CRubric::GetList(array("SORT"=>"ASC", "NAME"=>"ASC"), array("ACTIVE"=>"Y", "LID"=>LANG));
while($rub->ExtractFields("r_")):
?>
    <input type="checkbox" name="sf_RUB_ID[]" value="<?echo $r_ID?>">
    <?echo $r_NAME?> (<?echo CRubric::GetSubscriptionCount($r_ID);?>)<br>
<?
endwhile;
?>


Update

CRubric::Update

bool
CRubric::Update(
    int ID,
    array arFields
);

Функция модифицирует рассылку.

Параметры функции

Параметр | Описание
ID | Идентификатор рассылки.
arFields | Массив со значениями полей объекта "Рассылка".

Возвращаемые значения

В случае успешного изменения возвращается true. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке.

Пример использования

$rubric = new CRubric;
$arFields = Array(
    "ACTIVE" => ($ACTIVE <> "Y"? "N":"Y"),
    "NAME" => $NAME,
    "SORT" => $SORT,
    "DESCRIPTION" => $DESCRIPTION,
    "LID" => $LID
);
if($ID>0)
{
    if(!$rubric->Update($ID, $arFields))
        echo $rubric->LAST_ERROR;
}


Поля CRubric

CRubric::Поля CRubric

Класс CRubric использует следующие поля при работе с объектом "Рассылка":

Название поля | Описание | Тип | Обяз.
ID | Идентификатор рассылки | int | Да.
LID | Идентификатор сайта | char(2) | Да.
NAME | Название рассылки | string(100) | Да.
DESCRIPTION | Описание рассылки для подписчиков | text |
SORT | Сортировка в списке | int |
ACTIVE | Признак активности рассылки (Y/N) | char(1) |
VISIBLE | Показывать рассылку в списке публичных или нет (Y/N) | char(1) |
AUTO | Признак того, что выпуски рассылки генерируются автоматически (Y/N) | char(1) |
LAST_EXECUTED | Время последней генерации выпуска. | datetime |
DAYS_OF_MONTH | Список дней месяца для генерации выпуска. | string(100) |
DAYS_OF_WEEK | Список дней недели для генерации выпуска. | string(15) |
TIMES_OF_DAY | Список времен дня для генерации выпуска. | string(100) |
TEMPLATE | Относительный путь к каталогу шаблона. | string(100) |
FROM_FIELD | Поле письма "От кого". Может использоваться в шаблоне генерации выпуска. | string(255) |


Класс CSubscription

CSubscription - класс для работы с подписками на рассылки.

Методы класса

Метод | Описание
Add | Функция добавляет подписку на рассылки и отправляет подписчику письмо с кодом подтверждения подписки (если не указано не отправлять).
Authorize | Авторизует посетителя для доступа к редактированию подписки. Признак успешной авторизации сохраняется в PHP-сессии.
ConfirmEvent | Функция добавляет событие SUBSCRIBE_CONFIRM для отправки подписчику письма с кодом подтверждения подписки. Письмо формируется по шаблону типа "SUBSCRIBE_CONFIRM - Подтверждение подписки".
Delete | Функция удаляет подписку.
GetByEmail | Функция выбирает подписку по уникальному Email.
GetByID | Функция выбирает подписку по ее идентификатору.
GetList | Функция выбирает список подписок по фильтру.
GetRubricArray | Функция возвращает массив идентификаторов рассылок, на которые подписан данный адрес.
GetRubricList | Функция возвращает выборку рассылок, на которые подписан данный адрес.
GetUserSubscription | Функция возвращает массив полей подписки текущего пользователя. Подписка определяется по Email, сохраненному в куках посетителя, либо по Email авторизованного пользователя.
IsAuthorized | Функция проверяет, авторизован ли текущий посетитель для доступа к информации о подписке.
Update | Функция изменяет данные подписки. Если изменяется адрес подписки, то функция снимает подтверждение с подписки и генерирует событие для отправки письма с кодом подтверждения подписки (если это явно не запрещено). Если подписка не подтверждена, а массив полей включает в себя правильный CONFIRM_CODE, то подписка подтверждается.


Add

CSubscription::Add

int
CSubscription::Add(
    array arFields,
    string SITE_ID = SITE_ID
);

Функция добавляет подписку на рассылки и отправляет подписчику письмо с кодом подтверждения подписки (если не указано не отправлять).

Параметры функции

Параметр | Описание
arFields Массив со значениями полей объекта "Подписка". Дополнительно могут быть указаны поля:
  • RUB_ID - массив идентификаторов рассылок, на которые подписывается адрес;
  • SEND_CONFIRM - отправлять ли письмо с кодом подтверждения подписчику (Y/N).
  • ALL_SITES - отписать подписчика от рассылок всех сайтов или от только от заданного SITE_ID (Y/N).
SITE_ID | Идентификатор сайта, по которому определяется шаблон письма о подтверждении подписки. По умолчанию параметр принимает значение текущего сайта.

Требования к полям передаваемым в arFields

  • EMAIL - должно содержать правильный адрес e-mail (см. функцию check_email). Также выполняется проверка уникальности EMAIL.
  • TO_FIELD - в случае когда поле DIRECT_SEND равно Y не должно быть пустым.
  • USER_ID - если задано, то должно содержать идентификатор зарегистрированного пользователя.

Возвращаемые значения

В случае успешного добавления возвращается ID подписки. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке (так же возбуждается исключение CMain::ThrowException).

Пример использования

//there must be at least one newsletter category
if(!is_array($RUB_ID) || count($RUB_ID) == 0)
    $strWarning .= "There must be at least one category."."<br>";

if($strWarning == "")
{
    $arFields = Array(
        "USER_ID" => ($USER->IsAuthorized()? $USER->GetID():false),
        "FORMAT" => ($FORMAT <> "html"? "text":"html"),
        "EMAIL" => $EMAIL,
        "ACTIVE" => "Y",
        "RUB_ID" => $RUB_ID
    );
    $subscr = new CSubscription;

    //can add without authorization
    $ID = $subscr->Add($arFields);
    if($ID>0)
        CSubscription::Authorize($ID);
    else
        $strWarning .= "Error adding subscription: ".$subscr->LAST_ERROR."<br>";
}


Authorize

CSubscription::Authorize

bool
CSubscription::Authorize(
    int ID,
    string CONFIRM_CODE = false
);

Авторизует посетителя для доступа к редактированию подписки. Признак успешной авторизации сохраняется в PHP-сессии ($_SESSION["SESS_SUBSCR_AUTH"][$ID]).

Если подписка анонимная, то авторизация проверяется по коду подтверждения подписки. Если подписка принадлежит зарегистрированному пользователю, то доступ предоставляется только авторизованному пользователю-владельцу подписки.

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.
CONFIRM_CODE | Пароль для авторизации доступа, должен совпадать с кодом подтверждения подписки, сгенерированным при добавлении или изменении адреса подписки. Если параметр принимает значение false, то производится безусловная авторизация.

Возвращаемые значения

При успешной авторизации доступа к подписке функция возвращает true, иначе false.

Пример использования

//try to authorize subscription by CONFIRM_CODE or user password AUTH_PASS
if($ID > 0 && !CSubscription::IsAuthorized($ID))
{
    if($str_USER_ID > 0 && !empty($AUTH_PASS))
    {
        //trying to login user
        $usr = CUser::GetByID($str_USER_ID);
        if(($usr_arr = $usr->Fetch()))
        {
            $res = $USER->Login($usr_arr["LOGIN"], $AUTH_PASS);
            if($res["TYPE"] == "ERROR")
                $strWarning .= $res["MESSAGE"];
        }
    }
    CSubscription::Authorize($ID, (empty($AUTH_PASS)? $CONFIRM_CODE:$AUTH_PASS));
}


ConfirmEvent

CSubscription::ConfirmEvent

bool
CSubscription::ConfirmEvent(
    int ID,
    string SITE_ID = SITE_ID
);

Функция добавляет событие SUBSCRIBE_CONFIRM для отправки подписчику письма с кодом подтверждения подписки. Письмо формируется по шаблону типа "SUBSCRIBE_CONFIRM - Подтверждение подписки".

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.
SITE_ID | Идентификатор сайта, по которому определяется шаблон письма о подтверждении подписки. По умолчанию параметр принимает значение текущего сайта.

Возвращаемые значения

При успешном добавлении события функция возвращает true, иначе false.

Пример использования

if($ID > 0)
{
    //confirmation code request
    if($action == "sendcode")
    {
        if(CSubscription::ConfirmEvent($ID))
            echo "Subscription confirmation was sent successfully";
    }
}


Delete

CSubscription::Delete

mixed
CSubscription::Delete(
    int ID
);

Функция удаляет подписку.

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.

Возвращаемые значения

В случае успешного удаления возвращается результат типа CDBResult. В противном случае возвращается false.

Пример использования

if (($res = CSubscription::Delete($ID)) &&
     $res->AffectedRowsCount() < 1 ||
     $res == false)
    echo "Error deleting subscription.";
else
    echo "Subscription deleted.";


GetByEmail

CSubscription::GetByEmail

CDBResult
CSubscription::GetByEmail(
    string email
);

Функция выбирает подписку по уникальному Email.

Параметры функции

Параметр | Описание
email | Уникальный Email подписчика.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Подписка".

Пример использования

//new or existing subscription?
//ID==0 indicates new subscription
if(strlen($sf_EMAIL) > 0 || $ID > 0)
{
    if($ID > 0)
        $subscription = CSubscription::GetByID($ID);
    else
        $subscription = CSubscription::GetByEmail($sf_EMAIL);

    if($subscription->ExtractFields("str_"))
        $ID = (integer)$str_ID;
    else
        $ID=0;
}
else
    $ID = 0;


GetByID

CSubscription::GetByID

CDBResult
CSubscription::GetByID(
    int ID
);

Функция выбирает подписку по ее идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Подписка".

Пример использования

//new or existing subscription?
//ID==0 indicates new subscription
if(strlen($sf_EMAIL) > 0 || $ID > 0)
{
    if($ID > 0)
        $subscription = CSubscription::GetByID($ID);
    else
        $subscription = CSubscription::GetByEmail($sf_EMAIL);

    if($subscription->ExtractFields("str_"))
        $ID = (integer)$str_ID;
    else
        $ID=0;
}
else
    $ID = 0;


GetList

CSubscription::GetList

CDBResult
CSubscription::GetList(
    array aSort = Array(),
    array aFilter = Array()
);

Функция выбирает список подписок по фильтру.

Если параметр aFilter не задан, то сортировки будет выполнена в порядке убывания поля ID.

Параметры функции

Параметр Описание
aSort Массив, содержащий признак сортировки в виде наборов "название поля"=>"направление".

Название поля может принимать значение:
  • ID - идентификатор подписки;
  • DATE_INSERT - дата добавления;
  • DATE_UPDATE - дата изменения;
  • DATE_CONFIRM - дата подтверждения;
  • ACT - флаг активности;
  • CONF - флаг подтверждения;
  • EMAIL - адрес подписки;
  • FMT - формат подписки;
  • USER - идентификатор пользователя.
  • CONFIRM_CODE - код подтверждения подписки.
  • Направление сортировки может принимать значение:
  • ASC - по возрастанию;
  • DESC - по убыванию.
Например: array("EMAIL"=>"ASC", "ACT"=>"DESC")
aFilter Массив, содержащий фильтр в виде наборов "название поля"=>"значение фильтра".

Название поля может принимать значение:
  • ID - идентификатор подписки (возможны сложные условия);
  • EMAIL - адрес (возможны сложные условия);
  • UPDATE_1 - дата модификации (начало периода);
  • UPDATE_2 - дата модификации (конец периода);
  • INSERT_1 - дата добавления (начало периода);
  • INSERT_2 - дата добавления (конец периода);
  • USER - пользователь (возможны сложные условия по полям пользователя ID, LOGIN, NAME, LAST_NAME);
  • USER_ID - идентификатор пользователя (возможны сложные условия);
  • ANONYMOUS - флаг анонимности подписки;
  • CONFIRMED - флаг подтверждения подписки;
  • ACTIVE - флаг активности подписки;
  • FORMAT - формат подписки;
  • RUBRIC - рубрики подписки в виде массива идентификаторов или строки, сформированной по правилам логики фильтра.
Например: array("CONFIRMED"=>"Y", "ACTIVE"=>"Y")

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта "Подписка".

Пример использования

//в какие рубрики отправлять
$aPostRub = array();
$post_rub = CPostingGeneral::GetRubricList($post_arr["ID"]);
while($post_rub_arr = $post_rub->Fetch())
    $aPostRub[] = $post_rub_arr["ID"];

//активные и подтвержденные адреса, подписанные на рубрики
$subscr = CSubscription::GetList(
    array("ID"=>"ASC"),
    array("RUBRIC"=>$aPostRub, "CONFIRMED"=>"Y", "ACTIVE"=>"Y",
        "FORMAT"=>$post_arr["SUBSCR_FORMAT"], "EMAIL"=>$post_arr["EMAIL_FILTER"])
);
while(($subscr_arr = $subscr->Fetch()))
    $aEmail[] = $subscr_arr["EMAIL"];


GetRubricArray

CSubscription::GetRubricArray

array
CSubscription::GetRubricArray(
    int ID
);

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

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.

Возвращаемые значения

Массив целых чисел, идентификаторы рассылок.

Пример использования

<?
//shows all subscription categories and checks subscribed one
$aSubscrRub = CSubscription::GetRubricArray($ID);
$rub = CRubric::GetList(
    array("LID"=>"ASC", "SORT"=>"ASC", "NAME"=>"ASC"),
    array("ACTIVE"=>"Y", "LID"=>LANG)
);
while($rub->ExtractFields("r_")):
    $bChecked = in_array($r_ID, $aSubscrRub);
?>
<input type="checkbox"
       name="RUB_ID[]"
       value="<?echo $r_ID?>"<?if($bChecked) echo " checked"?>>
<?echo $r_NAME?><br>
<?
endwhile;
?>


GetRubricList

CSubscription::GetRubricList

CDBResult
CSubscription::GetRubricList(
    int ID );

Функция возвращает выборку рассылок, на которые подписан данный адрес.

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны некоторые поля объекта "Рассылка". А именно:

  • ID - Идентификатор рассылки;
  • NAME - Название рассылки;
  • SORT - Сортировка в списке;
  • LID - Идентификатор сайта;
  • ACTIVE - Признак активности рассылки (Y/N).
  • VISIBLE - Выводить в списке публичных рассылок (Y/N).

Пример использования

//array of subscribed categories
function GetRubricArray($ID)
{
    $aSubscrRub = array();
    if($ID>0)
    {
        $subscr_rub = CSubscription::GetRubricList($ID);
        while($subscr_rub_arr = $subscr_rub->Fetch())
            $aSubscrRub[] = $subscr_rub_arr["ID"];
    }
    return $aSubscrRub;
}


GetUserSubscription

CSubscription::GetUserSubscription

array
CSubscription::GetUserSubscription();

Функция возвращает массив полей подписки текущего пользователя. Подписка определяется по Email, сохраненному в куках посетителя, либо по Email авторизованного пользователя.

Параметры функции

Функция не имеет параметров.

Возвращаемые значения

Возвращается массив полей объекта "Подписка". Если подписка посетителя не найдена, то возвращается массив array("ID"=>0, "EMAIL"=>"").

Пример использования

//get current user subscription from cookies
$aSubscr = CSubscription::GetUserSubscription();

//get user's newsletter categories
$aSubscrRub = CSubscription::GetRubricArray(intval($aSubscr["ID"]));

//show subscription form
//.....


IsAuthorized

CSubscription::IsAuthorized

bool
CSubscription::IsAuthorized(
    int ID
);

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

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.

Возвращаемые значения

Если посетитель авторизован для доступа к данной подписке, то возвращается true, иначе false.

Пример использования

//check whether already authorized to show password field
$bShowPass = true;
$aSubscr = CSubscription::GetUserSubscription();
if($aSubscr["ID"] > 0)
{
    //try to authorize user account's subscription
    if($aSubscr["USER_ID"]>0 && !CSubscription::IsAuthorized($aSubscr["ID"]))
        CSubscription::Authorize($aSubscr["ID"], "");
    //check authorization
    if(CSubscription::IsAuthorized($aSubscr["ID"]))
        $bShowPass = false;
}


Update

CSubscription::Update

mixed
CSubscription::Update(
    int ID,
    array arFields,
    string SITE_ID = SITE_ID
);

Функция изменяет данные подписки. Если изменяется адрес подписки, то функция снимает подтверждение с подписки и генерирует событие для отправки письма с кодом подтверждения подписки (если это явно не запрещено). Если подписка не подтверждена, а массив полей включает в себя правильный CONFIRM_CODE, то подписка подтверждается.

Параметры функции

Параметр | Описание
ID | Идентификатор подписки.
arFields | Массив со значениями полей объекта "Подписка". Дополнительно могут быть указаны поля: RUB_ID - массив идентификаторов рассылок, на которые подписывается адрес; SEND_CONFIRM - отправлять ли письмо с кодом подтверждения подписчику при изменениии адреса (Y/N).
SITE_ID | Идентификатор сайта, по которому определяется шаблон письма о подтверждении подписки. По умолчанию параметр принимает значение текущего сайта.

Возвращаемые значения

В случае успешного изменения возвращается true. В противном случает возвращается false, и переменная класса LAST_ERROR содержит сообщение об ошибке (так же возбуждается исключение CMain::ThrowException).

При успешном результате переменная класса LAST_MESSAGE содержит строку-код информационного сообщения. Возможные значения:
"CONF" - подписка подтверждена;
"SENT" - сгенерировано событие для отправки письма с кодом подтверждения.

Пример использования

//confirmation code from letter or confirmation form
if($CONFIRM_CODE <> "" && $ID > 0 && empty($action))
{
    if($str_CONFIRMED <> "Y")
    {
        //subscribtion confirmation
        if($subscr->Update($ID, array("CONFIRM_CODE"=>$CONFIRM_CODE)))
            $str_CONFIRMED = "Y";
        $strWarning .= $subscr->LAST_ERROR;
        $iMsg = $subscr->LAST_MESSAGE;
    }
}

//*************************
//form actions processing
//*************************
if($ID > 0)
{
    if($action == "unsubscribe" && CSubscription::IsAuthorized($ID))
    {
        //unsubscription
        if($subscr->Update($ID, array("ACTIVE"=>"N")))
        {
            $str_ACTIVE = "N";
            $iMsg = "UNSUBSCR";
        }
    }
    if($action == "activate" && CSubscription::IsAuthorized($ID))
    {
        //activation
        if($subscr->Update($ID, array("ACTIVE"=>"Y")))
        {
            $str_ACTIVE = "Y";
            $iMsg = "ACTIVE";
        }
    }
}


Поля CSubscription

CSubscription::Поля CSubscription

Класс CSubscription использует следующие поля при работе с объектом "Подписка":

Название поля | Описание | Тип | Обяз.
ID | Идентификатор подписки. | int | Да.
DATE_INSERT | Дата добавления записи. | datetime |
DATE_UPDATE | Дата модификации записи. | datetime |
USER_ID | Идентификатор пользователя, которому принадлежит подписка. Если NULL, то подписка анонимна. | int |
ACTIVE | Признак активности подписки (Y/N). Если подписка не активна, то рассылка на этот адрес не производится. | char(1) |
EMAIL | Email подписки (уникальный). | string(255) | Да.
FORMAT | Предпочтительный формат выпуска (text/html). | string(4) |
CONFIRM_CODE | Код подтверждения подписки (пароль). | string(8) |
CONFIRMED | Признак подтверждения подписки (Y/N). | char(1) |
DATE_CONFIRM | Дата подтверждения подписки. | datetime |


События

Событие | Описание
BeforePostingSendMail | Вызывается перед отправкой выпуска каждому конкретному адресату.


BeforePostingSendMail

функция-обработчик(
 array &arFields
);
Событие "BeforePostingSendMail" вызывается перед отправкой выпуска из функции CPosting::SendMessage.

Параметры

Параметр Описание
arFields Массив следующего содержания:
  • POSTING_ID - идентификатор выпуска.
  • EMAIL - адрес на который будет отправлен выпуск.
  • SUBJECT - заголовок письма (в кодированном виде, если установлена соответсветствующая настройка модуля).
  • BODY - тело письма уже отформатированное в соответствии со стандартом MIME.
  • HEADER - служебные заголовки.

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

См. также

  • CPosting::SendMessage
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("subscribe", "BeforePostingSendMail", Array("MyClass", "BeforePostingSendMailHandler"));

class MyClass
{
    // создаем обработчик события "BeforePostingSendMail"
    function BeforePostingSendMailHandler($arFields)
    {
        $USER_NAME = "Подписчик";
        //Попробуем найти подписчика.
        $rs = CSubscription::GetByEmail($arFields["EMAIL"]);
        if($ar = $rs->Fetch())
        {
            if(intval($ar["USER_ID"]) > 0)
            {
                $rsUser = CUser::GetByID($ar["USER_ID"]);
                if($arUser = $rsUser->Fetch())
                {
                    $USER_NAME = $arUser["NAME"]." ".$arUser["LAST_NAME"];
                }
            }
        }
        $arFields["BODY"] = str_replace("#NAME#", $USER_NAME, $arFields["BODY"]);
        return $arFields;
    }
}
?>


Для разработчиков

Перед использованием модуля необходимо проверить установлен ли он и подключить его при помощи конструкции:

<?
if(CModule::IncludeModule("search"))
{
    //здесь можно использовать функции модуля
}
?>

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

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

Специальные константы.

Публичные функции и возвращаемые значения

Функция | Описание
stemming | Возвращает массив неизменных основ слов.
stemming_default | Функция морфологического анализа текста применяемая по умолчанию.
stemming_stop_default | Функция определения стоп слова применяемая по умолчанию.
stemming_letter_default | Функция возвращает алфавит по умолчанию.
tags_prepare | Возвращает массив тегов.
InputTags | Возвращает код html для ввода тегов с поддержкой автодополнения.

Классы модуля поиска

Класс | Описание
CSearch | Класс для индексирования сайта и осуществления поиска по индексу.
CSearchCustomRank | Класс поддержки правил сортировки.
CSiteMap | Класс поддержки Google Sitemap.
CSearchTags | Класс поддержки тегов.

События модуля поиска

Событие | Описание
BeforeIndex | Вызывается перед индексацией элемента.
OnSearch | Вызывается перед выполнением поисковых запросов.
OnReIndex | Вызывается при построении поискового индекса.
OnSearchGetFileContent | Вызывается по время переиндексации данных главного модуля.
OnSearchGetURL | Вызывается при форматировании элемента в результатах поиска.


Константы

  • CACHED_b_search_tags
  • CACHED_b_search_tags_len

Имя константы | Тип | Описание
CACHED_b_search_tags | А Т И С | Кешировать в управляемом кеше выпадающий список тегов или нет. Если равно false, то кеширование не производится. По умолчанию задается значение 3600, что означает кеширование на 1 час.
CACHED_b_search_tags_len | А Т И С | Максимально допустимая длина маски поиска тегов при которой будет включено управляемое кеширование. По умолчанию равно 2, что означает создание в пределе около 1000 файлов (все 2-х буквенные комбинации).

Обозначения типов констант:

  • А (авто) - константа инициализируется при подключении модуля автоматически
  • Т (страница) - константу можно определить на любой публичной странице до подключения пролога
  • И (инициализация) - константу можно определить в одном из следующих файлов:
    • /bitrix/php_interface/init.php - дополнительные параметры портала
    • /bitrix/php_interface/ID сайта/init.php - дополнительные параметры сайта
  • С (соединение с базой) - константу можно определить только в файле хранящим параметры соединения к базе: /bitrix/php_interface/dbconn.php


Классы модуля

Класс | Описание
CSearch | Класс для индексирования сайта и осуществления поиска по индексу.
CSearchCustomRank | Класс поддержки правил сортировки.
CSearchTags | Класс поддержки тегов.
CSiteMap | Класс поддержки Google Sitemap.


Класс CSearch

Класс для индексирования сайта и осуществления поиска по индексу

Методы класса

Метод | Описание
CSearch | Конструктор класса CSearch.
Search | Возвращает записи индекса, которые удовлетворяют заданной строке запроса и указанным параметрам, а так же доступны на просмотр для текущего посетителя (в соответствии с его уровнем доступа)
ChangeIndex | Функция изменяет проиндексированную информацию данного модуля.
ChangePermission | Функция изменяет права на доступ к проиндексированной информации данного модуля.
DeleteIndex | Функция удаляет из индекса поиска указанную информацию.
Index | Функция переиндексирует какую-то одиночную позицию (сообщение на форуме, новость и т.п.), причем комбинация (MODULE_ID, ITEM_ID) используется для определения переиндексируемого документа.
ReindexModule | Функция инициирует переиндексацию указанного модуля.
ReIndexAll | Пошаговая функция переиндексации.
ReIndexFile | Переиндексация статического файла.
Fetch | Возвращает следующий найденный элемент.


Конструктор CSearch

CSearch::Конструктор CSearch

CDBResult
CSearch(
    string strQuery,
    string LID = false,
    string MODULE_ID = false,
    string ITEM_ID = false,
    string PARAM1 = false,
    string PARAM2 = false,
    array aSort = array(),
    array aParamsEx = array(),
    bool bTagsCloud = false
);

Конструктор класса CSearch возвращает записи индекса, которые удовлетворяют заданной строке запроса и указанным параметрам, а так же доступны на просмотр для текущего посетителя (в соответствии с его уровнем доступа).

Устарел, лучше воспользоваться методом CSearch::Search. Это показано в приведенном ниже примере.

См. также

  • CSearch::Search

Пример использования

<?
$q = "жареная рыба или селедка";
$module_id = "forum";
//Эту строку заменяем
//$obSearch = new CSearch($q, LANG, $module_id);
// на следующую:
$obSearch = new CSearch;
$obSearch->Search(array(
    "QUERY" => $q,
    "SITE_ID" => LANG,
    "MODULE_ID" => $module_id,
));
if ($obSearch->errorno!=0):
    ?>
    <font class="text">В поисковой фразе обнаружена ошибка:</font>
    <?echo ShowError($obSearch->error);?>
    <font class="text">Исправьте поисковую фразу и повторите поиск.</font>
    <?
else:
    while($arResult = $obSearch->GetNext())
    {
    ?>
        <a href="<?echo $arResult["URL"]?>"><?echo $arResult["TITLE_FORMATED"]?></a>
        <?echo $arResult["BODY_FORMATED"]?>
        <hr size="1" color="#DFDFDF">
    <?
    }
endif;
?>


ChangeIndex

CSearch::ChangeIndex

void
CSearch::ChangeIndex(
    string MODULE_ID,
    array arFields,
    string ITEM_ID = false,
    string PARAM1 = false,
    string PARAM2 = false,
    string SITE_ID = false
);

Функция изменяет проиндексированную информацию данного модуля.

Параметры функции

Параметр | Описание
MODULE_ID | Код модуля, проиндексированную информацию которого необходимо поменять.
arFields Массив новых значений для поискового индекса. Массив должен иметь следующую структуру:
  • "DATE_CHANGE" => дата изменения индексируемого элемента,
  • "URL" => адрес индексируемого элемента,
  • "TITLE" => заголовок индексируемого элемента,
  • "BODY" => индексируемый текст,
  • "SEARCHABLE_CONTENT" => индекс,
  • "PARAM1" => первый параметр,
  • "PARAM2" => второй параметр,
  • "PERMISSIONS" => массив кодов групп, члены которых имеют право на чтение индексируемого элемента,
Атрибуты, значения которых не изменились, можно опустить.
ITEM_ID | Код элемента, индекс которого необходимо изменить. Если этот параметр равен false, то ограничение по коду элемента не устанавливается (изменяются индексы элементов с любыми кодами). Не обязательный параметр, по умолчанию равен false.
PARAM1 | Первый параметр элемента, ограничивающий набор проиндексированных элементов, индексы которых необходимо поменять. Если этот параметр равен false, то ограничение по первому параметру элемента не устанавливается. Не обязательный параметр, по умолчанию равен false.
PARAM2 | Второй параметр элемента, ограничивающий набор проиндексированных элементов, индексы которых необходимо поменять. Если этот параметр равен false, то ограничение по второму параметру элемента не устанавливается. Не обязательный параметр, по умолчанию равен false.
SITE_ID | Сайт проиндексированого элемента, ограничивающий набор элементов, индекс которых необходимо поменять. Если этот параметр равен false, то ограничение по сайту элемента не устанавливается. Необязательный параметр, по умолчанию равен false.

Примеры использования

При изменении заголовка темы форума необходимо соответствующим образом изменить индекс
<?
$new_title = "Новый заголовок темы";
$fid = 5;    // Код форума
$tid = 128;    // Код темы
CSearch::ChangeIndex("forum",
    array(
        "TITLE" => $new_title
    ),
    false, $fid, $tid);
?>


ChangePermission

CSearch::ChangePermission

void
CSearch::ChangePermission(
    string MODULE_ID,
    array arGroups,
    string ITEM_ID = false,
    string PARAM1 = false,
    string PARAM2 = false,
    string SITE_ID = false
);

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

Параметры функции

Параметр | Описание
MODULE_ID | Код модуля, права на доступ к информации которого необходимо поменять.
arGroups | Массив кодов групп, которые имеют право на чтение проиндексированной информации.
ITEM_ID | Код элемента, права на доступ к которому необходимо поменять. Если этот параметр равен false, то ограничение по коду элемента не устанавливается (изменяются права на доступ к элементу с любыми кодами). Не обязательный параметр, по умолчанию равен false.
PARAM1 | Первый параметр элемента, ограничивающий набор проиндексированных элементов, права на доступ к которым необходимо поменять. Если этот параметр равен false, то ограничение по первому параметру элемента не устанавливается. Не обязательный параметр, по умолчанию равен false.
PARAM2 | Второй параметр элемента, ограничивающий набор проиндексированных элементов, права на доступ к которым необходимо поменять. Если этот параметр равен false, то ограничение по второму параметру элемента не устанавливается. Не обязательный параметр, по умолчанию равен false.
SITE_ID | Сайт проиндексированного элемента, ограничивающий набор элементов, права на доступ к которым необходимо поменять. Если этот параметр равен false, то ограничение по сайту элемента не устанавливается. Необязательный параметр, по умолчанию равен false.

Примеры использования

Изменяем права на доступ к проиндексированным сообщениям данного форума при изменении прав на доступ к этому форуму
<?
$Forum_ID = 5;
$arGroups = CForum::GetAccessPermissions($Forum_ID);
$arGPerm = Array();
for ($i=0; $i < count($arGroups); $i++)
{
    if ($arGroups[$i][1]>="E")
    {
        $arGPerm[] = $arGroups[$i][0];
        if($arGroups[$i][0]==2)
            break;
    }
}
CSearch::ChangePermission("forum", $arGPerm, false, $Forum_ID);
?>


DeleteIndex

CSearch::DeleteIndex

void
CSearch::DeleteIndex(
    string MODULE_ID,
    string ITEM_ID = false,
    string PARAM1 = false,
    string PARAM2 = false,
    string SITE_ID = false
);

Функция удаляет из индекса поиска указанную информацию.

Параметры функции

Параметр | Описание
MODULE_ID | Код модуля, индексацию информации которого необходимо удалить .
ITEM_ID | Код элемента, индексацию информации которого необходимо удалить. Если этот параметр равен false, то ограничение по коду элемента не устанавливается (удаляется индексация информации с любыми кодами). Не обязательный параметр, по умолчанию равен false.
PARAM1 | Первый параметр элемента, ограничивающий набор проиндексированных элементов, индексацию информации которых необходимо удалить. Если этот параметр равен false, то ограничение по первому параметру элемента не устанавливается. Не обязательный параметр, по умолчанию равен false.
PARAM2 | Второй параметр элемента, ограничивающий набор проиндексированных элементов, индексацию информации которых необходимо удалить. Если этот параметр равен false, то ограничение по второму параметру элемента не устанавливается. Не обязательный параметр, по умолчанию равен false.
SITE_ID | Сайт проиндексированого элемента, ограничивающий набор элементов, индексацию информации которых необходимо удалить. Если этот параметр равен false, то ограничение по сайту элемента не устанавливается. Необязательный параметр, по умолчанию равен false.

Примеры использования

При удалении файла с диска необходимо удалить так же его индекс поиска, если он есть
<?
$path = "/ru/my_files/file.php";
if (unlink($_SERVER["DOCUMENT_ROOT"].$path))
{
    if (CModule::IncludeModule("search"))
        CSearch::DeleteIndex("main", $path);
}
?>


Fetch

CSearch::Fetch

array
CSearch::Fetch(
);

Возвращает следующий найденный элемент.

Если поле результата URL начинается с символа "=", то вызываются обработчики события OnSearchGetURL.

Параметры функции

Нет параметров.

Возвращаемое значение

Смотри описание возвращаемого значения метода CSearch::Search. Если достигнут конец выборки, возвращается false.


Index

CSearch::Index

int
CSearch::Index(
    string MODULE_ID,
    string ITEM_ID,
    array arFields,
    bool bOverWrite = false,
    string SEARCH_SESS_ID = ''
);

Функция переиндексирует какую-то одиночную позицию (сообщение на форуме, новость и т.п.), причем комбинация (MODULE_ID, ITEM_ID) используется для определения переиндексируемого документа.

Вначале индексации вызывается событие BeforeIndex. Затем вычисляется пользовательский вес позиции. И производится собственно переиндексация.

Параметры функции

Параметр | Описание
MODULE_ID | Код модуля, которому принадлежит индексируемый элемент.
ITEM_ID | Код индексируемого элемента.
arFields | Массив свойств индексируемого элемента.
bOverWrite | Перетирать индекс поиска элемента если элемент уже проиндексирован. Не обязательный параметр, по умолчанию равен false.
SEARCH_SESS_ID | Служебный параметр, используется при пошаговой переиндексации.

Примеры использования

<?
CSearch::Index(
    "iblock",
    $ID,
    Array(
        "DATE_CHANGE"=>$arIBlockElement["DATE_CHANGE"],
        "TITLE"=>$arIBlockElement["NAME"],
        "SITE_ID"=>$arSites,
        "PERMISSION"=>$arGroups,
        "PARAM1"=>$arIBlockElement["IBLOCK_TYPE_ID"],
        "PARAM2"=>$IBLOCK_ID,
        "PERMISSIONS"=>$arGroups,
        "URL"=>str_replace("#ID#", $arIBlockElement["ID"], $DETAIL_PAGE_URL),
        "BODY"=>$arIBlockElement["DETAIL_TEXT"]
        "TAGS"=>$arIBlockElement["TAGS"]
    ),
    $bOverWrite
);
?>


ReIndexAll

CSearch::ReIndexAll

mixed
CSearch::ReIndexAll(
    bool bFull = false,
    int max_execution_time = 0,
    array NS = Array()
);

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

Параметры функции

Параметр | Описание
bFull | Если равен true, то на первом шаге поисковый индекс будет полностью очищен. По умолчанию равен false, что приводит к перестройке индекса только тех элементов, содержимое которых изменилось.
max_execution_time | Если задан и больше нуля, то как только время выполнения функции превысит значение этого параметра выполнение функции завершится. Данные для начала следующего шага будут возвращены как результат работы функции.
NS | Хранит состояние процесса индексации (прогресс) на начало шага.

Возвращаемое значение

Функция возвращает массив, если требуется вызвать функцию еще раз. Или число проиндексированных элементов, если переиндексация завершена.

См. также

  • OnReIndex

Примеры использования

<?
//Этот пример не является примером пошаговой индексации.
//Для этого надо вызывать функцию ReIndexAll только один раз за запуск скрипта.
//А промежуточное состояние (NS) можно сохранять например в файле.

$NS = false;
$NS = CSearch::ReIndexAll(false, 60, $NS);
while(is_array($NS))
    $NS = CSearch::ReIndexAll(false, 60, $NS);
echo $NS;

?>


ReIndexFile

CSearch::ReIndexFile

int
CSearch::ReindexFile(
    string path
);

Функция переиндексирует указанный файл.

Сначала определяется удовлетворяет файл и его размер настройкам модуля поиска. Если одна из проверок не проходит, то возвращается 0. Затем вызываются обработчики события OnSearchGetFileContent модуля "search". После того как один из обработчиков вернет не false, вызов остальных произведен не будет. И наконец вызывается метод CSearch::Index

Параметры функции

Параметр | Описание
path | Путь относительно корня сайта к переиндексируемому файлу.

Возвращаемое значение

Функция возвращает уникальный идентификатор в поисковом индексе в случае успеха и 0 в противном случае.

См. также

  • OnSearchGetFileContent
  • CSearch::Index


ReindexModule

CSearch::ReindexModule

void
CSearch::ReindexModule(
    string MODULE_ID,
    bool bFull = false
);

Функция инициирует переиндексацию указанного модуля. Для того, чтобы модуль был переиндексирован, он должен предоставить соответствующий метод, который должен быть зарегистрирован в системе событий как обработчик события OnReIndex модуля "search".

С помощью этого метода невозможно переиндексировать данные модуля "main". Т.к. индексация файлов выполняется не через обработчики событий, а непосредственно модулем поиска. Но можно воспользоваться функцией CSearch::ReIndexAll, передав на первом шаге $NS = array("MODULE_ID"=>"main").

Параметры функции

Параметр | Описание
MODULE_ID | Код модуля, переиндексация которого требуется.
bFull | Производить ли полную переиндексацию с очисткой старых поисковых индексов. Не обязательный параметр, по умолчанию равен false.

См. также

  • OnReIndex

Примеры использования

OnReindex.

// регистрируем обработчик события "OnReindex" модуля "search"
RegisterModuleDependences("search", "OnReindex", "my_module", "CMyModule", "OnReindex");

// создаем в модуле my_module в классе CMyModule функцию-метод OnReindex
function OnReindex()
{
    global $DB;
    $arResult = array();

    $strSql =
        "SELECT FT.ID, FT.TITLE, FT.MESSAGE, ".
        "  DATE_FORMAT(FT.POST_DATE, '%d.%m.%Y %H:%i:%s') as POST_DATE, FT.LID ".
        "FROM b_my_table FT ";

    $db_res = $DB->Query($strSql);
    while ($res = $db_res->Fetch())
    {
        $arResult[] = array(
            "ID" => $res["ID"],
            "LID" => $res["LID"],
            "DATE_CHANGE" => $res["POST_DATE"],
            "URL" => "/my_module/index.php?ID=".$res["ID"],
            "PERMISSIONS" => array(2),
            "TITLE" => $res["TITLE"],
            "BODY" => $res["POST_MESSAGE"]
        );
    }
    return $arResult;
}

// вызываем переиндексацию модуля
CSearch::ReIndexModule("my_module");

?>


Search

CSearch::Search

void CSearch::Search(
    array arParams,
    array aSort = array(),
    array aParamsEx = array(),
    bool bTagsCloud = false
);

Этот метод возвращает записи индекса, которые удовлетворяют заданной строке запроса и указанным параметрам, а так же доступны на просмотр для текущего посетителя (в соответствии с его уровнем доступа).

Перед выполнением поисковых запросов вызывается событие OnSearch.

Параметры функции

Параметр | Описание
arParams Массив, содержащий условия поиска в виде наборов "название поля"=>"значение".

Название поля может принимать значение:
  • QUERY - Строка запроса. Обязательный элемент. Должна быть сформирована в соответствии с правилами языка запросов.
  • TAGS - Список тегов. В результате поиска будут возвращены все элементы имеющие данные теги.
  • SITE_ID - Сайт, в информации которого производится поиск. Не обязательный параметр, по умолчанию равен текущему.
  • MODULE_ID - Код модуля, данными которого ограничивается поиск. Если этот параметр равен false, то поиск производится по всем модулям. Не обязательный параметр, по умолчанию равен false.
  • ITEM_ID - Код проиндексированного элемента. Используется для ограничения области поиска по коду элемента. Если параметр имеет значение false, то ограничение не производится. Не обязательный параметр, по умолчанию равен false.
  • PARAM1 - Первый параметр элемента или массив первых параметров. Используется для ограничения области поиска по произвольному параметру. Если параметр имеет значение false, то ограничение не производится. Не обязательный параметр, по умолчанию равен false.
  • PARAM2 - Второй параметр элемента или массив вторых параметров. Используется для ограничения области поиска по произвольному параметру. Если параметр имеет значение false, то ограничение не производится. Не обязательный параметр, по умолчанию равен false.
  • MODULE_ID - идентификатор модуля или массив идентификаторов;
  • ITEM_ID - идентификатор элемента или массив;
  • URL - маска адреса относительно корня сайта, по которому доступен данный элемент или массив масок адресов;
  • DATE_CHANGE - время изменения элемента в формате сайта (включает время);
  • CHECK_DATES - если задан и равен Y, то найдены будут только активные элементы;
aSort Массив, содержащий признак сортировки в виде наборов "название поля"=>"направление".

Название поля может принимать значение:
  • ID - идентификатор в поисковом индексе;
  • MODULE_ID - идентификатор модуля;
  • ITEM_ID - идентификатор элемента поискового индекса (например для форума это идентификатор сообщения);
  • TITLE - заголовок;
  • PARAM1 - первый параметр элемента;
  • PARAM2 - второй параметр элемента;
  • DATE_FROM - дата начала активности элемента;
  • DATE_TO - дата окончания активности элемента;
  • RANK - вычисленное значение релевантности;
  • TITLE_RANK - количество вхождений подстрок запроса в заголовок. Позволяет повысить значимость заголовка в результатах поиска;
  • CUSTOM_RANK - заданное значение релевантности;
  • DATE_CHANGE - время изменения элемента;
Направление сортировки может принимать значение:
  • ASC - по возрастанию;
  • DESC - по убыванию.
Пример (именно это значение считается по умолчанию):
array("CUSTOM_RANK"=>"DESC", "RANK"=>"DESC", "DATE_CHANGE"=>"DESC")
В случае когда параметр bTagsCloud равен true, допустимыми полями являются:
  • DATE_CHANGE - время изменения элемента;
  • NAME - значение тег;
  • CNT - частота тега;
aParamsEx Массив массивов, содержащий дополнительные условия поиска в виде наборов "название поля"=>"значение". Эти условия будут объединены по условию ИЛИ. Смотри описание параметра arParams.

Так же может содержать элемент:
  • STEMMING - Если равно true, то при поиске будет учитываться морфология. Если false, то не будет. Если не задано, то будет использоваться настройка модуля;
Пример сложного условия:
        array(
            array(
                "MODULE_ID" => "forum",
                "PARAM1" => array(1, 2),
            ),
            array(
                "MODULE_ID" => "iblock",
                "PARAM2" => 3,
            ),
        )
В данном случае поиск будет осуществляться в форумах с идентификаторами 1 и 2, а также в инфоблоке с идентификатором 3.
bTagsCloud | Признак построения облака тегов. Если задан и равен true, то будет построено облако тегов.

Возвращаемое значение

Набор записей, каждая из которых представляет собой массив следующей структуры:

Array(
    [ID] => Код индекса
    [DATE_CHANGE] => Дата изменения проиндексированного элемента
    [MODULE_ID] => Модуль, которому принадлежит проиндексированный элемент
    [ITEM_ID] => Код проиндексированного элемента
    [LID] => Языковое зеркало (язык) сайта
    [URL] => Адрес относительно корня сайта, по которому доступен данный элемент (с заменой специальных символов <, >, " на &lt;, &gt;, &quot;)
    [TITLE] => Заголовок проиндексированного элемента (с заменой спец. символов)
    [BODY] => Текст проиндексированного элемента (с заменой спец. символов)
    [SEARCHABLE_CONTENT] => Индекс элемента, по которому идет поиск (с заменой спец. символов)
    [PARAM1] => Первый параметр элемента
    [PARAM2] => Второй параметр элемента
    [~URL] => Адрес относительно корня сайта, по которому доступен данный элемент
    [~TITLE] => Заголовок проиндексированного элемента
    [~BODY] => Текст проиндексированного элемента
    [~SEARCHABLE_CONTENT] => Индекс элемента, по которому идет поиск
    [TITLE_FORMATED] => Заголовок проиндексированного элемента с выделением искомых слов
    [BODY_FORMATED] => Часть текста проиндексированного элемента с выделением искомых слов
    [URL_WO_PARAMS] => Адрес элемента без параметров добавленных в обработчиках события OnSearch.
)

Если задано построение облака тегов, то:

Array(
    [NAME] => тег
    [CNT] => частота
    [DATE_CHANGE] => Максимальная дата изменения элемента имеющего данный тег
    [FULL_DATE_CHANGE] => Дата изменения элемента включая время.
)

Примеры использования

Поиск в форумах текущего сайта указанной строки

<?
$q = "жареная рыба или селедка";
$module_id = "forum";
$obSearch = new CSearch;
$obSearch->Search(array(
    "QUERY" => $q,
    "SITE_ID" => LANG,
    "MODULE_ID" => $module_id,
));
if ($obSearch->errorno!=0):
    ?>
    <font class="text">В поисковой фразе обнаружена ошибка:</font>
    <?echo ShowError($obSearch->error);?>
    <font class="text">Исправьте поисковую фразу и повторите поиск.</font>
    <?
else:
    while($arResult = $obSearch->GetNext())
    {?>
        <a href="<?echo $arResult["URL"]?>"><?echo $arResult["TITLE_FORMATED"]?></a>
        <?echo $arResult["BODY_FORMATED"]?>
    <hr size="1" color="#DFDFDF">
    <?}
endif;
?>


Методы класса

Класс поддержки правил сортировки.

Методы класса

Метод | Описание
GetList | Получение списка правил сортировки.
GetByID | Получение правила сортировки по ID.
Add | Функция добавляет новое правило.
Update | Изменение правила сортировки.
Delete | Удаление правила сортировки.
StartUpdate | Подготовка к применению изменений в правилах.
NextUpdate | Шаг применения изменений правил сортировки.
Поля объекта CSearchCustomRank | Описание полей доступных в методах класса.


Add

CSearchCustomRank::Add

int
CSearchCustomRank::Add(
    array arFields
);

Функция добавляет новое правило.

После удаления всех требуемых правил необходимо пересчитать поисковый индекс методами CSearchCustomRank::StartUpdates и CSearchCustomRank::NextUpdate.

Параметры функции

Параметр | Описание
arFields | Массив со значениями полей объекта правила сортировки.

Возвращаемые значения

В случае успешного добавления возвращается ID нового правила. В противном случае возвращается false.

См. также

  • Поля объекта правила сортировки
  • CSearchCustomRank::StartUpdates
  • CSearchCustomRank::NextUpdate


Delete

CSearchCustomRank::Delete

CDBResult
CSearchCustomRank::Delete(
    int ID
);

Удаление правила сортировки по идентификатору.

После удаления всех требуемых правил необходимо пересчитать поисковый индекс методами CSearchCustomRank::StartUpdates и CSearchCustomRank::NextUpdate.

Параметры функции

Параметр | Описание
ID | Идентификатор правила сортировки.

Возвращаемые значения

Если правило успешно удалено, то возвращается результат запроса типа CDBResult, в противном случае функция вернет false.

См. также

  • CSearchCustomRank::StartUpdates
  • CSearchCustomRank::NextUpdate


GetByID

CSearchCustomRank::GetByID

CDBResult
CSearchCustomRank::GetByID(
    int ID
);

Получение правила сортировки по идентификатору.

Параметры функции

Параметр | Описание
ID | Идентификатор правила сортировки.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта правила сортировки.

См. также

  • Поля объекта правила сортировки


GetList

CSearchCustomRank::GetList

CDBResult
CSearchCustomRank::GetList(
    array aSort = array(),
    array aFilter = array()
);

Получение списка правил сортировки по фильтру.

Параметры функции

Параметр Описание
aSort Массив, содержащий признак сортировки в виде наборов "название поля"=>"направление".

Название поля может принимать значение названия любого из полей объекта правила сортировки. Не обязательный параметр. По умолчанию равен:
        array(
            "SITE_ID"=>"ASC",
            "MODULE_ID"=>"ASC",
            "PARAM1"=>"DESC",
            "PARAM2"=>"DESC",
            "ITEM_ID"=>"DESC",
        )
aFilter Массив, содержащий фильтр в виде наборов "название поля"=>"значение фильтра".

Название поля может принимать значение названия любого из полей объекта правила сортировки. Фильтрация осуществляется по точному совпадению значения фильтра и правила. Не обязательный параметр.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля объекта правила сортировки.

См. также

  • Поля объекта правила сортировки


NextUpdate

CSearchCustomRank::NextUpdate

array
CSearchCustomRank::NextUpdate(
);

Шаг применения изменений правил сортировки.

Данная функция применяет следующее непримененное правило сортировки к поисковому индексу. Применение правил требуется всякий раз когда происходят их изменения (CSearchCustomRank::Add, CSearchCustomRank::Update и CSearchCustomRank::Delete). При индексации данных или после переиндексации данная процедура не требуется, т.к. правила сортировки учитываются в процессе построения поискового индекса.

Перед началом применения правил необходимо инициировать процесс вызвав CSearchCustomRank::StartUpdates.

Параметры функции

Нет параметров.

Возвращаемые значения

В случае успешного выполнения возвращается массив следующей структуры:

  • DONE - количество уже примененных правил;
  • TODO - сколько правил еще надо применить.

В противном случае возвращается false и через LAST_ERROR экземпляра класса можно получить текст сообщения об ошибке.

См. также

  • CSearchCustomRank::StartUpdates
  • CSearchCustomRank::Add
  • CSearchCustomRank::Update
  • CSearchCustomRank::Delete


StartUpdate

CSearchCustomRank::StartUpdate

CDBResult
CSearchCustomRank::StartUpdate(
);

Подготовка к применению изменений в правилах.

Данная функция начинает процедуру применения правил сортировки к поисковому индексу. Применение правил требуется всякий раз когда происходят их изменения (CSearchCustomRank::Add, CSearchCustomRank::Update и CSearchCustomRank::Delete). При индексации данных или после переиндексации данная процедура не требуется, т.к. правила сортировки учитываются в процессе построения поискового индекса.

Фактически данный метод сбрасывает все весовые коэффициенты. А для собственно применения правил необходимо воспользоваться пошаговой CSearchCustomRank::NextUpdate.

Параметры функции

Нет параметров.

Возвращаемые значения

В случае успешного выполнения возвращается объект CDBResult. В противном случае возвращается false.

См. также

  • CSearchCustomRank::NextUpdate
  • CSearchCustomRank::Add
  • CSearchCustomRank::Update
  • CSearchCustomRank::Delete


Update

CSearchCustomRank::Update

bool
CSearchCustomRank::Update(
    int ID,
    array arFields
);

Изменение правила сортировки.

После удаления всех требуемых правил необходимо пересчитать поисковый индекс методами CSearchCustomRank::StartUpdate и CSearchCustomRank::NextUpdate.

Параметры функции

Параметр | Описание
ID | Идентификатор правила.
arFields | Массив со значениями полей объекта правила сортировки.

Возвращаемые значения

В случае успешного добавления возвращается true. В противном случает возвращается false.

См. также

  • Поля объекта правила сортировки
  • CSearchCustomRank::StartUpdate
  • CSearchCustomRank::NextUpdate


Поля объекта CSearchCustomRank

CSearchCustomRank::Поля объекта CSearchCustomRank

Класс CSearchCustomRank использует следующие поля при работе с объектом "Правило сортировки".

Название поля | Описание | Тип | Обяз.
ID | Идентификатор правила. | int | Да.
SITE_ID | Сайт для элементов которого данное правило будет применяться. | char(2) | Да.
MODULE_ID | Идентификатор модуля для элементов которого данное правило будет применяться. | string(200) | Да.
PARAM1 | Первый параметр элемента. | text |
PARAM2 | Второй параметр элемента. | text |
ITEM_ID | Идентификатор элемента поискового индекса. | string(255) |
RANK | Вес. | int | Да.
APPLIED | Признак применения правила. | char(1) | Да.


Методы класса

Класс поддержки тегов.

Методы класса

Метод | Описание
GetList | Получение списка тегов элементов поискового индекса.


GetList

CSearchTags::GetList

CDBResult
CSearchTags::GetList(
    array arSelect = array(),
    array arFilter = array(),
    array arOrder = array(),
    int limit = 100
);

Получение списка тегов элементов поискового индекса.

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

Параметры функции

Параметр | Описание
arSelect Массив, содержащий поля для выборки.

Название поля может принимать значение:
  • NAME - тег;
  • CNT - частота тега, количество элементов поискового индекса содержащих этот тег;
  • DATE_CHANGE - максимальная дата модификации (в полном формате) элементов поискового индекса содержащих этот тег;
Не обязательный параметр. По умолчанию равен:
        array(
            "NAME",
            "CNT",
        )
arFilter Массив, содержащий фильтр в виде наборов "название поля"=>"значение фильтра".

Название поля может принимать значение:
  • SITE_ID - массив идентификаторов сайтов;
  • TAG - начало тега, будут возвращены все теги начинающиеся с этого значения;
  • MODULE_ID - идентификатор модуля;
  • PARAM1 - первый параметр элемента;
  • PARAM2 - второй параметр элемента;
Пример:
        array(
            "SITE_ID"=>array("s1"),
            "TAG"=>"We",
            "MODULE_ID"=>"iblock",
        )
arOrder Массив, содержащий признак сортировки в виде наборов "название поля"=>"направление".

Название поля может принимать значение:
  • NAME - тег;
  • CNT - частота тега, количество элементов поискового индекса содержащих этот тег;
  • DATE_CHANGE - максимальная дата модификации (в полном формате) элементов поискового индекса содержащих этот тег;
Направление сортировки может принимать значение:
  • ASC - по возрастанию;
  • DESC - по убыванию.
Не обязательный параметр. По умолчанию равен:
        array(
            "NAME"=>"ASC",
        )
limit | Ограничение количества тегов в результатах.

Возвращаемые значения

Возвращается результат запроса типа CDBResult. При выборке из результата методами класса CDBResult становятся доступны поля перечисленные в параметре arSelect.

См. также

  • Константы модуля поиска

Примеры использования

Получение списка десяти самых популярных тегов модуля информационных блоков.
<?
//подключение модуля поиска
if(CModule::IncludeModule('search'))
{
    $rsTags = CSearchTags::GetList(
        array(),
        array(
            "MODULE_ID" => "iblock",
        ),
        array(
            "CNT" => "DESC",
        ),
        10
    );
    while($arTag = $rsTags->Fetch())
        print_r($arTag);
}
?>


Методы класса

Класс поддержки Google Sitemap.

Методы класса

Метод | Описание
Create | Создание карты сайта в формате Google Sitemap.


Create

CSiteMap::Create

mixed

  CSiteMap::Create(
    string site_id,
    array max_execution_time,
    array NS,
    array arOptions = array()
);

Создание карты сайта в формате Google Sitemap.

Создание всегда происходит в пошаговом режиме.

Параметры функции

Параметр | Описание
site_id | Идентификатор сайта для которого будет создаваться карта.
max_execution_time | Элемент этого массива с индексом 0 задает максимальное время одно шага в секундах. А с индексом 1 - максимальное количество записей поискового индекса (рекомендовано задавать не более 5000).
NS | Начало шага. Передается результат, возвращенный предыдущим вызовом этой функции.
arOptions | Необязательный параметр. Если содержит ключ FORUM_TOPICS_ONLY со значением Y, то при установленном модуле форума в Sitemap попадут не все сообщения, а только те которые начинают новую тему на форуме. Причем дата модификации будет равна дате добавления последнего сообщения в данную тему.

Возвращаемое значение

  • false - в случае возникновения ошибки.
  • true - успешное создание карты.
  • array - требуется еще один вызов функции.

Примеры использования

Построение карты сайта из сценария вызываемого в cron'е.
<?
//подключение модуля поиска
if(CModule::IncludeModule('search'))
{
    //В этом массиве будут передаваться данные "прогресса". Он же послужит индикатором окончания исполнения.
    $NS=Array();
    //Задаем максимальную длительность одной итерации равной "бесконечности".
    $sm_max_execution_time = 0;
    //Это максимальное количество ссылок обрабатываемых за один шаг.
    //Установка слишком большого значения приведет к значительным потерям производительности.
    $sm_record_limit = 5000;
    do {
        $cSiteMap = new CSiteMap;
        //Выполняем итерацию создания,
        $NS = $cSiteMap->Create("ru", array($sm_max_execution_time, $sm_record_limit), $NS);
        //Пока карта сайта не будет создана.
    } while(is_array($NS));
}
?>


События модуля

Событие | Описание
BeforeIndex | Вызывается перед индексацией элемента.
OnSearch | Вызывается перед выполнением поисковых запросов.
OnReIndex | Вызывается при построении поискового индекса.
OnSearchGetFileContent | Вызывается при индексации статических файлов.
OnSearchGetURL | Вызывается при форматировании элемента в результатах поиска.


BeforeIndex

функция-обработчик(
    array arFields
);

Событие "BeforeIndex" вызывается перед индексацией элемента функцией CSearch::Index.

Параметры

Параметр Описание
arFields Массив следующего содержания:
  • MODULE_ID - идентификатор модуля (не изменится);
  • ITEM_ID - идентификатор элемента (не изменится);
  • PARAM1 - первый параметр элемента;
  • PARAM2 - второй параметр элемента;
  • DATE_FROM - дата начала активности элемента;
  • DATE_TO - дата окончания активности элемента;
  • TITLE - заголовок;
  • BODY - содержание;
  • TAGS - теги элемента;
  • SITE_ID - массив сайтов;
  • PERMISSIONS - массив идентификаторов групп пользователей которым разрешено чтение;
  • URL - адрес относительно корня сайта, по которому доступен данный элемент;

Данный обработчик может модифицировать поля параметра arFields и должен вернуть его как результат своей работы.

См. также

  • CSearch::Index
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("search", "BeforeIndex", Array("MyClass", "BeforeIndexHandler"));

class MyClass
{
    // создаем обработчик события "BeforeIndex"
    function BeforeIndexHandler($arFields)
    {
    if($arFields["MODULE_ID"] == "iblock" && $arFields["PARAM2"] == 33)
    {
        if(array_key_exists("BODY", $arFields))
        {
            $arFields["BODY"] .= " самые свежие новости";
        }
    }
    return $arFields;
    }
}
?>


OnReIndex

bool
функция-обработчик(
    array NS,
    string oCallback,
    string callback_method
);

Событие "OnReindex" вызывается во время переиндексации данных модуля функциями CSearch::ReindexModule или CSearch::ReIndexAll.

Параметры

Параметр | Описание
NS Массив в котором передается информация о начале текущего шага.
  • MODULE - идентификатор модуля;
  • ID - идентификатор элемента;
  • SITE_ID - массив сайтов;
oCallback | Объект модуля поиска для вызова метода индексации элемента.
callback_method | Метод объекта модуля поиска для индексации элемента.

См. также

  • CSearch::ReindexModule
  • CSearch::ReIndexAll
  • Обработка событий

Пример функции-обработчика:

<?

// регистрируем обработчик события "OnReindex" модуля "search"
RegisterModuleDependences("search", "OnReindex", "my_module", "CMyModule", "OnReindex");

// создаем в модуле my_module в классе CMyModule функцию-метод OnReindex
function OnReindex($NS, $oCallback, $callback_method)
{
    global $DB;

    $NS["ID"] = intval($NS["ID"]);
    if($NS["MODULE"]=="my_module" && $NS["ID"] > 0)
        $strWhere = "WHERE ID > ".$NS["ID"];
    else
        $strWhere = "";

    $strSql =
        "SELECT FT.ID, FT.TITLE, FT.MESSAGE, ".
        "  DATE_FORMAT(FT.POST_DATE, '%d.%m.%Y %H:%i:%s') as POST_DATE, FT.LID ".
        "FROM b_my_table FT ".
        $strWhere.
        " ORDER BY FT.ID";

    $db_res = $DB->Query($strSql);
    while ($res = $db_res->Fetch())
    {
        $Result = array(
            "ID" => $res["ID"],
            "SITE_ID" => array("s1"),
            "DATE_CHANGE" => $res["POST_DATE"],
            "URL" => "/my_module/index.php?ID=".$res["ID"],
            "PERMISSIONS" => array(2),
            "TITLE" => $res["TITLE"],
            "BODY" => $res["MESSAGE"],
        );
        $index_res = call_user_func(array($oCallback, $callback_method), $Result);
        if(!$index_res)
            return $Result["ID"];
    }
    return false;
}

// вызываем переиндексацию модуля
CSearch::ReIndexModule("my_module");

?>


OnSearch

string
функция-обработчик(
    string strQuery
);

Событие "OnSearch" вызывается перед выполнением поисковых запросов функцией CSearch::Search.

Параметры

Параметр | Описание
strQuery | Поисковая фраза. Если используется поиск по тегам, то в начале добавляется "tags:".

Возвращаемое значение

Функция обработчик может вернуть строку вида "параметр=значение" которая будет добавлена к ссылкам на найденные элементы. Используется модулем статистики для учета поисковых фраз внутреннего поисковика.

См. также

  • CSearch::Search
  • Обработка событий

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("search", "OnSearch", Array("MyClass", "OnSearchHandler"));

class MyClass
{
    // создаем обработчик события "BeforeIndex"
    function OnSearchHandler($strQuery)
    {
    if(strpos($strQuery, "tags:")!==false)
        return "tags_search=Y";
    else
        return "";
    }
}
?>


OnSearchGetFileContent

mixed
функция-обработчик(
    string absolute_path
);

Событие "OnSearchGetFileContent" вызывается во время переиндексации данных главного модуля CSearch::ReIndexFile.

Параметры

Параметр | Описание
absolute_path | Абсолютный путь к индексируемому файлу.

Возвращаемое значение

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

  • TITLE - заголовок (обязательное поле);
  • CONTENT - содержимое документа;
  • PROPERTIES - массив свойств документа (обязательное). Если свойств нет, то должен быть передан пустой массив. Содержимое элемента этого массива с именем указанным в настройках модуля как "Код свойства страницы в котором хранятся теги" будет занесен в теги;

Или может вернуть false, если не знает как файл должен быть обработан.

См. также

  • CSearch::ReIndexFile
  • Обработка событий

Пример функции-обработчика:

<?
//init.php

// индексируем сжатые gzip файлы.
// регистрируем обработчик события "OnSearchGetFileContent" модуля "search"
AddEventHandler("search", "OnSearchGetFileContent", array("CMyClass", "OnSearchGetFileContent_gzip"));

class CMyClass
{
    function OnSearchGetFileContent_gzip($absolute_path)
    {

        if(file_exists($absolute_path) && is_file($absolute_path) && substr($absolute_path, -3) == ".gz")
        {
            return array(
                "TITLE" => basename($absolute_path),
                "CONTENT" => implode("\n", gzfile($absolute_path)),
                "PROPERTIES" => array(),
            );
        }
        else
            return false;
    }
}

?>


OnSearchGetURL

string
функция-обработчик(
    array arFields
);

Событие "OnSearchGetURL" вызывается при форматировании элемента в результатах поиска из функции CSearch::Fetch и при построении Google Sitemap CSiteMap::Create.

Параметры

Параметр | Описание
arFields | Массив описывающий элемент поискового индекса.

Возвращаемое значение

Функция обработчик может применить форматирование к элементу URL. И должна его вернуть даже если форматирование не было применено.

См. также

  • CSearch::Fetch
  • CSiteMap::Create
  • Обработка событий

Пример функции-обработчика:

<?
//init.php

// регистрируем обработчик события "OnSearchGetURL" модуля "search"
AddEventHandler("search", "OnSearchGetURL", array("CMyClass", "OnSearchGetURL"));

class CMyClass
{
    function OnSearchGetURL($arFields)
    {
        $url = str_replace("#MY_SID#", md5(rand()), $arFields["URL"]);
        return $url;
    }
}

?>


Функции модуля

Функция | Описание
Stemming | Возвращает массив неизменных основ слов.
Stemming_default | Функция морфологического анализа текста применяемая по умолчанию.
Stemming_stop_default | Функция определения стоп слова применяемая по умолчанию.
Stemming_letter_default | Функция возвращает алфавит по умолчанию.
Tags_prepare | Возвращает массив тегов.
InputTags | Возвращает код html для ввода тегов с поддержкой автодополнения.


InputTags

string
InputTags(
    string sName,
    string sValue = '',
    array  arSites = array(),
    string sHTML = '',
    string sId = ''
);

Функция возвращает код html для ввода тегов с поддержкой автодополнения.

Параметры функции

Параметр | Описание
sName | Имя элемента управления html.
sValue | Начальное значение элемента управления. Необязательный параметр. По умолчанию - пустая строка.
arSites | Массив идентификаторов сайтов для которых будет строиться облако тегов. Необязательный параметр. По умолчанию берется текущий сайт.
sHTML | Произвольный html код, который будет вставлен в элемент управления. Необязательный параметр. По умолчанию - пустая строка.
sId | Идентификатор элемента управления (id). Необязательный параметр. По умолчанию идентификатор будет сгенерирован автоматически.

Возвращаемое значение

Функция возвращает html код элемента управления.

Примеры использования

<?
echo InputTags("TAGS", $arElement["TAGS"]);
?>


Stemming

array
stemming(
    string sText,
    string sLang="ru"
);

Функция производит морфологический анализ текста и возвращает массив неизменных основ слов.

Сначала ищется и подключается анализатор для заданного языка (параметр sLang):

  • Выполняется попытка подключения файла $_SERVER["DOCUMENT_ROOT"].BX_PERSONAL_ROOT."/php_interface/".$sLang."/search/stemming.php" и если в нем определена функция "stemming_"$sLang, то на этом поиск завершается.
  • Иначе выполняется попытка подключить анализатор из набора поставляемых с модулем поиска.
  • Если и эта попытка провалилась, то будет использован анализатор по умолчанию Stemming_default.

Также ожидается, что в одном из файлов определена функция поиска стоп слов - "stemming_stop_".$sLang. Если это не так, то для определения списка стоп слов будет использована функция по умолчанию Stemming_stop_default.

Далее текст приводится к верхнему регистру и разбивается на отдельные слова. Разбивка происходит путем удаления всех символов не входящих в алфавит языка. Алфавит задается следующим образом:

  • В расчет принимаются все символы возвращаемые функцией Stemming_letter_default;
  • К ним добавляются символы возвращаемые функцией "stemming_letter_".$sLang (если таковая определена);
  • А также символы входящие в соответствующую настройку модуля поиска.

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

Параметры функции

Параметр | Описание
sText | Содержит текст для морфологического анализа.
sLang | Идентификатор языка текста.

Возвращаемое значение

Функция возвращает ассоциативный массив ключами которого являются неизменные основы слов, а значениями частота их появления.

См. также

  • Stemming_default
  • Stemming_stop_default
  • Stemming_letter_default

Примеры использования

<?
$ar = stemming("Зебры любят зебр, а не слонов!", "ru");
print_r($ar);

//Будет напечатано:
/*
array(
    "ЗЕБР" => 2
    "ЛЮБ" => 1
    "СЛОН" => 1
)
*/
?>


Stemming_default

string
stemming_default(
    string sText
);

Функция морфологического анализа текста применяемая по умолчанию.

Параметры функции

Параметр | Описание
sText | Слово для морфологического анализа.

Возвращаемое значение

Функция возвращает sText.

См. также

  • Stemming


Stemming_letter_default

string
stemming_letter_default(
);

Функция возвращает алфавит по умолчанию.

Возвращаемое значение

Функция возвращает строку содержащую все символы латинского алфавита, а также цифры.

См. также

  • Stemming


Stemming_stop_default

bool
stemming_stop_default(
    string sWord
);

Функция определения стоп слова применяемая по умолчанию.

Параметры функции

Параметр | Описание
sWord | Неизменная основа слова.

Возвращаемое значение

Функция возвращает true если sWord не является стоп словом и false в противном случае. Определение происходит по длине слова. Стоп словами считаются все, имеющие длину меньше двух символов.

См. также

  • Stemming


Tags_prepare

array
tags_prepare(
    string sText,
    string site_id = false
);

Функция разбивает текст на отдельные теги и возвращает массив.

Сначала по site_id определяется язык. Далее текст разбивается на отдельные слова. Разбивка происходит путем удаления всех символов не входящих в алфавит языка (см. описание функции Stemming) за исключением символов подчеркивания, пробельных, точки и тире.

Параметры функции

Параметр | Описание
sText | Содержит текст для разбивки на теги.
site_id | Идентификатор сайта.

Возвращаемое значение

Функция возвращает массив тегов.

См. также

  • Stemming

Примеры использования

<?
$ar = tags_prepare("apache, Web 2.0, AJAX", "s1");
print_r($ar);

//Будет напечатано:
/*
array(
    "apache" => "apache"
    "Web 2.0" => "Web 2.0"
    "AJAX" => "AJAX"
)
*/
?>


Для разработчиков

В данном разделе представлена информация, необходимая для использования модуля.


Инсталляция

Для инсталляции модуля необходимо:
  1. Перейти на страницу "Модули" и нажать на кнопку "Установить" напротив модуля рекламы.
  2. После установки перейдите на страницу "Типы баннеров" и создайте необходимые вам типы баннеров.
  3. В HTML шаблоне сайта выделите области для показа баннеров того или иного типа. После этого, для вывода баннеров, воспользуйтесь следующей схемой:

    <?
// прежде чем начинается вывод страницы, необходимо получить HTML баннеров
if (CModule::IncludeModule("advertising")):
    $strBanner_top	= CAdvBanner::Show("TOP");
    $strBanner_bottom = CAdvBanner::Show("BOTTOM");
    $strBanner_left   = CAdvBanner::Show("LEFT");
endif;
?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head></head>
<body>
    <?
    // выводим HTML баннеров в заранее отведенных рекламных областях
    echo $strBanner_top;
    echo $strBanner_bottom;
    echo $strBanner_left;
    ?>
</body>
</html>
    Т.е., перед тем как начинается вывод HTML-контента, вы предварительно запоминаете HTML всех баннеров в PHP переменных, а уже затем используете их вывод в том месте дизайна, где вам необходимо.


Классы

CAdvBanner

Класс для работы с рекламными баннерами.

Методы класса

Метод | Описание
Set | Создает новый баннер, либо обновляет существующий.
GetList | Возвращает список баннеров с использованием фильтра.
GetByID | Возвращает один баннер по его ID.
Delete | Удаляет баннер.
Show | Выбирает в соответствии с весами (приоритетами) произвольный баннер по указанному типу, фиксирует факт показа баннера в базе данных и возвращает готовый HTML баннера (используется в шаблоне сайта для вывода баннеров).
Click | По заданному ID баннера фиксирует по нему клик в базе данных.
FixShow | Фиксирует в базе данных факт показа баннера.
GetRandom | Выбирает в соответствии с весами (приоритетами) произвольный баннер по указанному типу и возвращает массив частично его описывающий.
GetHTML | По заданному массиву описывающего баннер возвращает готовый HTML баннера.

CAdvContract

Класс для работы с рекламными контрактами.

Методы класса

Метод | Описание
Set | Создает новый рекламный контракт, либо обновляет существующий.
GetList | Возвращает список контрактов с использованием фильтра.
GetByID | Возвращает один контракт по его ID.
Delete | Удаляет контракт и все баннеру к нему привязанные.
GetUserPermissions | Возвращает массив прав заданного пользователя по всем контрактам.
GetContractPermissions | Возвращает массив прав всех пользователей по заданному контракту.
IsModuleAccess | Возвращает true, если текущий пользователь отвечает правам переданным в качестве параметров, иначе false.

CAdvType

Класс для работы с типами баннеров.

Методы класса

Метод | Описание
Set | Создает новый тип баннера, либо обновляет существующий.
GetList | Возвращает список типов с использованием фильтра.
GetByID | Возвращает один тип по заданному ID.
Delete | Удаляет тип и все баннеры к нему привязанные.


Класс CAdvBanner

CAdvBanner

Класс для работы с рекламными баннерами.

Методы класса

Метод | Описание
Set | Создает новый баннер, либо обновляет существующий.
GetList | Возвращает список баннеров с использованием фильтра.
GetByID | Возвращает один баннер по его ID.
Delete | Удаляет баннер.
Show | Выбирает в соответствии с весами (приоритетами) произвольный баннер по указанному типу, фиксирует факт показа баннера в базе данных и возращает готовый HTML баннера (используется в шаблоне сайта для вывода баннеров).
Click | По заданному ID баннера фиксирует по нему клик в базе данных.
FixShow | Фиксирует в базе данных факт показа баннера.
GetRandom | Выбирает в соответствии с весами (приоритетами) произвольный баннер по указанному типу и возращает массив частично его описывающий.
GetHTML | По заданному массиву описывающего баннер возвращает готовый HTML баннера.
GetKeywords | Функция возвращает весь или часть массива, хранящего ключевые слова, заданные для данной страницы.
ResetKeywords | Функция обнуляет массив (либо его части) ключевых слов баннеров заданных для страницы.
SetDesiredKeywords | Функция задает массив желательных ключевых слов для данной страницы.
SetRequiredKeywords | Функция задает массив обязательных ключевых слов для данной страницы.


Click

CAdvBanner::Click

CAdvBanner::Click

(
 int BANNER_ID,
 int CONTRACT_ID=false
);

Функция фиксирует клик по баннеру в базе данных.

Параметры функции

Параметры | Описание
BANNER_ID | ID баннера.
CONTRACT_ID | ID контракта которому принадлежит баннер; если задано false - ID контракта берется из параметров баннера.


Delete

CAdvBanner::Delete

boolean
CAdvBanner::Delete(
 int BANNER_ID,
 char(1) CHECK_RIGHTS="Y"
);

Функция удаляет баннер.

Параметры функции

Параметры | Описание
BANNER_ID | ID баннера.
CHECK_RIGHTS | "Y" - необходимо проверить право на удаление у текущего пользователя; "N" - прав проверять не надо.


FixShow

CAdvBanner::FixShow

CAdvBanner::FixShow

(
 array arrBanner
);

Функция фиксирует показ баннера в базе данных. Помимо этого, функция устанавливает cookie в котором фиксирует факт того что посетителю был показан баннер.

Параметры функции

Параметры Описание
arrBanner Массив, описывающий параметры баннера; в массиве достаточно и необходимо иметь наличие следующих индексов и соответствующих значений:
  • ID - ID баннера
  • CONTRACT_ID - ID контракта баннера


GetByID

CAdvBanner::GetByID

record set
CAdvBanner::GetByID(

 int BANNER_ID,

 char(1) CHECK_RIGHTS="Y"

);

Функция возвращает баннер по его ID.

Параметры функции

Параметры | Описание
BANNER_ID | ID баннера.
CHECK_RIGHTS | Параметр проверяет уровень доступа к модулю Реклама (администратор рекламы, рекламодатель и т.д.). Если параметр определён как "N", то считается, что текущий пользователь обладает административными правами доступа к модулю Реклама. Если параметр пропущен либо равен "Y", то функция проверяет уровень доступа к контракту, которому принадлежит баннер.

Пример массива, получаемого после Fetch результата, возвращенного данной функции

<?
Array
(
    [LAMP] => green
    [ID] => 88
    [CONTRACT_ID] => 1
    [TYPE_SID] => TOP
    [GROUP_SID] =>
    [STATUS_SID] => PUBLISHED
    [STATUS_COMMENTS] =>
    [NAME] =>
    [ACTIVE] => Y
    [LID] =>
    [WEIGHT] => 100
    [MAX_SHOW_COUNT] => 300
    [MAX_CLICK_COUNT] => 100
    [SHOW_COUNT] => 102
    [CLICK_COUNT] => 4
    [IMAGE_ID] => 1032
    [IMAGE_ALT] =>
    [URL] => http://www.1c-bitrix.ru?banner_param=#EVENT_GID#
    [URL_TARGET] => _parent
    [CODE] =>
<TABLE class=smalltext cellSpacing=0 cellPadding=0 width=145>
<TR>
<TD></TD>
<TD>
<DIV align=center>
<A class=righthead href="/ru/partners/partnership.php">Партнёрская программа</A>
</DIV></TD></TR>
<TR>
<TD></TD>
<TD height=8></TD></TR>
<TR>
<TD width=5></TD>
<TD vAlign=bottom>
<DIV align=center>
<A href="/ru/partners/partnership.php">
<IMG height=95 src="/images/advert/free.gif" width=100 border=0></A></DIV></TD></TR>
<TR>
<TD></TD>
<TD height=5></TD></TR>
<TR>
<TD></TD>
<TD>Разработчики сайтов и интеграторы получают:<BR>
<B><FONT class=smalltext>
<IMG height=8 src="/images/list_bullet.gif" width=8>
</FONT></B>
<FONT color=#ff5a31>скидки до 50%</FONT>
<BR><B><FONT class=smalltext>
<IMG height=8 src="/images/list_bullet.gif" width=8>
</FONT></B>
<FONT color=#ff5a31>бесплатную копиию</FONT></TD></TR>
<TR>
<TD></TD>
<TD height=5></TD></TR>
<TR>
<TD></TD>
<TD>
<DIV align=right>
<A class=bottomlinks
 href="/ru/partners/partnership.php">Подробнее</A>
 <IMG height=7 src="/images/main_button_more_3.gif" width=7>
 </DIV></TD></TR></TABLE>
    [CODE_TYPE] => html
    [STAT_EVENT_1] =>
    [STAT_EVENT_2] =>
    [STAT_EVENT_3] =>
    [FOR_NEW_GUEST] =>
    [COMMENTS] =>
    [CREATED_BY] => 2
    [MODIFIED_BY] => 2
    [CTR] => 3.92
    [DATE_LAST_SHOW] => 24.06.2004 17:39:50
    [DATE_LAST_CLICK] => 24.06.2004 14:47:53
    [DATE_SHOW_FROM] => 10.06.2004
    [DATE_SHOW_TO] => 07.07.2007
    [DATE_CREATE] => 10.06.2004 11:25:59
    [DATE_MODIFY] => 24.06.2004 14:33:56
    [CONTRACT_NAME] => Default
    [TYPE_NAME] => Top banner
)
?>


GetHTML

CAdvBanner::GetHTML

text
CAdvBanner::GetHTML(
 array arrBanner

);

Функция возвращает готовый HTML баннера.

Параметры функции

Параметры Описание
arrBanner Массив, описывающий параметры баннера; в массиве достаточно и необходимо иметь наличие следующих индексов и соответствующих значений:
  • IMAGE_ID - ID изображения баннера (если оно используется)
  • IMAGE_ALT - всплывающая подсказка на изображении (если оно используется)
  • URL - ссылка на изображении
  • URL_TARGET - значение параметра target для тэга <a>, влияет на поведение браузера при клике на изображение баннера
  • CODE - код баннера (если используется)
  • CODE_TYPE - тип кода баннера [text | html]


GetKeywords

CAdvBanner::GetKeywords

array
CAdvBanner::GetKeywords(
    varchar(255) TYPE_SID="",
    varchar(255) LOGIC="",
    char(1) EXACT_MATCH=""
);

Описание

Функция возвращает весь или часть массива, хранящего ключевые слова, заданные для данной страницы с помощью функций CAdvBanner::SetDesiredKeywords и CAdvBanner::SetRequiredKeywords.

Параметры функции

Параметр | Описание
TYPE_SID | Символьный идентификатор типа рекламы. Если задан, то возвращаются все ключевые слова по заданные для данного типа.
LOGIC | Идентификатор обязательности наличия ключевых слов в баннере. Возможные значения: "DESIRED" либо "REQUIRED". Если задан тип рекламы и данный параметр, то функция возвратит массив ключевых слов заданных для соответствующего типа и работающих по логике "ПРИСУТСТВИЕ ЖЕЛАТЕЛЬНО" либо "ПРИСУТСТВИЕ ОБЯЗАТЕЛЬНО".
EXACT_MATCH | Идентификатор типа поиска (прямое совпадение либо вхождение части слова). Возможные значения: "Y" либо "N". Если задан тип рекламы, идентификатор логики и данный параметр, то функция возвратит массив ключевых слов заданных для соответствующего типа, работающих по соответствующей логике, при этом слова в массиве будут заданы для поиска вхождения (EXACT_MATCH=N), либо для поиска прямого совпадения (EXACT_MATCH=Y).

Примеры использования

Array
(
    [LEFT] => Array
    (
        [REQUIRED] => Array
        (
            [Y] => Array
            (
                [0] => GeForce
                [1] => Radion
                [2] => AverTV
                [3] => Sony
            )
        )
    )

    [TOP] => Array
    (
        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => BMW
                [1] => top soft
                [2] => печать
            )
        )
    )
)

Слова, заданные в вышеописанном массиве, обеспечат следующую логику при выборке баннеров для показа на данной странице:

  1. Для типа "LEFT" с наивысшим приоритетом будут показаны только те баннеры, у которых будут найдены точные совпадения со всеми ключевыми словами "GeForce", "Radion", "AverTV", "Sony".
  2. Для типа "TOP" будут показаны с наивысшим приоритетом только те баннеры, у которых хотя бы одно ключевое слово или его часть будет найдено в списке "BMW", "top soft", "печать".

Если на странице заданы ключевые слова, то возможны две ситуация когда:

  1. Не будет найден ни один баннер, подходящий под условия ключевых фраз. В этом случае будут показываться все баннеры, у которых список ключевых фраз пуст, в соответствии с приоритетом указанным в их настройках.
  2. Будет найдено несколько баннеров, удовлетворяющих условию ключевых фраз. В этом случае, среди этих баннеров будет выбран один в соответствии с приоритетом, указанным в его настройках, а также в соответствии с приоритетом, указанным в настройках контракта, к которому принадлежит этот баннер.

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


GetList

CAdvBanner::GetList

record set
CAdvBanner::GetList(
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered,

 char(1) CHECK_RIGHTS="Y"
);

Функция предназначена для получения списка баннеров.

Параметры функции

Параметры | Описание
by Идентификатор позволяющий задать имя поля для сортировки. Допустимы следующие значения:
  • s_id - по ID
  • s_lamp - по индикатору
  • s_name - по имени баннера
  • s_type_sid - по типу баннера
  • s_contract_id - по ID контракта
  • s_group_sid - по имени группы
  • s_show_count - по количеству показов
  • s_max_show_count - по максимальному количеству показов
  • s_date_last_show - по дате последнего показа
  • s_click_count - по количеству кликов на баннер
  • s_max_click_count - по максимальному количеству кликов
  • s_date_last_click - по дате последнего клика
  • s_active - по флагу активности
  • s_weight - по весу баннера
  • s_status_sid - по статусу баннера
  • s_date_show_from - по дате начала показов
  • s_date_show_to - по дате окончания показов
  • s_ctr - по CTR баннера
order Порядок сортировки. Допустимы следующие значения:
  • desc - по убыванию (значение по умолчанию)
  • asc - по возрастанию
arFilter Массив для фильтрации значений. В массиве допустимы следующие индексы:
  • ID - ID баннера (допускается сложная логика)
  • ID_EXACT_MATCH - "Y" - при фильтрации по ID баннера будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • LAMP - значение индикатора: "red", "green"
  • LANG - двухсимвольный идентификатор языковой части сайта в которой будет показываться баннер
  • SHOW_COUNT_1 - левая часть интервала для числа показов
  • SHOW_COUNT_2 - правая часть интервала для числа показов
  • CLICK_COUNT_1 - левая часть интервала для числа кликов
  • CLICK_COUNT_2 - правая часть интервала для числа кликов
  • CTR_1 - левая часть интервала для CTR баннера
  • CTR_2 - правая часть интервала для CTR баннера
  • GROUP - имя группы баннера (допускается сложная логика)
  • GROUP_EXACT_MATCH - "Y" - при фильтрации по имени группы будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • STATUS_SID - символьный код статуса (допускается сложная логика); символьный код статуса может принимать следующие значения:
    • PUBLISHED - баннер подтвержден и опубликован
    • READY - баннер на рассмотрении
    • REJECTED - баннер отклонен
  • CONTRACT_ID - ID контракта (допускается сложная логика)
  • CONTRACT_ID_EXACT_MATCH - "Y" - при фильтрации по ID контракта будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • CONTRACT - ID, имя, описание контракта (допускается сложная логика)
  • CONTRACT_EXACT_MATCH - "Y" - при фильтрации по ID, имени, описанию контракта будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • TYPE_SID - символьный код типа баннера (допускается сложная логика)
  • TYPE_SID_EXACT_MATCH - "Y" - при фильтрации по символьному коду типа баннера будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • NAME - имя баннера (допускается сложная логика)
  • NAME_EXACT_MATCH - "Y" - при фильтрации по имени баннера будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • CODE - код баннера (допускается сложная логика)
  • CODE_EXACT_MATCH - "Y" - при фильтрации по коду баннера будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • COMMENTS - комментарий к баннеру (допускается сложная логика)
  • COMMENTS_EXACT_MATCH - "Y" - при фильтрации по комментарию к баннеру будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
is_filtered | Переменная возвращающая true в том случае если список баннеров отфильтрован по какому либо критерию; либо false в противном случае.
CHECK_RIGHTS | Параметр проверяет уровень доступа к модулю Реклама (администратор рекламы, рекламодатель и т.д.). Если параметр определён как "N", то считается, что текущий пользователь обладает административными правами доступа к модулю Реклама. Если параметр пропущен либо равен "Y", то функция проверяет уровень доступа к модулю.

Примеры использования

<?
$FilterArr = Array(
    "find_id",
    "find_id_exact_match",
    "find_lamp",
    "find_lang",
    "find_show_count_1",
    "find_show_count_2",
    "find_click_count_1",
    "find_click_count_2",
    "find_ctr_1",
    "find_ctr_2",
    "find_contract_id",
    "find_contract",
    "find_contract_exact_match",
    "find_group",
    "find_group_exact_match",
    "find_status_sid",
    "find_type_sid",
    "find_type",
    "find_type_exact_match",
    "find_name",
    "find_name_exact_match",
    "find_code",
    "find_code_exact_match",
    "find_comments",
    "find_comments_exact_match"
    );
if (strlen($set_filter)>0) InitFilterEx($FilterArr,"ADV_BANNER_LIST","set");
else InitFilterEx($FilterArr,"ADV_BANNER_LIST","get");
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"ADV_BANNER_LIST");
InitBVar($find_id_exact_match);
InitBVar($find_status_exact_match);
InitBVar($find_group_exact_match);
InitBVar($find_contract_exact_match);
InitBVar($find_type_exact_match);
InitBVar($find_name_exact_match);
InitBVar($find_code_exact_match);
InitBVar($find_comments_exact_match);
$arFilter = Array(
    "ID"					=> $find_id,
    "ID_EXACT_MATCH"		=> $find_id_exact_match,
    "LAMP"				  => $find_lamp,
    "LANG"				  => $find_lang,
    "SHOW_COUNT_1"		  => $find_show_count_1,
    "SHOW_COUNT_2"		  => $find_show_count_2,
    "CLICK_COUNT_1"		 => $find_click_count_1,
    "CLICK_COUNT_2"		 => $find_click_count_2,
    "CTR_1"				 => $find_ctr_1,
    "CTR_2"				 => $find_ctr_2,
    "GROUP"				 => $find_group,
    "GROUP_EXACT_MATCH"	 => $find_group_exact_match,
    "STATUS_SID"			=> $find_status_sid,
    "CONTRACT_ID"		   => $find_contract_id,
    "CONTRACT"			  => $find_contract,
    "CONTRACT_EXACT_MATCH"  => $find_contract_exact_match,
    "TYPE_SID"			  => $find_type_sid,
    "TYPE"				  => $find_type,
    "TYPE_EXACT_MATCH"	  => $find_type_exact_match,
    "NAME"				  => $find_name,
    "NAME_EXACT_MATCH"	  => $find_name_exact_match,
    "CODE"				  => $find_code,
    "CODE_EXACT_MATCH"	  => $find_code_exact_match,
    "COMMENTS"			  => $find_comments,
    "COMMENTS_EXACT_MATCH"  => $find_comments_exact_match
    );
$rsBanners = CAdvBanner::GetList($by, $order, $arFilter, $is_filtered, "N");
$rsBanners->NavStart(20);
$rsBanners->NavPrint("Баннеры");
while($arBanner = $rsBanners->NavNext(true, "f_"))
{
    echo "<pre>"; print_r($arBanner); echo "</pre>";
}
?>

Пример массива получаемого после Fetch одной строки выборки данной функции

<?
Array
(
    [LAMP] => green
    [ID] => 88
    [CONTRACT_ID] => 1
    [TYPE_SID] => TOP
    [GROUP_SID] =>
    [STATUS_SID] => PUBLISHED
    [STATUS_COMMENTS] =>
    [NAME] =>
    [ACTIVE] => Y
    [LID] =>
    [WEIGHT] => 100
    [MAX_SHOW_COUNT] => 300
    [MAX_CLICK_COUNT] => 100
    [SHOW_COUNT] => 102
    [CLICK_COUNT] => 4
    [IMAGE_ID] => 1032
    [IMAGE_ALT] =>
    [URL] => http://www.1c-bitrix.ru?banner_param=#EVENT_GID#
    [URL_TARGET] => _parent
    [CODE] => <TABLE class=smalltext cellSpacing=0 cellPadding=0 width=145>
<TR>
<TD></TD>
<TD>
<DIV align=center>
<A class=righthead href="/ru/partners/partnership.php">Партнёрская программа</A>
</DIV>
</TD></TR>
<TR>
<TD></TD>
<TD height=8></TD></TR>
<TR>
<TD width=5></TD>
<TD vAlign=bottom>
<DIV align=center>
<A href="/ru/partners/partnership.php">
<IMG height=95 src="/images/advert/free.gif" width=100 border=0></A>
</DIV></TD></TR>
<TR>
<TD></TD>
<TD height=5></TD></TR>
<TR>
<TD></TD>
<TD>Разработчики сайтов и интеграторы получают:<BR>
<B><FONT class=smalltext>
<IMG height=8 src="/images/list_bullet.gif" width=8>
</FONT></B>
<FONT color=#ff5a31>скидки до 50%</FONT> <BR>
<B><FONT class=smalltext>
<IMG height=8 src="/images/list_bullet.gif" width=8>
</FONT></B>
<FONT color=#ff5a31>бесплатную копиию</FONT>
</TD></TR>
<TR>
<TD></TD>
<TD height=5></TD></TR>
<TR>
<TD></TD>
<TD>
<DIV align=right>
<A class=bottomlinks href="/ru/partners/partnership.php">Подробнее</A>
<IMG height=7 src="/images/main_button_more_3.gif" width=7>
</DIV></TD></TR></TABLE>
    [CODE_TYPE] => html
    [STAT_EVENT_1] =>
    [STAT_EVENT_2] =>
    [STAT_EVENT_3] =>
    [FOR_NEW_GUEST] =>
    [COMMENTS] =>
    [CREATED_BY] => 2
    [MODIFIED_BY] => 2
    [CTR] => 3.92
    [DATE_LAST_SHOW] => 24.06.2004 17:39:50
    [DATE_LAST_CLICK] => 24.06.2004 14:47:53
    [DATE_SHOW_FROM] => 10.06.2004
    [DATE_SHOW_TO] => 07.07.2007
    [DATE_CREATE] => 10.06.2004 11:25:59
    [DATE_MODIFY] => 24.06.2004 14:33:56
    [CONTRACT_NAME] => Default
    [TYPE_NAME] => Top banner
)
?>


GetRandom

CAdvBanner::GetRandom

array
CAdvBanner::GetRandom(
 varchar(255) TYPE_SID

);

Функция выбирает в соответствии с весами (приоритетами) произвольный баннер по указанному типу и возвращает массив частично его описывающий.

Параметры функции

Параметры | Описание
TYPE_SID | Символьный идентификатор типа.

Пример массива, возвращаемого функцией

Array
(
    [ID] => 94
    [CONTRACT_ID] => 3
    [TYPE_SID] => LEFT2
    [STATUS_SID] => PUBLISHED
    [STATUS_COMMENTS] =>
    [NAME] => Баннер
    [GROUP_SID] => группа 1
    [ACTIVE] => Y
    [LID] =>
    [WEIGHT] => 2000
    [MAX_SHOW_COUNT] => 1000
    [MAX_CLICK_COUNT] => 50
    [SHOW_COUNT] => 67
    [CLICK_COUNT] => 4
    [DATE_LAST_SHOW] => 2004-06-24 14:47:47
    [DATE_LAST_CLICK] => 2004-06-22 11:33:18
    [DATE_SHOW_FROM] => 2004-01-07 00:00:00
    [DATE_SHOW_TO] => 2004-07-07 23:59:59
    [IMAGE_ID] => 1028
    [IMAGE_ALT] => текст подсказки
    [URL] => http://www.1c-bitrix.ru
    [URL_TARGET] => _parent
    [CODE] => <TABLE class=smalltext cellSpacing=0 cellPadding=0 width=145>
<TR>
<TD></TD>
<TD>
<DIV align=center>
<A class=righthead href="/ru/partners/partnership.php">Партнёрская программа</A>
</DIV></TD></TR>
<TR>
<TD></TD>
<TD height=8></TD></TR>
<TR>
<TD width=5></TD>
<TD vAlign=bottom>
<DIV align=center><A href="/ru/partners/partnership.php">
<IMG height=95 src="/images/advert/free.gif" width=100 border=0>
</A></DIV></TD></TR>
<TR>
<TD></TD>
<TD height=5></TD></TR>
<TR>
<TD></TD>
<TD>Разработчики сайтов и интеграторы получают:<BR><B>
<FONT class=smalltext><IMG height=8 src="/images/list_bullet.gif" width=8></FONT></B>
<FONT color=#ff5a31>скидки до 50%</FONT> <BR><B>
<FONT class=smalltext><IMG height=8 src="/images/list_bullet.gif" width=8></FONT></B>
<FONT color=#ff5a31>бесплатную копиию</FONT></TD></TR>
<TR>
<TD></TD>
<TD height=5></TD></TR>
<TR>
<TD></TD>
<TD>
<DIV align=right>
<A class=bottomlinks href="/ru/partners/partnership.php">Подробнее</A>
<IMG height=7 src="/images/main_button_more_3.gif" width=7>
</DIV></TD></TR></TABLE>
    [CODE_TYPE] => html
    [STAT_EVENT_1] =>
    [STAT_EVENT_2] =>
    [STAT_EVENT_3] =>
    [FOR_NEW_GUEST] =>
    [COMMENTS] =>
    [DATE_CREATE] => 2004-06-15 15:13:41
    [CREATED_BY] => 342
    [DATE_MODIFY] => 2004-06-22 19:31:50
    [MODIFIED_BY] => 343
)


ResetKeywords

CAdvBanner::ResetKeywords

array
CAdvBanner::ResetKeywords(
    varchar(255) TYPE_SID="",
    varchar(255) LOGIC="",
    char(1) EXACT_MATCH=""
);

Описание

Функция обнуляет массив (либо его части) ключевых слов баннеров заданных для страницы.

Параметры функции

Параметр | Описание
TYPE_SID | Символьный идентификатор типа рекламы. Если задан, то обнуляется массив ключевых слов заданных для данного типа.
LOGIC | Идентификатор обязательности наличия ключевых слов в баннере. Возможные значения: "DESIRED" либо "REQUIRED". Если задан тип рекламы и данный параметр, то функция обнулит массив ключевых слов заданных для соответствующего типа и работающих по логике "ПРИСУТСТВИЕ ЖЕЛАТЕЛЬНО" либо "ПРИСУТСТВИЕ ОБЯЗАТЕЛЬНО".
EXACT_MATCH | Идентификатор типа поиска (прямое совпадение либо вхождение части слова). Возможные значения: "Y" либо "N". Если задан тип рекламы, идентификатор логики поиска баннеров и данный параметр, то обнуляется массив данного параметра, данной логики поиска и данного типа рекламы.

Примеры использования

Пример массива ключевых слов баннеров

Array
(
    [LEFT] => Array
    (
        [REQUIRED] => Array
        (
            [Y] => Array
            (
                [0] => GeForce
                [1] => Radion
            )
            [N] => Array
            (
                [0] => video
                [1] => directx
            )
        )

        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => game
                [1] => 3D
            )
        )
    )

    [] => Array
    (
        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => GeForce
                [1] => Radion
                [2] => Sony
            )
        )
    )

    [TOP] => Array
    (
        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => BMW
                [1] => top soft
                [2] => печать
            )
        )
    )
)

Если для вышеописанного массива вызвать функцию CAdvBanner::ResetKeywords("LEFT","REQUIRED","N"), то массив ключевых слов будет выглядеть следующим образом:

Array
(
    [LEFT] => Array
    (
        [REQUIRED] => Array
        (
            [Y] => Array
            (
                [0] => GeForce
                [1] => Radion
            )
        )

        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => game
                [1] => 3D
            )
        )
    )

    [] => Array
    (
        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => GeForce
                [1] => Radion
                [2] => Sony
            )
        )
    )

    [TOP] => Array
    (
        [DESIRED] => Array
        (
            [N] => Array
            (
                [0] => BMW
                [1] => top soft
                [2] => печать
            )
        )
    )
)


Set

CAdvBanner::Set

int
CAdvBanner::Set(
 array arFields,
 int BANNER_ID="",
 char(1) CHECK_RIGHTS="Y"

);

Функция создает новый баннер, либо модифицирует существующий в случае указания во втором параметре ID баннера. Возвращает ID созданного баннера, либо ID модифицированного баннера.

Параметры функции

Параметры | Описание
arFields Массив параметров баннера. В массиве допустимы следующие индексы:
  • CONTRACT_ID - ID контракта (обязательный параметр для нового баннера)
  • TYPE_SID - символьный идентификатор типа баннера
  • STATUS_SID - символьный идентификатор статуса баннера, допустимы следующие значения:
    • PUBLISHED - баннер подтвержден и опубликован
    • READY - баннер на рассмотрении
    • REJECTED - баннер отклонен
  • STATUS_COMMENTS - комментарий к статусу
  • NAME - имя баннера
  • GROUP_SID - имя группы баннера
  • ACTIVE - флаг активности: "Y" - баннер активен; "N" - баннер не активен;
  • arrSITE - код языковой части сайта в которой будет показываться баннер
  • WEIGHT - вес (приоритет) баннера
  • MAX_SHOW_COUNT - максимальное количество показов баннера
  • RESET_SHOW_COUNT - флаг необходимости сбросить счетчик показов у баннера (автоматически будет уменьшен счетчик показов у всего контракта)
  • MAX_CLICK_COUNT - максимальное количество кликов на баннер
  • RESET_CLICK_COUNT - флаг необходимости сбросить счетчик кликов на баннер (автоматически будет уменьшен счетчик кликов у всего контракта)
  • DATE_SHOW_FROM - дата начала показов баннера
  • DATE_SHOW_TO - дата окончания показов баннера
  • arrIMAGE_ID - массив описывающий загружаемое изображение; в массиве допустимые следующие индексы:
    • name - исходное имя загружаемого файла
    • type - тип загружаемого файла (например: "image/gif")
    • tmp_name - имя временного файла на сервере
    • error - код ошибки ("0" - нет ошибок)
    • size - размер загружаемого файла
    • MODULE_ID - идентификатор модуля ("advertising")
  • IMAGE_ALT - текст всплывающей подсказки к изображению
  • URL - ссылка на изображении. В данном поле можно использовать шаблон #EVENT_GID#, который при клике на баннер будет заменен на идентификатор посетителя который используется в модуле статистики при загрузке событий.
  • URL_TARGET - в данном поле вы можете задать строку влияющее на поведение браузера при нажатии на ссылку-изображение:
    • _self - открыть в текущем окне
    • _blank - открыть в новом окне
    • _parent - открыть в своем фреймсете
    • _top - во всем текущем окне браузера
  • CODE - код баннера
  • CODE_TYPE - тип кода баннера: "text" - код баннера будет выведен как текст; "html" - код баннера будет выведен как HTML;
  • STAT_EVENT_1 - идентификатор типа события - " event1" (события регистрируются в модуле статистики)
  • STAT_EVENT_2 - идентификатор типа события - " event2"
  • STAT_EVENT_3 - дополнительный параметр события - " event3". В коде баннера, event1, event2, event3 можно использовать следующие шаблоны:
    • #BANNER_NAME# - имя баннера
    • #BANNER_ID# - ID баннера
    • #CONTRACT_ID# - ID контракта
    • #TYPE_SID# - тип баннера
  • FOR_NEW_GUEST - "Y" - показывать баннер только для новых посетителей; "N" - показывать баннер только для посетителей уже посещавших сайт
  • COMMENTS - комментарий к баннеру
  • arrSHOW_PAGE - массив страниц и разделов сайта на которых должен показываться баннер
  • arrNOT_SHOW_PAGE - массив страниц и разделов сайта на которых не должен показываться баннер
  • arrCOUNTRY - массив двухсимвольных кодов стран посетителям которых необходимо показывать баннер
  • arrSTAT_ADV - массив идентификаторов рекламных кампаний посетителям которых необходимо показывать баннер (как на прямых заходах, так и на возвратах)
  • arrWEEKDAY - массив описывающий время и дни недели для показа баннера; в массиве допустимы следующие индексы:
    • SUNDAY - массив часов в которые надо показывать баннер в воскресенье (0-23)
    • MONDAY - -||- в понедельник
    • TUESDAY - -||- во вторник
    • WEDNESDAY - -||- в среду
    • THURSDAY - -||- в четверг
    • FRIDAY - -||- в пятницу
    • SATURDAY - -||- в субботу
  • SEND_EMAIL - флаг необходимости отослать EMail владельцам контракта при смене статуса баннера; письмо отсылается по шаблону "Изменился статус баннера"
BANNER_ID | ID баннера, если не указывать - создаётся новый баннер.
CHECK_RIGHTS | Флаг необходимости проверки прав текущего пользователя: "Y" - необходимо проверить права текущего пользователя; "N" - баннер создавать и модифицировать независимо от прав текущего пользователя.

Примеры использования

Пример кода добавляющего новый баннер, либо модифицирующий существующий:
<?
if ((strlen($save)>0 || strlen($apply)>0) && $REQUEST_METHOD=="POST")
{
    InitBVar($SEND_EMAIL);
    $arrIMAGE_ID = $HTTP_POST_FILES["IMAGE_ID"];
    $arrIMAGE_ID["MODULE_ID"] = "advertising";
    $arrIMAGE_ID["del"] = ${"IMAGE_ID_del"};
    $arrWEEKDAY = array(
        "SUNDAY"	=> $arrSUNDAY,
        "MONDAY"	=> $arrMONDAY,
        "TUESDAY"   => $arrTUESDAY,
        "WEDNESDAY" => $arrWEDNESDAY,
        "THURSDAY"  => $arrTHURSDAY,
        "FRIDAY"	=> $arrFRIDAY,
        "SATURDAY"  => $arrSATURDAY
        );
    if ($action=="view" && $isAbsAdmin)
    {
         $arFields = array(
            "STATUS_SID"		=> $STATUS_SID,
            "STATUS_COMMENTS"   => $STATUS_COMMENTS
            );
    }
    else
    {
         $arFields = array(
            "CONTRACT_ID"	   => $CONTRACT_ID,
            "TYPE_SID"		  => $TYPE_SID,
            "STATUS_SID"		=> $STATUS_SID,
            "STATUS_COMMENTS"   => $STATUS_COMMENTS,
            "NAME"			  => $NAME,
            "GROUP_SID"		 => $GROUP_SID,
            "ACTIVE"		=> $ACTIVE,
            "arrSITE"		=> $arrSITE,
            "WEIGHT"		=> $WEIGHT,
            "MAX_SHOW_COUNT"	=> $MAX_SHOW_COUNT,
            "RESET_SHOW_COUNT"  => $RESET_SHOW_COUNT,
            "MAX_CLICK_COUNT"   => $MAX_CLICK_COUNT,
            "RESET_CLICK_COUNT" => $RESET_CLICK_COUNT,
            "DATE_SHOW_FROM"	=> $DATE_SHOW_FROM,
            "DATE_SHOW_TO"	  => $DATE_SHOW_TO,
            "arrIMAGE_ID"	   => $arrIMAGE_ID,
            "IMAGE_ALT"		 => $IMAGE_ALT,
            "URL"			   => $URL,
            "URL_TARGET"		=> $URL_TARGET,
            "CODE"			  => $CODE,
            "CODE_TYPE"		 => $CODE_TYPE,
            "STAT_EVENT_1"	  => $STAT_EVENT_1,
            "STAT_EVENT_2"	  => $STAT_EVENT_2,
            "STAT_EVENT_3"	  => $STAT_EVENT_3,
            "FOR_NEW_GUEST"	 => $FOR_NEW_GUEST,
            "COMMENTS"		  => $COMMENTS,
            "arrSHOW_PAGE"	  => split("[\n\r]",$SHOW_PAGE),
            "arrNOT_SHOW_PAGE"  => split("[\n\r]",$NOT_SHOW_PAGE),
            "arrCOUNTRY"		=> $arrCOUNTRY,
            "arrSTAT_ADV"	   => $arrSTAT_ADV,
            "arrWEEKDAY"		=> $arrWEEKDAY,
            "SEND_EMAIL"		=> $SEND_EMAIL
            );
    }
    if ($ID = CAdvBanner::Set($arFields, $ID))
    {
        if (strlen($strError) <= 0)
        {
             if (strlen($save) > 0)
                 LocalRedirect("adv_banner_list.php?lang=".LANG);
             else
                 LocalRedirect("adv_banner_edit.php?ID=".$ID."&CONTRACT_ID=".$CONTRACT_ID."&lang=".LANG."&action=".$action);
        }
    }
    $DB->PrepareFields("b_adv_banner");
}
?>


SetDesiredKeywords

CAdvBanner::SetDesiredKeywords

CAdvBanner::SetDesiredKeywords(
    mixed keywords,
    varchar(255) TYPE_SID=""
);

Описание

Функция задает массив желательных ключевых слов для данной страницы. Если одно из ключевых слов баннера (либо контракта, к которому принадлежит баннер) будет найдено в данном массиве, то этот баннер будет показываться на данной странице с более высоким приоритетом. В случае, если не будет найден ни один баннер, отвечающий установленным ключевым словам, то баннер для показа будет выбран из тех, для которых вообще не установлено ни одно ключевое слово.

Параметры функции

Параметр | Описание
keywords | Ключевые слова. Конструкции, которые можно передавать в этом параметре, описаны в примечаниях ниже.
TYPE_SID | Идентификатор типа. В данном параметре вы можете указать тип рекламы для которой будут заданы ключевые слова. Если данный параметр оставить пустым, то ключевые слова будут заданы для всех типов.

Примеры использования

Пример использования на конкретной странице:

<?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("advertising"))
{
     // желательные ключевые слова с точным совпадением
     $arrKeywords = array();
     $arrKeywords[] = array("EXACT_MATCH" => "Y", "KEYWORD" => "GeForce");
     $arrKeywords[] = array("EXACT_MATCH" => "Y", "KEYWORD" => "video");
     CAdvBanner::SetDesiredKeywords($arrKeywords, "LEFT");

     // желательные ключевые слова с вхождением
     CAdvBanner::SetDesiredKeywords(array("Ford", "BMW", "Lada"), "RIGHT");
}

$APPLICATION->SetTitle("Заголовок страницы");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");

// тело страницы
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>

Пример использования для всего сайта, в prolog_after.php:

<?
if (CModule::IncludeModule("advertising"))
{
    CAdvBanner::SetDesiredKeywords($APPLICATION->GetPageProperty("keywords"));
}
?>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
</head>
<body>
...

Примечания

Конструкции, которые можно передавать в параметре keywords, включают.

  1. Массив, состоящий из массивов, каждый из которых имеет ключи:
    • EXACT_MATCH - указывает как искать слово - точное совпадение (Y), либо вхождение (N).
    • KEYWORDS - ключевое слово.
    Пример:

    Array
(
    [0] => Array
    (
        [EXACT_MATCH] => Y
        [KEYWORD] => GeForce
    )

    [1] => Array
    (
        [EXACT_MATCH] => Y
        [KEYWORD] => Radeon
    )
)
  2. Массив, элементами которого будут являтся сами ключевые слова.

    Пример:

    Array
(
    [0] => GeForce
    [1] => Radion
    [2] => Sony
)
    В этом варианте по умолчанию в дальнейшем будет искаться вхождение ключевых слов баннера в данные ключевые слова (либо наоборот).
  3. Список ключевых слов, разделенных запятой.

    Пример:

    "GeForce, Radion, Sony"
    В этом варианте по умолчанию в дальнейшем будет также искаться вхождение ключевых слов баннера в данные ключевые слова (либо наоборот).


SetRequiredKeywords

CAdvBanner::SetRequiredKeywords

CAdvBanner::SetRequiredKeywords(
    mixed keywords,
    varchar(255) TYPE_SID=""
);

Описание

Функция задает массив обязательных ключевых слов для данной страницы. Баннер будет показан на данной странице с наивысшим приоритетом только в том случае, если все слова из заданного с помощью данной функции массива, будут найдены в ключевых словах баннера (либо контракта к которому принадлежит баннер). В случае, если не будет найден ни один баннер отвечающий установленным ключевым словам, то баннер для показа будет выбран из тех, для которых вообще не установлено ни одно ключевое слово.

Параметры функции

Параметр | Описание
keywords | Ключевые слова. Конструкции, которые можно передавать в этом параметре, описаны в примечаниях ниже.
TYPE_SID | Идентификатор типа. В данном параметре можно указать тип рекламы, для которой будут заданы ключевые слова. Если данный параметр оставить пустым, то ключевые слова будут заданы для всех типов.

Примеры использования

Пример использования на конкретной странице:

<?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
if (CModule::IncludeModule("advertising"))
{
    // обязательные ключевые слова с точным совпадением
    $arrKeywords = array();
    $arrKeywords[] = array("EXACT_MATCH" => "Y", "KEYWORD" => "GeForce");
    $arrKeywords[] = array("EXACT_MATCH" => "Y", "KEYWORD" => "video");
    CAdvBanner::SetRequiredKeywords($arrKeywords, "LEFT");

    // обязательные ключевые слова с вхождением
    CAdvBanner::SetRequiredKeywords(array("Ford", "BMW", "Lada"), "RIGHT");
}

$APPLICATION->SetTitle("Заголовок страницы");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_after.php");

// тело страницы
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/epilog.php");
?>

Пример использования для всего сайта, в prolog_after.php:

<?
if (CModule::IncludeModule("advertising"))
{
    CAdvBanner::SetRequiredKeywords($APPLICATION->GetProperty("keywords"));
}

?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
</head>
<body>
...

Если на странице заданы ключевые слова, то возможны две ситуация:

  1. Не будет найден ни один баннер подходящий под условия ключевых фраз. В этом случае будут показываться все баннеры, у которых список ключевых фраз пуст, в соответствии с приоритетом указанным в их настройках.
  2. Будет найдено несколько баннеров удовлетворяющих условию ключевых фраз. В этом случае среди этих баннеров будет выбран один в соответствии с приоритетом, указанным в его настройках, а также в соответствии с приоритетом указанным в настройках контракта к которому принадлежит этот баннер.

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

Примечания

Конструкции, которые можно передавать в параметре keywords, включают.

  1. Массив, состоящий из массивов, каждый из которых имеет ключи:
    • EXACT_MATCH - указывает как искать слово - точное совпадение (Y), либо вхождение (N).
    • KEYWORDS - ключевое слово.
    Пример:

    Array
(
    [0] => Array
    (
        [EXACT_MATCH] => Y
        [KEYWORD] => GeForce
    )

    [1] => Array
    (
        [EXACT_MATCH] => Y
        [KEYWORD] => Radeon
    )
)
  2. Массив, элементами которого будут являтся сами ключевые слова.

    Пример:

    Array
(
    [0] => GeForce
    [1] => Radion
    [2] => Sony
)
    В этом варианте по умолчанию в дальнейшем будет искаться вхождение ключевых слов баннера в данные ключевые слова (либо наоборот).
  3. Список ключевых слов, разделенных запятой.

    Пример:

    "GeForce, Radion, Sony"
    В этом варианте по умолчанию в дальнейшем будет также искаться вхождение ключевых слов баннера в данные ключевые слова (либо наоборот).


Show

CAdvBanner::Show

text
CAdvBanner::Show(
 varchar(255) TYPE_SID

);

Функция выбирает в соответствии с весами (приоритетами) произвольный баннер по указанному типу, фиксирует факт показа баннера в базе данных и возвращает готовый HTML баннера (используется в шаблоне сайта для вывода баннеров).

Параметры функции

Параметры | Описание
TYPE_SID | Символьный идентификатор типа.

Примеры использования

<!-- Пример кода, который может быть использован
в HTML шаблоне сайта для вывода баннера типа "TOP": -->

<?
if (CModule::IncludeModule("advertising")) :
    $s = CAdvBanner::Show("TOP");
    if (strlen($s)>0) :
        // выводим HTML баннера
        ?>
        <table width="0%" border="0" cellspacing="0" cellpadding="0">
            <tr>
                <td align=center><?=$s?></td>
            </tr>
        </table>
        <?
    endif;
endif;
?>


Класс CAdvContract

CAdvContract

Класс для работы с рекламными контрактами.

Методы класса

Метод | Описание
Set | Создает новый рекламный контракт, либо обновляет существующий.
GetList | Возвращает список контрактов с использованием фильтра.
GetByID | Возвращает один контракт по его ID.
Delete | Удаляет контракт и все баннеру к нему привязанные.
GetUserPermissions | Возвращает массив прав заданного пользователя по всем контрактам.
GetContractPermissions | Возвращает массив прав всех пользователей по заданному контракту.
IsModuleAccess | Возвращает true, если текущий пользователь отвечает правам переданным в качестве параметров, иначе false.


Delete

CAdvContract::Delete

boolean
CAdvContract::Delete(
 int CONTRACT_ID,
 char(1) CHECK_RIGHTS="Y"

);

Функция удаляет контракт и все баннеры к нему привязанные.

Параметры функции

Параметры | Описание
CONTRACT_ID | ID контракта.
CHECK_RIGHTS | "Y" - необходимо проверить право на удаление у текущего пользователя; "N" - прав проверять не надо.


GetByID

CAdvContract::GetByID

record set
CAdvContract::GetByID(

 int CONTRACT_ID,

 char(1) CHECK_RIGHTS="Y"

);

Функция возвращает контракт по его ID.

Параметры функции

Параметры | Описание
CONTRACT_ID | ID контракта.
CHECK_RIGHTS | Параметр проверяет уровень доступа к модулю Реклама (администратор рекламы, рекламодатель и т.д.). Если параметр определён как "N", то считается, что текущий пользователь обладает административными правами доступа к модулю Реклама. Если параметр пропущен либо равен "Y", то функция проверяет уровень доступа к контракту, которому принадлежит баннер.

Пример массива получаемого после Fetch результата возвращенного данной функции

<?
Array
(
    [LAMP] => green
    [ID] => 3
    [ACTIVE] => Y
    [NAME] => заголовок контракта
    [DESCRIPTION] => описание контракта
    [ADMIN_COMMENTS] => административный комментарий
    [WEIGHT] => 1000
    [SORT] => 200
    [MAX_SHOW_COUNT] => 1000
    [SHOW_COUNT] => 312
    [MAX_CLICK_COUNT] => 100
    [CLICK_COUNT] => 64
    [EMAIL_COUNT] => 0
    [CREATED_BY] => 2
    [MODIFIED_BY] => 2
    [DEFAULT_STATUS_SID] => READY
    [CTR] => 20.51
    [DATE_SHOW_FROM] => 15.06.2004
    [DATE_SHOW_TO] => 07.07.2009
    [DATE_CREATE] => 07.06.2004 19:04:55
    [DATE_MODIFY] => 24.06.2004 10:56:08
    [BANNER_COUNT] => 12
)
?>


GetContractPermissions

CAdvContract::GetContractPermissions

text
CAdvContract::GetContractPermissions(
 int CONTRACT_ID
);

Функция возвращает права всех пользователей по заданному контракту.

Параметры функции

Параметры | Описание
CONTRACT_ID | ID контракта.

Пример массива массива возвращаемого функцией

Array
(
    [VIEW] => Array
        (
            [0] => Array
                (
                    [USER_ID] => 341
                    [USER_LOGIN] => view
                    [USER_NAME] => Сергей
                    [USER_LAST_NAME] => Рыжиков
                    [USER_EMAIL] => mail@server.com
                )

            [1] => Array
                (
                    [USER_ID] => 340
                    [USER_LOGIN] => edit
                    [USER_NAME] => Анна
                    [USER_LAST_NAME] => Долгова
                    [USER_EMAIL] => mail@server.com
                )

            [2] => Array
                (
                    [USER_ID] => 2
                    [USER_LOGIN] => nessy
                    [USER_NAME] => Vitaly
                    [USER_LAST_NAME] => Kaplich
                    [USER_EMAIL] => nessy@bitrix.bx
                )

        )

    [ADD] => Array
        (
            [0] => Array
                (
                    [USER_ID] => 342
                    [USER_LOGIN] => add
                    [USER_NAME] => Андрей
                    [USER_LAST_NAME] =>
                    [USER_EMAIL] => mail@server.com
                )

            [1] => Array
                (
                    [USER_ID] => 340
                    [USER_LOGIN] => edit
                    [USER_NAME] => Анна
                    [USER_LAST_NAME] => Долгова
                    [USER_EMAIL] => mail@server.com
                )

            [2] => Array
                (
                    [USER_ID] => 2
                    [USER_LOGIN] => nessy
                    [USER_NAME] => Vitaly
                    [USER_LAST_NAME] => Kaplich
                    [USER_EMAIL] => nessy@bitrix.bx
                )

        )

    [EDIT] => Array
        (
            [0] => Array
                (
                    [USER_ID] => 340
                    [USER_LOGIN] => edit
                    [USER_NAME] => Анна
                    [USER_LAST_NAME] => Долгова
                    [USER_EMAIL] => mail@server.com
                )

            [1] => Array
                (
                    [USER_ID] => 2
                    [USER_LOGIN] => nessy
                    [USER_NAME] => Vitaly
                    [USER_LAST_NAME] => Kaplich
                    [USER_EMAIL] => nessy@bitrix.bx
                )

        )

)


GetList

CAdvContract::GetList

record set
CAdvContract::GetList(
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered,

 char(1) CHECK_RIGHTS="Y"
);

Функция предназначена для получения списка контрактов.

Параметры функции

Параметры | Описание
by Идентификатор позволяющий задать имя поля для сортировки. Допустимы следующие значения:
  • s_id - по ID
  • s_lamp - по индикатору контракта
  • s_name - по заголовку контракта
  • s_description - по описанию контракта
  • s_active - по флагу активности
  • s_weight - по весу
  • s_sort - по сортировки
  • s_date_modify - по дате модификации
  • s_modified_by - по ID пользователя изменившего контракт
  • s_banner_count - по числу баннеров приписанных к контракту
  • s_ctr - по отклику (CTR) контракта
  • s_show_count - по суммарному числу показов баннеров контракта
  • s_max_show_count - по максимальному суммарному числу всех показов баннеров контракта
  • s_click_count - по суммарному числу кликов на баннеры контракта
  • s_max_click_count - по максимальному суммарному числу кликов на баннеры контракта
arFilter Массив для фильтрации значений. В массиве допустимы следующие индексы:
  • ID - ID контракта (допускается сложная логика)
  • - "Y" - при фильтрации по ID контракта будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • LAMP - значение индикатора: "red", "green"
  • DATE_MODIFY_1 - левая часть интервала для даты модификации контракта
  • DATE_MODIFY_2 - правая часть интервала для даты модификации контракта
  • NAME - имя контракта (допускается сложная логика)
  • NAME_EXACT_MATCH - "Y" - при фильтрации по имени контракта будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • DESCRIPTION - описание контракта (допускается сложная логика)
  • DESCRIPTION_EXACT_MATCH - "Y" - при фильтрации по описанию контракта будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • OWNER - ID, ФИО, логин владельца контракта (допускается сложная логика)
  • OWNER_EXACT_MATCH - "Y" - при фильтрации по ID, ФИО, логину владельца контракта будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • BANNER_COUNT_1 - левая часть интервала для числа баннеров контракта
  • BANNER_COUNT_2 - правая часть интервала для числа баннеров контракта
  • SHOW_COUNT_1 - левая часть интервала для суммарного числа показов баннеров контракта
  • SHOW_COUNT_2 - правая часть интервала для суммарного числа показов баннеров контракта
  • CLICK_COUNT_1 - левая часть интервала для суммарного числа кликов по баннерам контракта
  • CLICK_COUNT_2 - правая часть интервала для суммарного числа кликов по баннерам контракта
  • CTR_1 - левая часть интервала для CTR контракта
  • CTR_2 - правая часть интервала для CTR контракта
  • ADMIN_COMMENTS - административный комментарий к контракту (допускается сложная логика)
  • ADMIN_COMMENTS_EXACT_MATCH - "Y" - при фильтрации по административному комментарию к контракту будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
CHECK_RIGHTS | Параметр проверяет уровень доступа к модулю Реклама (администратор рекламы, рекламодатель и т.д.) Если параметр определён как "N", то считается, что текущий пользователь обладает административными правами доступа к модулю Реклама. Если параметр пропущен либо равен "Y", то функция проверяет уровень доступа к контракту, которому принадлежит баннер.

Примеры использования

<?
// фильтр
$FilterArr = Array(
    "find_id",
    "find_id_exact_match",
    "find_date_modify_1",
    "find_date_modify_2",
    "find_name",
    "find_name_exact_match",
    "find_description",
    "find_description_exact_match",
    "find_lamp",
    "find_owner",
    "find_owner_exact_match",
    "find_banner_count_1",
    "find_banner_count_2",
    "find_show_count_1",
    "find_show_count_2",
    "find_click_count_1",
    "find_click_count_2",
    "find_ctr_1",
    "find_ctr_2",
    "find_admin_comments",
    "find_admin_comments_exact_match"
    );
if (strlen($set_filter)>0) InitFilterEx($FilterArr,"ADV_CONTRACT_LIST","set");
else InitFilterEx($FilterArr,"ADV_CONTRACT_LIST","get");
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"ADV_CONTRACT_LIST");
InitBVar($find_id_exact_match);
InitBVar($find_name_exact_match);
InitBVar($find_description_exact_match);
InitBVar($find_owner_exact_match);
InitBVar($find_admin_comments_exact_match);
$arFilter = Array(
    "ID"							=> $find_id,
    "ID_EXACT_MATCH"				=> $find_id_exact_match,
    "DATE_MODIFY_1"				 => $find_date_modify_1,
    "DATE_MODIFY_2"				 => $find_date_modify_2,
    "NAME"						  => $find_name,
    "NAME_EXACT_MATCH"			  => $find_name_exact_match,
    "DESCRIPTION"				   => $find_description,
    "DESCRIPTION_EXACT_MATCH"	   => $find_description_exact_match,
    "LAMP"						  => $find_lamp,
    "OWNER"						 => $find_owner,
    "OWNER_EXACT_MATCH"			 => $find_owner_exact_match,
    "BANNER_COUNT_1"				=> $find_banner_count_1,
    "BANNER_COUNT_2"				=> $find_banner_count_2,
    "SHOW_COUNT_1"				  => $find_show_count_1,
    "SHOW_COUNT_2"				  => $find_show_count_2,
    "CLICK_COUNT_1"				 => $find_click_count_1,
    "CLICK_COUNT_2"				 => $find_click_count_2,
    "CTR_1"						 => $find_ctr_1,
    "CTR_2"						 => $find_ctr_2,
    "ADMIN_COMMENTS"				=> $find_admin_comments,
    "ADMIN_COMMENTS_EXACT_MATCH"	=> $find_admin_comments_exact_match
    );
$rsAdvContract = CAdvContract::GetList($by, $order, $arFilter, $is_filtered, "N");
?>

Пример массива получаемого после Fetch одной строки выборки данной функции

<?
Array
(
    [LAMP] => green
    [ID] => 3
    [ACTIVE] => Y
    [NAME] => заголовок контракта
    [DESCRIPTION] => описание контракта
    [ADMIN_COMMENTS] => административный комментарий
    [WEIGHT] => 1000
    [SORT] => 200
    [MAX_SHOW_COUNT] => 1000
    [SHOW_COUNT] => 312
    [MAX_CLICK_COUNT] => 100
    [CLICK_COUNT] => 64
    [EMAIL_COUNT] => 0
    [CREATED_BY] => 2
    [MODIFIED_BY] => 2
    [DEFAULT_STATUS_SID] => READY
    [CTR] => 20.51
    [DATE_SHOW_FROM] => 15.06.2004
    [DATE_SHOW_TO] => 07.07.2009
    [DATE_CREATE] => 07.06.2004 19:04:55
    [DATE_MODIFY] => 24.06.2004 10:56:08
    [BANNER_COUNT] => 12
)
?>


GetUserPermissions

CAdvContract::GetUserPermissions

text
CAdvContract::GetUserPermissions(
 int USER_ID=false
);

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

Параметры функции

Параметры | Описание
USER_ID | ID пользователя; если не определён - используется ID текущего пользователя.

Пример массива массива возвращаемого функцией

Array
(
    [34] => Array
        (
            [0] => ADD
            [1] => VIEW
            [2] => EDIT
        )
    [52] => Array
        (
            [0] => ADD
            [1] => VIEW
        )
)
Индексом массива является ID контракта.
Значением - массив прав на данный контракт.


IsModuleAccess

CAdvContract::IsModuleAccess

boolean
CAdvContract::IsModuleAccess(
 char(1) permission
);

Функция возвращает true, если текущий пользователь имеет право, переданное в качестве параметра, иначе false.

Параметры функции

Параметры Описание
permission Символ отвечающий за тот или иное право на модуль рекламы, возможны следующие значения:
  • D - доступ закрыт
  • K - работа с контрактами (рекламодатель)
  • R - просмотр всего без права изменения
  • T - управление баннерами
  • W - полный административный доступ


Set

CAdvContract::Set

int
CAdvContract::Set(
 array arFields,
 int CONTRACT_ID="",
 char(1) CHECK_RIGHTS="Y"

);

Функция создает новый контракт, либо модифицирует существующий в случае указания во втором параметре ID контракта. Возвращает ID созданного контракта, либо ID модифицированного контракта.

Параметры функции

Параметры | Описание
arFields Массив параметров контракта. В массиве допустимы следующие индексы:
  • ACTIVE - флаг активности: "Y" - контракт активен; "N" - контракт не активен;
  • NAME - заголовок контракта
  • DESCRIPTION - описание контракта
  • ADMIN_COMMENTS - административный комментарий
  • WEIGHT - вес (приоритет) контракта
  • SORT - порядок сортировки
  • MAX_SHOW_COUNT - максимальное суммарное число показов всех баннеров контракта
  • MAX_CLICK_COUNT - максимальное суммарное число кликов на все баннеры контракта
  • DATE_SHOW_FROM - дата начала показов баннеров
  • DATE_SHOW_TO - дата окончания показов баннеров
  • DEFAULT_STATUS_SID - статус по умолчанию для новых баннеров или при модификации отображаемой части существующих, допустимы следующие значения:
    • PUBLISHED - баннер подтвержден и опубликован
    • READY - баннер на рассмотрении
    • REJECTED - баннер отклонен
  • arrSHOW_PAGE - массив страниц и разделов сайта на которых должны показываться баннеры контракта
  • arrNOT_SHOW_PAGE - массив страниц и разделов сайта на которых не могут показываться баннеры контракта
  • arrTYPE - массив доступных типов баннеров
  • arrWEEKDAY - массив описывающий время и дни недели для показа баннера; в массиве допустимы следующие индексы:
    • SUNDAY - массив часов в которые надо показывать баннер в воскресенье (0-23)
    • MONDAY - -||- в понедельник
    • TUESDAY - -||- во вторник
    • WEDNESDAY - -||- в среду
    • THURSDAY - -||- в четверг
    • FRIDAY - -||- в пятницу
    • SATURDAY - -||- в субботу
  • arrUSER_VIEW - массив ID пользователей для которых доступен просмотр параметров контракта и баннеров и их графики
  • arrUSER_ADD - массив ID пользователей для которых доступен просмотр параметров контракта и управление баннерами
  • arrUSER_EDIT - массив ID пользователей для которых доступно редактирование заголовка и описания контракта, а также возможность назначения прав для просмотра и управления баннерами
CONTRACT_ID | ID контракта, если не указывать - создаётся новый контракт.
CHECK_RIGHTS | Флаг необходимости проверки прав текущего пользователя: "Y" - необходимо проверить права текущего пользователя; "N" - контракт создавать и модифицировать независимо от прав текущего пользователя.

Примеры использования

Пример кода добавляющего новый контракт, либо модифицирующий существующий:
<?
if ((strlen($save)>0 || strlen($apply)>0) && $REQUEST_METHOD=="POST")
{
    $arrWEEKDAY = array(
        "SUNDAY"	=> $arrSUNDAY,
        "MONDAY"	=> $arrMONDAY,
        "TUESDAY"	=> $arrTUESDAY,
        "WEDNESDAY"	=> $arrWEDNESDAY,
        "THURSDAY"	=> $arrTHURSDAY,
        "FRIDAY"	=> $arrFRIDAY,
        "SATURDAY"	=> $arrSATURDAY
        );
    $arFields = array(
        "ACTIVE"				=> $ACTIVE,
        "NAME"				  => $NAME,
        "DESCRIPTION"		   => $DESCRIPTION,
        "ADMIN_COMMENTS"		=> $ADMIN_COMMENTS,
        "WEIGHT"				=> $WEIGHT,
        "SORT"				  => $SORT,
        "MAX_SHOW_COUNT"		=> $MAX_SHOW_COUNT,
        "MAX_CLICK_COUNT"	   => $MAX_CLICK_COUNT,
        "DATE_SHOW_FROM"		=> $DATE_SHOW_FROM,
        "DATE_SHOW_TO"		  => $DATE_SHOW_TO,
        "DEFAULT_STATUS_SID"	=> $DEFAULT_STATUS_SID,
        "arrSHOW_PAGE"		  => split("[\n\r]",$SHOW_PAGE),
        "arrNOT_SHOW_PAGE"	  => split("[\n\r]",$NOT_SHOW_PAGE),
        "arrTYPE"			   => $arrTYPE,
        "arrWEEKDAY"			=> $arrWEEKDAY,
        "arrUSER_VIEW"		  => $arrUSER_VIEW,
        "arrUSER_ADD"		   => $arrUSER_ADD,
        "arrUSER_EDIT"		  => $arrUSER_EDIT
        );
    if ($ID = CAdvContract::Set($arFields, $ID))
    {
        if (strlen($strError)<=0)
        {
            if (strlen($save) > 0)
                LocalRedirect("adv_contract_list.php?lang=".LANG);
            else
                LocalRedirect("adv_contract_edit.php?ID=".$ID."&lang=".LANG);
        }
    }
    $DB->PrepareFields("b_adv_contract");
}
?>


Класс CAdvType

CAdvType

Класс для работы с типами баннеров.

Методы класса

Метод | Описание
Set | Создает новый тип баннера, либо обновляет существующий.
GetList | Возвращает список типов с использованием фильтра.
GetByID | Возвращает один тип по заданному ID.
Delete | Удаляет тип и все баннеры к нему привязанные.


Delete

CAdvType::Delete

boolean
CAdvType::Delete(
 varchar(255) TYPE_SID,
 char(1) CHECK_RIGHTS="Y"
);

Функция удаляет тип баннеров и все баннеры к нему привязанные.

Параметры функции

Параметры | Описание
TYPE_SID | Символьный идентификатор типа.
CHECK_RIGHTS | "Y" - необходимо проверить право на удаление у текущего пользователя; "N" - прав проверять не надо.


GetByID

CAdvType::GetByID

record set
CAdvType::GetByID(
 varchar(255) TYPE_SID,

 char(1) CHECK_RIGHTS="Y"
);

Функция возвращает тип баннера по его символьному ID.

Параметры функции

Параметры | Описание
TYPE_SID | Символьный ID типа.
CHECK_RIGHTS | Параметр проверяет уровень доступа к модулю Реклама (администратор рекламы, рекламодатель и т.д.). Если параметр определён как "N", то считается, что текущий пользователь обладает административными правами доступа к модулю Реклама. Если параметр пропущен либо равен "Y", то функция проверяет уровень доступа к контракту, которому принадлежит баннер.

Пример массива получаемого после Fetch результата возвращенного данной функции

<?
Array
(
    [SID] => TOP
    [ACTIVE] => Y
    [SORT] => 10
    [NAME] => Top banner
    [DESCRIPTION] => описание типа
    [DATE_CREATE] => 03.06.2004 17:27:00
    [DATE_MODIFY] => 03.06.2004 17:27:00
    [CREATED_BY] => 2
    [MODIFIED_BY] => 2
    [BANNER_COUNT] => 63
)
?>


GetList

CAdvType::GetList

record set
CAdvType::GetList(
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered,

 char(1) CHECK_RIGHTS="Y"
);

Функция предназначена для получения списка типов баннеров.

Параметры функции

Параметры | Описание
by Идентификатор позволяющий задать имя поля для сортировки. Допустимы следующие значения:
  • s_sid - по символьному ID типа
  • s_date_modify - по дате модификации
  • s_modified_by - по ID пользователя изменившего тип
  • s_date_create - по дате создания
  • s_created_by - по ID пользователя создавшего тип
  • s_active - по флагу активности
  • s_name - по имени
  • s_banners - по количеству баннеров данного типа
  • s_description - по описанию
order Порядок сортировки. Допустимы следующие значения:
  • desc - по убыванию (значение по умолчанию)
  • asc - по возрастанию
arFilter Массив для фильтрации значений. В массиве допустимы следующие индексы:
  • SID - символьный ID типа (допускается сложная логика)
  • SID_EXACT_MATCH - "Y" - при фильтрации по символьному ID типа будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • DATE_MODIFY_1 - левая часть интервала для даты модификации типа
  • DATE_MODIFY_2 - правая часть интервала для даты модификации типа
  • ACTIVE - флаг активности типа ("Y" - активен; "N" - не активен)
  • NAME - имя типа (допускается сложная логика)
  • NAME_EXACT_MATCH - "Y" - при фильтрации по имени типа будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
  • DESCRIPTION - описание типа (допускается сложная логика)
  • DESCRIPTION_EXACT_MATCH - "Y" - при фильтрации по описанию типа будет искаться точное совпадение; "N" - в противном случае будет искаться вхождение (по умолчанию)
is_filtered | Переменная возвращающая true в том случае если список типов отфильтрован по какому либо критерию; либо false в противном случае.
CHECK_RIGHTS | Параметр проверяет уровень доступа к модулю Реклама (администратор рекламы, рекламодатель и т.д.) Если параметр определён как "N", то считается, что текущий пользователь обладает административными правами доступа к модулю Реклама. Если параметр пропущен либо равен "Y", то функция проверяет уровень доступа к контракту, которому принадлежит баннер.

Примеры использования

<?
$FilterArr = Array(
    "find_sid",
    "find_sid_exact_match",
    "find_date_modify_1",
    "find_date_modify_2",
    "find_active",
    "find_name",
    "find_name_exact_match",
    "find_description",
    "find_description_exact_match"
    );
if (strlen($set_filter)>0) InitFilterEx($FilterArr,"ADV_TYPE_LIST","set");
else InitFilterEx($FilterArr,"ADV_TYPE_LIST","get");
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"ADV_TYPE_LIST");
InitBVar($find_sid_exact_match);
InitBVar($find_name_exact_match);
InitBVar($find_description_exact_match);
$arFilter = Array(
    "SID"					   => $find_sid,
    "SID_EXACT_MATCH"		   => $find_sid_exact_match,
    "DATE_MODIFY_1"			 => $find_date_modify_1,
    "DATE_MODIFY_2"			 => $find_date_modify_2,
    "ACTIVE"					=> $find_active,
    "NAME"					  => $find_name,
    "NAME_EXACT_MATCH"		  => $find_name_exact_match,
    "DESCRIPTION"			   => $find_description,
    "DESCRIPTION_EXACT_MATCH"   => $find_description_exact_match,
    );
$rsAdvType = CAdvType::GetList($by, $order, $arFilter, $is_filtered, "Y");
?>

Пример массива получаемого после Fetch одной строки выборки данной функции

<?
Array
(
    [SID] => TOP
    [ACTIVE] => Y
    [SORT] => 10
    [NAME] => Top banner
    [DESCRIPTION] => описание типа
    [DATE_CREATE] => 03.06.2004 17:27:00
    [DATE_MODIFY] => 03.06.2004 17:27:00
    [CREATED_BY] => 2
    [MODIFIED_BY] => 2
    [BANNER_COUNT] => 63
)
?>


Set

CAdvType::Set

varchar(255)
CAdvType::Set(
 array arFields,
 varchar(255) TYPE_SID="",
 char(1) CHECK_RIGHTS="Y"
);

Функция создает новый тип баннеров, либо модифицирует существующий в случае указания во втором параметре символьного ID типа. Возвращает ID созданного типа, либо ID модифицированного типа.

Параметры функции

Параметры | Описание
arFields Массив параметров контракта. В массиве допустимы следующие индексы:
  • SID - символьный ID типа (используется в публичной части при выводе баннеров по типу)
  • ACTIVE - флаг активности: "Y" - тип активен; "N" - тип не активен;
  • NAME - имя типа
  • DESCRIPTION - описание типа
  • SORT - порядок сортировки типа в списках
TYPE_SID | ID типа, если не указывать - создаётся новый тип.
CHECK_RIGHTS | Флаг необходимости проверки прав текущего пользователя: "Y" - необходимо проверить права текущего пользователя; "N" - тип создавать и модифицировать независимо от прав текущего пользователя.

Примеры использования

<!-- Пример кода добавляющего новый контракт
либо модифицирующий существующий: -->
<?
if ((strlen($save)>0 || strlen($apply)>0) && $REQUEST_METHOD=="POST")
{
    $arFields = array(
        "SID"			   => $SID,
        "ACTIVE"			=> $ACTIVE,
        "SORT"			  => $SORT,
        "NAME"			  => $NAME,
        "DESCRIPTION"	   => $DESCRIPTION
        );
    if ($SID = CAdvType::Set($arFields, $OLD_SID))
    {
        if (strlen($strError)<=0)
        {
            if (strlen($save) > 0)
                LocalRedirect("adv_type_list.php?lang=".LANG);
            else
                LocalRedirect("adv_type_edit.php?SID=".$SID."&lang=".LANG);
        }
    }
    $DB->PrepareFields("b_adv_type");
}
?>


Переменные окружения

Статистика

  • Классы
  • Инсталляция
  • Переменные окружения
  • Список терминов


Инсталляция

Для инсталляции модуля требуется выполнить следующие действия.

  1. На странице списка модулей нажмите кнопку Установить напротив модуля статистики.
  2. Введите начальные параметры, перечисленные в таблице ниже.
    Параметр Описание
    Перегенерировать индекс для поиска страны по IP адресу ? Подразумевает пересоздание индекса по базе IP адресов для определения страны посетителя.

    Объем базы IP адресов составляет не менее 60 000 записей. Поэтому, пересоздание индекса может занять определённое время. Если ваш сайт в момент инсталляции нагружен потоком посетителей, то лучше не устанавливать данный флаг и при необходимости произвести переиндексацию базы на странице настроек модуля "Статистика".
    Начальное значение для количества хитов В случае, если вы инсталлируете статистику в уже работавший до этого сайт с накопленной статистикой, можно указать начальное значение для счетчика хитов. Это значение, в частности, будет использовано при выводе результирующей таблицы статистики в публичной части (если такая таблица у вас выводится).

    Данный параметр доступен в случае, если инсталляция модуля производится в базу, в которой отсутствуют таблицы модуля "Статистика".
    Начальное значение для количества хостов Соответственно начальное значение для счетчика хостов.

    Данный параметр доступен в случае, если инсталляция модуля производится в базу, в которой отсутствуют таблицы модуля "Статистика".
    Начальное значение для количества посетителей Соответственно начальное значение для счетчика посетителей.

    Данный параметр доступен в случае, если инсталляция модуля производится в базу, в которой отсутствуют таблицы модуля "Статистика".
  3. После нажатия кнопки Установить в базе данных будут созданы таблицы модуля, а также скопированы необходимые скрипты.
  4. Если вы подключаете модуль "Статистика" на сайте, созданном не на базе системы "1С-Битрикс: Управление сайтом" (например, при инсталляции редакции "Веб-аналитика"), следует для всех страниц сайта, для которых вам необходимо собирать статистику:
    • в самом начале файла страницы добавить следующий код:
      <?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/include_statistics_before.php");
?>
    • в самом конце файла страницы добавить следующий код:
      <?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/include_statistics_after.php");
?>


Список терминов

Ниже перечислены термины, на основе которых базируется идеология модуля "Статистика".

  • Рекламная кампания
  • Идентификаторы рекламной кампании (referer1, referer2)
  • Дополнительный параметр рекламной кампании (referer3)
  • Прямой заход по рекламной кампании
  • Возврат по рекламной кампании
  • Трафик рекламной кампании
  • Внимательность посетителей рекламной кампании
  • Затраты на рекламную кампанию
  • Доходы рекламной кампании
  • Прибыль рекламной кампании
  • Рентабельность рекламной кампании
  • Событие
  • Тип события
  • Идентификаторы типа события (event1, event2)
  • Дополнительный параметр события (event3)
  • Специальный параметр события
  • Обработчик CSV файлов
  • Посетитель
  • Пользователь
  • Новый посетитель
  • Посетители в online
  • UserAgent
  • Сессия
  • Хост
  • Хит
  • Поисковая фраза
  • Поисковая система
  • Домен поисковой системы
  • UserAgent поисковой системы
  • Хит поисковой системы
  • Стоп-лист
  • Запись стоп-листа
  • Маска подсети для стоп-листа
  • Конъюнкция
  • Ссылающийся сайт (страница)
  • Полный путь
  • Отрезок пути
  • IP-адрес
  • Октет IP-адреса
  • Языки в настройках браузера
  • 404 ошибка
  • Метод HTTP запроса
  • Cookie
  • Точка входа
  • Точка выхода
  • Лимит активности
  • Добавление в "Избранное"
    Рекламная кампания
    В модуле статистики предусмотрен механизм обсчета определённых потоков посетителей, приходящих на сайт. Каждый такой поток можно идентифицировать по ряду признаков:
    1. Наличие в ссылке, ведущей на ваш сайт, одного или двух параметров – referer1, referer2 (либо их синонимов, задаваемых в настройках модуля). Пример подобной ссылки: http://www.bitrixsoft.ru/?referer1=bsm&referer2=doc.
    2. Поисковые системы, с которых могут заходить посетители.
    3. Маски любых ссылающихся страниц.
    4. Маски страниц вашего сайта, на которые приходят посетители.
    Для каждого такого потока посетителей отдельно считаются:
    1. Сессии.
    2. Хиты.
    3. Хосты.
    4. Посетители.
    5. Новые посетители.
    6. Посетители, добавившие сайт в Избранное.
    7. Все события, инициированные посетителями данной рекламной кампании.
    Для ряда этих данных в отчетах по рекламным кампаниям вы можете видеть две цифры:
    • На прямом заходе по рекламной кампании
    • На возврате по рекламной кампании.

    Рекламная кампания определяется только на первом хите сессии.

    Идентификаторы рекламной кампании (referer1, referer2)
    Идентификаторы рекламной кампании (РК) - это два произвольных строковых значения, которые в первую очередь позволяют идентифицировать РК в более понятном виде, чем просто цифровой ID, а во-вторых, позволяют группировать различные РК в соответствующем отчете. Данные идентификаторы могут быть заданы:
    • "Вручную" в форме редактирования/создания РК.
    • Автоматически. Если на первом хите сессии в параметрах страницы присутствуют referer1, referer2 (либо их синонимы) и если в настройках модуля статистики включен параметр "Автоматически создавать рекламные кампании при наличии параметров referer1, referer2 в URL'е", то это позволит автоматически создавать новые РК с идентификаторами, значения которых совпадут в параметрами referer1, referer2.
    Дополнительный параметр рекламной кампании (referer3)
    Задать данный параметр (referer3) можно в ссылке на сайт одновременно с идентификаторами рекламной кампании. Например:

    http://www.bitrixsoft.ru/?referer1=bsm&referer2=doc&referer3=xxx

    Если по такой ссылке зайдет посетитель, то он будет фиксироваться по рекламной кампании с идентификаторами "bsm/doc" и дополнительным параметром "xxx", который будет доступен для просмотра в отчете "Сессии". Цель подобного параметра - персонализировать заход по рекламной кампании.

    Прямой заход по рекламной кампании
    Прямым заходом по рекламной кампании считается сессия, открытая в момент идентификации посетителя как посетителя по той или иной рекламной кампании. Т.е., если вы переходите по ссылке http://www.bitrix.ru/?referer1=bsm&referer2=doc, то после того, как вы зайдете на сайт, у вас откроется сессия и вы будете идентифицированы как посетитель по рекламной кампании: r1: bsm; r2: doc. Пока сессия открыта, вы считаетесь посетителем, сделавшим прямой заход по соответствующей рекламной кампании.

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

    Трафик рекламной кампании
    Под данным термином понимается совокупность таких статистических параметров как:
    1. Сессии;
    2. Хиты;
    3. Хосты;
    4. Посетители;
    5. Новые посетители;
    6. Посетители, добавившие сайт в Избранное;
    7. Все события, инициированные посетителями данной рекламной кампании.

    Внимательность посетителей рекламной кампании
    Среднее количество хитов за одну сессию. Данные параметр отдельно считается для сессии на прямом заходе и на возврате.

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

    Доходы рекламной кампании
    Денежная сумма, полученная от посетителей той или иной рекламной кампании.

    Прибыль рекламной кампании
    Разница между доходами и затратами на рекламную кампанию.

    Рентабельность рекламной кампании
    Рентабельность рекламной кампании рассчитывается по формуле (прибыль / расходы) * 100%.

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

    Тип события
    Каждое событие, фиксируемое на сайте имеет свой тип. Тип события представляет из себя совокупность:
    • идентификаторов (event1, event2) типа события
    • названия
    • описания
    • индекса сортировки
    • времени хранения событий данного типа
    • времени хранения динамики количества событий данного типа в разрезе по дням
    • дополнительных настроек

    Идентификаторы типа события (event1, event2)
    Идентификаторы типа события - два произвольных строковых значения, которые, в первую очередь, позволяют идентифицировать тип события в более читабельном виде, чем просто цифровой ID, а во вторых, позволяют группировать различные типы событий в соответствующем отчете. Данные идентификаторы могут быть заданы:
    • "Вручную" в форме редактирования/создания типа события.
    • Автоматически. При создании событий такими функциями как CStatEvent::AddByEvents, CStatEvent::AddCurrent. Если тип события, идентификатор которого был указан в параметрах этих функций, не существует, то он автоматически будет создан.

    Дополнительный параметр события (event3)
    Задать данный параметр можно при создании события соответствующими функциями. Значения этих дополнительных параметров можно посмотреть в отчете "События", выводящем каждое событие по отдельности. Цель данного параметра - персонализация каждого отдельного события.

    Специальный параметр события
    Используется для идентификации посетителя, при уходе его на внешний сайт (например на внешнюю платежную систему для оплаты товара), впоследствии специальный параметр может быть использован для фиксации событий, произошедших вне пределов сайта (например оплата того или иного товара) (подробнее см. метод CStatEvent::Add и "Загрузка событий"). Значение данного параметра представляет из себя строку состоящую из:
    • краткий идентификатор портала (из настроек модуля "Статистика")
    • ID сессии
    • ID посетителя
    • двусимвольный идентификатор страны
    • ID рекламной кампании
    • флаг прямого захода, либо возврата по рекламной кампании
    • двусимвольный идентификатор сайта
    В зависимости от значения параметра "Кодировать дополнительный параметр #EVENT_GID# для событий" (из настроек модуля "Статистика"), данный специальный параметр может быть как в закодированном, так и в открытом виде.

    Обработчик CSV файлов
    Представляет из себя специальный PHP скрипт, главная задача которого - сконвертировать CSV формат отчета о продажах какой либо платежной системы, в стандартный CSV формат принимаемый модулем "Статситика", для загрузки событий. Стандартный CSV формат выглядит как:
    • ID типа события
    • дополнительный параметр события
    • дата и время генерации события
    • специальный параметр события
    • денежная сумма
    • знак денежной суммы: "Y" - положительная сумма; "N" - отрицательная сумма.

    Посетитель
    Посетителем является уникальный цифровой идентификатор, выданный любому браузеру и сохраняющийся в файлах cookie (файлы, используемые браузерами для хранения информации от посещенных ранее сайтов на локальной машине). Если браузер (либо любая другая программа) не поддерживает cookie (обычные и/или сессионные), используется специальный механизм идентификации посетителя по хэш-функции (MD5) от переменных окружения, включающих в себя IP-адрес, настройки браузера, настройки провайдера и другие параметры, характеризующие посетителя в данный момент его захода на сайт.

    Другими словами, посетитель – это один браузер (или любая другая программа), зашедшие на сайт.

    В данном модуле статистики используется различные степени уникальности посетителей. В меню Статистика вы можете видеть количество уникальных посетителей за день, а также количество уникальных посетителей относительно всего времени ведения статистики (с момента инсталляции модуля).

    Для рекламных кампаний, также, как и для хостов, соблюдается уникальность посетителей в пределах данной рекламной кампании. При этом под новыми посетителями понимаются посетители, впервые пришедшие на сайт в обоих случаях.
    Новый посетитель
    Это посетитель от которого не был получен его цифровой идентификатор. Предположительно считается, что такие посетители впервые приходят на сайт.
    Пользователь
    Синонимом данного термина можно считать "бюджет пользователя", "профайл пользователя". Это совокупность таких параметров как:
    • логин
    • пароль
    • E-Mail
    • фамилия
    • имя
    • персональные данные
    • данные по работе
    • административные заметки
    Один посетитель сайта может быть авторизованным в тот или иной момент как тот или иной пользователь.
    Посетители в online
    Это список посетителей сайта, сделавших хит в течении последних N секунд. Данное количество секунд задается в настройках модуля "Статистика" в параметре "Интервал посетителей в online (сек.)".
    UserAgent
    Под данным термином понимают содержимое поля UserAgent в протоколе HTTP, которое заполняется программой, обращающейся к веб-серверу. Такой программой могут быть: браузеры, программы скачивания, offline-браузеры, поисковые роботы и т.д. Данное поле предназначено для самоидентификации таких программ. Как правило, значение этого поля можно самостоятельно поменять, многие программы позволяют это делать через стандартный интерфейс (например, ReGet).

    Примеры значений UserAgent’ов:
    • Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; NetCaptor 7.0.2 Final; .NET CLR 1.0.3705) - так идентифицирует себя браузер NetCaptor.
    • ReGet SE version 1.3.1* - так идентифицирует себя программа для скачивания файлов из Интернета "ReGet".
    Сессия
    Под термином сессия в системе 1C-Битрикс: Управление сайтом понимается сессия PHP. Сессия может открываться в момент захода на сайт и закрывается при закрытии окна браузера. Также новая сессия открывается при авторизации посетителя и закрывается, если закончить сеанс авторизации (разлогиниться). Синонимом термина сессия можно считать термин заход. Другими словами, сессия - один визит на сайт.

    Хост
    Термин хост означает IP-адрес посетителя сайта. В системе 1C-Битрикс: Управление сайтом все хосты представленные в статистических отчетах имеют свою степень уникальности.

    В меню Статистика вы можете видеть количество уникальных хостов (IP-адресов) за день, а в отдельной ячейке – количество уникальных хостов относительно всего времени ведения статистики, с момента инсталляции модуля.

    Для рекламных кампаний уникальность определяется только в пределах данной рекламной кампании, т.е. все посетители и их IP-адреса, зашедшие по данной рекламной кампании запоминаются в специальной таблице и уникальность IP-адреса, а также посетителя, определяется фактом наличия данного IP-адреса, либо посетителя, в вышеописанной таблице. Как правило, в большинстве систем сбора статистики принято, что количество хостов не должно отличаться от количества посетителей более чем на 10% (чем больше различие, тем менее точно считается статистика). В данном модуле статистики различие, как правило, не превышает 3%.

    Хит
    Под термином хит понимается одна загрузка страницы. Нажатие на ссылку на сайте и загрузка страницы приводит к генерации хита. Перезагрузка страницы с помощью F5 или Ctrl+F5 генерирует хит. Запрос к несуществующей страницы (404 ошибка) также генерирует хит.

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

    Поисковая система
    Под термином поисковая система понимается любая поисковая система Интернета. Синонимом данного термина можно также считать поисковик. Пример: Google, Rambler, Yandex, Aport и т.д. Каждая поисковая система характеризуется UserAgent’ом, под которым идентифицируется индексирующий сайты робот, а также группой доменов – адресов сайтов на которых можно воспользоваться поиском и переменной содержащей поисковую фразу.

    Домен поисковой системы
    Это один из возможно многих доменов той или иной поисковой системы. К примеру для поисковой системы Google, существует много доменов, перечислим только некоторые из них:
    • www.google.com
    • www.google.ru
    • www.google.de
    • ...
    К примеру для Yandex, существует нижеследующие домены:
    • www.yandex.ru
    • www.ya.ru

    UserAgent поисковой системы
    Это UserAgent специальной программы, называемой "поисковым роботом" (или "ботом"). Цель данной программы - индексация содержимого вашего сайта, другими словами - занесение часть содержимого вашего сайта для базы данных, которая в дальнейшем используется для поиска в помощью той или иной поисковой системы. Каждая поисковая система имеет как правило, индивидуального поискового робота, имеющего свой индивидуальный UserAgent, но это бывает не всегда, иногда одна или более поисковых систем используют одного поискового робота (например Google и Yahoo).

    Хит поисковой системы
    Под данным термином понимается факт индексации одной страницы. Все поисковые системы имеют ряд механизмов для индексации Интернет-ресурсов. Сама индексация осуществляется так называемыми поисковыми роботами. Каждый робот имеет идентификатор хранящийся в UserAgent’е. В момент когда робот пытается проиндексировать ту или иную страницу вашего сайта, он запрашивает ее у веб-сервера и загружает ее HTML-код (отсюда название хит) и затем производит индексацию содержимого этой страницы. Все подобные загрузки фиксируются модулем статистики в виде хит поисковика, при этом поисковые роботы между собой различаются по UserAgent’у.

    Стоп-лист
    Представляет из себе совокупность записей. Цель стоп-листа - ограничить доступ либо перенаправить посетителей вашего сайта на другую страницу, возможно даже другого сайта.

    Запись стоп-листа
    Это набор параметров, по которым необходимо отфильтровать поток посетителей и выполнить с ними какие- либо действия: перенаправить, показать сообщение, просто не показать сайт и т.п.

    Маска подсети для стоп-листа

    В терминологии сетей TCP/IP маской подсети или маской сети называется битовая маска, определяющая, какая часть IP-адреса узла сети относится к адресу сети, а какая — к адресу самого узла в этой сети. Например, узел с IP-адресом 12.34.56.78 и маской подсети 255.255.0.0 находится в сети 12.34.0.0.

    Чтобы получить адрес сети, зная IP-адрес и маску подсети, необходимо применить к ним операцию поразрядной конъюнкции. Например, в случае более сложной маски:

    IP-адрес:       00001100 00100010 00111000 1001110 (12.34.56.78)
Маска подсети:  11111111 11111111 11100000 0000000 (255.255.224.0)
--------------------------------------------------------------------
Адрес сети:     00001100 00100010 00100000 0000000 (12.34.32.0)

    Запись стоп-листа содержит два поля: IP адрес сети и маска сети. Посетитель считается попадающим под ту или иную запись стоп-листа в случае если при наложении маски сети на его IP адрес мы получим IP адрес сети.

    Пример 1. Стоит задача ограничить доступ всех посетителей приходящих с IP = 206.191.49.66

    1. В этом случае нам необходимо задать:
      • IP адрес сети = 206.191.49.66
      • маска сети = 255.255.255.255
    2. В момент захода на сайт посетителя с IP = 206.191.49.66 будет произведена следующая операция конъюнкции:
      IP-адрес посетителя: 11010001 10111111 11000001 1000010 (206.191.49.66)
маска сети:          11111111 11111111 11111111 1111111 (255.255.225.255)
----------------------------------------------------------------------------
Результат:           11010001 10111111 11000001 1000010 (206.191.49.66)
      Если результат совпадает с IP адресом сети, то посетитель попадает под данную запись стоп-листа, что в данном случае и происходит. Таким образом все посетители заходящие на сайт с IP = 206.191.49.66 попадут под данную запись стоп-листа.

    Пример 2. Стоит задача ограничить доступ всех посетителей приходящих с подсети = 206.191.49.xxx (IP в интервале от 206.191.49.1 до 206.191.49.255)

    1. В этом случае нам необходимо задать:
      • IP адрес сети = 206.191.49.0
      • маска сети = 255.255.255.0
    2. В момент захода на сайт посетителя с IP = 206.191.49.76 будет произведена следующая операция конъюнкции:
      IP-адрес посетителя: 11010001 10111111 11000001 1001100 (206.191.49.76)
маска сети:          11111111 11111111 11111111 0000000 (255.255.225.0)
----------------------------------------------------------------------------
Результат:           11010001 10111111 11000001 0000000 (206.191.49.0)
      Если результат совпадает с IP адресом сети, то посетитель попадает под данную запись стоп-листа. Таким образом все посетители заходящие на сайт с IP в интервале от 206.191.49.1 до 206.191.49.255 попадут под данную запись стоп-листа.

    Конъюнкция
    Логическая операция. Правила данной операции представлены ниже:
    Операнд 1:  0110
Операнд 2:  1010
Результат:  0010

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

    Полный путь
    Полный путь по сайту – это набор страниц (одна и более), которые последовательно открывал посетитель сайта, пользуясь ссылками на этих страницах. Путь может разветвляться образуя несколько путей в том случае если посетитель открывает с одной страницы сразу несколько ссылок. В Internet Explorer это можно сделать, кликнув на ссылку левой кнопкой мыши, удерживая клавишу "Shift", либо кликнув правой кнопкой мыши по ссылке и выбрав пункт меню "Open in New Window".

    Отрезок пути
    В модуле статистики принято следующее определение отрезка пути по сайту.
    Отрезок пути по сайту это набор страниц состоящий из первой страницы пути и произвольного количество последующих страниц данного пути.

    К примеру, вы заходите на сайт на страницу 1, затем видите на ней ссылку, ведущую на страницу 2, и идете по ней, затем следуете на ссылку ведущую на страницу 3. Таким образом, вы проследовали по сайту одним путём, состоящим из трех отрезков:

    • страница 1
    • страница 1 –> страница 2
    • страница 1 -> страница 2 -> страница 3
    Если со страницы 3 вы откроете ссылку, ведущую на страницу 4 ("Shift" + клик на ссылку левой кнопкой мыши или клик на ссылку правой кнопкой мыши и выбор пункта меню "Open in New Window"), и точно также - ссылку ведущую на страницу 5, то в сумме вы пройдете по двум путям, каждый из которых будет состоять из 4 отрезков, первые 3 из которых будут одинаковыми.

    IP-адрес
    Это уникальный идентификатор (адрес) устройства (обычно компьютера), подключённого к локальной сети или интернету, если быть более точным, то IP-адрес - это идентификатор одного сетевого соединения.

    IP-адрес представляет собой 32-битовое (по версии IPv4) или 128-битовое (по версии IPv6) двоичное число. Удобной формой записи IP-адреса (IPv4) является запись в виде четырёх десятичных чисел (октетов) (от 0 до 255), разделённых точками, например, 192.168.0.1. (или 128.10.2.30 — традиционная десятичная форма представления адреса, а 10000000 00001010 00000010 00011110 — двоичная форма представления этого же адреса).

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

    Каждая страна имеет персональный набор интервалов IP-адресов. Благодаря этому существует возможность определить страну посетителя сайта по его IP-адресу.

    Октет IP-адреса
    Часть IP-адреса, представляющее из себя двоичное число от 0 до 255.

    Языки в настройках браузера
    В ряде браузеров присутствует настройка, позволяющая задать набор языков которые понимает посетитель сайта. К примеру в Internet Explorer данная настройка доступна в пункте меню:

    "Tools" -> "Internet Options..." -> закладка "General" -> кнопка "Languages"

    404 ошибка
    При запросе браузером посетителя сайта той или иной страницы, может сложиться ситуация когда этой страницы физически (как файла) может не быть на сервере. В этом случае веб-сервер генерирует 404 ошибку и отсылает статус этой ошибки (404) браузеру посетителя сайта. Есть возможность перехватить обработку этой ошибки, например для Apache необходимо разместить файл с именем .htaccess в корне вашего сайта (либо в подкаталоге запрашиваемой страницы) к примеру со следующим содержимым:

    ErrorDocument 404 /404_handler.php
    В данном примере, при возникновении 404 ошибки на веб-сервере управление будет передано скрипту /404_handler.php, в котором вы, как веб-разработчик, можете выполнить любое действие.

    Для фиксации 404 ошибки на той или иной странице в модуле "Статистика", необходимо в любом месте страницы, но до эпилога, инициализировать константу "ERROR_404" значением "Y". Пример:

    define("ERROR_404", "Y");
    Метод HTTP запроса
    Существуют несколько методов HTTP запросов: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT. В основном используются GET, POST, HEAD.
    • GET

      Данные передаваемые этим методом закодированы непосредственно в URI. Например:

      http://www.bitrixsoft.ru/bitrix/admin/stat_list.php?find_site_id=ru&find_date1_DAYS_TO_BACK=2&find_date2=&lang=ru&set_filter=Y&set_filter=%D3%F1%F2%E0%ED%EE%E2%E8%F2%FC

      Переменные передаются парами, разделенными символом "&", каждая пара состоит из "названия переменной" и "значение переменной". При это значение переменной должно быть URL-кодировано.

    • POST

      Данные передаваемый этим методом закодированы в теле HTTP-запроса.

    • HEAD

      Основное назначение данного метода - получение информации о запрашиваемой странице. Он аналогичен методу GET, но сервер в качестве ответа возвращает только HTTP-заголовки без содержимого запрошенной страницы.

    Cookie
    Часть информации, передаваемая веб-сервером, принимаемая браузером посетителя сайта и сохраняемая в файле на компьютере посетителя сайта. Как правило, используется для определения уникальности посетителя, времени его последнего визита, личных настроек, уникального идентификатора корзины покупок и т.д.

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

    Точка выхода
    Когда вы заходите на сайт, вы можете просмотреть одну и более страниц. Последняя страница, которую вы просмотрите будет являться точкой выхода. Другими словами, точки выхода – это последние страницы в сессиях.

    Лимит активности
    В настройках модуля "Статистика" существует возможность задать лимит активности. Превышение данного лимита означает, что посетитель сайта превысил установленное количество хитов за определённый интервал времени. В момент превышения лимита, посетителю сайта отсылается HTTP статус "503 Service Unavailable" и на экран выводится соответствующее сообщение. Достигается это посредством подключения файла /bitrix/activity_limit.php.

    Данный функционал как правило используется в целях снизить нагрузку на сайт создаваемую индексирующими роботами поисковых систем, оффлайн-браузеров и т.п. При получении статуса 503 поисковые роботы как правило снижают частоту индексации сайта, но в то же время есть возможность отключить проверку лимита активности для той или иной поисковой системы, делается это в ее настройках. Отчасти лимит активности может быть использован для отражения ddos атак, но его нельзя считать при этом эффективным средством, т.к. контроль лимита активности осуществляется все таки за счет ресурсов сайта.

    Добавление в "Избранное"

    Большинство браузеров предоставляют возможность запомнить адрес сайта в так называемых "закладках" или в папке "Избранное" ("Favorites"). В момент такого запоминания, браузер как правило запрашивает иконку сайта хранящуюся в файле /favicon.ico. Это дает возможность фиксировать подобные события в модуле "Статистика".

    В тоже время, есть определённая погрешность в подобной технологии и связана с тем, что ряд браузеров (Firefox, NetCaptor, MyIE) запрашивают данную иконку вне зависимости от того добавил ли посетитель сайт в "Избранное" или нет, но это не касается Internet Explorer. Учитывая то, что подавляющее большинство пользователей сети Интернет пользуются Internet Explorer, вышеописанная погрешность невелика.


Переменные окружения

Модуль статистики реализует следующие сессионные переменные:
$_SESSION["SESS_SESSION_ID"] | ID сессии.
$_SESSION["SESS_GUEST_ID"] | ID посетителя.
$_SESSION["SESS_GUEST_NEW"] | "Y" - посетитель впервые на сайте; "N" - посетитель вернулся на сайт.
$_SESSION["SESS_COUNTRY_ID"] | двухсимвольный идентификатор страны посетителя.
$_SESSION["SESS_ADV_ID"] | ID рекламной кампании по которой посетитель делает прямой заход.
$_SESSION["SESS_LAST_ADV_ID"] | ID последней рекламной кампании посетителя по которой он сделал прямой заход, либо по которой вернулся.
$_SESSION["SESS_LAST_USER_ID"] | ID пользователя после его последней авторизации.
$_SESSION["SESS_LAST_USER_AUTH"] | "Y" - в последний раз посетитель был авторизован; "N" - нет.
$_SESSION["SESS_GUEST_FAVORITES"] | "Y" - посетитель уже добавлял сайт в избранное; "N" - нет.
$_SESSION["FROM_SEARCHER_ID"] | ID поисковика с которого посетитель пришел на сайт.
$_SESSION["SESS_SEARCH_PHRASE"] | поисковая фраза с которой посетитель пришел на сайт.
$_SESSION["SESS_SEARCHER_ID"] | ID поисковика робот которого индексирует сайт.


Классы

  • CAdv
  • CAutoDetect
  • CCountry
  • CGuest
  • CHit
  • CPage
  • CPath
  • CPhrase
  • CReferer
  • CSearcher
  • CSearcherHit
  • CSession
  • CStatEvent
  • CStatEventType
  • CStatistics
  • CStopList
  • CTraffic
  • CUserOnline


Класс CAdv

CAdv - класс для работы с рекламными кампаниями.

Методы класса

Метод | Описание
Delete | Удаляет рекламную кампанию.
GetByID | Возвращает настройки рекламной кампании.
GetDropdownList | Возвращает список рекламных кампаний для вывода его в выпадающем списке с помощью функции SelectBox, либо в списке множественного выбора с помощью функции SelectBoxM.
GetDynamicList | Возвращает данные по трафику рекламной кампании в разрезе по дням.
GetEventList | Возвращает список типов событий инициализированным посетителями зашедшими по определённой рекламной кампании.
GetList | Возвращает список рекламных кампаний с рассчитанными статистическими показателями и со всеми данными по трафику.
GetSimpleList | Возвращает список рекламных кампаний.
Reset | Обнуляет статистические данные рекламной кампании.

См. также

  • Термин "Рекламная кампания"
  • Пользовательская документация, раздел Веб-аналитика > Рекламные кампании > Список кампаний.


Delete

CAdv::Delete

bool
CAdv::Delete(
 int adv_id
)

Удаляет рекламную кампанию.

Параметры функции

Параметр | Описание
adv_id | ID рекламной кампании.

См. также

  • Термин "Рекламная кампания"
  • CAdv::Reset

Примеры использования

<?
$adv_id = 1;
if (CAdv::Delete($adv_id))
    echo "Рекламная кампания #".$adv_id." успешно удалена.";
?>


GetByID

CAdv::GetByID

CDBResult
CAdv::GetByID(
 int adv_id
)

Возвращает настройки рекламной кампании.

Параметры функции

Параметр | Описание
adv_id | ID рекламной кампании.

Структура возвращаемой записи

Array
(
    [ID] => ID
    [REFERER1] => идентификатор referer1
    [REFERER2] => идентификатор referer2
    [DATE_FIRST] => дата первого прямого захода
    [DATE_LAST] => дата последнего прямого захода или возврата
    [COST] => затраты
    [REVENUE] => доходы
    [DESCRIPTION] => описание
    [PRIORITY] => приоритет
    [EVENTS_VIEW] => режим показа списка событий, возможные значения:
        link - ссылкой на список
        list - списком
        event1 - сгруппированными по event1
        event2 - сгруппированными по event2
    [GUESTS] => суммарное кол-во посетителей на прямом заходе
    [NEW_GUESTS] => суммарное кол-во новых посетителей на прямом заходе
    [FAVORITES] => суммарное кол-во посетителей добавившие сайт в "Избранное"
        на прямом заходе
    [C_HOSTS] => суммарное кол-во хостов на прямом заходе
    [SESSIONS] => суммарное кол-во сессий на прямом заходе
    [HITS] => суммарное кол-во хитов на прямом заходе
    [GUESTS_BACK] => суммарное кол-во посетителей на возврате
    [FAVORITES_BACK] => суммарное кол-во посетителей добавившие сайт в "Избранное"
        на возврате
    [HOSTS_BACK] => суммарное кол-во хостов на возврате
    [SESSIONS_BACK] => суммарное кол-во сессий на возврате
    [HITS_BACK] => суммарное кол-во хитов на возврате
)

См. также

  • Термин "Рекламная кампания"

Примеры использования

<?
$adv_id = 1;
if ($rs = CAdv::GetByID($adv_id))
{
    $ar = $rs->Fetch();
    // выведем настройки рекламной кампании
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetDropdownList

CAdv::GetDropdownList

CDBResult
CAdv::GetDropdownList(
 string order = "ORDER BY REFERER1, REFERER2"
)

Возвращает список рекламных кампаний (РК) для вывода его в выпадающем списке с помощью функции SelectBox, либо в списке множественного выбора с помощью функции SelectBoxM.

Параметры функции

Параметр | Описание
order | SQL код, позволяющий задать произвольную сортировку списка рекламных кампаний.

Структура возвращаемой записи

Array
(
    [REFERENCE_ID] => ID РК
    [REFERENCE] => [ID РК] referer1 / referer2
)

См. также

  • Термин "Рекламная кампания"
  • CAdv::GetList
  • CAdv::GetSimpleList
  • SelectBox
  • SelectBoxM

Примеры использования

<?
// выпадающий список с одиночным выбором
echo SelectBox("ADV_ID", CAdv::GetDropdownList(), "", intval($ADV_ID));

// список из 20 видимых элементов с возможностью множественного выбора
echo SelectBoxM("arADV_ID[]", CAdv::GetDropdownList(), $arADV_ID, "", false, 20);
?>


GetDynamicList

CAdv::GetDynamicList

CDBResult
CAdv::GetDynamicList(
 int adv_id,
 string &by = "s_date",
 string &order = "desc",
 array &max_min,
 array filter = array()
)

Возвращает данные по трафику рекламной кампании в разрезе по датам.

Параметры функции

Параметр | Описание
adv_id | ID рекламной кампании.
by Поле для сортировки. Возможные значения:
  • s_date - дата
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию
  • desc - по убыванию
max_min Ссылка на массив содержащий максимальную и минимальную даты результирующего списка. Структура данного массива:
Array
(
    [DATE_FIRST] => минимальная дата
    [MIN_DAY] => день минимальной даты (1-31)
    [MIN_MONTH] => месяц минимальной даты (1-12)
    [MIN_YEAR] => год минимальной даты

    [DATE_LAST] => максимальная дата
    [MAX_DAY] => день максимальной даты (1-31)
    [MAX_MONTH] => месяц максимальной даты (1-12)
    [MAX_YEAR] => год максимальной даты
)
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • DATE_1 - дата "с"
  • DATE_2 - дата "по"

Структура возвращаемой записи

Array
(
    [DATE_STAT] => дата
    [DAY] => день (1-31)
    [MONTH] => месяц (1-12)
    [YEAR] => год
    [GUESTS] => посетителей на прямом заходе
    [NEW_GUESTS] => новых посетителей на прямом заходе
    [FAVORITES] => посетителей, добавивших сайт в "Избранное" на прямом заходе
    [C_HOSTS] => хостов на прямом заходе
    [SESSIONS] => сессий на прямом заходе
    [HITS] => хитов на прямом заходе
    [GUESTS_BACK] => посетителей на возврате
    [FAVORITES_BACK] => посетителей, добавивших сайт в "Избранное" на возврате
    [HOSTS_BACK] => хостов на возврате
    [SESSIONS_BACK] => сессий на возврате
    [HITS_BACK] => хитов на возврате
)

См. также

  • Термин "Рекламная кампания"

Примеры использования

<?
$adv_id = 1;

// установим фильтр на декабрь 2005 года
$arFilter = array(
    "DATE1" => "01.12.2005",
    "DATE2" => "31.12.2005"
    );

// получим набор записей
$rs = CAdv::GetDynamicList(
    $adv_id,
    ($by="s_date"),
    ($order="desc"),
    $arMaxMin,
    $arFilter,
    $is_filtered
    );

// выведем массив с максимальной и минимальной датами
echo "<pre>"; print_r($arMaxMin); echo "</pre>";

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetEventList

CAdv::GetEventList

CDBResult
CAdv::GetEventList(
 int adv_id,
 string &by = "s_counter",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список типов событий, инициализированных посетителями, зашедшими по определённой рекламной кампании (РК).

Параметры функции

Параметр | Описание
adv_id | ID рекламной кампании.
by Поле для сортировки. Возможные значения:
  • s_id - ID типа события
  • s_event1 - идентификатор event1 типа события
  • s_event2 - идентификатор event2 типа события
  • s_sort - индекс сортировки типа события
  • s_name - наименование типа события
  • s_counter - количество событий инициализированных посетителями на прямом заходе по рекламной кампании adv_id
  • s_counter_back - количество событий инициализированных посетителями на возврате по рекламной кампании adv_id
  • s_def - сортировка по умолчанию (для вывода в соответствующей таблице)
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию
  • desc - по убыванию
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID типа события
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение
  • EVENT1* - идентификатор event1 типа события
  • EVENT1_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT1 будет искаться точное совпадение
  • EVENT2* - идентификатор event2 типа события
  • EVENT2_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT2 будет искаться точное совпадение
  • KEYWORDS* - имя и описание типа события
  • KEYWORDS_EXACT_MATCH - если значение равно "Y", то при фильтрации по KEYWORDS будет искаться точное совпадение
  • DATE1_PERIOD - начальная дата периода
  • DATE2_PERIOD - конечная дата периода
  • COUNTER_PERIOD_1 - если установлены DATE1_PERIOD или DATE2_PERIOD, то в данном поле можно указать начальное значение интервала количества событий инициализированных посетителями на прямом заходе по рекламной кампании adv_id
  • COUNTER_PERIOD_2 - если установлены DATE1_PERIOD или DATE2_PERIOD, то в данном поле можно указать конечное значение интервала количества событий инициализированных посетителями на прямом заходе по рекламной кампании adv_id
  • COUNTER_BACK_PERIOD_1 - если установлены DATE1_PERIOD или DATE2_PERIOD, то в данном поле можно указать начальное значение интервала количества событий инициализированных посетителями на возврате по рекламной кампании adv_id
  • COUNTER_BACK_PERIOD_2 - если установлены DATE1_PERIOD или DATE2_PERIOD, то в данном поле можно указать конечное значение интервала количества событий инициализированных посетителями на возврате по рекламной кампании adv_id
  • MONEY_PERIOD_1 - если установлены DATE1_PERIOD или DATE2_PERIOD, то в данном поле можно указать начальное значение интервала количество денег инициализированных посетителями на прямом заходе по рекламной кампании adv_id
  • MONEY_PERIOD_2 - если установлены DATE1_PERIOD или DATE2_PERIOD, то в данном поле можно указать конечное значение интервала количества денег инициализированных посетителями на прямом заходе по рекламной кампании adv_id
* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка типов событий. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID типа события
    [EVENT1] => идентификатор event1
    [EVENT2] => идентификатор event2
    [C_SORT] => сортировка
    [NAME] => название
    [EVENT] => название либо [ID] event1 / event2
    [DESCRIPTION] => описание
    [COUNTER] => суммарное кол-во событий данного типа на прямом заходе по РК
    [COUNTER_BACK] => суммарное кол-во событий данного типа на возврате по РК
    [COUNTER_TODAY] => кол-во событий данного типа на прямом заходе по РК за сегодня
    [COUNTER_YESTERDAY] => кол-во событий данного типа на прямом заходе по РК за вчера
    [COUNTER_BEF_YESTERDAY] => кол-во событий данного типа на прямом заходе по РК
        за позавчера
    [COUNTER_PERIOD] => кол-во событий данного типа на прямом заходе по РК за период
    [COUNTER_BACK_TODAY] => кол-во событий данного типа на возврате по РК за сегодня
    [COUNTER_BACK_YESTERDAY] => кол-во событий данного типа на возврате по РК за вчера
    [COUNTER_BACK_BEF_YESTERDAY] => кол-во событий данного типа на возврате по РК
       за позавчера
    [COUNTER_BACK_PERIOD] => кол-во событий данного типа на возврате по РК за период
    [MONEY] => итоговая денежная сумма событий данного типа на прямом заходе по РК
    [MONEY_TODAY] => денежная сумма событий данного типа на прямом заходе по РК за сегодня
    [MONEY_YESTERDAY] => денежная сумма событий данного типа на прямом заходе по РК
       за вчера
    [MONEY_BEF_YESTERDAY] => денежная сумма событий данного типа на прямом заходе по РК
       за позавчера
    [MONEY_PERIOD] => денежная сумма событий данного типа на прямом заходе по РК за период
    [MONEY_BACK] => итоговая денежная сумма событий данного на возврате по РК
    [MONEY_BACK_TODAY] => денежная сумма событий данного типа на возврате по РК за сегодня
    [MONEY_BACK_YESTERDAY] => денежная сумма событий данного типа на возврате по РК за вчера
    [MONEY_BACK_BEF_YESTERDAY] => денежная сумма событий данного типа на возврате по РК
       за позавчера
    [MONEY_BACK_PERIOD] => денежная сумма событий данного типа на возврате по РК за период
)

См. также

  • Термин "Рекламная кампания"
  • Термин "Событие"

Примеры использования

<?
$adv_id = 1;

// отфильтруем по типам события "download / file1" и "download / file2"
// а также получим дополнительные данные за декабрь 2005 года
$arFilter = array(
    "EVENT1"       => "download",
    "EVENT2"       => "file1 | file2",
    "DATE1_PERIOD" => "01.12.2005",
    "DATE2_PERIOD" => "31.12.2005"
    );

// получим список записей
$rs = CAdv::GetEventList(
    $adv_id,
    ($by="s_counter"),
    ($order="desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CAdv::GetList

CDBResult
CAdv::GetList(
 string &by = "SESSIONS",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 mixed limit = "",
 array &referer_group,
 string &sql
)

Возвращает список рекламных кампаний (РК) с рассчитанными статистическими показателями и со всеми данными по трафику.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • ID - ID РК;
  • PRIORITY - приоритет;
  • REFERER1 - идентификатор referer1 РК;
  • REFERER2 - идентификатор referer2 РК;
  • C_TIME_FIRST - время начала РК (первый прямой заход);
  • C_TIME_LAST - последний прямой заход или возврат по РК;
  • ADV_TIME - длительность РК (разница C_TIME_LAST - C_TIME_FIRST);
  • ATTENT - коэфициент внимательности посетителей на прямом заходе по РК;
  • ATTENT_BACK - коэфициент внимательности посетителей на возврате по РК;
  • NEW_VISITORS - процент посетителей впервые пришедших на сайт по данной РК от общего количества посетителей пришедших по данной РК;
  • RETURNED_VISITORS - процент посетителей возвратившихся на сайт после прямого захода по данной РК;
  • VISITORS_PER_DAY - среднее количество посетителей за день;
  • COST - затраты на РК;
  • REVENUE - доходы с РК;
  • BENEFIT - прибыль РК;
  • ROI - рентабельность РК;
  • SESSION_COST - средняя стоимость сессии (затраты/кол-во сессий на прямом заходе);
  • VISITOR_COST - средняя стоимость посетителя (затраты/кол-во посетителей на прямых заходах);
  • GUESTS - суммарное кол-во посетителей на прямых заходах;
  • GUESTS_BACK - суммарное кол-во посетителей на возвратах;
  • NEW_GUESTS - суммарное кол-во новых посетителей по данной РК;
  • FAVORITES - суммарное кол-во посетителей, добавивших сайт в "Избранное" на прямом заходе по РК;
  • FAVORITES_BACK - суммарное кол-во посетителей, добавивших сайт в "Избранное" на возврате по РК;
  • C_HOSTS - суммарное кол-во хостов на прямом заходе по РК;
  • HOSTS_BACK - суммарное кол-во хостов на возврате по РК;
  • SESSIONS - суммарное кол-во сессий на прямом заходе по РК;
  • SESSIONS_BACK - суммарное кол-во сессий на возврате по РК;
  • HITS - суммарное кол-во хитов на прямом заходе по РК;
  • HITS_BACK - суммарное кол-во хитов на возврате по РК;
  • GUESTS_TODAY - кол-во посетителей на прямом заходе за сегодня;
  • GUESTS_BACK_TODAY - кол-во посетителей на возврате за сегодня;
  • NEW_GUESTS_TODAY - кол-во новых посетителей за сегодня;
  • FAVORITES_TODAY - кол-во посетителей, добавивших сайт в "Избранное" на прямом заходе за сегодня;
  • FAVORITES_BACK_TODAY - кол-во посетителей, добавивших сайт в "Избранное" на возврате за сегодня;
  • C_HOSTS_TODAY - кол-во хостов на прямом заходе за сегодня;
  • HOSTS_BACK_TODAY - кол-во хостов на возврате за сегодня;
  • SESSIONS_TODAY - кол-во сессий на прямом заходе за сегодня;
  • SESSIONS_BACK_TODAY - кол-во сессий на возврате за сегодня;
  • HITS_TODAY - кол-во хитов на прямом заходе за сегодня;
  • HITS_BACK_TODAY - кол-во хитов на возврате за сегодня;
  • GUESTS_YESTERDAY - кол-во посетителей на прямом заходе за вчера;
  • GUESTS_BACK_YESTERDAY - кол-во посетителей на возврате за вчера;
  • NEW_GUESTS_YESTERDAY - кол-во новых посетителей за вчера;
  • FAVORITES_YESTERDAY - кол-во посетителей, добавивших сайт в "Избранное" на прямом заходе за вчера;
  • FAVORITES_BACK_YESTERDAY - кол-во посетителей, добавивших сайт в "Избранное" на возврате за вчера;
  • C_HOSTS_YESTERDAY - кол-во хостов на прямом заходе за вчера;
  • HOSTS_BACK_YESTERDAY - кол-во хостов на возврате за вчера;
  • SESSIONS_YESTERDAY - кол-во сессий на прямом заходе за вчера;
  • SESSIONS_BACK_YESTERDAY - кол-во сессий на возврате за вчера;
  • HITS_YESTERDAY - кол-во хитов на прямом заходе за вчера;
  • HITS_BACK_YESTERDAY - кол-во хитов на возврате за вчера;
  • GUESTS_BEF_YESTERDAY - кол-во посетителей на прямом заходе за позавчера;
  • GUESTS_BACK_BEF_YESTERDAY - кол-во посетителей на возврате за позавчера;
  • NEW_GUESTS_BEF_YESTERDAY - кол-во новых посетителей за позавчера;
  • FAVORITES_BEF_YESTERDAY - кол-во посетителей, добавивших сайт в "Избранное" на прямом заходе за позавчера;
  • FAVORITES_BACK_BEF_YESTERDAY - кол-во посетителей, добавивших сайт в "Избранное" на возврате за позавчера;
  • C_HOSTS_BEF_YESTERDAY - кол-во хостов на прямом заходе за позавчера;
  • HOSTS_BACK_BEF_YESTERDAY - кол-во хостов на возврате за позавчера;
  • SESSIONS_BEF_YESTERDAY - кол-во сессий на прямом заходе за позавчера;
  • SESSIONS_BACK_BEF_YESTERDAY - кол-во сессий на возврате за позавчера;
  • HITS_BEF_YESTERDAY - кол-во хитов на прямом заходе за позавчера;
  • HITS_BACK_BEF_YESTERDAY - кол-во хитов на возврате за позавчера;
  • GUESTS_PERIOD - кол-во посетителей на прямом заходе за установленный в фильтре (filter) интервал времени;
  • GUESTS_BACK_PERIOD - кол-во посетителей на возврате за установленный в фильтре интервал времени;
  • NEW_GUESTS_PERIOD - кол-во новых посетителей за установленный в фильтре интервал времени;
  • FAVORITES_PERIOD - кол-во посетителей, добавивших сайт в "Избранное" на прямом заходе за установленный в фильтре интервал времени;
  • FAVORITES_BACK_PERIOD - кол-во посетителей, добавивших сайт в "Избранное" на возврате за установленный в фильтре интервал времени;
  • C_HOSTS_PERIOD - кол-во хостов на прямом заходе за установленный в фильтре интервал времени;
  • HOSTS_BACK_PERIOD - кол-во хостов на возврате за установленный в фильтре интервал времени;
  • SESSIONS_PERIOD - кол-во сессий на прямом заходе за установленный в фильтре интервал времени;
  • SESSIONS_BACK_PERIOD - кол-во сессий на возврате за установленный в фильтре интервал времени;
  • HITS_PERIOD - кол-во хитов на прямом заходе за установленный в фильтре интервал времени;
  • HITS_BACK_PERIOD - кол-во хитов на возврате за установленный в фильтре интервал времени.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • GROUP - список возможных значений:
    • referer1 - список РК будет сгруппирован по идентификатору referer1 РК;
    • referer2 - список РК будет сгруппирован по идентификатору referer2 РК.
  • ID* - ID РК;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • DATE1_PERIOD - начальное значение периода за который необходимо получить данные;
  • DATE2_PERIOD - конечное значение периода за который необходимо получить данные;
  • DATE1_FIRST - начальное значение интервала для поля "время начала РК";
  • DATE2_FIRST - конечное значение интервала для поля "время начала РК";
  • DATE1_LAST - начальное значение интервала для поля "время окончания РК";
  • DATE2_LAST - конечное значение интервала для поля "время окончания РК";
  • REFERER1* - идентификатор referer1 РК;
  • REFERER1_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER1 будет искаться точное совпадение;
  • REFERER2* - идентификатор referer2 РК;
  • REFERER2_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER2 будет искаться точное совпадение;
  • PRIORITY1 - начальное значение интервала для поля "приоритет РК";
  • PRIORITY2 - конечное значение интервала для поля "приоритет РК";
  • NEW_GUESTS1 - начальное значение интервала для поля "новые посетители РК";
  • NEW_GUESTS2 - конечное значение интервала для поля "новые посетители РК";
  • GUESTS_BACK - флаг означающий по какому полю фильтровать посетителей, список возможных значений:
    • N - на прямом заходе;
    • Y - на возврате.
  • GUESTS1 - начальное значение интервала для поля "посетители на прямом заходе или на возврате" (в зависимости от флага GUESTS_BACK);
  • GUESTS2 - конечное значение интервала для поля "посетители на прямом заходе или на возврате" (в зависимости от флага GUESTS_BACK);
  • FAVORITES_BACK - флаг означающий по какому полю фильтровать посетителей, добавившие сайт в "Избранное", список возможных значений:
    • N - на прямом заходе;
    • Y - на возврате.
  • FAVORITES1 - начальное значение интервала для поля "посетители, добавившие сайт в Избранное на прямом заходе или возврате" (в зависимости от флага FAVORITES_BACK);
  • FAVORITES2 - конечное значение интервала для поля "посетители, добавившие сайт в Избранное на прямом заходе или возврате" (в зависимости от флага FAVORITES_BACK);
  • HOSTS_BACK - флаг означающий по какому полю фильтровать хосты, список возможных значений:
    • N - на прямом заходе;
    • Y - на возврате.
  • HOSTS1 - начальное значение интервала для поля "хосты на прямом заходе или возврате" (в зависимости от флага HOSTS_BACK);
  • HOSTS2 - конечное значение интервала для поля "хосты на прямом заходе или возврате" (в зависимости от флага HOSTS_BACK);
  • SESSIONS_BACK - флаг означающий по какому полю фильтровать сессии, список возможных значений:
    • N - на прямом заходе;
    • Y - на возврате.
  • SESSIONS1 - начальное значение интервала для поля "сессии на прямом заходе или возврате" (в зависимости от флага SESSIONS_BACK);
  • SESSIONS2 - конечное значение интервала для поля "сессии на прямом заходе или возврате" (в зависимости от флага SESSIONS_BACK);
  • HITS_BACK - флаг означающий по какому полю фильтровать хиты, список возможных значений:
    • N - на прямом заходе;
    • Y - на возврате.
  • HITS1 - начальное значение интервала для поля "хиты на прямом заходе или возврате" (в зависимости от флага HITS_BACK);
  • HITS2 - конечное значение интервала для поля "хиты на прямом заходе или возврате" (в зависимости от флага HITS_BACK);
  • COST1 - начальное значение интервала для поля "затраты на РК";
  • COST2 - конечное значение интервала для поля "затраты на РК";
  • REVENUE1 - начальное значение интервала для поля "доходы с РК";
  • REVENUE2 - конечное значение интервала для поля "доходы с РК";
  • BENEFIT1 - начальное значение интервала для поля "прибыль с РК";
  • BENEFIT2 - конечное значение интервала для поля "прибыль с РК";
  • ROI1 - начальное значение интервала для поля "рентабельность РК";
  • ROI2 - конечное значение интервала для поля "рентабельность РК";
  • ATTENT1 - начальное значение интервала для поля "коэфициент внимательности посетителей РК";
  • ATTENT2 - конечное значение интервала для поля "коэфициент внимательности посетителей РК";
  • VISITORS_PER_DAY1 - начальное значение интервала для поля "среднее кол-во посетителей в день";
  • VISITORS_PER_DAY2 - конечное значение интервала для поля "среднее кол-во посетителей в день";
  • DURATION1 - начальное значение интервала для поля "длительность РК";
  • DURATION2 - конечное значение интервала для поля "длительность РК";
  • CURRENCY - валюта в которой заданы финансовые показатели РК;
  • DESCRIPTION* - описание РК;
  • DESCRIPTION_EXACT_MATCH - если значение равно "Y", то при фильтрации по DESCRIPTION будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка рекламных кампаний. Если значение равно "true", то список был отфильтрован.
limit | Максимальное число РК которые будут выбраны в списке. Если значение равно "", то кол-во РК будет ограничено в соответствии со значением параметра "Максимальное кол-во показываемых записей в таблицах" из настроек модуля "Статистика".
referer_group Ссылка на массив инициализируемый только при установленной группировке по referer1 или referer2 (если filter["GROUP"]="referer1" или filter["GROUP"]="referer2"). Структура данного массива:
[referer1 или referer2] => Array
    (
        [REFERER1] => referer1 или
        [REFERER2] => referer2

        [GUESTS_TODAY] => посетителей на прямом заходе за сегодня
        [GUESTS_BACK_TODAY] => посетителей на возврате за сегодня
        [NEW_GUESTS_TODAY] => новых посетителей за сегодня
        [FAVORITES_TODAY] => посетителей, добавивших сайт в "Избранное"
            на прямом заходе за сегодня
        [FAVORITES_BACK_TODAY] => посетителей, добавившие сайт в "Избранное"
            на возврате за сегодня
        [C_HOSTS_TODAY] => хостов на прямом заходе за сегодня
        [HOSTS_BACK_TODAY] => хостов на возврате за сегодня
        [SESSIONS_TODAY] => сессий на прямом заходе за сегодня
        [SESSIONS_BACK_TODAY] => сессий на возврате за сегодня
        [HITS_TODAY] => хитов на прямом заходе за сегодня
        [HITS_BACK_TODAY] => хитов на возврате за сегодня

        [GUESTS_YESTERDAY] => посетителей на возврате за вчера
        [GUESTS_BACK_YESTERDAY] => посетителей на возврате за вчера
        [NEW_GUESTS_YESTERDAY] => новых посетителей за вчера
        [FAVORITES_YESTERDAY] => посетителей, добавившие сайт в
            "Избранное" на прямом заходе за вчера
        [FAVORITES_BACK_YESTERDAY] => посетителей, добавившие сайт в
            "Избранное" на возврате за вчера
        [C_HOSTS_YESTERDAY] => хостов на прямом заходе за вчера
        [HOSTS_BACK_YESTERDAY] => хостов на возврате за вчера
        [SESSIONS_YESTERDAY] => сессий на прямом заходе за вчера
        [SESSIONS_BACK_YESTERDAY] => сессий на возврате за вчера
        [HITS_YESTERDAY] => хитов на прямом заходе за вчера
        [HITS_BACK_YESTERDAY] => хитов на возврате за вчера

        [GUESTS_BEF_YESTERDAY] => посетителей на прямом заходе за позавчера
        [NEW_GUESTS_BEF_YESTERDAY] => новых посетителей за позавчера
        [FAVORITES_BEF_YESTERDAY] => посетителей, добавившие сайт в
            "Избранное" на прямом заходе за позавчера
        [C_HOSTS_BEF_YESTERDAY] => хостов на прямом заходе за позавчера
        [SESSIONS_BEF_YESTERDAY] => сессий на прямом заходе за позавчера
        [HITS_BEF_YESTERDAY] => хитов на прямом заходе за позавчера
        [GUESTS_BACK_BEF_YESTERDAY] => посетителей на возврате за позавчера
        [FAVORITES_BACK_BEF_YESTERDAY] => посетителей, добавившие сайт в
           "Избранное" на возврате за позавчера
        [HOSTS_BACK_BEF_YESTERDAY] => хостов на возврате за позавчера
        [SESSIONS_BACK_BEF_YESTERDAY] => сессий на возврате за позавчера
        [HITS_BACK_BEF_YESTERDAY] => хитов на возврате за позавчера

        [GUESTS_PERIOD] => посетителей на прямом заходе за период времени
            (установка периода времени осушествляется инициализацией
            filter["DATE1_PERIOD"] и/или filter["DATE2_PERIOD"])
        [GUESTS_BACK_PERIOD] => посетителей на возврате за период времени
        [NEW_GUESTS_PERIOD] => новые посетители на прямом заходе за
             период времени
        [C_HOSTS_PERIOD] => хосты на прямом заходе за период времени
        [HOSTS_BACK_PERIOD] => хостов на возврате за период времени
        [FAVORITES_PERIOD] => посетителей, добавившие сайт в
            "Избранное" на прямом заходе за период времени
        [FAVORITES_BACK_PERIOD] => посетителей, добавившие сайт в
            "Избранное" на возврате за период времени
        [SESSIONS_PERIOD] => сессий на прямом заходе за период времени
        [SESSIONS_BACK_PERIOD] => сессий на возврате за период времени
        [HITS_PERIOD] => хитов на прямом заходе за период времени
        [HITS_BACK_PERIOD] => хитов на возврате за период времени
    )
sql | Ссылка на результирующий SQL запрос по которому будет выбран список РК.

Структура возвращаемой записи

Array
(
    [ID] => ID
    [PRIORITY] => приоритет
    [REFERER1] => идентификатор referer1
    [REFERER2] => идентификатор referer2
    [DESCRIPTION] => описание
    [EVENTS_VIEW] => режим показа списка событий, возможные значения:
        link - ссылкой на список
        list - списком
        event1 - сгруппированными по event1
        event2 - сгруппированными по event2

    [DATE_FIRST] => дата первого прямого захода
    [DATE_LAST] => дата последнего прямого захода или возврата
    [ADV_TIME] => длительность РК в секундах

    [ATTENT] => внимательность на прямом заходе
    [ATTENT_BACK] => внимательность на возврате
    [NEW_VISITORS] => процент новых посетителей
    [RETURNED_VISITORS] => процент вернувшихся на сайт посетителей после прямого захода
    [VISITORS_PER_DAY] => среднее кол-во посетителей в день

    [CURRENCY] => валюта в которой заданы финансовые показатели
    [COST] => затраты
    [REVENUE] => доход
    [BENEFIT] => прибыль
    [SESSION_COST] => стоимость сессии
    [VISITOR_COST] => стоимость посетителя
    [ROI] => рентабельность

    [GUESTS] => суммарное кол-во посетителей на прямом заходе
    [NEW_GUESTS] => суммарное кол-во новых посетителей на прямом заходе
    [FAVORITES] => суммарное кол-во посетителей, добавившие сайт в "Избранное"
        на прямом заходе
    [C_HOSTS] => суммарное кол-во хостов на прямом заходе
    [SESSIONS] => суммарное кол-во сессий на прямом заходе
    [HITS] => суммарное кол-во хитов на прямом заходе
    [GUESTS_BACK] => суммарное кол-во посетителей на возврате
    [FAVORITES_BACK] => суммарное кол-во посетителей, добавившие сайт в "Избранное"
        на возврате
    [HOSTS_BACK] => суммарное кол-во хостов на возврате
    [SESSIONS_BACK] => суммарное кол-во сессий на возврате
    [HITS_BACK] => суммарное кол-во хитов на возврате

    [GUESTS_TODAY] => посетителей на прямом заходе за сегодня
    [GUESTS_BACK_TODAY] => посетителей на возврате за сегодня
    [NEW_GUESTS_TODAY] => новых посетителей на возврате за сегодня
    [FAVORITES_TODAY] => посетителей, добавившие сайт в "Избранное" на прямом заходе
        за сегодня
    [FAVORITES_BACK_TODAY] => посетителей, добавившие сайт в "Избранное" на возврате
        за сегодня
    [C_HOSTS_TODAY] => хостов на прямом заходе за сегодня
    [HOSTS_BACK_TODAY] => хостов на возврате за сегодня
    [SESSIONS_TODAY] => сессий на прямом заходе за сегодня
    [SESSIONS_BACK_TODAY] => сессий на возврате за сегодня
    [HITS_TODAY] => хитов на прямом заходе за сегодня
    [HITS_BACK_TODAY] => хитов на возврате за сегодня

    [GUESTS_YESTERDAY] => посетителей на прямом заходе за вчера
    [GUESTS_BACK_YESTERDAY] => посетителей на возврате за вчера
    [NEW_GUESTS_YESTERDAY] => новых посетителей на возврате за вчера
    [FAVORITES_YESTERDAY] => посетителей, добавившие сайт в "Избранное" на прямом заходе
        за вчера
    [FAVORITES_BACK_YESTERDAY] => посетителей, добавившие сайт в "Избранное" на возврате
        за вчера
    [C_HOSTS_YESTERDAY] => хостов на прямом заходе за вчера
    [HOSTS_BACK_YESTERDAY] => хостов на возврате за вчера
    [SESSIONS_YESTERDAY] => сессий на прямом заходе за вчера
    [SESSIONS_BACK_YESTERDAY] => сессий на возврате за вчера
    [HITS_YESTERDAY] => хитов на прямом заходе за вчера
    [HITS_BACK_YESTERDAY] => хитов на возврате за вчера

    [GUESTS_BEF_YESTERDAY] => посетителей на прямом заходе за позавчера
    [GUESTS_BACK_BEF_YESTERDAY] => посетителей на возврате за позавчера
    [NEW_GUESTS_BEF_YESTERDAY] => новых посетителей на возврате за позавчера
    [FAVORITES_BEF_YESTERDAY] => посетителей, добавившие сайт в "Избранное"
        на прямом заходе за позавчера
    [FAVORITES_BACK_BEF_YESTERDAY] => посетителей, добавившие сайт в "Избранное"
        на возврате за позавчера
    [C_HOSTS_BEF_YESTERDAY] => хостов на прямом заходе за позавчера
    [HOSTS_BACK_BEF_YESTERDAY] => хостов на возврате за позавчера
    [SESSIONS_BEF_YESTERDAY] => сессий на прямом заходе за позавчера
    [SESSIONS_BACK_BEF_YESTERDAY] => сессий на возврате за позавчера
    [HITS_BEF_YESTERDAY] => хитов на прямом заходе за позавчера
    [HITS_BACK_BEF_YESTERDAY] => хитов на возврате за позавчера

    [GUESTS_PERIOD] => посетителей на прямом заходе за период
    [GUESTS_BACK_PERIOD] => посетителей на возврате за период
    [NEW_GUESTS_PERIOD] => новых посетителей на возврате за период
    [FAVORITES_PERIOD] => посетителей, добавившие сайт в "Избранное" на прямом заходе
        за период
    [FAVORITES_BACK_PERIOD] => посетителей, добавившие сайт в "Избранное" на возврате
        за период
    [C_HOSTS_PERIOD] => хостов на прямом заходе за период
    [HOSTS_BACK_PERIOD] => хостов на возврате за период
    [SESSIONS_PERIOD] => сессий на прямом заходе за период
    [SESSIONS_BACK_PERIOD] => сессий на возврате за период
    [HITS_PERIOD] => хитов на прямом заходе за период
    [HITS_BACK_PERIOD] => хитов на возврате за период
)

См. также

  • Термин "Рекламная кампания"
  • CAdv::GetSimpleList
  • CAdv::GetDropdownList

Примеры использования

<?
// отфильтруем по рекламным кампаниям в referer1 которых входит "google"
// а также получим дополнительные данные за декабрь 2005 года
$arFilter = array(
    "REFERER1"     => "google",
    "DATE1_PERIOD" => "01.12.2005",
    "DATE2_PERIOD" => "31.12.2005"
    );

// получим список записей
$rs = CAdv::GetList(
    ($by="SESSIONS"),
    ($order="desc"),
    $arFilter,
    $is_filtered,
    "",
    $referer_group,
    $sql
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetSimpleList

CAdv::GetSimpleList

CDBResult
CAdv::GetSimpleList(
 string &by = "s_referer1",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает упрощённый список рекламных кампаний (РК).

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID РК;
  • s_referer1 - идентификатор referer1 РК;
  • s_referer2 - идентификатор referer2 РК;
  • s_description - описание РК.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID РК;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • REFERER1* - идентификатор referer1 РК;
  • REFERER1_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER1 будет искаться точное совпадение;
  • REFERER2* - идентификатор referer2 РК;
  • REFERER2_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER2 будет искаться точное совпадение;
  • DESCRIPTION* - описание РК;
  • DESCRIPTION_EXACT_MATCH - если значение равно "Y", то при фильтрации по DESCRIPTION будет искаться точное совпадение.
* - допускается сложная логика (см. Пользовательскую документацию, раздел Общая информация > Сложная логика в фильтре)
is_filtered | Флаг отфильтрованности списка рекламных кампаний. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID
    [REFERER1] => идентификатор referer1
    [REFERER2] => идентификатор referer2
    [DESCRIPTION] => описание
)

См. также

  • Термин "Рекламная кампания"
  • CAdv::GetList
  • CAdv::GetDropdownList

Примеры использования

<?
// выберем только те рекламные кампании у которых в referer1 входит "google"
$arFilter = array(
    "REFERER1" => "google"
    );

// получим список записей
$rs = CAdv::GetSimpleList(
    ($by="s_referer1"),
    ($order="desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Reset

CAdv::Reset

bool
CAdv::Reset(
 int adv_id
)

Обнуляет статистические данные рекламной кампании.

Параметры функции

Параметр | Описание
adv_id | ID рекламной кампании.

См. также

  • Термин "Рекламная кампания"
  • CAdv::Delete

Примеры использования

<?
$adv_id = 1;
if (CAdv::Reset($adv_id))
    echo "Данные по рекламной кампании #".$adv_id." успешно удалены.";
?>


Класс CAutoDetect

CAutoDetect - класс для поиска неизвестных UserAgent'ов.

Методы класса

Метод | Описание
GetList | Возвращает список незнакомых UserAgent'ов.

См. также

  • Пользовательскую документацию, раздел Веб-аналитика > Поисковые системы > Автодетект


GetList

CAutoDetect::GetList

CDBResult
CAutoDetect::GetList(
 string &by = "s_counter",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список незнакомых UserAgent'ов. Функция анализирует список сессий, и собирает все UserAgent'ы которые не принадлежат ни одной поисковой системе и ни одному браузеру (UserAgent'ы браузеров задаются в настройках модуля "Статистика").

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_user_agent - UserAgent;
  • s_counter - количество сессий.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • LAST - флаг определяющий какие сессии буду анализироваться, возможные значения:
    • Y - за текущий день;
    • N - за предыдущие дни (не включая текущий).
  • USER_AGENT* - искомый UserAgent (маска, либо его часть);
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение;
  • COUNTER1 - начальное значение интервала для поля "количество сессий";
  • COUNTER2 - конечное значение интервала для поля "количество сессий".
* - допускается сложная логика (Пользовательская документация, раздел Общая информация > Сложная логика в фильтре)
is_filtered | Флаг отфильтрованности списка UserAgent'ов. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [USER_AGENT] => UserAgent
    [COUNTER] => кол-во сессий
)

См. также

  • Пользовательскую документацию, раздел Веб-аналитика > Поисковые системы > Автодетект

Примеры использования

<?
// выберем данные только за последний день
$arFilter = array(
    "LAST" => "Y"
    );

// получим список записей
$rs = CAutoDetect::GetList(
    ($by = "s_counter"),
    ($order = "desc"),
    $arFilter = array(),
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CCountry

CCountry - класс для получения данных по трафику в разрезе по странами.

Методы класса

Метод | Описание
GetGraphArray | Возвращает данные необходимые для построения графика и круговой диаграммы посещаемости в разрезе по странам.
GetList | Возвращает список стран, определённых в модуле "Статистика".

См. также

  • Пользовательскую документацию, "География по странам"


GetGraphArray

CCountry::GetGraphArray

array
CCountry::GetGraphArray(
 array filter,
 array &legend
)

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

Параметры функции

Параметр Описание
filter Массив для фильтрации стран. В массиве допустимы следующие ключи:
  • COUNTRY_ID - двухсимвольный идентификатор страны;
  • DATE1 - начальное значение интервала времени;
  • DATE2 - конечное значение интервала времени.
legend Массив содержащий суммарные показатели по каждой стране, а также цвет линии графика и сектора круговой диаграммы для каждой страны. Структура данного массива:
Array
(
    [ID страны] => Array
        (
            [NAME] => название страны
            [SESSIONS] => кол-во сессий за интервал времени
            [NEW_GUESTS] => кол-во новых посетителей за интервал времени
            [HITS] => кол-во хитов за интервал времени
            [C_EVENTS] => кол-во событий за интервал времени
            [TOTAL_SESSIONS] => суммарное кол-во сессий
            [TOTAL_NEW_GUESTS] => суммарное кол-во новых посетителей
            [TOTAL_HITS] => суммарное кол-во хитов
            [TOTAL_C_EVENTS] => суммарное кол-во событий
            [COLOR] => цвет линии графика и сектора круговой диаграммы
        )
    ...
)

Структура возвращаемого массива

Array
(
    [дата] => Array
        (
            [D] => день (1-31)
            [M] => месяц (1-12)
            [Y] => год
            [ID страны] => Array
                (
                    [SESSIONS] => кол-во сессий по стране за дату
                    [NEW_GUESTS] => кол-во новых посетителей по стране за дату
                    [HITS] => кол-во хитов по стране за дату
                    [C_EVENTS] => кол-во событий по стране за дату
                )
            ...

        )
    ...
)

См. также

  • Пользовательскую документацию, "География по странам"

Примеры использования

<?
// отфильтруем данные только по России на декабрь 2007 года
$arFilter = Array(
    "COUNTRY_ID" => "ru",
    "DATE1"      => "01.12.2007",
    "DATE2"      => "31.12.2007"
    );

// получим массив данных в разрезе по дням
$arDays = CCountry::GetGraphArray($arFilter, $arLegend);

// выведем полученные данные по России за декабрь 2007 года
while (list($date, $arr) = each($arrDays))
{
    echo "Дата: ".$date."<br>";
    echo "Данные на эту дату: <pre>"; print_r($arr); echo "</pre>";
}
?>


GetList

CCountry::GetList

CDBResult
CCountry::GetList(
 string &by = "s_name",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список стран, определённых в модуле "Статистика". Загрузка списка стран осуществляется при переиндексации базы IP адресов в настройках модуля "Статистика".

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - двухсимвольный идентификатор страны;
  • s_short_name - трехсимвольный идентификатор страны;
  • s_name - наименование страны;
  • s_sessions - суммарное кол-во сессий по данной стране;
  • s_new_guests - суммарное кол-во новых посетителей по данной стране;
  • s_hits - суммарное кол-во хитов по данной стране;
  • s_events - суммарное кол-во событий по данной стране.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - двухсимвольный идентификатор страны;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SHORT_NAME* - трехсимвольный идентификатор страны;
  • SHORT_NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по SHORT_NAME будет искаться точное совпадение;
  • NAME* - наименование страны;
  • NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по NAME_EXACT_MATCH будет искаться точное совпадение;
  • SESSIONS1 - начальное значение интервала для поля "кол-во сессий";
  • SESSIONS2 - конечное значение интервала для поля "кол-во сессий";
  • NEW_GUESTS1 - начальное значение интервала для поля "кол-во новых посетителей";
  • NEW_GUESTS2 - конечное значение интервала для поля "кол-во новых посетителей";
  • HITS1 - начальное значение интервала для поля "кол-во хитов";
  • HITS2 - конечное значение интервала для поля "кол-во хитов";
  • EVENTS1 - начальное значение интервала для поля "кол-во событий";
  • EVENTS2 - конечное значение интервала для поля "кол-во событий".

    * - допускается сложная логика
is_filtered | Флаг отфильтрованности списка UserAgent'ов. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => двухсимвольный идентификатор страны
    [SHORT_NAME] => трехсимвольный идентификатор страны
    [NAME] => название страны
    [SESSIONS] => суммарное кол-во сессий
    [NEW_GUESTS] => суммарное кол-во новых посетителей
    [HITS] => суммарное кол-во хитов
    [C_EVENTS] => суммарное кол-во событий
    [REFERENCE_ID] => параметр REFERENCE_ID для использования в
        функции SelectBox или SelectBoxM
    [REFERENCE] => параметр REFERENCE для использования в
        функции SelectBox или SelectBoxM
)

См. также

  • Пользовательскую документацию, настройки модуля "Статистика"
  • SelectBox
  • SelectBoxM

Примеры использования

<?
// выберем только те страны из которых было не менее 100 заходов на сайт
$arFilter = array(
    "SESSIONS1" => 100
    );

// получим список записей
$rs = CCountry::GetList(
    ($by = "s_name"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>

<?
// выпадающий список с одиночным выбором
echo SelectBox("COUNTRY_ID", CCountry::GetList(), "", intval($COUNTRY_ID));

// список из 20 видимых элементов с возможностью множественного выбора
echo SelectBoxM("arCOUNTRY_ID[]", CCountry::GetList(), $arCOUNTRY_ID, "", false, 20);
?>


Класс CGuest

CGuest - класс для получения данных по посетителям сайта.

Методы класса

Метод | Описание
GetByID | Возвращает данные по указанному посетителю.
GetList | Возвращает список посетителей.

См. также

  • Термин "Посетитель"
  • Пользовательская документация, отчет "Посетители"


GetByID

CGuest::GetByID

CDBResult
CGuest::GetByID(
 int guest_id
)

Возвращает данные по указанному посетителю.

Параметры функции

Параметр | Описание
guest_id | ID посетителя.

Структура возвращаемой записи

Array
(
    [ID] => ID посетителя
    [FAVORITES] => [Y|N] флаг добавления сайта в "Избранное"
    [C_EVENTS] => количество событий сгенерированных данным посетителей
    [SESSIONS] => количество сессий данного посетителя
    [HITS] => количество хитов данного посетителя
    [REPAIR] => [Y|N] флаг того что данный посетитель был "восстановлен" после очистки устаревших данных (Y)
    [FIRST_SESSION_ID] => ID сессии первого захода на сайт
    [FSESSION_TIME] => длительность первой сессии посетителя (сек.)
    [FSESSION_HITS] => кол-во хитов первой сессии посетителя
    [FIRST_DATE] => время первого захода на сайт
    [FIRST_URL_FROM] => адрес страницы с которой посетитель впервые пришел на сайт
    [FIRST_URL_TO] => адрес страницы сайта на которую посетитель впервые пришел
    [FIRST_URL_TO_404] => флаг 404 ошибки на странице сайта на которую посетитель впервые пришел
    [FIRST_SITE_ID] => ID сайта на который посетитель впервые пришел
    [FIRST_ADV_ID] => ID рекламной кампании по которой посетитель впервые пришел на сайт
    [FIRST_REFERER1] => идентификатор referer1 рекламной кампании FIRST_ADV_ID
    [FIRST_REFERER2] => идентификатор referer2 рекламной кампании FIRST_ADV_ID
    [FIRST_REFERER3] => дополнительный параметр referer3 рекламной кампании FIRST_ADV_ID
    [LAST_SESSION_ID] => ID сессии последнего захода на сайт
    [LSESSION_TIME] => длительность последней сессии посетителя (сек.)
    [LSESSION_HITS] => кол-во хитов последней сессии посетителя
    [LAST_DATE] => время последнего захода на сайт
    [LAST_USER_ID] => ID пользователя
    [USER_NAME] => имя и фамилия пользователя под которым посетитель был авторизован последний раз
    [LOGIN] => логин пользователя под которым посетитель был авторизован последний раз
    [LAST_USER_AUTH] => [Y|N] был ли авторизован посетитель в последнем заходе на сайт
    [LAST_URL_LAST] => адрес последней страницы на которую зашел посетитель
    [LAST_URL_LAST_404] => флаг 404 ошибки (страница не существует) на последней странице сайта на которую зашел посетитель
    [LAST_USER_AGENT] => UserAgent посетителя в последнем заходе
    [LAST_IP] => IP адрес посетителя сайта в последнем заходе
    [LAST_COOKIE] => Cookie посетителя сайта в последнем заходе
    [LAST_LANGUAGE] => языки установленные в настройках браузера посетителя в последнем заходе
    [LAST_ADV_ID] => ID рекламной кампании по которой посетитель пришел на сайт в последнем заходе
    [LAST_ADV_BACK] => [Y|N] флаг того был ли это возврат (Y) или прямой заход (N) по рекламной кампании LAST_ADV_ID
    [LAST_REFERER1] => идентификатор referer1 рекламной кампании LAST_ADV_ID
    [LAST_REFERER2] => идентификатор referer2 рекламной кампании LAST_ADV_ID
    [LAST_REFERER3] => дополнительный параметр referer3 рекламной кампании LAST_ADV_ID
    [LAST_SITE_ID] => ID сайта последнего захода
    [LAST_COUNTRY_ID] => ID страны посетителя в последнем заходе
    [COUNTRY_NAME] => название страны посетителя в последнем заходе
)

См. также

  • Термин "Посетитель"

Примеры использования

<?
$guest_id = 1;
if ($rs = CGuest::GetByID($guest_id))
{
    $ar = $rs->Fetch();
    // выведем параметры посетителя
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CGuest::GetList

CDBResult
CGuest::GetList(
 string &by = "s_last_date",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список посетителей.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID посетителя;
  • s_events - суммарное кол-во событий сгенерированных посетителем;
  • s_sessions - суммарное кол-во сессий посетителя;
  • s_hits - суммарное кол-во хитов посетителя;
  • s_first_site_id - ID сайта на который впервые пришел посетитель;
  • s_first_date - время первого захода на сайт;
  • s_first_url_from - страница с которой впервые пришел посетитель;
  • s_first_url_to - страница куда впервые пришел посетитель;
  • s_first_adv_id - ID рекламной кампании первого захода;
  • s_last_site_id - ID сайта последнего захода посетителя;
  • s_last_date - время последнего захода поестителя;
  • s_last_user_id - ID пользователя;
  • s_last_url_last - последняя страница на которую заходил посетитель;
  • s_last_user_agent - UserAgent посетителя на последнем заходе;
  • s_last_ip - IP адрес посетителя на последнем заходе;
  • s_last_adv_id - ID рекламной кампании на последнем заходе;
  • s_last_country_id - ID страны посетителя на последнем заходе.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID посетителя;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • REGISTERED - был ли посетитель когда либо авторизован на сайте, возможные значения:
    • Y - был;
    • N - не был.
  • FIRST_DATE1 - начальное значение интервала для поля "дата первого захода на сайт";
  • FIRST_DATE2 - конечное значение интервала для поля "дата первого захода на сайт";
  • LAST_DATE1 - начальное значение интервала для поля "дата последнего захода на сайт";
  • LAST_DATE2 - конечное значение интервала для поля "дата первого захода на сайт";
  • PERIOD_DATE1 - начальное значение интервала для даты посещения посетителем сайта;
  • PERIOD_DATE2 - конечно значение интервала для даты посещения посетителем сайта;
  • SITE_ID* - ID сайта первого либо последнего захода;
  • SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE_ID будет искаться вхождение;
  • FIRST_SITE_ID* - ID сайта первого захода;
  • FIRST_SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по FIRST_SITE_ID будет искаться вхождение;
  • LAST_SITE_ID* - ID сайта последнего захода;
  • LAST_SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по LAST_SITE_ID будет искаться вхождение;
  • URL* - страница откуда впервые пришел посетитель, страница на которую впервые пришел посетитель и последняя страница просмотренная посетителем;
  • URL_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL будет искаться точное совпадение;
  • URL_404 - была ли 404 ошибка на первой странице или на последней странице посещенной посетителем, возможные значения:
    • Y - была;
    • N - не было.
  • USER_AGENT* - UserAgent посетителя на последнем заходе;
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение;
  • ADV - флаг "приходил ли посетитель когда либо по рекламной кампании (не равной NA/NA)", возможные значения:
    • Y - посетитель приходил по какой либо рекламной кампании (не равной NA/NA);
    • N - не приходил никогда ни по одной рекламной кампании (не равной NA/NA).
  • ADV_ID - ID рекламной кампании первого либо последнего захода посетителя (при этом это мог быть как прямой заход так и возврат по рекламной кампании);
  • REFERER1* - идентификатор referer1 рекламной кампании первого либо последнего захода посетителя;
  • REFERER1_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER1 будет искаться точное совпадение;
  • REFERER2* - идентификатор referer2 рекламной кампании первого либо последнего захода посетителя;
  • REFERER2_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER2 будет искаться точное совпадение;
  • REFERER3* - дополнительный параметр referer3 рекламной кампании первого либо последнего захода посетителя;
  • REFERER3_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER3 будет искаться точное совпадение;
  • EVENTS1 - начальное значение для интервала кол-ва событий сгенерированных посетителем;
  • EVENTS2 - конечное значение для интервала кол-ва событий сгенерированных посетителем;
  • SESS1 - начальное значение для интервала кол-ва сессий сгенерированных посетителем;
  • SESS2 - конечное значение для интервала кол-ва сессий сгенерированных посетителем;
  • HITS1 - начальное значение для интервала кол-ва хитов сгенерированных посетителем;
  • HITS2 - конечное значение для интервала кол-ва хитов сгенерированных посетителем;
  • FAVORITES - флаг "добавлял ли посетитель сайт в "Избранное"", возможные значения:
    • Y - добавлял;
    • N - не добавлял.
  • IP - IP адрес посетителя сайта в последнем заходе;
  • LANG - языки установленные в настройках браузера посетителя в последнем заходе;
  • COUNTRY_ID* - ID страны (двухсимвольный идентификатор) посетителя в последнем заходе;
  • COUNTRY_ID_EXACT_MATCH - если значение равно "Y", то при фильтрации по COUNTRY_ID будет искаться точное совпадение;
  • COUNTRY* - название страны;
  • COUNTRY_EXACT_MATCH - если значение равно "Y", то при фильтрации по COUNTRY будет искаться точное совпадение;
  • USER* - ID, логин, имя, фамилия пользователя, под которыми посетитель последний раз был авторизован;
  • USER_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_ID будет искаться точное совпадение;
  • USER_ID* - ID пользователя, под которым посетитель последний раз был авторизован;
  • USER_ID_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER будет искаться точное совпадение.

* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка посетителей. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID посетителя
    [FAVORITES] => [Y|N] флаг добавления сайта в "Избранное"
    [C_EVENTS] => количество событий сгенерированных данным посетителей
    [SESSIONS] => количество сессий данного посетителя
    [HITS] => количество хитов данного посетителя
    [FIRST_SESSION_ID] => ID сессии первого захода на сайт
    [FIRST_DATE] => время первого захода на сайт
    [FIRST_URL_FROM] => адрес страницы с которой посетитель впервые пришел на сайт
    [FIRST_URL_TO] => адрес страницы сайта на которую посетитель впервые пришел
    [FIRST_URL_TO_404] => флаг 404 ошибки (страница не существует) на странице сайта на которую посетитель впервые пришел
    [FIRST_SITE_ID] => ID сайта на который посетитель впервые пришел
    [FIRST_ADV_ID] => ID рекламной кампании по которой посетитель впервые пришел на сайт
    [FIRST_REFERER1] => идентификатор referer1 рекламной кампании FIRST_ADV_ID
    [FIRST_REFERER2] => идентификатор referer2 рекламной кампании FIRST_ADV_ID
    [FIRST_REFERER3] => дополнительный параметр referer3 рекламной кампании FIRST_ADV_ID
    [LAST_SESSION_ID] => ID сессии последнего захода на сайт
    [LAST_DATE] => время последнего захода на сайт
    [LAST_USER_ID] => ID пользователя
    [LAST_USER_AUTH] => [Y|N] был ли авторизован посетитель в последнем заходе на сайт
    [LAST_URL_LAST] => адрес последней страницы на которую зашел посетитель
    [LAST_URL_LAST_404] => флаг 404 ошибки (страница не существует) на последней странице сайта на которую зашел посетитель
    [LAST_USER_AGENT] => UserAgent посетителя в последнем заходе
    [LAST_IP] => IP адрес посетителя сайта в последнем заходе
    [LAST_LANGUAGE] => языки установленные в настройках браузера посетителя в последнем заходе
    [LAST_ADV_ID] => ID рекламной кампании по которой посетитель пришел на сайт в последнем заходе
    [LAST_ADV_BACK] => [Y|N] флаг того был ли это возврат (Y) или прямой заход (N) по рекламной кампании LAST_ADV_ID
    [LAST_REFERER1] => идентификатор referer1 рекламной кампании LAST_ADV_ID
    [LAST_REFERER2] => идентификатор referer2 рекламной кампании LAST_ADV_ID
    [LAST_REFERER3] => дополнительный параметр referer3 рекламной кампании LAST_ADV_ID
    [LAST_SITE_ID] => ID сайта последнего захода
    [LAST_COUNTRY_ID] => ID страны посетителя в последнем заходе
    [LAST_COUNTRY_NAME] => название страны посетителя в последнем заходе (если установлено filter["COUNTRY_ID"])
)

См. также

  • Термин "Посетитель"

Примеры использования

<?
// выберем только тех посетителей UserAgent которых содержит "Opera"
$arFilter = array(
    "USER_AGENT" => "Opera"
    );

// получим список записей
$rs = CGuest::GetList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CHit

CHit - класс для получения данных по хитами посетителей.

Методы класса

Метод | Описание
GetByID | Возвращает данные по указанному хиту.
GetList | Возвращает список хитов.

См. также

  • Термин "Хит"
  • Пользовательская документация, отчет "Хиты посетителей"


GetByID

CHit::GetByID

CDBResult
CHit::GetByID(
 int hit_id
)

Возвращает данные по указанному хиту посетителя.

Параметры функции

Параметр | Описание
hit_id | ID хита.

Структура возвращаемой записи

Array
(
    [ID] => ID хита
    [SESSION_ID] => ID сессии
    [DATE_HIT] => время хита
    [GUEST_ID] => ID посетителя
    [NEW_GUEST] => [Y|N] флаг "был ли это новый посетитель на сайте" (Y)
    [USER_ID] => ID пользователя под которым посетитель был авторизован (в момент хита или до этого)
    [USER_AUTH] => флаг "был ли посетитель авторизован в момент хита"
    [URL] => страница хита
    [URL_404] => была ли 404 ошибка на странице хита
    [URL_FROM] => страница откуда пришел посетитель
    [IP] => IP адрес посетитель в момент хита
    [METHOD] => HTTP метод отсылки данных
    [COOKIES] => содержимое Cookie посетителя в момент хита
    [USER_AGENT] => UserAgent посетителя в момент хита
    [STOP_LIST_ID] => ID записи стоп-листа под которую попал посетитель (если это имело место быть)
    [COUNTRY_ID] => ID страны (двухсимвольный идентификатор) посетителя сайта в момент хита (определяется по IP адресу)
    [COUNTRY_NAME] => название страны посетителя сайта в момент хита (определяется по IP адресу)
    [SITE_ID] => ID сайта (двухсимвольный идентификатор)
    [LOGIN] => логин пользователя под которым посетитель был авторизован (в момент хита или до этого)
    [USER_NAME] => имя и фамилия пользователя под которым посетитель был авторизован (в момент хита или до этого)
)

См. также

  • Термин "Хит"

Примеры использования

<?
$hit_id = 1;
if ($rs = CHit::GetByID($hit_id))
{
    $ar = $rs->Fetch();
    // выведем параметры хита
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CHit::GetList

CDBResult
CHit::GetList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список хитов посетителей.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID хита;
  • s_site_id - ID сайта;
  • s_session_id - ID сессии;
  • s_date_hit - время хита;
  • s_user_id - ID пользователя под которым был авторизован посетитель (в момент хита или до того);
  • s_guest_id - ID посетителя;
  • s_ip - IP адрес посетителя;
  • s_url - страница хита;
  • s_country_id - ID страны посетителя.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID хита;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • GUEST_ID* - ID посетителя;
  • GUEST_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по GUEST_ID будет искаться вхождение;
  • NEW_GUEST - флаг "новый посетитель", возможные значения:
    • Y - посетитель впервые на портале;
    • N - посетитель уже посещал ранее портал.
  • SESSION_ID* - ID сессии;
  • SESSION_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SESSION_ID будет искаться вхождение;
  • STOP_LIST_ID* - ID записи стоп-листа под которую попал посетитель (если это имело место быть);
  • STOP_LIST_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по STOP_LIST_ID будет искаться вхождение;
  • URL* - страница хита;
  • URL_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL будет искаться точное совпадение;
  • URL_404 - была ли 404 ошибка на странице хита
    • Y - была;
    • N - не было.
  • USER* - ID, логин, имя, фамилия пользователя под которым был авторизован посетитель в момент хита или до него;
  • USER_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER будет искаться точное совпадение;
  • REGISTERED - флаг "был ли авторизован посетитель в момент хита или до этого", возможные значения:
    • Y - был;
    • N - не был.
  • DATE_1 - начальное значение интервала времени хита;
  • DATE_2 - конечное значение интервала времени хита;
  • IP* - IP адрес посетителя в момент хита;
  • IP_EXACT_MATCH - если значение равно "Y", то при фильтрации по IP будет искаться точное совпадение;
  • USER_AGENT* - UserAgent посетителя в момент хита;
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение;
  • COUNTRY_ID* - ID страны посетителя в момент хита;
  • COUNTRY_ID_EXACT_MATCH - если значение равно "Y", то при фильтрации по COUNTRY_ID будет искаться точное совпадение;
  • COUNTRY* - название страны;
  • COUNTRY_EXACT_MATCH - если значение равно "Y", то при фильтрации по COUNTRY будет искаться точное совпадение;
  • COOKIE* - содержимое Cookie в момент хита;
  • COOKIE_EXACT_MATCH - если значение равно "Y", то при фильтрации по COOKIE будет искаться точное совпадение;
  • STOP -
    • Y - был;
    • N - не был.
  • SITE_ID* - ID сайта;
  • SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE_ID будет искаться вхождение.

* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка хитов. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID хита
    [SESSION_ID] => ID сессии
    [DATE_HIT] => время хита
    [GUEST_ID] => ID посетителя
    [NEW_GUEST] => [Y|N] флаг "был ли это новый посетитель на сайте" (Y)
    [USER_ID] => ID пользователя под которым посетитель был авторизован (в момент хита или до этого)
    [USER_AUTH] => флаг "был ли посетитель авторизован в момент хита"
    [URL] => страница хита
    [URL_404] => была ли 404 ошибка на странице хита
    [URL_FROM] => страница откуда пришел посетитель
    [IP] => IP адрес посетитель в момент хита
    [METHOD] => HTTP метод отсылки данных
    [COOKIES] => содержимое Cookie посетителя в момент хита
    [USER_AGENT] => UserAgent посетителя в момент хита
    [STOP_LIST_ID] => ID записи стоп-листа под которую попал посетитель (если это имело место быть)
    [COUNTRY_ID] => ID страны (двухсимвольный идентификатор) посетителя сайта в момент хита (определяется по IP адресу)
    [COUNTRY_NAME] => название страны посетителя сайта в момент хита (определяется по IP адресу)
    [SITE_ID] => ID сайта (двухсимвольный идентификатор)
    [LOGIN] => логин пользователя под которым посетитель был авторизован (в момент хита или до этого)
    [USER_NAME] => имя и фамилия пользователя под которым посетитель был авторизован (в момент хита или до этого)
)

См. также

  • Термин "Хит"

Примеры использования

<?
// выберем хиты сессии #1056
$arFilter = array(
    "SESSION_ID" => 1056
    );

// получим список записей
$rs = CHit::GetList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CPage

CPage - класс для получения данных о посещенных страницах сайта.

Методы класса

Метод | Описание
GetDynamicList | Возвращает данные по посещаемости указанной страницы в разрезе по дням.
GetList | Возвращает список посещенных на сайте страниц.

См. также

  • Пользовательская документация, отчет "Разделы и страницы"


GetDynamicList

CPage::GetDynamicList

CDBResult
CPage::GetDynamicList(
 string url,
 string &by = "s_date",
 string &order = "desc",
 array filter = array()
)

Возвращает данные по посещаемости указанной страницы (каталогу) в разрезе по дням.

Параметры функции

Параметр | Описание
url | Полный путь к странице (каталогу) по которой необходимо получить данные.
by Порядок сортировки. Возможные значения:
  • s_date - дата.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • DATE1 - начальное значение интервала даты;
  • DATE2 - конечное значение интервала даты;
  • ADV* - ID рекламной кампании (РК), данное поле позволяет отфильтровать только те страницы (каталоги) которые были открыты только посетителями по данной РК и соответственно получить данные по посещаемости страницы (каталога) url только этих посетителей;
  • ADV_EXACT_MATCH - если значение равно "N", то при фильтрации по ADV будет искаться вхождение;
  • ADV_DATA_TYPE - флаг "возврат или прямой заход по рекламной кампании" (используется только если указано filter["ADV"]), возможные значения:
    • B - показывать данные по посетителям только на возврате по РК;
    • P - показывать данные по посетителям только на прямом заходе по РК.

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

* - допускается сложная логика

Структура возвращаемой записи

Array
(
    [DATE_STAT] => дата
    [DAY] => номер дня (1-31)
    [MONTH] => номер месяца (1-12)
    [YEAR] => год
    [COUNTER] => кол-во хитов на странице url
    [ENTER_COUNTER] => сколько раз данная страница была точкой входа
    [EXIT_COUNTER] => сколько раз данная страница была точкой выхода
)

См. также

  • Термин "Точка входа"
  • Термин "Точка выхода"

Примеры использования

<?
$url = "http://www.bitrixsoft.ru/about/index.php";

// установим фильтр на декабрь 2007 года
// по прямым заходам с рекламной кампании 1 либо 2
$arFilter = array(
    "DATE1" => "01.12.2007",
    "DATE2" => "31.12.2007",
    "ADV"   => "1 | 2",
    "ADV_DATA_TYPE" => "P"
    );

// получим набор записей
$rs = CPage::GetDynamicList(
    $url,
    ($by="s_date"),
    ($order="desc"),
    $arFilter,
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CPage::GetList

CDBResult
CPage::GetList(
 string counter_type = "",
 string &by = "s_last_date",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список посещенных на сайте страниц (каталогов) и данные по их посещаемости.

Параметры функции

Параметр | Описание
counter_type Тип счетчика. Возможные значения:
  • ENTER_COUNTER - кол-во раз когда данная страница (каталог) была точкой входа;
  • EXIT_COUNTER - кол-во раз когда данная страница (каталог) была точкой выхода.
По умолчанию в счетчике хранится общее число хитов по странице (каталогу) (включая и точки входа и точки выхода).
by Порядок сортировки. Возможные значения:
  • s_url - страница (каталог);
  • s_counter - счетчик.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • DATE1 - начальное значение для интервала даты за которую необходимо получить данные;
  • DATE2 - конечное значение для интервала даты за которую необходимо получить данные;
  • DIR - флаг "показывать только каталоги или только страницы", возможные значения:
    • Y - в результирующем списке должны быть только каталоги;
    • N - в результирующем списке должны быть только страницы.
  • URL* - Полный путь к странице (каталогу) для которой необходимо вывести данные;
  • URL_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL будет искаться точное совпадение;
  • URL_404 - была ли 404 ошибка на странице, возможные значения:
    • Y - была;
    • N - не было.
    Для фильтрации каталогов данное поле не может использоваться.
  • ADV* - ID рекламной кампании (РК), данное поле позволяет отфильтровать только те страницы (каталоги) которые были открыты только посетителями по данной РК и соответственно получить данные по посещаемости страницы (каталога) url только этих посетителей;
  • ADV_EXACT_MATCH - если значение равно "N", то при фильтрации по ADV будет искаться вхождение;
  • ADV_DATA_TYPE - флаг типа данных для рекламной кампании, возможные значения:
    • P - только по прямым заходам по рекламной кампании;
    • B - только по возвратам по рекламной кампании;
    • S - сумма по прямым заходам и возвратам.
  • SITE_ID* - ID сайта;
  • SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE_ID будет искаться вхождение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка страниц (каталогов). Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [URL] => страница (раздел)
    [DIR] => [Y|N] флаг "страница(N) или каталог(Y)"
    [SITE_ID] => ID сайта
    [URL_404] => флаг 404 ошибки для страницы
    [COUNTER] => счетчик хитов на данной странице (в данном каталоге)
                 (только если counter_type<>ENTER_COUNTER
                 и counter_type<>EXIT_COUNTER)
    [ENTER_COUNTER] => счетчик сколько раз данная страница (каталог)
                       являлась точкой входа (только при установленном
                       counter_type=ENTER_COUNTER)
    [EXIT_COUNTER] => счетчик сколько раз данная страница (каталог)
                      являлась точкой выхода (только при установленном
                      counter_type=EXIT_COUNTER)
)

См. также

  • Термин "Точка входа"
  • Термин "Точка выхода"

Примеры использования

<?
// получим данные по заданной странице
$arFilter = array(
    "URL" => "http://www.bitrixsoft.ru/about/index.php",
    "URL_EXACT_MATCH" => "Y"
    );

// получим список записей
$rs = CPage::GetList(
    "",
    ($by = "s_last_date"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CPath

CPath - класс для получения данных о путях по сайту.

Методы класса

Метод | Описание
GetByID | По указанному ID записи, функция возвращает данные из таблицы, хранящей статистическую информацию как по полным путям, так и по отрезкам путей в разрезе по дням.
GetList | Возвращает данные из таблицы, хранящей статистическую информацию как по полным путям, так и по отрезкам путей в разрезе по дням.

См. также

  • Пользовательскуя докуметацию, отчет "Пути по сайту"
  • Термин "Полный путь"
  • Термин "Отрезок пути"


GetByID

CPath::GetByID

CDBResult
CPath::GetByID(
 int id
)

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

Параметры функции

Параметр | Описание
id | ID записи из таблицы.

Структура возвращаемой записи

Array
(
    [ID] => ID записи из таблицы отрезков путей по сайту
    [PATH_ID] => ID отрезка пути
    [PARENT_PATH_ID] => ID родительского отрезка пути
    [DATE_STAT] => дата
    [COUNTER] => количество переходов по данному отрезку пути
    [COUNTER_ABNORMAL] => количество переходов по данному отрезку пути
                          без передачи браузером адреса
                          ссылающейся страницы (HTTP_REFERER)
    [COUNTER_FULL_PATH] => количество переходов по полному пути,
                           страницы которого перечислены в [PAGES]
    [PAGES] => набор страниц входящих в полный путь
    [FIRST_PAGE] => первая страница пути
    [FIRST_PAGE_404] => флаг 404 ошибки на первой странице пути
    [FIRST_PAGE_SITE_ID] => ID сайта первой страницы пути
    [PREV_PAGE] => предпоследняя страница пути
    [PREV_PAGE_HASH] => хэш (crc32) предпоследней страницы пути
    [LAST_PAGE] => последняя страница пути
    [LAST_PAGE_404] => флаг 404 ошибки на последней странице пути
    [LAST_PAGE_SITE_ID] => ID сайта последней страницы пути
    [LAST_PAGE_HASH] => хэш (crc32) последней страницы пути
    [STEPS] => количество страниц входящих в полный путь
               (количество страниц в [PAGES])
)

См. также

  • Термин "Полный путь"
  • Термин "Отрезок пути"

Примеры использования

<?
$path_id = 1;
if ($rs = CPath::GetByID($path_id))
{
    $ar = $rs->Fetch();
    // выведем параметры отрезка пути
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CPath::GetList

CDBResult
CPath::GetList(
 int parent_id = "",
 string counter_type = "COUNTER_FULL_PATH",
 string &by = "s_counter",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

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

Параметры функции

Параметр | Описание
parent_id | ID "родительского" отрезка пути (предшествовавшему текущему).
counter_type Тип счетчика, возможные значения:
  • COUNTER_FULL_PATH - количество переходов по полному пути;
  • COUNTER - количество переходов по отрезку пути.
by Поле для сортировки. Возможные значения:
  • s_counter - значение счетчика тип которого задается в counter_type;
  • s_last_page - последняя страница отрезка пути (используется только если counter_type=COUNTER);
  • s_pages - набор всех страниц полного пути (используется только если counter_type=COUNTER_FULL_PATH).
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • PATH_ID* - ID отрезка пути;
  • PATH_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по PATH_ID будет искаться вхождение;
  • DATE1 - начальное значение для интервала даты;
  • DATE2 - конечное значение для интервала даты;
  • FIRST_PAGE* - первая страница пути;
  • FIRST_PAGE_EXACT_MATCH - если значение равно "Y", то при фильтрации по FIRST_PAGE будет искаться точное совпадение;
  • FIRST_PAGE_SITE_ID - ID сайта первой страницы пути;
  • FIRST_PAGE_SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по FIRST_PAGE_SITE_ID будет искаться вхождение;
  • FIRST_PAGE_404 - была ли 404 ошибка на первой странице пути, возможные значения:
    • Y - была;
    • N - не была.
  • LAST_PAGE* - последняя страница пути;
  • LAST_PAGE_EXACT_MATCH - если значение равно "Y", то при фильтрации по LAST_PAGE будет искаться точное совпадение;
  • LAST_PAGE_SITE_ID* - ID сайта последней страницы пути;
  • LAST_PAGE_SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по LAST_PAGE_SITE_ID будет искаться вхождение;
  • LAST_PAGE_404 - была ли 404 ошибка на последней странице пути, возможные значения:
    • Y - была;
    • N - не была.
  • PAGE* - произвольная страница пути
  • PAGE_EXACT_MATCH - если значение равно "N", то при фильтрации по PAGE будет искаться вхождение
  • PAGE_SITE_ID - ID сайта произвольной страницы пути
  • PAGE_404 - была ли 404 ошибка на произвольной странице пути, возможные значения:
    • Y - была
    • N - не была.
  • ADV* - ID рекламной кампании, по посетителям которой надо получить данные;
  • ADV_EXACT_MATCH - если значение равно "N", то при фильтрации по ADV будет искаться вхождение;
  • ADV_DATA_TYPE - флаг типа данных для рекламной кампании, возможные значения:
    • P - только по прямым заходам по рекламной кампании;
    • B - только по возвратам по рекламной кампании;
    • S - сумма по прямым заходам и возвратам.
  • STEPS1 - начальное значение интервала для поля "количество страниц в пути";
  • STEPS2 - конечное значение интервала для поля "количество страниц в пути".
* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка записей. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

В зависимости от типа счетчика (counter_type), структура возвращаемой записи различная.

  • если counter_type = COUNTER:
    Array(
    [PATH_ID] => ID отрезка пути
    [LAST_PAGE] => последняя страница отрезка пути
    [LAST_PAGE_404] => [Y|N] флаг 404 ошибки  на последней странице пути
    [LAST_PAGE_SITE_ID] => ID сайта последней страницы пути
    [COUNTER] => количество переходов по отрезку пути
)
  • если counter_type = COUNTER_FULL_PATH:
    Array(
    [PATH_ID] => ID пути
    [PAGES] => набор страниц входящих в полный путь
    [COUNTER] => количество переходов по полному пути
)

См. также

  • Термин "Полный путь"
  • Термин "Отрезок пути"

Примеры использования

<?
// выберем данные по полным путям пройденных посетителями
// рекламной кампании #1 или #2
$arFilter = array(
    "ADV" => "1 | 2"
    );

// получим список записей
$rs = CPath::GetList(
    "",
    "COUNTER_FULL_PATH",
    ($by = "s_counter"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CPhrase

CPhrase - класс для получения данных по поисковым фразам.

Методы класса

Метод | Описание
GetList | Возвращает список поисковых фраз.

См. также

  • Пользовательскую документацию, отчет "Поисковые фразы"
  • Термин "Поисковая фраза"
  • Термин "Поисковая система"


GetList

CPhrase::GetList

CDBResult
CPhrase::GetList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 int &total,
 string &group_by,
 int &max
)

Возвращает список поисковых фраз с возможностью группировки по поисковое фразе или поисковой системе.

Параметры функции

Параметр | Описание
by Поле для сортировки. В зависимости от группировки списка, набор доступных значений данной переменной может быть различным.
  • при группировке по поисковой фразе (filter["GROUP"]="P"):
    • s_phrase - поисковая фраза;
    • s_quantity - количество заходов с той или иной поисковой фразой.
  • при группировке по поисковой системе (filter["GROUP"]="S"):
    • s_name - поисковая система;
    • s_quantity - количество заходов с данной поисковой системы;
    • s_average_hits - среднее количество хитов производимое посетителями заходящим с той или иной поисковой системы.
  • когда группировка не установлена:
    • s_id - ID записи;
    • s_counter - счетчик;
    • s_site_id - ID сайта на который пришли;
    • s_phrase - поисковая фраза;
    • s_searcher_id - ID поисковой системы;
    • s_referer_id - ID записи из таблицы ссылающихся сайтов (страниц);
    • s_date_hit - дата захода;
    • s_url_to - страница на которую пришли;
    • s_session_id - ID сессии.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID - ID записи;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SESSION_ID - ID сессии;
  • SESSION_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SESSION_ID будет искаться вхождение;
  • SEARCHER_ID - ID поисковой системы;
  • SEARCHER_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SEARCHER_ID будет искаться вхождение;
  • REFERER_ID - ID записи из таблицы ссылающихся сайтов (страниц);
  • REFERER_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по REFERER_ID будет искаться вхождение;
  • SEARCHER* - название поисковой системы;
  • SEARCHER_EXACT_MATCH - если значение равно "Y", то при фильтрации по SEARCHER будет искаться точное совпадение;
  • DATE1 - начальное значение интервала для поля "дата";
  • DATE2 - конечно значение интервала для поля "дата";
  • PHRASE* - поисковая фраза;
  • PHRASE_EXACT_MATCH - если значение равно "Y", то при фильтрации по PHRASE будет искаться точное совпадение;
  • TO* - страница на которую пришли;
  • TO_EXACT_MATCH - если значение равно "Y", то при фильтрации по TO будет искаться точное совпадение;
  • TO_404 - была ли 404 ошибка на странице на которую пришли, возможные значения:
    • Y - была;
    • N - не была.
  • SITE_ID - ID сайта, на который пришли;
  • GROUP - группировка результирующего списка, возможные значения:
    • P - группировка по поисковой фразе;
    • S - группировка по поисковой системе.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.
total | Суммарное количество поисковых фраз.
group_by Группировка списка поисковых фраз. Возможные значения:
  • P - группировка по поисковой фразе;
  • S - группировка по поисковой системе.
max | Количество заходов по самой популярной поисковой фразе.

Структура возвращаемой записи

В зависимости от установленной группировки, структура возвращаемой записи различная.

  • при группировке по поисковой фразе (filter["GROUP"]="P"):
    Array
(
    [PHRASE] => поисковая фраза
    [QUANTITY] => сколько раз заходили на сайт по данной
                  поисковой фразе
    [PERCENT] => процент от общего количества заходов по
                 разным поисковым фразам
)
  • при группировке по поисковой системе (filter["GROUP"]="S"):
    Array
(
    [SEARCHER_ID] => ID поисковой системы
    [SEARCHER_NAME] => название поисковой системы
    [QUANTITY] => количество заходов с поисковой системы
    [PERCENT] => процент заходов с данной поисковой системы
    [AVERAGE_HITS] => среднее количество хитов, производимое
                      посетителями, заходящими с той или иной
                      поисковой системы
)
  • когда группировка не установлена:
    Array
(
    [ID] => ID записи
    [PHRASE] => поисковая фраза
    [DATE_HIT] => время
    [SESSION_ID] => ID сессии
    [REFERER_ID] => ID записи из таблицы ссылающихся сайтов (страниц)
    [SEARCHER_ID] => ID поисковой системы
    [SEARCHER_NAME] => название поисковой системы
    [URL_TO] => страница на которую пришли
    [URL_TO_404] => [Y|N] флаг 404 ошибки на странице,
                    на которую пришли
    [SITE_ID] => ID сайта, на который пришли
)

См. также

  • Термин "Поисковая фраза"
  • Термин "Поисковая система"

Примеры использования

<?
// отфильтруем только те поисковые фразы
// которые искали на сайте с помощью внутреннего поиска
$arFilter = array(
    "SEARCHER_ID"  => 1
    );

// получим список записей
$rs = CPhrase::GetList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered,
    $total,
    $group_by,
    $max
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CReferer

CReferer - класс для получения данных о ссылающихся сайтах.

Методы класса

Метод | Описание
GetList | Возвращает список ссылающихся сайтов (страниц).

См. также

  • Пользовательскую документацию, отчет "Ссылающиеся сайты"
  • Термин "Ссылающийся сайт (страница)"


GetList

CReferer::GetList

CDBResult
CReferer::GetList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 int &total,
 string &group_by,
 int &max
)

Возвращает список ссылающихся сайтов (страниц).

Параметры функции

Параметр | Описание
by Поле для сортировки. В зависимости от группировки списка, набор доступных значений данной переменной может быть различным.
  • при группировке по ссылающейся странице (filter["GROUP"]="U"):
    • s_url_from - ссылающаяся страница;
    • s_quantity - количество заходов с ссылающейся страницы;
    • s_average_hits - среднее количество хитов, производимое посетителями заходящими с той или ссылающейся страницы.
  • при группировке по ссылающемуся домену (filter["GROUP"]="S"):
    • s_url_from - ссылающийся домен;
    • s_quantity - количество заходов с ссылающегося домена;
    • s_average_hits - среднее количество хитов, производимое посетителями.
  • когда группировка не установлена:
    • s_id - ID записи;
    • s_site_id - ID сайта, на который пришли;
    • s_url_from - ссылающаяся страница (с которой пришли);
    • s_url_to - страница на которую пришли;
    • s_date_hit - дата;
    • s_session_id - ID сессии.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID - ID записи;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SESSION_ID - ID сессии;
  • SESSION_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SESSION_ID будет искаться вхождение;
  • DATE1 - начальное значение интервала для поля "дата";
  • DATE2 - конечное значение интервала для поля "дата";
  • FROM_PROTOCOL - протокол ссылающейся страницы;
  • FROM_PROTOCOL_EXACT_MATCH - если значение равно "Y", то при фильтрации по FROM_PROTOCOL будет искаться точное совпадение;
  • FROM_DOMAIN - домен ссылающейся страницы;
  • FROM_DOMAIN_EXACT_MATCH - если значение равно "Y", то при фильтрации по FROM_DOMAIN будет искаться точное совпадение;
  • FROM_PAGE - ссылающаяся страница;
  • FROM_PAGE_EXACT_MATCH - если значение равно "Y", то при фильтрации по FROM_PAGE будет искаться точное совпадение;
  • FROM - протокол + домен + ссылающаяся страница;
  • FROM_EXACT_MATCH - если значение равно "Y", то при фильтрации по FROM будет искаться точное совпадение;
  • TO* - страница на которую пришли;
  • TO_EXACT_MATCH - если значение равно "Y", то при фильтрации по TO будет искаться точное совпадение;
  • TO_404 - была ли 404 ошибка на странице, на которую пришли, возможные значения:
    • Y - была;
    • N - не была.
  • SITE_ID - ID сайта на который пришли;
  • GROUP - группировка результирующего списка; возможные значения:
    • S - группировка по ссылающемуся домену (сайту);
    • U - группировка по ссылающейся странице.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.
total | Суммарные количество заходов с ссылающихся страниц.
group_by Группировка результирующего списка. Возможные значения:
  • U - группировка по ссылающейся странице;
  • S - группировка по ссылающемуся домену.
max | Количество заходов с самой популярной ссылающейся страницы.

Структура возвращаемой записи

В зависимости от установленной группировки, структура возвращаемой записи различная.

  • при группировке по ссылающейся странице (filter["GROUP"]="U"):
    Array
(
    [URL_FROM] => ссылающаяся страница
    [QUANTITY] => сколько раз зашли с данной ссылающейся страницы
    [PERCENT] => процент заходов с данной ссылающейся страницы,
                 относительно всех заходов со всех ссылающихся сайтов
    [AVERAGE_HITS] => среднее количество хитов, производимое
                      посетителями, заходящими с данной
                      ссылающейся страницы
)
  • при группировке по ссылающемуся домену (filter["GROUP"]="S"):
    Array
(
    [URL_FROM] => ссылающийся домен
    [QUANTITY] => сколько раз зашли с данного ссылающегося домена
    [PERCENT] => процент заходов с данного ссылающегося домена,
                 относительно всех заходов со всех ссылающихся сайтов
    [AVERAGE_HITS] => среднее количество хитов, производимое
                      посетителями, заходящими с данного
                      ссылающегося домена
)
  • когда группировка не установлена:
    Array
(
    [ID] => ID записи
    [URL_FROM] => ссылающаяся страница
    [DATE_HIT] => дата
    [SESSION_ID] => ID сессии
    [URL_TO] => страница, на которую пришли
    [URL_TO_404] => [Y|N] флаг 404 ошибки на странице на которую пришли
    [SITE_ID] => ID сайта на который пришли
)

См. также

  • Термин "Ссылающийся сайт (страница)"

Примеры использования

<?
// отфильтруем только заходы с доменов "google"
// сгруппировав по ссылающемуся домену
$arFilter = array(
    "FROM_DOMAIN"  => "google",
    "GROUP"        => "S"
    );

// получим список записей
$rs = CReferer::GetList(
    ($by = "s_url_from"),
    ($order = "desc"),
    $arFilter,
    $is_filtered,
    $total,
    $group_by,
    $max
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CSearcher

CSearcher - класс для работы с поисковыми системами.

Методы класса

Метод | Описание
GetByID | Возвращает данные по указанной поисковой системе.
GetDomainList | Возвращает список доменов поисковых систем.
GetDropdownList | Возвращает список поисковых систем для вывода его в выпадающем списке с помощью функции SelectBox, либо в списке множественного выбора с помощью функции SelectBoxM.
GetDynamicList | Возвращает количество хитов, для указанной поисковой системы в разрезе по дням.
GetList | Возвращает список поисковых систем и количество хитов каждой из них за все время ведения статистики, за последние 3 дня, либо за указанный интервал времени.

См. также

  • Пользовательскую документацию, отчет "Поисковые системы"


GetByID

CSearcher::GetByID

CDBResult
CSearcher::GetByID(
 int searcher_id
)

Возвращает данные по указанной поисковой системе.

Параметры функции

Параметр | Описание
searcher_id | ID поисковой системы.

Структура возвращаемой записи

Array
(
    [ID] => ID поисковый системы
    [DATE_CLEANUP] => дата очистки устаревших данных по
                      индексации страниц, в разрезе по дням
    [TOTAL_HITS] => суммарное количество проиндексированных страниц
    [SAVE_STATISTIC] => [Y|N] флаг "сохранять ли информацию
                                    о проиндексированных страницах"
    [ACTIVE] => [Y|N] флаг активности
    [NAME] => название поисковой системы
    [USER_AGENT] => UserAgent поисковой системы
    [DIAGRAM_DEFAULT] => [Y|N] флаг "включать в диаграмму
                                     и график по умолчанию"
    [HIT_KEEP_DAYS] => сколько дней хранить хиты поисковой системы
    [DYNAMIC_KEEP_DAYS] => сколько дней хранить данные по
                           индексации сайта в разрезе по дням
    [PHRASES] => количество заходов на сайт по
                 поисковой фразе с данной поисковой системы
    [PHRASES_HITS] => суммарное количество хитов,
                      производимое посетителями, заходящими с данной
                      поисковой системы по той или иной поисковой фразе
    [CHECK_ACTIVITY] => [Y|N] флаг "проверять ли лимит активности для
                                    данной поисковой системы в моменты
                                    индексации сайта"
)

См. также

  • CSearcher::GetDomainList
  • Термин "Поисковая система"

Примеры использования

<?
$searcher_id = 1;
if ($rs = CSearcher::GetByID($searcher_id))
{
    $ar = $rs->Fetch();
    // выведем параметры поисковой системы
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetDomainList

CSearcher::GetDomainList

CDBResult
CSearcher::GetDomainList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список доменов поисковых систем.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID домена;
  • s_domain - домен;
  • s_variable - имя переменной (или группа имен переменных разделенных запятой) в которых хранится поисковая фраза.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID домена;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SEARCHER_ID* - ID поисковой системы;
  • SEARCHER_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SEARCHER_ID будет искаться вхождение;
  • DOMAIN* - домен;
  • DOMAIN_EXACT_MATCH - если значение равно "Y", то при фильтрации по DOMAIN будет искаться точное совпадение;
  • VARIABLE* - имя переменной (или группа имен переменных разделенных запятой) в которых хранится поисковая фраза;
  • VARIABLE_EXACT_MATCH - если значение равно "Y", то при фильтрации по VARIABLE будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID домена
    [DOMAIN] => домен
    [VARIABLE] => имя переменной (или группа имен переменных,
                  разделенных запятой) в которых хранится поисковая фраза
)

См. также

  • CSearcher::GetByID
  • Термин "Домен поисковой системы"

Примеры использования

<?
// выберем домены поисковой системы #20
$arFilter = array(
    "SEARCHER_ID" => 20
    );

// получим список записей
$rs = CSearcher::GetDomainList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetDropdownList

CSearcher::GetDropdownList

CDBResult
CSearcher::GetDropdownList(
 string order = "ORDER BY NAME, ID"
)

Возвращает список поисковых систем для вывода его в выпадающем списке с помощью функции SelectBox, либо в списке множественного выбора с помощью функции SelectBoxM.

Параметры функции

Параметр | Описание
order | SQL код, позволяющий задать произвольную сортировку результирующего списка.

См. также

  • CSearcher::GetList
  • Термин "Поисковая система"

Примеры использования

<?
// выпадающий список с одиночным выбором
echo SelectBox(
    "SEARCHER_ID",
    CSearcher::GetDropdownList(),
    "",
    intval($SEARCHER_ID)
    );

// список из 20 видимых элементов с возможностью множественного выбора
echo SelectBoxM(
    "arSEARCHER_ID[]",
    CSearcher::GetDropdownList(),
    $arSEARCHER_ID,
    "",
    false,
    20
    );
?>


GetDynamicList

CSearcher::GetDynamicList

CDBResult
CSearcher::GetDynamicList(
 int searcher_id,
 string &by = "s_date",
 string &order = "desc",
 array &max_min,
 array filter = array()
)

Возвращает количество хитов (проиндексированных страниц), для указанной поисковой системы в разрезе по дням.

Параметры функции

Параметр | Описание
searcher_id | ID поисковой системы.
by Поле для сортировки. Возможные значения:
  • s_date - дата.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
max_min Ссылка на массив содержащий максимальную и минимальную даты результирующего списка. Структура данного массива:
Array
(
    [DATE_FIRST] => минимальная дата
    [MIN_DAY] => номер дня для минимальной даты (1-31)
    [MIN_MONTH] => номер месяца для минимальной даты (1-12)
    [MIN_YEAR] => номер года для минимальной даты

    [DATE_LAST] => максимальная дата
    [MAX_DAY] => номер дня для максимальной даты (1-31)
    [MAX_MONTH] => номер месяца для максимальной даты (1-12)
    [MAX_YEAR] => номер года для максимальной даты
)
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • DATE1 - начальное значение интервала для поля "дата";
  • DATE2 - конечное значение интервала для поля "дата".

Структура возвращаемой записи

Array
(
    [DATE_STAT] => дата
    [DAY] => номер дня (1-31)
    [MONTH] => номер месяца (1-12)
    [YEAR] => номер года
    [TOTAL_HITS] => количество хитов (проиндексированных страниц)
)

См. также

  • Термин "Хит поисковой системы"

Примеры использования

<?
$searcher_id = 1;

// установим фильтр на декабрь 2005 года
$arFilter = array(
    "DATE1" => "01.12.2005",
    "DATE2" => "31.12.2005"
    );

// получим набор записей
$rs = CSearcher::GetDynamicList(
    $searcher_id,
    ($by="s_date"),
    ($order="desc"),
    $arMaxMin,
    $arFilter
    );

// выведем массив с максимальной и минимальной датами
echo "<pre>"; print_r($arMaxMin); echo "</pre>";

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CSearcher::GetList

CDBResult
CSearcher::GetList(
 string &by = "s_today_hits",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 mixed limit = false
)

Возвращает список поисковых систем и количество хитов (проиндексированных страниц) каждой из них за все время ведения статистики, за последние 3 дня, либо за указанный интервал времени.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID поисковой системы;
  • s_date_last - дата последнего хита;
  • s_today_hits - количество хитов за сегодня;
  • s_yesterday_hits - количество хитов за вчера;
  • s_b_yesterday_hits - количество хитов за позавчера;
  • s_total_hits - суммарное количество хитов;
  • s_period_hits - количество хитов за установленный период времени (filter["DATE1"], filter["DATE2"]);
  • s_name - название поисковой системы;
  • s_user_agent - UserAgent поисковой системы.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID поисковой системы;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение
  • ACTIVE - флаг активности, возможные значения:
    • Y - активна;
    • N - не активна.
  • SAVE_STATISTIC - флаг "сохранять хиты поисковой системы", возможные значения:
    • Y - да;
    • N - нет.
  • DIAGRAM_DEFAULT - флаг "включать в круговую диаграмму и график по умолчанию", возможные значения:
    • Y - да;
    • N - нет.
  • HITS1 - начальное значение интервала для поля "количество хитов";
  • HITS2 - конечное значение интервала для поля "количество хитов";
  • DATE1_PERIOD - начальное значение значение для произвольного периода;
  • DATE2_PERIOD - конечное значение значение для произвольного периода;
  • DATE1 - начальное значение интервала для поля "дата последнего хита поисковой системы";
  • DATE2 - конечное значение интервала для поля "дата последнего хита поисковой системы";
  • NAME* - наименование поисковой системы;
  • NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по NAME будет искаться точное совпадение;
  • USER_AGENT* - UserAgent поисковой системы;
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности списка поисковых систем. Если значение равно "true", то список был отфильтрован.
limit | Максимальное количество поисковых систем которые будут выбраны в списке. Если значение равно false, то кол-во РК будет ограничено в соответствии со значением параметра "Максимальное кол-во показываемых записей в таблицах" из настроек модуля "Статистика".

Структура возвращаемой записи

Array
(
    [ID] => ID поисковой системы
    [NAME] => название
    [USER_AGENT] => UserAgent
    [DIAGRAM_DEFAULT] => [Y|N] флаг "включать в круговую диаграмму и график по умолчанию"
    [DATE_LAST] => дата последнего хита
    [TOTAL_HITS] => суммарное количество хитов
    [TODAY_HITS] => количество хитов за сегодня
    [YESTERDAY_HITS] => количество хитов за вчера
    [B_YESTERDAY_HITS] => количество хитов за позавчера
    [PERIOD_HITS] => количество хитов за установленный период времени (filter["DATE1_PERIOD"], filter["DATE2_PERIOD"])
)

См. также

  • CSearcher::GetDropdownList
  • Термин "Поисковая система"

Примеры использования

<?
// отфильтруем данные только для поисковой системы #20 и #21
// а также получим дополнительные данные на декабрь 2005 года
$arFilter = array(
    "ID"           => "20 | 21",
    "DATE1_PERIOD" => "01.12.2005",
    "DATE2_PERIOD" => "31.12.2005",
    );

// получим список записей
$rs = CSearcher::GetList(
    ($by = "s_today_hits"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CSearcherHit

CSearcherHit - класс для получения данных о хитах поисковых систем (проиндекированных страниц).

Методы класса

Метод | Описание
GetList | Возвращает список хитов поисковых систем.

См. также

  • Пользовательскую документацию, отчет "Хиты поисковиков"
  • Термин "Хит поисковой системы"


GetList

CSearcherHit::GetList

CDBResult
CSearcherHit::GetList(
 string &by = "s_date_hit",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список хитов поисковых систем.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID хита;
  • s_site_id - ID сайта;
  • s_date_hit - дата хита;
  • s_searcher_id - ID поисковой системы;
  • s_user_agent - UserAgent поисковой системы;
  • s_ip - IP адрес поисковой системы;
  • s_url - адрес проиндексированной страницы.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID хита;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • SEARCHER_ID* - ID поисковой системы;
  • SEARCHER_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SEARCHER_ID будет искаться вхождение;
  • URL* - адрес проиндексированной страницы;
  • URL_404 - была ли 404 ошибка на проиндексированной странице:
    • Y - была;
    • N - не была.
  • SEARCHER* - название поисковой системы;
  • SEARCHER_EXACT_MATCH - если значение равно "Y", то при фильтрации по SEARCHER будет искаться точное совпадение;
  • DATE1 - начальное значение интервала для поля "дата хита";
  • DATE2 - конечное значение интервала для поля "дата хита";
  • IP* - IP адрес поисковой системы;
  • IP_EXACT_MATCH - если значение равно "Y", то при фильтрации по IP будет искаться точное совпадение;
  • USER_AGENT* - UserAgent поисковой системы;
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение;
  • SITE_ID* - ID сайта;
  • SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE_ID будет искаться вхождение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID хита
    [DATE_HIT] => дата хита
    [SEARCHER_ID] => ID поисковой системы
    [SEARCHER_NAME] => название поисковой системы
    [URL] => адрес проиндексированной страницы
    [URL_404] => [Y|N] флаг 404 ошибки на проиндексированной странице
    [IP] => IP адрес поисковой системы
    [USER_AGENT] => UserAgent поисковой системы
    [HIT_KEEP_DAYS] => индивидуально количество дней,
                       отводимое для хранения хитов поисковой системы
    [SITE_ID] => ID сайта
)

См. также

  • Термин "Хит поисковой системы"

Примеры использования

<?
// отфильтруем страницы проиндексированные
// поисковой системой #20 и #21
$arFilter = array(
    "SEARCHER_ID" => "20 | 21"
    );

// получим список записей
$rs = CSearcherHit::GetList(
    ($by = "s_url"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CSession

CSession - класс для получения данных о сессиях посетителей.

Методы класса

Метод | Описание
GetByID | Возвращает данные по указанной сессии.
GetList | Возвращает список сессий.

См. также

  • Пользовательская документация, отчет "Сессии посетителей"


GetByID

CSession::GetByID

CDBResult
CSession::GetByID(
 int session_id
)

Возвращает данные по указанной сессии.

Параметры функции

Параметр | Описание
session_id | ID сессии.

Структура возвращаемой записи

Array
(
    [ID] => ID сессии
    [GUEST_ID] => ID посетителя
    [NEW_GUEST] => [Y|N] флаг "новый посетитель"
    [USER_ID] => ID пользователя, под которым последний раз
                 был авторизован посетитель
    [USER_AUTH] => [Y|N] флаг "был ли посетитель авторизован
                               в данной сессии"
    [LOGIN] => логин пользователя, под которым последний раз
               был авторизован посетитель
    [USER_NAME] => имя и фамилия пользователя, под которым последний раз
                   был авторизован посетитель
    [C_EVENTS] => количество событий, произведенных в данной сесси
    [HITS] => количество хитов данной сессии
    [FAVORITES] => [Y|N] флаг "добавлял ли посетитель сайт в
                               "Избранное" в данной сессии"
    [URL_FROM] => ссылающаяся страница для первого хита сессии
    [URL_TO] => первая страница сессии
    [URL_TO_404] => [Y|N] флаг 404 ошибки на первой странице сессии
    [URL_LAST] => последняя страница сессии
    [URL_LAST_404] => [Y|N] флаг 404 ошибки на первой странице сессии
    [USER_AGENT] => UserAgent посетителя
    [DATE_STAT] => дата начала сессии
    [DATE_FIRST] => время первого хита сессии
    [DATE_LAST] => время последнего хита сессии
    [SESSION_TIME] => разница во времени между первым и
                      последним хитом сессии (сек.)
    [IP_FIRST] => IP адрес посетителя на первом хите сессии
                  (в виде: XXX.XXX.XXX.XXX)
    [IP_FIRST_NUMBER] => IP адрес посетителя на первом хите сессии
                         (в числовом представлении)
    [IP_LAST] => IP адрес посетителя на последнем хите сессии
                 (в виде: XXX.XXX.XXX.XXX)
    [IP_LAST_NUMBER] => IP адрес посетителя на последнем хите сессии
                        (в числовом представлении)
    [FIRST_HIT_ID] => ID первого хита
    [FIRST_SITE_ID] => ID сайта для первого хита сессии
    [LAST_HIT_ID] => ID последнего хита
    [LAST_SITE_ID] => ID сайта для последнего хита сессии
    [ADV_ID] => ID рекламной кампании
    [ADV_BACK] => [Y|N] флаг прямого захода (N)
                  или возврата (Y) по рекламной кампании
    [REFERER1] => идентификатор referer1 рекламной кампании
    [REFERER2] => идентификатор referer2 рекламной кампании
    [REFERER3] => дополнительный параметр referer3 рекламной кампании
    [COUNTRY_ID] => ID страны посетителя
    [COUNTRY_NAME] => название страны посетителя
    [STOP_LIST_ID] => ID записи стоп-листа,
                      под которую попал посетитель
                      (если это имело место быть)
    [PHPSESSID] => идентификатор сессии выданный PHP
)

См. также

  • Термин "Сессия"

Примеры использования

<?
$session_id = 1;
if ($rs = CSession::GetByID($session_id))
{
    $ar = $rs->Fetch();
    // выведем параметры сессии
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CSession::GetList

CDBResult
CSession::GetList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список сессий.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID сессии;
  • s_last_site_id - ID сайта последнего хита сессии;
  • s_first_site_id - ID сайта первого хита сессии;
  • s_date_first - время первого хита сессии;
  • s_date_last - время последнего хита сессии;
  • s_user_id - ID пользователя под которым последний раз был авторизован посетитель;
  • s_guest_id - ID посетителя;
  • s_ip - IP адрес посетителя на последнем хите сессии;
  • s_hits - количество хитов в данной сессии;
  • s_events - количество событий в данной сессии;
  • s_adv_id - ID рекламной кампании по которой пришел посетитель;
  • s_country_id - ID страны посетителя;
  • s_url_last - страница первого хита сессии;
  • s_url_to - страница последнего хита сессии.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID сессии;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • GUEST_ID* - ID посетителя;
  • GUEST_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по GUEST_ID будет искаться вхождение;
  • NEW_GUEST - флаг "новый посетитель", возможные значения:
    • Y - посетитель впервые на портале;
    • N - посетитель уже посещал ранее портал.
  • USER_ID* - ID пользователя под которым последний раз был авторизован посетитель;
  • USER_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по USER_ID будет искаться вхождение;
  • USER_AUTH - флаг "был ли посетитель авторизован в данной сессии", возможные значения:
    • Y - да;
    • N - нет.
  • USER* - ID, логин, имя, фамилия пользователя под которым последний раз был авторизован посетитель;
  • USER_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER будет искаться точное совпадение;
  • REGISTERED - флаг "был ли авторизован посетитель в данной сессии или до этого", возможные значения:
    • Y - был;
    • N - не был.
  • FAVORITES - флаг "добавлял ли посетитель сайт в "Избранное"", возможные значения:
    • Y - да;
    • N - нет.
  • EVENTS1 - начальное значение интервала для поля "количество событий данной сессии";
  • EVENTS2 - конечное значение интервала для поля "количество событий данной сессии";
  • HITS1 - начальное значение интервала для поля "количество хитов данной сессии";
  • HITS2 - конечное значение интервала для поля "количество хитов данной сессии";
  • ADV - флаг "приходил ли посетитель в данной сессии по какой-либо рекламной кампании", возможные значения:
    • Y - да;
    • N - нет.
  • ADV_ID* - ID рекламной кампании;
  • ADV_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ADV_ID будет искаться вхождение;
  • ADV_BACK - флаг "возврат по рекламной кампании", возможные значения:
    • Y - был возврат;
    • N - был прямой заход.
  • REFERER1* - идентификатор referer1 рекламной кампании;
  • REFERER1_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER1 будет искаться точное совпадение;
  • REFERER2* - идентификатор referer2 рекламной кампании;
  • REFERER2_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER2 будет искаться точное совпадение;
  • REFERER3* - дополнительный параметр referer3 рекламной кампании;
  • REFERER3_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER3 будет искаться точное совпадение;
  • STOP - флаг "попал ли посетитель под какую либо запись стоп-листа", возможные значения:
    • Y - да;
    • N - нет.
  • STOP_LIST_ID* - ID записи стоп-листа под которую попал посетитель, если это имело место быть;
  • STOP_LIST_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по STOP_LIST_ID будет искаться вхождение;
  • COUNTRY_ID* - ID страны посетителя;
  • COUNTRY_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по COUNTRY_ID будет искаться вхождение;
  • COUNTRY* - наименование страны посетителя;
  • COUNTRY_EXACT_MATCH - если значение равно "Y", то при фильтрации по COUNTRY будет искаться точное совпадение;
  • IP* - IP адрес посетителя на последнем хите сессии;
  • IP_EXACT_MATCH - если значение равно "Y", то при фильтрации по IP будет искаться точное совпадение;
  • USER_AGENT* - UserAgent посетителя;
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение;
  • DATE_START_1 - начальное значение интервала для поля "время первого хита сессии";
  • DATE_START_2 - конечное значение интервала для поля "время первого хита сессии";
  • DATE_END_1 - начальное значение интервала для поля "время последнего хита сессии";
  • DATE_END_2 - конечное значение интервала для поля "время последнего хита сессии";
  • URL_TO* - первая страница сессии;
  • URL_TO_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL_TO будет искаться точное совпадение;
  • URL_TO_404 - была ли 404 ошибка на первой страницы сессии
    • Y - была;
    • N - не было.
  • FIRST_SITE_ID* - ID сайта на первом хите сессии;
  • FIRST_SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по FIRST_SITE_ID будет искаться вхождение;
  • URL_LAST* - последняя страница сессии;
  • URL_LAST_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL_LAST будет искаться точное совпадение;
  • URL_LAST_404 - была ли 404 ошибка на последней страницы сессии
    • Y - была;
    • N - не было.
  • LAST_SITE_ID* - ID сайта на последнем хите сессии;
  • LAST_SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по LAST_SITE_ID будет искаться вхождение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID сессии
    [GUEST_ID] => ID посетителя
    [NEW_GUEST] => флаг "новый посетитель" (Y - новый; N - вернувшийся)
    [USER_ID] => ID пользователя под которым последний раз был
                 авторизован посетитель
    [USER_AUTH] => флаг "авторизован ли посетитель в данной сессии"
                   (Y - да; N - нет)
    [C_EVENTS] => количество событий произведенных в данной сессии
    [HITS] => количество хитов произведенных в данной сессии
    [FAVORITES] => флаг "добавлял ли посетитель сайт в "Избранное"
                         в данной сессии
    [STOP_LIST_ID] => ID записи стоп-листа, под которую попал посетитель
                      (если это имело место быть)
    [COUNTRY_ID] => ID страны посетителя
    [USER_AGENT] => UserAgent посетителя

    [URL_FROM] => ссылающаяся страница для первого хита сессии

    [DATE_STAT] => дата первого хита сессии
    [DATE_FIRST] => время первого хита сессии
    [URL_TO] => страница первого хита сессии
    [URL_TO_404] => флаг 404 ошибки на первой странице сессии
                    (Y - да; N - нет)
    [FIRST_HIT_ID] => ID первого хита
    [FIRST_SITE_ID] => ID сайта для первого хита сессии
    [IP_FIRST] => IP адрес посетителя на первом хите сессии
                  (в виде: XXX.XXX.XXX.XXX)
    [IP_FIRST_NUMBER] => IP адрес посетителя на первом хите сессии
                         (в числовом представлении)

    [DATE_LAST] => время последнего хита сессии
    [URL_LAST] => страница последнего хита сессии
    [URL_LAST_404] => флаг 404 ошибки на последней странице сессии
                      (Y - да; N - нет)
    [LAST_HIT_ID] => ID последнего хита
    [LAST_SITE_ID] => ID сайта для последнего хита сессии
    [IP_LAST] => IP адрес посетителя на последнем хите сессии
                 (в виде: XXX.XXX.XXX.XXX)
    [IP_LAST_NUMBER] => IP адрес посетителя на последнем хите сессии
                        (в числовом представлении)

    [ADV_ID] => ID рекламной кампании
    [ADV_BACK] => флаг прямого захода (N) или возврата (Y)
                  по рекламной кампании
    [REFERER1] => идентификатор referer1 рекламной кампании
    [REFERER2] => идентификатор referer2 рекламной кампании
    [REFERER3] => дополнительный параметр referer3 рекламной кампании

    [SESSION_TIME] => разница во времени между первым и последним
                     хитом сессии (сек.)
    [PHPSESSID] => идентификатор сессии выданный PHP
)

См. также

  • Термин "Сессия"

Примеры использования

<?
// выберем все неудаленные сессии посетителя #1025
$arFilter = array(
    "GUEST_ID" => "1025"
    );

// получим список записей
$rs = CSession::GetList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CStatEvent

CStatEvent - класс для работы с событиями.

Методы класса

Метод | Описание
Add | Добавляет событие по заданному ID типа события и специальному параметру.
AddByEvents | Добавляет событие по заданным идентификаторам типа события и специальному параметру.
AddCurrent | Добавляет событие используя текущие параметры посетителя.
DecodeGid | Декодирует специальный параметр используемый при создании события.
Delete | Удаляет указанное событие.
GetGID | Возвращает специальный параметр для текущего посетителя.
GetHandlerList | Возвращает список доступных обработчиков CSV файлов для вывода его в выпадающем списке с помощью функции SelectBoxFromArray, либо в списке множественного выбора с помощью функции SelectBoxMFromArray.
GetList | Возвращает список событий.
GetListByGuest | Возвращает список событий по указанному ID посетителя сайта.

См. также

  • Пользовательскую документацию, отчет "Список событий"


Add

CStatEvent::Add

int
CStatEvent::Add(
 int type_id,
 string event3,
 string date,
 string gid,
 mixed money = "",
 string currency = "",
 string chargeback = "N"
)

Добавляет событие по заданному типу и специальному параметру.

Параметры функции

Параметр | Описание
type_id | ID типа события.
event3 | Дополнительный параметр event3 события.
date | Дата в текущем формате.
gid | Специальный параметр в котором закодированы все необходимые данные для добавления события.
money | Денежная сумма.
currency | Трехсимвольный идентификатор валюты. Идентификаторы валют задаются в модуле "Валюты".
chargeback Флаг отрицательной суммы. Используется, когда необходимо зафиксировать событие о возврате денег (chargeback). Возможные значения:
  • Y - денежная сумма отрицательная;
  • N - денежная сумма положительная.

Возвращаемое значение

Функция возвращает ID добавленного события в случае успеха и 0 если событие не было добавлено по каким либо причинам.

См. также

  • CStatEvent::AddByEvents
  • CStatEvent::AddCurrent
  • Загрузка событий
  • Термин "Событие"
  • Термин "Дополнительный параметр события (event3)"
  • Термин "Специальный параметр события"

Примеры использования

<?
// добавим событие по типу события #1
// данный тип должен быть заранее создан

// специальный параметр события в незакодированном виде
$gid = "BITRIX_SM.995.82.N0.25.N.ru";

// дата должна быть заданы в формате текущего сайта или языка
$date = "23.12.2005 18:15:10";

CStatEvent::Add(1, "", $date, $gid, 99, "USD");
?>
<?
// добавим событие по типу события #2
// данный тип должен быть заранее создан

// специальный параметр события в закодированном виде
$gid = "BITRIX_SM.OTk1LjgyLk4wLjI1Lk4ucnU%3D";

// дата должна быть заданы в формате текущего сайта или языка
$date = "01.06.2005";

CStatEvent::Add(2, "", $date, $gid, "199", "EUR");
?>


AddByEvents

CStatEvent::AddByEvents

int
CStatEvent::AddByEvents(
 string event1,
 string event2,
 string event3,
 string date,
 string gid,
 mixed money = "",
 string currency = "",
 string chargeback = "N"
)

Добавляет событие по заданным идентификаторам типа события и специальному параметру. Если типа события с идентификаторами event1, event2 не существует, то он будет автоматически создан с указанными идентификаторами.

Параметры функции

Параметр | Описание
event1 | Идентификатор типа события event1.
event2 | Идентификатор типа события event2.
event3 | Дополнительный параметр event3 события.
date | Дата в текущем формате.
gid | Специальный параметр в котором закодированы все необходимые данные для добавления события.
money | Денежная сумма.
currency | Трехсимвольный идентификатор валюты. Идентификаторы валют задаются в модуле "Валюты".
chargeback Флаг отрицательной суммы. Используется когда необходимо зафиксировать событие о возврате денег (chargeback). Возможные значения:
  • Y - денежная сумма отрицательная;
  • N - денежная сумма положительная.

Возвращаемое значение

Функция возвращает ID добавленного события в случае успеха и 0 если событие не было добавлено по каким либо причинам.

См. также

  • CStatEvent::Add
  • CStatEvent::AddCurrent
  • Загрузка событий
  • Термин "Событие"
  • Термин "Дополнительный параметр события (event3)"
  • Термин "Специальный параметр события"

Примеры использования

<?
// добавим событие по типу softkey/buy
// если такого типа нет, то он автоматически будет создан

// специальный параметр события в незакодированном виде
$gid = "BITRIX_SM.995.82.N0.25.N.ru";

// дата должна быть заданы в формате текущего сайта или языка
$date = "23.12.2005 18:15:10";

CStatEvent::AddByEvents("softkey", "buy", "", $date, $gid, "899", "USD");
?>

<?
// добавим событие по типу regnow/buy
// если такого типа нет, то он автоматически будет создан

// специальный параметр события в закодированном виде
$gid = "BITRIX_SM.OTk1LjgyLk4wLjI1Lk4ucnU%3D";

// дата должна быть заданы в формате текущего сайта или языка
$date = "01.06.2005";

CStatEvent::AddByEvents("regnow", "buy", "", $date, $gid, "199", "EUR");
?>


AddCurrent

CStatEvent::AddCurrent

array
CStatEvent::AddCurrent(
 string event1,
 string event2 = "",
 string event3 = "",
 mixed money = "",
 string currency = "",
 string goto = "",
 string chargeback = "N",
 mixed site_id = false
)

Добавляет событие используя текущие параметры посетителя. Если типа события с идентификаторами event1, event2 не существует, то он будет автоматически создан с указанными идентификаторами.

Параметры функции

Параметр | Описание
event1 | Идентификатор типа события event1.
event2 | Идентификатор типа события event2.
event3 | Дополнительный параметр event3 события.
money | Денежная сумма.
currency | Трехсимвольный идентификатор валюты. Идентификаторы валют задаются в модуле "Валюты".
goto | Адрес страницы куда перешел посетитель. Как правило используется в скриптах вида /bitrix/redirect.php, перенаправляющих посетителей на другие страницы с одновременной фиксацией события.
chargeback Флаг отрицательной суммы. Используется когда необходимо зафиксировать событие о возврате денег (chargeback). Возможные значения:
  • Y - денежная сумма отрицательная;
  • N - денежная сумма положительная.
site_id | ID сайта к которому будет привязано будущее событие.

Возвращаемое значение

Функция возвращает массив вида:

Array
(
    [TYPE_ID] => ID типа события
    [EID] => ID добавленного события
)

См. также

  • CStatEvent::Add
  • CStatEvent::AddByEvents
  • Термин "Событие"
  • Термин "Дополнительный параметр события (event3)"

Примеры использования

<?
// зафиксируем событие типа "Просмотр спец. страницы" (view/special_page)
CStatEvent::AddCurrent("softkey", "out", $GLOBALS["APPLICATION"]->GetCurPage());
?>
<?
// зафиксируем событие типа "Уход на оплату заказа на Софткее" (softkey/out)
// если такого типа не существует, то он будет автоматически создан
// событие будет фиксироваться по параметрам текущего посетителя сайта

// в данной переменной может быть задана страница на которую осуществляется переход
$goto = "http://www.softkey.ru/catalog/basket.php?prodid=902&quantity=1&referer1=ritlabs_site&referer2=BITRIX_SM.OTk1LjgyLk4wLjI1Lk4ucnU%3D";

CStatEvent::AddCurrent("softkey", "out", "", "", "", $goto);
?>
<?
// зафиксируем событие типа "Скачивание файла manual.chm" (download/manual)
// если такого типа не существует, то он будет автоматически создан
// событие будет фиксироваться по параметрам текущего посетителя сайта

// сначала проверим не скачивал ли уже текущий посетитель этот файл
// в течение последнего часа

// получим ID типа события
$rs = CStatEventType::GetByEvents($event1, $event2);
if ($ar = $rs->Fetch())
{
    // теперь получим все события данного типа для текущего посетителя сайта
    // произошедшие за последний час (3600 секунд)
    $rs = CStatEvent::GetListByGuest($_SESSION["SESS_GUEST_ID"], $ar["TYPE_ID"], "", 3600);

    // если таких событий не было то
    if (!($ar=$rs->Fetch()))
    {
        // добавляем данное событие
        CStatEvent::AddCurrent("download", "manual");
    }
}
?>


DecodeGID

CStatEvent::DecodeGID

array
CStatEvent::DecodeGID(
 string gid
)

Декодирует специальный параметр используемый при создании события в функциях CStatEvent::Add, CStatEvent::AddByEvents.

Функция успешно декодирует параметр как в открытом виде, так и в base64-кодированном.

Параметры функции

Параметр | Описание
gid | Специальный параметр события.

Возвращаемое значение

Функция возвращает массив вида:

Array
(
    [SESSION_ID] => ID сессии
    [GUEST_ID] => ID посетителя
    [COUNTRY_ID] => ID страны
    [ADV_ID] => ID рекламной кампании
    [ADV_BACK] => Y - возврат по рекламной кампании; N - прямой заход
    [SITE_ID] => ID сайта
)

См. также

  • CStatEvent::GetGID
  • Термин "Специальный параметр события"

Примеры использования

<?
// раскодируем специальный параметр события
$arr = CStatEvent::DecodeGID("BITRIX_SM.OTk1LjgyLk4wLjI1Lk4ucnU%3D");

// распечатаем результирующий массив
echo "<pre>"; print_r($arr); echo "</pre>";
?>


Delete

CStatEvent::Delete

bool
CStatEvent::Delete(
 int event_id
)

Удаляет указанное событие.

Параметры функции

Параметр | Описание
event_id | ID удаляемого события.

Возвращаемое значение

Функция возвращает "true" в случае успешного удаления и "false" в случае неудачи.

См. также

  • Термин "Событие"

Примеры использования

<?
$event_id = 1;
if (CStatEvent::Delete($event_id))
    echo "Событие #".$event_id." успешно удалено.";
?>


GetGID

CStatEvent::GetGID

string
CStatEvent::GetGID(
 mixed site_id = false
)

Возвращает специальный параметр используемый при создании события в функциях CStatEvent::Add, CStatEvent::AddByEvents.

Значение данного параметра формируется на основе нижеследующих данных текущего посетителя:

  • краткий идентификатор портала (из настроек модуля "Статистика");
  • ID сессии;
  • ID посетителя;
  • двухсимвольный идентификатор страны;
  • ID рекламной кампании;
  • флаг прямого захода, либо возврата по рекламной кампании;
  • двухсимвольный идентификатор сайта.
В зависимости от значения настройки "Кодировать дополнительный параметр #EVENT_GID# для событий" модуля "Статистика" возвращаемый параметр может быть как в открытом виде, так и в base64-кодированном виде.

Параметры функции

Параметр | Описание
site_id | ID сайта.

См. также

  • CStatEvent::DecodeGID
  • Термин "Специальный параметр события"

Примеры использования

<?
// страница, на которую посетитель будет перенаправлен
// после фиксации события.
// например: платежная система или регистратор
$goto = "http://www.softkey.ru/catalog/basket.php?prodid=902&"
        "quantity=1&referer1=ritlabs_site&referer2=#EVENT_GID#";

// фиксируем событие
$goto = eregi_replace("#EVENT_GID#",
                      urlencode(CStatEvent::GetGID()),
                      $goto);
CStatEvent::AddCurrent("softkey", "out", "", "", "", $goto);

// перенаправляем посетителя
LocalRedirect($goto);
?>


GetHandlerList

CStatEvent::GetHandlerList

array
CStatEvent::GetHandlerList(
 array &handlers
)

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

Обработчики CSV файлов могут быть как пользовательские (путь к ним указывается в параметре "Путь к дополнительным обработчикам при ручной загрузке событий" в настройках модуля "Статистика"), так и стандартные - входящие в дистрибутив модуля (хранятся в каталоге /bitrix/modules/statistic/loading/).

Параметры функции

Параметр Описание
handlers Данная переменная после отработки функции будет содержать в себе массив путей относительно корня к пользовательским обработчикам. Пример данного массива:
Array
(
    [0] => /bitrix/php_interface/include/statistic/regnow_alawar.php
    [1] => /bitrix/php_interface/include/statistic/regnow_editable.php
    [2] => /bitrix/php_interface/include/statistic/regsoft_editable.php
    [3] => /bitrix/php_interface/include/statistic/shareit_editable.php
    [4] => /bitrix/php_interface/include/statistic/softkey_editable.php
)

Возвращаемое значение

Пример массива, возвращаемого функцией:

Array
(
    [reference] => Array
        (
            [0] => regnow.php
            [1] => regsoft.php
            [2] => shareit_eur.php
            [3] => shareit_usd.php
            [4] => softkey.php
            [5] => [1] regnow_alawar.php
            [6] => [2] regnow_editable.php
            [7] => [3] regsoft_editable.php
            [8] => [4] shareit_editable.php
            [9] => [5] softkey_editable.php
        )

    [reference_id] => Array
        (
            [0] => /bitrix/modules/statistic/loading/regnow.php
            [1] => /bitrix/modules/statistic/loading/regsoft.php
            [2] => /bitrix/modules/statistic/loading/shareit_eur.php
            [3] => /bitrix/modules/statistic/loading/shareit_usd.php
            [4] => /bitrix/modules/statistic/loading/softkey.php
            [5] => /bitrix/php_interface/include/statistic/regnow_alawar.php
            [6] => /bitrix/php_interface/include/statistic/regnow_editable.php
            [7] => /bitrix/php_interface/include/statistic/regsoft_editable.php
            [8] => /bitrix/php_interface/include/statistic/shareit_editable.php
            [9] => /bitrix/php_interface/include/statistic/softkey_editable.php
        )

)

См. также

  • CStatEvent::Add
  • CStatEvent::AddByEvents
  • Загрузка событий
  • Термин "Событие"

Примеры использования

<?
// получим список доступных обработчиков
$arrHandlers = CStatEvent::GetHandlerList($arUSER_HANDLERS);

// выведем этот список в виде выпадающего списка
echo SelectBoxFromArray("handler", $arrHandlers, $handler, " ");
?>


GetList

CStatEvent::GetList

CDBResult
CStatEvent::GetList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список событий.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID события;
  • s_site_id - ID сайта;
  • s_type_id - ID типа события;
  • s_event3 - дополнительный параметр event3 события;
  • s_date_enter - время создания события;
  • s_adv_id - ID рекламной кампании;
  • s_adv_back - флаг возврата либо прямого захода по рекламной кампании;
  • s_session_id - ID сессии;
  • s_guest_id - ID посетителя;
  • s_hit_id - ID хита;
  • s_url - страница где зафиксированно событие;
  • s_referer_url - ссылающаяся страница;
  • s_redirect_url - страница куда был перенаправлен посетитель после фиксации события;
  • s_country_id - ID страны посетителя;
  • s_money - денежная сумма.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID события;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • EVENT_ID* - ID типа события;
  • EVENT_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по EVENT_ID будет искаться вхождение;
  • EVENT_NAME* - название типа события;
  • EVENT_NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT_NAME будет искаться точное совпадение;
  • EVENT1* - идентификатор event1 типа события;
  • EVENT1_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT1 будет искаться точное совпадение;
  • EVENT2* - идентификатор event2 типа события;
  • EVENT2_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT2 будет искаться точное совпадение;
  • EVENT3* - дополнительный параметр event3 события;
  • EVENT3_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT3 будет искаться точное совпадение;
  • DATE - время события (точное совпадение);
  • DATE1 - начальное значение интервала для поля "дата события";
  • DATE2 - начальное значение интервала для поля "дата события";
  • MONEY - денежная сумма события (точное совпадение);
  • MONEY1 - начальное значение интервала для поля "денежная сумма";
  • MONEY2 - конечное значение интервала для поля "денежная сумма";
  • CURRENCY - трехсимвольный идентификатор валюты для денежной суммы;
  • SESSION_ID* - ID сессии;
  • SESSION_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SESSION_ID будет искаться вхождение;
  • GUEST_ID* - ID посетителя;
  • GUEST_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по GUEST_ID будет искаться вхождение;
  • ADV_ID* - ID рекламной кампании;
  • ADV_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ADV_ID будет искаться вхождение;
  • ADV_BACK - флаг "возврат по рекламной кампании", возможные значения:
    • Y - был возврат;
    • N - был прямой заход.
  • HIT_ID* - ID хита;
  • HIT_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по HIT_ID будет искаться вхождение;
  • COUNTRY_ID* - ID страны посетителя сгенерировавшего событие;
  • COUNTRY_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по COUNTRY_ID будет искаться вхождение;
  • COUNTRY* - название страны посетителя сгенерировавшего событие;
  • COUNTRY_EXACT_MATCH - если значение равно "Y", то при фильтрации по COUNTRY будет искаться точное совпадение;
  • REFERER_URL* - ссылающаяся страница;
  • REFERER_URL_EXACT_MATCH - если значение равно "Y", то при фильтрации по REFERER_URL будет искаться точное совпадение;
  • REFERER_SITE_ID - ID сайта для ссылающейся страницы;
  • URL* - страница на которой было зафиксировано событие;
  • URL_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL будет искаться точное совпадение;
  • SITE_ID - ID сайта для страницы на которой было зафиксировано событие;
  • REDIRECT_URL* - страница куда был перенаправлен посетитель после фиксации события;
  • REDIRECT_URL_EXACT_MATCH - если значение равно "Y", то при фильтрации по REDIRECT_URL будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID события
    [EVENT3] => дополнительный параметр event3 события
    [TYPE_ID] => ID типа события
    [DATE_ENTER] => время создания события
    [EVENT1] => идентификатор event1 типа события
    [EVENT2] => идентификатор event2 типа события
    [NAME] => название типа события
    [EVENT] => event1 / event2, либо название типа события
               (если оно задано)
    [DESCRIPTION] => описание типа события

    [ADV_ID] => ID рекламной кампании
    [ADV_BACK] => флаг прямого захода (N) или возврата (Y)
                  по рекламной кампании
    [COUNTRY_ID] => ID страны посетителя
    [COUNTRY_NAME] => название страны посетителя
    [SESSION_ID] => ID сессии
    [GUEST_ID] => ID посетителя
    [HIT_ID] => ID хита

    [REFERER_URL] => ссылающаяся страница
    [REFERER_SITE_ID] => ID сайта для ссылающейся страницы
    [URL] => страница на которой было зафиксировано событие
    [SITE_ID] => ID сайта для страницы, на которой было
                 зафиксировано событие
    [REDIRECT_URL] => страница, на которую был перенаправлен
                      посетитель после фиксации события

    [MONEY] => денежная сумма
    [CHARGEBACK] => Y - отрицательная денежная сумма;
                    N - положительная денежная сумма
    [CURRENCY] => трехсимвольный идентификатор валюты для денежной суммы
)

См. также

  • CStatEvent::GetListByGuest
  • Термин "Событие"

Примеры использования

<?
// выберем все неудаленные события посетителя #1025
$arFilter = array(
    "GUEST_ID" => "1025"
    );

// получим список записей
$rs = CStatEvent::GetList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetListByGuest

CStatEvent::GetListByGuest

CDBResult
CStatEvent::GetListByGuest(
 int guest_id,
 mixed type_id = false,
 mixed event3 = false,
 mixed time = false
)

Возвращает список идентификаторов событий по указанному ID посетителя сайта.

Параметры функции

Параметр | Описание
guest_id | ID посетителя.
type_id | ID типа события. Если значение равно "false", то фильтрации по типу события не будет.
event3 | Дополнительный параметр event3 события. Если значение равно "false", то фильтрации по event3 не будет.
time | Количество секунд, прошедших с текущего момента. Если значение равно "false", то фильтрации по времени не будет.

Структура возвращаемой записи

Array
(
    [ID] => ID события
)

См. также

  • CStatEvent::GetList
  • Термин "Событие"
  • Термин "Дополнительный параметр события (event3)"

Примеры использования

<?
// зафиксируем событие типа
// "Скачивание файла manual.chm" (download/manual)
// если такого типа не существует, он будет автоматически создан
// событие будет фиксироваться по параметрам
// текущего посетителя сайта

// сначала проверим - не скачивал ли уже текущий посетитель
// этот файл в течение последнего часа

// получим ID типа события
$rs = CStatEventType::GetByEvents($event1, $event2);
if ($ar = $rs->Fetch())
{
    // теперь получим все события данного типа
    // для текущего посетителя сайта,
    // произошедшие за последний час (3600 секунд)
    $rs = CStatEvent::GetListByGuest($_SESSION["SESS_GUEST_ID"],
                                     $ar["TYPE_ID"], "", 3600);

    // если таких событий не было...
    if (!($ar=$rs->Fetch()))
    {
        // ...добавляем данное событие
        CStatEvent::AddCurrent("download", "manual");
    }
}
?>


Класс CStatEventType

CStatEventType - класс для работы с типами событий.

Методы класса

Метод | Описание
ConditionSet | Находит тип события по указанным идентификаторам, либо создает новый тип события если такого ещё не существует.
Delete | Удаляет указанный тип события.
GetByEvents | Возвращает тип события по указанным идентификаторам.
GetByID | Возвращает данные по указанному типу события.
GetDropdownList | Возвращает список типов событий для вывода его в выпадающем списке с помощью функции SelectBox, либо в списке множественного выбора с помощью функции SelectBoxM.
GetDynamicList | Возвращает количество событий указанного типа в разрезе по дням.
GetList | Возвращает список типов событий.
GetSimpleList | Возвращает список типов событий в упрощённом виде.

См. также

  • Пользовательская документация, отчет "Типы событий"


ConditionSet

CStatEventType::ConditionSet

int
CStatEventType::ConditionSet(
 string event1,
 string event2,
 array &type
)

Находит тип события по указанным идентификаторам, либо создает новый тип события если такого ещё не существует.

Параметры функции

Параметр | Описание
event1 | Идентификатор event1 типа события.
event2 | Идентификатор event2 типа события.
type Ссылка на массив описывающий найденный, либо созданный тип события. Структура данного массива:
Array
(
    [TYPE_ID] => ID типа события
    [DYNAMIC_KEEP_DAYS] => количество дней, отведенное для
                           хранения статистики по данному
                           типу события в разрезе по дням
    [KEEP_DAYS] => количество дней, отведенное для хранения
                   событий данного типа
    [DATE_ENTER_STR] => дата создания события
)

Возвращаемое значение

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

См. также

  • CStatEventType::GetByEvents
  • CStatEventType::GetByID
  • Термин "Тип события"

Примеры использования

<?
// получим ID типа события "softkey/order"
// либо создадим новый тип события
$TYPE_ID = CStatEventType::ConditionSet("softkey", "order", $arEventType);
?>


Delete

CStatEventType::Delete

bool
CStatEventType::Delete(
 int type_id
)

Удаляет указанный тип события, вместе со всеми событиями данного типа.

Параметры функции

Параметр | Описание
type_id | ID типа события.

Возвращаемое значение

Функция возвращает "true" в случае успешного удаления типа события, либо "false" в противном случае.

См. также

  • Термин "Тип события"

Примеры использования

<?
$type_id = 1;
if (CStatEventType::Delete($type_id))
    echo "Тип события #".$type_id." успешно удалено.";
?>


GetByEvents

CStatEventType::GetByEvents

CDBResult
CStatEventType::GetByEvents(
 string event1,
 string event2
)

Возвращает тип события по указанным идентификаторам.

Параметры функции

Параметр | Описание
event1 | Идентификатор event1 типа события.
event2 | Идентификатор event2 типа события.

Структура возвращаемой записи

Array
(
    [TYPE_ID] => ID типа события
    [DYNAMIC_KEEP_DAYS] => количество дней, отведенное для
                           хранения статистики по данному типу
                           события в разрезе по дням
    [KEEP_DAYS] => количество дней, отведенное для хранения
                   событий данного типа
    [DATE_ENTER_STR] => дата создания события
)

См. также

  • CStatEventType::ConditionSet
  • Термин "Тип события"

Примеры использования

<?
// зафиксируем событие типа "Скачивание файла manual.chm" (download/manual)
// если такого типа не существует, он будет автоматически создан
// событие будет фиксироваться по параметрам текущего посетителя сайта

// сначала проверим не скачивал ли уже текущий посетитель этот файл
// в течение последнего часа

// получим ID типа события
$rs = CStatEventType::GetByEvents($event1, $event2);
if ($ar = $rs->Fetch())
{
    // теперь получим все события данного типа для текущего посетителя сайта
    // произошедшие за последний час (3600 секунд)
    $rs = CStatEvent::GetListByGuest($_SESSION["SESS_GUEST_ID"],
                                     $ar["TYPE_ID"], "", 3600);

    // если таких событий не было...
    if (!($ar = $rs->Fetch()))
    {
        // ...добавляем данное событие
        CStatEvent::AddCurrent("download", "manual");
    }
}
?>


GetByID

CStatEventType::GetByID

CDBResult
CStatEventType::GetByID(
 int type_id
)

Возвращает данные по указанному типу события.

Параметры функции

Параметр | Описание
type_id | ID типа события.

Структура возвращаемой записи

Array
(
    [ID] => ID типа события
    [EVENT1] => идентификатор event1 типа события
    [EVENT2] => идентификатор event2 типа события
    [NAME] => название типа события
    [EVENT] => event1 / event2, либо название типа события если оно указано
    [DESCRIPTION] => описание типа события
    [MONEY] => суммарная денежная сумма по данному типу события
    [DATE_ENTER] => дата создания типа события
    [DATE_CLEANUP] => дата очистки статистики по
                      данному типу события в разрезе по дням
    [C_SORT] => порядок сортировки
    [COUNTER] => счетчик хранящий часть суммарного количества
                 событий данного типа
    [ADV_VISIBLE] => [Y|N] флаг: включать ли статистику по
                     данному типу события в отчет по рекламным кампаниям
    [KEEP_DAYS] => количество дней отведенное для
                   хранения событий данного типа
    [DYNAMIC_KEEP_DAYS] => количество дней, отведенное для хранения
                           статистики по данному типу события
                           в разрезе по дням
    [DIAGRAM_DEFAULT] => [Y|N] флаг: включать ли данный тип события
                         в круговую диаграмму и график по умолчанию
)

См. также

  • CStatEventType::GetByEvents
  • CStatEventType::ConditionSet
  • Термин "Тип события"

Примеры использования

<?
$type_id = 1;
if ($rs = CStatEventType::GetByID($type_id))
{
    $ar = $rs->Fetch();
    // выведем параметры типа события
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetDropdownList

CStatEventType::GetDropdownList

CDBResult
CStatEventType::GetDropdownList(
 string order = "ORDER BY EVENT1, EVENT2"
)

Возвращает список типов событий для вывода его в выпадающем списке с помощью функции SelectBox, либо в списке множественного выбора с помощью функции SelectBoxM.

Параметры функции

Параметр | Описание
order | SQL код, позволяющий задать произвольную сортировку списка типов событий.

Структура возвращаемой записи

Array
(
    [REFERENCE_ID] => ID типа событий
    [REFERENCE] => "[ID] (event1 / event2) название типа события"
)

См. также

  • CStatEventType::GetList
  • CStatEventType::GetSimpleList
  • Термин "Тип события"

Примеры использования

<?
// выпадающий список с одиночным выбором
echo SelectBox(
    "SEARCHER_ID",
    CStatEventType::GetDropdownList(),
    "",
    intval($SEARCHER_ID)
    );

// список из 20 видимых элементов с возможностью множественного выбора
echo SelectBoxM(
    "arSEARCHER_ID[]",
    CStatEventType::GetDropdownList(),
    $arSEARCHER_ID,
    "",
    false,
    20
    );
?>


GetDynamicList

CStatEventType::GetDynamicList

CDBResult
CStatEventType::GetDynamicList(
 int type_id,
 string &by = "s_date",
 string &order = "desc",
 array max_min,
 array filter
)

Возвращает количество событий указанного типа в разрезе по дням.

Параметры функции

Параметр | Описание
type_id | ID типа события.
by Поле для сортировки. Возможные значения:
  • s_date - дата.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
max_min Ссылка на массив содержащий максимальную и минимальную даты результирующего списка. Структура данного массива:
Array
(
    [DATE_FIRST] => минимальная дата
    [MIN_DAY] => день минимальной даты (1-31)
    [MIN_MONTH] => месяц минимальной даты (1-12)
    [MIN_YEAR] => год минимальной даты

    [DATE_LAST] => максимальная дата
    [MAX_DAY] => день максимальной даты (1-31)
    [MAX_MONTH] => месяц максимальной даты (1-12)
    [MAX_YEAR] => год максимальной даты
)
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • DATE1 - начальное значение интервала для поля "дата";
  • DATE2 - конечное значение интервала для поля "дата".

Структура возвращаемой записи

Array
(
    [DATE_STAT] => дата
    [DAY] => день (1-31)
    [MONTH] => месяц (1-12)
    [YEAR] => год
    [COUNTER] => количество событий указанного типа для данной даты
)

См. также

  • CStatEventType::GetList
  • CStatEventType::GetSimpleList

Примеры использования

<?
$type_id = 1;

// установим фильтр на декабрь 2007 года
$arFilter = array(
    "DATE1" => "01.12.2007",
    "DATE2" => "31.12.2007"
    );

// получим набор записей
$rs = CStatEventType::GetDynamicList(
    $type_id,
    ($by="s_date"),
    ($order="desc"),
    $arMaxMin,
    $arFilter
    );

// выведем массив с максимальной и минимальной датами
echo "<pre>"; print_r($arMaxMin); echo "</pre>";

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CStatEventType::GetList

CDBResult
CStatEventType::GetList(
 string &by = "s_today_counter",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 mixed limit = false
)

Возвращает список типов событий.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID типа события;
  • s_date_last - дата последнего события данного типа;
  • s_date_enter - дата первого события данного типа;
  • s_today_counter - количество событий данного типа за сегодня;
  • s_yesterday_counter - количество событий данного типа за вчера;
  • s_b_yesterday_counter - количество событий данного типа за позавчера;
  • s_total_counter - суммарное количество событий данного типа;
  • s_period_counter - количество событий данного типа за указанный период (filter[DATE1_PERIOD], filter[DATE2_PERIOD]);
  • s_name - название типа события;
  • s_event1 - идентификатор event1 типа события;
  • s_event2 - идентификатор event2 типа события;
  • s_event12 - сортировка по "EVENT1, EVENT2";
  • s_chart - сортировка по "DIAGRAM_DEFAULT desc, TOTAL_COUNTER";
  • s_stat - сортировка по "TODAY_COUNTER desc, YESTERDAY_COUNTER desc, B_YESTERDAY_COUNTER desc, TOTAL_COUNTER desc, PERIOD_COUNTER".
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID типа события;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • EVENT1* - идентификатор event1 типа события;
  • EVENT1_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT1 будет искаться точное совпадение;
  • EVENT2* - идентификатор event2 типа события;
  • EVENT2_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT2 будет искаться точное совпадение;
  • NAME* - название типа события;
  • NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по NAME будет искаться точное совпадение;
  • DESCRIPTION* - описание типа события;
  • DESCRIPTION_EXACT_MATCH - если значение равно "Y", то при фильтрации по DESCRIPTION будет искаться точное совпадение;
  • DATE_ENTER_1 - начальное значение интервала для поля "дата первого события данного типа";
  • DATE_ENTER_2 - конечное значение интервала для поля "дата первого события данного типа";
  • DATE_LAST_1 - начальное значение интервала для поля "дата последнего события данного типа";
  • DATE_LAST_2 - конечное значение интервала для поля "дата последнего события данного типа";
  • DATE1_PERIOD - начальное значение значение для произвольного периода;
  • DATE2_PERIOD - конечное значение значение для произвольного периода;
  • COUNTER1 - начальное значение интервала для поля "суммарное количество событий данного типа";
  • COUNTER2 - конечное значение интервала для поля "суммарное количество событий данного типа";
  • ADV_VISIBLE - флаг включать ли статистику по данному типу события в отчет по рекламным кампаниям, возможные значения:
    • Y - включать;
    • N - не включать.
  • DIAGRAM_DEFAULT - флаг включать ли данный тип события в круговую диаграмму и график по умолчанию, возможные значения:
    • Y - включать;
    • N - не включать.
  • KEEP_DAYS1 - начальное значение интервала для поля "количество дней отведенное для хранения событий данного типа";
  • KEEP_DAYS2 - конечное значение интервала для поля "количество дней отведенное для хранения событий данного типа";
  • DYNAMIC_KEEP_DAYS1 - начальное значение интервала для поля "количество дней отведенное для хранения статистики по данному типу события в разрезе по дням";
  • DYNAMIC_KEEP_DAYS2 - конечное значение интервала для поля "количество дней отведенное для хранения статистики по данному типу события в разрезе по дням";
  • MONEY1 - начальное значение интервала для поля "суммарная денежная сумма для данного типа событий";
  • MONEY2 - конечное значение интервала для поля "суммарная денежная сумма для данного типа событий";
  • CURRENCY - трехсимвольный идентификатор валюты для денежной суммы;
  • GROUP - группировка результирующего списка, возможные значения:
    • event1 - группировка по event1;
    • event2 - группировка по event2.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.
limit | Максимальное число типов событий которые будут выбраны в списке. Если значение равно "false", то кол-во РК будет ограничено в соответствии со значением параметра Максимальное кол-во показываемых записей в таблицах из настроек модуля "Статистика".

Структура возвращаемой записи

В зависимости от установленной группировки, структура возвращаемой записи различная.

  • при группировке по event1 (filter["GROUP"]="event1"):
    Array
(
    [EVENT1] => идентификатор event1 типа события
    [DATE_ENTER] => дата первого события, тип которого
                    имеет данный идентификатор event1
    [DATE_LAST] => дата последнего события, тип которого
                   имеет данный идентификатор event1
    [TOTAL_COUNTER] => суммарное количество событий
    [TODAY_COUNTER] => количество событий за сегодня
    [YESTERDAY_COUNTER] => количество событий за вчера
    [B_YESTERDAY_COUNTER] => количество событий за позавчера
    [PERIOD_COUNTER] => количество событий за период времени,
                        указанный в фильтре
                        (filter[DATE1_PERIOD], filter[DATE2_PERIOD])
    [TOTAL_MONEY] => суммарная денежная сумма
    [TODAY_MONEY] => денежная сумма за сегодня
    [YESTERDAY_MONEY] => денежная сумма за вчера
    [B_YESTERDAY_MONEY] => денежная сумма за позавчера
    [PERIOD_MONEY] => денежная сумма за период времени,
                      указанный в фильтре
                      (filter[DATE1_PERIOD], filter[DATE2_PERIOD])
    [CURRENCY] => трехсимвольный идентификатор валюты
)
  • при группировке по event2 (filter["GROUP"]="event2"):
    Array
(
    [EVENT2] => идентификатор event2 типа события
    [DATE_ENTER] => дата первого события, тип которого имеет
                    данный идентификатор event2
    [DATE_LAST] => дата последнего события, тип которого имеет
                   данный идентификатор event2
    [TOTAL_COUNTER] => суммарное количество событий
    [TODAY_COUNTER] => количество событий за сегодня
    [YESTERDAY_COUNTER] => количество событий за вчера
    [B_YESTERDAY_COUNTER] => количество событий за позавчера
    [PERIOD_COUNTER] => количество событий за период времени,
                        указанный в фильтре
                        (filter[DATE1_PERIOD], filter[DATE2_PERIOD])
    [TOTAL_MONEY] => суммарная денежная сумма
    [TODAY_MONEY] => денежная сумма за сегодня
    [YESTERDAY_MONEY] => денежная сумма за вчера
    [B_YESTERDAY_MONEY] => денежная сумма за позавчера
    [PERIOD_MONEY] => денежная сумма за период времени,
                      указанный в фильтре
                      (filter[DATE1_PERIOD], filter[DATE2_PERIOD])
    [CURRENCY] => трехсимвольный идентификатор валюты
)
  • когда группировка не установлена:
    Array
(
    [ID] => ID типа события
    [EVENT1] => идентификатор event1 типа события
    [EVENT2] => идентификатор event2 типа события
    [DIAGRAM_DEFAULT] => [Y|N] флаг: включать ли данный тип события
                         в круговую диаграмму и график по умолчанию
    [NAME] => название типа события
    [EVENT] => event1 / event2, либо название типа события
               (если оно указано)
    [DESCRIPTION] => описание типа события
    [TOTAL_COUNTER] => суммарное количество событий данного типа
    [TODAY_COUNTER] => количество событий данного типа за сегодня
    [YESTERDAY_COUNTER] => количество событий данного типа за вчера
    [B_YESTERDAY_COUNTER] => количество событий данного типа
                             за позавчера
    [PERIOD_COUNTER] => количество событий данного типа за период времени,
                        указанный в фильтре
                        (filter[DATE1_PERIOD], filter[DATE2_PERIOD])
    [TOTAL_MONEY] => суммарная денежная сумма по данному типу события
    [TODAY_MONEY] => денежная сумма по данному типу события за сегодня
    [YESTERDAY_MONEY] => денежная сумма по данному типу события за вчера
    [B_YESTERDAY_MONEY] => денежная сумма по данному типу события за позавчера
    [PERIOD_MONEY] => денежная сумма по данному типу события за период времени,
                      указанный в фильтре
                      (filter[DATE1_PERIOD], filter[DATE2_PERIOD])
    [CURRENCY] => трехсимвольный идентификатор валюты
)

См. также

  • CStatEventType::GetDynamicList
  • CStatEventType::GetSimpleList
  • Термин "Тип события"

Примеры использования

<?
// получим данные только по тем типам событий
// у которых event1 = "download"
// а также получим дополнительные данные на декабрь 2007 года
$arFilter = array(
    "DATE1_PERIOD" => "01.12.2007",
    "DATE2_PERIOD" => "31.12.2007",
    "EVENT1"       => "download"
    );

// получим список записей
$rs = CStatEventType::GetList(
    ($by = "s_today_counter"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetSimpleList

CStatEventType::GetSimpleList

CDBResult
CStatEventType::GetSimpleList(
 string &by = "s_event1",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список типов событий в упрощённом виде.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID типа события;
  • s_event1 - идентификатор event1 типа события;
  • s_event2 - идентификатор event2 типа события;
  • s_name - название типа события;
  • s_description - описание типа события.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID типа события;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • EVENT1* - идентификатор event1 типа события;
  • EVENT1_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT1 будет искаться точное совпадение;
  • EVENT2* - идентификатор event2 типа события;
  • EVENT2_EXACT_MATCH - если значение равно "Y", то при фильтрации по EVENT2 будет искаться точное совпадение;
  • NAME* - название типа события;
  • NAME_EXACT_MATCH - если значение равно "Y", то при фильтрации по NAME будет искаться точное совпадение;
  • DESCRIPTION* - описание типа события;
  • DESCRIPTION_EXACT_MATCH - если значение равно "Y", то при фильтрации по DESCRIPTION будет искаться точное совпадение;
  • KEYWORDS - event1, event2, название и описание типа события;
  • KEYWORDS_EXACT_MATCH - если значение равно "Y", то при фильтрации по KEYWORDS будет искаться точное совпадение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [ID] => ID типа события
    [EVENT1] => идентификатор event1 типа события
    [EVENT2] => идентификатор event2 типа события
    [NAME] => название типа события
    [EVENT] => event1 / event2, либо название типа события если оно указано
    [DESCRIPTION] => описание типа события
)

См. также

  • CStatEventType::GetDynamicList
  • CStatEventType::GetList
  • Термин "Тип события"

Примеры использования

<?
// выберем только те типы событий у которых в event1 входит "download"
$arFilter = array(
    "EVENT1" => "download"
    );

// получим список записей
$rs = CStatEventType::GetSimpleList(
    ($by="s_event2"),
    ($order="desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CStatistics

CStatistics - класс содержащий общие методы работы с модулем "Статистика".

Методы класса

Метод | Описание
CleanUp | Очищает собранные статистические данные.
Keep | Собирает статистические данные.

См. также

  • Введение в модуль "Статистика"


CleanUp

CStatistics::CleanUp

bool
CStatistics::CleanUp(
 string date = "",
 array &errors
)

Очищает собранные статистические данные.

Параметры функции

Параметр | Описание
date | Дата в формате текущего сайта (или языка) до которой (включительно) необходимо очистить статистику. Если в данном параметре не указать дату, то будут очищены все накопленные данные статистики.
errors | Если параметр date не содержит даты, то в данном параметре будут возвращены возможные ошибки которые могут возникнуть в процессе полной очистки данных статистики.

Возвращаемое значение

Функция возвращает "true", в случае успешного выполнения и "false" - в противном случае.

См. также

  • Настройки модуля "Статистика"

Примеры использования

<?
// дата в формате текущего сайта или языка
// до которой включительно будет очищена вся собранная статистика
$date = "31.12.2007";

// очищаем
CStatistics::CleanUp($date);
?>


Keep

CStatistics::Keep

CStatistics::Keep(
 bool handle_call = false
)

Вызов данной функции обеспечивает сбор всех статистических данных.

При инсталлированном модуле статистики данная функция автоматически вызывается в прологе. Но есть возможность отключить автоматический вызов этой функции в прологе, инициализировав константу STOP_STATISTICS перед подключением пролога. После этого данную функцию можно вызвать, указав в параметрах handle_call=true.

Параметры функции

Параметр | Описание
handle_call | Если значение данного параметра равно "true", то функция проигнорирует константу STOP_STATISTICS и продолжит свою работу.

См. также

  • Константа "STOP_STATISTICS"
  • Константа "NO_KEEP_STATISTIC"

Примеры использования

<?
// отключим автоматический сбор статистики в прологе
define("STOP_STATISTICS", true);
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

// вручную запустим сбор статистики
CStatistics::Keep(true);

...

?>


Класс CStopList

CStopList - класс для работы со стоп-листом.

Методы класса

Метод | Описание
Check | Выполняет проверку на попадание текущего посетителя в стоп-лист.
GetByID | Возвращает данные по записи стоп-листа.
GetList | Возвращает список записей стоп-листа.

См. также

  • Работа со стоп-листом


Check

CStopList::Check

mixed
CStopList::Check(
 string test = "N",
 mixed params = false
)

Выполняет проверку на попадание текущего посетителя под условия записей стоп-листа. Данная функция автоматически вызывается в прологе на каждом хите.

Параметры функции

Параметр Описание
test При управлении стоп-листом существует вероятность занести самого себя в стоп-лист. Для исключения подобных ситуаций, система сначала добавляет в стоп-лист тестовую запись, проверяет текущего посетителя на попадание в стоп-лист по этой тестовой записи и если посетитель не пападает под нее, то она удаляется.

Если вызвать данную функцию с параметром test="Y", она проверит попадание текущего посетителя только под тестовые записи стоп-листа. Если же функция вызывается с параметром test="N" (значение по умолчанию), то она будет проверять попадание посетителя уже под все записи стоп-листа, за исключением тестовых.
params Здесь можно задать массив параметров для которых будет произведена проверка на попадание в стоп-лист. Ключами данного массива могут быть:
  • IP - IP адрес в формате XXX.XXX.XXX.XXX;
  • USER_AGENT - UserAgent (полный, либо его часть);
  • URL_FROM - ссылающаяся страница;
  • URL_TO - страница на которую приходит посетитель;
  • SITE_ID - ID сайта.

Возвращаемое значение

Функция возвращает ID записи стоп-листа под которую попал посетитель, либо "false" в противном случае.

См. также

  • Термин "Стоп-лист"
  • Термин "Маска подсети для стоп-листа"

Примеры использования

<?
// зададим параметры посетителя для которых мы хотим проверить попадание в стоп-лист
$arParams = array(
    "IP" => "192.168.0.1",
    "USER_AGENT" => "Firefox"
    );

$record_id = CStopList::Check("N", $arParams);
if (intval($record_id)>0)
    echo "Попадание в стоп-лист под параметры записи #".intval($record_id);
?>


GetByID

CStopList::GetByID

CDBResult
CStopList::GetByID(
 int record_id
)

Возвращает данные по записи стоп-листа.

Параметры функции

Параметр | Описание
record_id | ID записи сто-листа.

Структура возвращаемой записи

Array
(
    [ID] => ID записи
    [TIMESTAMP_X] => время изменения
    [DATE_START] => время с которого запись начинает действовать
    [DATE_END] => время после которого действие записи заканчивается
    [ACTIVE] => "Y" - запись активна; "N" - запись не активна
    [SAVE_STATISTIC] => "Y" - сохранять статистику по посетителю,
                        попавшему в стоп-лист;
                        "N" - не сохранять подобную статистику
    [IP_1] => октет 1 IP адреса
    [IP_2] => октет 2 IP адреса
    [IP_3] => октет 3 IP адреса
    [IP_4] => октет 4 IP адреса
    [MASK_1] => маска для октета 1 IP адреса
    [MASK_2] => маска для октета 2 IP адреса
    [MASK_3] => маска для октета 3 IP адреса
    [MASK_4] => маска для октета 4 IP адреса
    [USER_AGENT] => UserAgent посетителя
    [USER_AGENT_IS_NULL] => "Y" - UserAgent посетителя не задан (пустой);
                            "N" - UserAgent посетителя задан
                            (значение по умолчанию)
    [URL_TO] => страница (или ее часть),
                на которую приходит посетитель
    [URL_FROM] => ссылающаяся страница (или ее часть),
                  с которой приходит посетитель
    [MESSAGE] => текст сообщения, которое будет выдано посетителю сайта,
                 в случае его попадания под данную запись стоп-листа
    [MESSAGE_LID] => язык сообщения задаваемого в поле [MESSAGE]
    [URL_REDIRECT] => страница, на которую необходимо перенаправить
                      посетителя после его попадания
                      под данную запись стоп-листа
    [COMMENTS] => административный комментарий;
                  используется, как правило,
                  для указания причин создания данной записи
    [TEST] => "Y" - данная запись является тестовой;
              "N" - данная запись не тестовая
              (см. функцию CStopList::Check)
    [SITE_ID] => ID сайта, для которого запись будет действительна;
                 если значение не задано, то это означает,
                 что запись действительная для всех сайтов
    [LAMP] => "green" - запись активна и работает;
              "red" - запись по каким либо причинам не активна
              (возможно истек срок действия, либо снят флаг активности)
)

См. также

  • Термин "Стоп-лист"

Примеры использования

<?
$stop_id = 1;
if ($rs = CStopList::GetByID($stop_id))
{
    $ar = $rs->Fetch();
    // выведем параметры записи стоп-листа
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


GetList

CStopList::GetList

CDBResult
CStopList::GetList(
 string &by = "s_id",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered
)

Возвращает список записей стоп-листа.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID записи;
  • s_date_start - время начала активности записи;
  • s_date_end - время окончания активности записи ;
  • s_site_id - ID сайта для которого действительна записи;
  • s_active - флаг активности записи;
  • s_save_statistic - флаг необходимости сохранять статистику по посетителю попавшему в стоп-лист;
  • s_ip - IP адрес посетителя;
  • s_mask - маска IP адреса посетителя;
  • s_url_to - страница на которую приходит посетитель;
  • s_url_from - ссылающаяся страница, с которой приходит посетитель.
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID сессии;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • DATE_START_1 - начальное значение интервала для поля "время начала активности записи";
  • DATE_START_2 - конечное значение интервала для поля "время начала активности записи";
  • DATE_END_1 - начальное значение интервала для поля "время окончания активности записи";
  • DATE_END_2 - конечное значение интервала для поля "время окончания активности записи";
  • ACTIVE - флаг активности записи, воможные значения:
    • Y - запись активна;
    • N - запись не активна.
  • SAVE_STATISTIC - флаг необходимости сохранения статистики по посетителю попавшему в стоп-лист, воможные значения:
    • Y - статистику сохранять;
    • N - статистику не сохранять.
  • IP_1* - октет 1 IP адреса;
  • IP_1_EXACT_MATCH - если значение равно "N", то при фильтрации по IP_1 будет искаться вхождение;
  • IP_2* - октет 2 IP адреса;
  • IP_2_EXACT_MATCH - если значение равно "N", то при фильтрации по IP_2 будет искаться вхождение;
  • IP_3* - октет 3 IP адреса;
  • IP_3_EXACT_MATCH - если значение равно "N", то при фильтрации по IP_3 будет искаться вхождение;
  • IP_4* - октет 4 IP адреса;
  • IP_4_EXACT_MATCH - если значение равно "N", то при фильтрации по IP_4 будет искаться вхождение;
  • URL_FROM* - ссылающаяся страница, с которой приходит посетитель;
  • URL_FROM_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL_FROM будет искаться точное совпадение;
  • USER_AGENT* - UserAgent посетителя;
  • USER_AGENT_EXACT_MATCH - если значение равно "Y", то при фильтрации по USER_AGENT будет искаться точное совпадение;
  • MESSAGE* - текст сообщения которое будет выдано посетителю сайта, в случае его попадания под данную запись стоп-листа;
  • MESSAGE_EXACT_MATCH - если значение равно "Y", то при фильтрации по MESSAGE будет искаться точное совпадение;
  • COMMENTS* - административный комментарий, используется как правило для указания причин создания данной записи;
  • COMMENTS_EXACT_MATCH - если значение равно "Y", то при фильтрации по COMMENTS будет искаться точное совпадение;
  • URL_TO* - страница (или ее часть) на которую приходит посетитель;
  • URL_TO_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL_TO будет искаться точное совпадение;
  • URL_REDIRECT* - страница на которую необходимо перенаправить посетителя после его попадания под данную запись стоп-листа;
  • URL_REDIRECT_EXACT_MATCH - если значение равно "Y", то при фильтрации по URL_REDIRECT будет искаться точное совпадение;
  • SITE_ID* - ID сайта для которого запись будет действительна; если значение не задано, то это означает что запись действительная для всех сайтов;
  • SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE_ID будет искаться вхождение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.

Структура возвращаемой записи

Array
(
    [DATE_START] => время с которого запись начинает действовать
    [DATE_END] => время после которого действие записи заканчивается
    [ACTIVE] => "Y" - запись активна; "N" - запись не активна
    [SAVE_STATISTIC] => "Y" - сохранять статистику по посетителю,
                        попавшему в стоп-лист;
                        "N" - не сохранять подобную статистику
    [IP_1] => октет 1 IP адреса
    [IP_2] => октет 2 IP адреса
    [IP_3] => октет 3 IP адреса
    [IP_4] => октет 4 IP адреса
    [MASK_1] => маска для октета 1 IP адреса
    [MASK_2] => маска для октета 2 IP адреса
    [MASK_3] => маска для октета 3 IP адреса
    [MASK_4] => маска для октета 4 IP адреса
    [USER_AGENT] => UserAgent посетителя
    [USER_AGENT_IS_NULL] => "Y" - UserAgent посетителя не задан (пустой);
                            "N" - UserAgent посетителя задан
                            (значение по умолчанию)
    [URL_TO] => страница (или ее часть) на которую приходит посетитель
    [URL_FROM] => ссылающаяся страница (или ее часть),
                  с которой приходит посетитель
    [MESSAGE] => текст сообщения которое будет выдано посетителю сайта,
                 в случае его попадания под данную запись стоп-листа
    [MESSAGE_LID] => язык сообщения задаваемого в поле [MESSAGE]
    [URL_REDIRECT] => страница на которую необходимо перенаправить
                     посетителя после его попадания
                     под данную запись стоп-листа
    [COMMENTS] => административный комментарий; используется, как правило,
                  для указания причин создания данной записи
    [TEST] => "Y" - данная запись является тестовой;
              "N" - данная запись не тестовая
              (см. функцию CStopList::Check)
    [SITE_ID] => ID сайта для которого запись будет действительна;
                 если значение не задано, то это означает что запись
                 действительная для всех сайтов
    [LAMP] => "green" - запись активна и работает;
              "red" - запись не активная по каким либо причинам
              (возможно истек срок действия, либо снят флаг активности)
)

См. также

  • Термин "Стоп-лист"

Примеры использования

<?
// выберем записи стоп-листа с IP адресами 192.168.0.xxx
$arFilter = array(
    "IP_1" => 192,
    "IP_2" => 168,
    "IP_3" => 0
    );

// получим список записей
$rs = CStopList::GetList(
    ($by = "s_id"),
    ($order = "desc"),
    $arFilter,
    $is_filtered
    );

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Класс CTraffic

CTraffic - класс для получения общих данных по посещаемости сайта.

Методы класса

Метод | Описание
GetCommonValues | Возвращает основные статистические данные (количество хитов, хостов, сессий, посетителей, событий) за весь период ведения статистики, за последние 3 дня, а также за произвольный указанный интервал времени.
GetDailyList | Возвращает основные статистические данные, а также данные по внимательности посетителей в разрезе по дням.
GetPhraseList | Возвращает количество поисковых фраз за весь период ведения статистики, за последние 3 дня, а также за произвольный указанный интервал времени.
GetRefererList | Возвращает количество ссылающихся сайтов за весь период ведения статистики, за последние 3 дня, а также за произвольный указанный интервал времени.
GetSumList | Возвращает основные статистические данные в разрезе по часам, дням недели и месяцам.

См. также

  • Отчет "Сводная статистика"
  • Отчет "Посещаемость"


GetCommonValues

CTraffic::GetCommonValues

array
CTraffic::GetCommonValues(
 array filter = array()
)

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

При фильтрации по сайту (filter[SITE_ID]), будут доступны только данные по хитам, хостам, сессиям, событиям. Данные по посетителям будут отсутствовать, т.к. текущая версия модуля предполагает, что посетитель один на весь портал.

Параметры функции

Параметр Описание
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • SITE_ID - ID сайта для которого необходимо получить статистику;
  • DATE1 - начальная дата;
  • DATE2 - конечная дата.

Возвращаемое значение

В случае если не установлена фильтрация по сайту, то структура возвращаемого массива будет следующей:

Array
(
    [TOTAL_HITS] => суммарное количество хитов за все время ведения статистики
    [TOTAL_SESSIONS] => суммарное количество сессий за все время ведения статистики
    [TOTAL_EVENTS] => суммарное количество событий за все время ведения статистики
    [TOTAL_HOSTS] => суммарное количество хостов за все время ведения статистики
    [TOTAL_GUESTS] => суммарное количество посетителей за все время ведения статистики
    [TOTAL_FAVORITES] => суммарное количество посетителей, добавивших сайт в
                         "Избранное" за все время ведения статистики

    [TODAY_HITS] => количество хитов за сегодня
    [TODAY_SESSIONS] => количество сессий за сегодня
    [TODAY_EVENTS] => количество событий за сегодня
    [TODAY_HOSTS] => количество хостов за сегодня
    [TODAY_GUESTS] => суммарное количество посетителей за сегодня
    [TODAY_NEW_GUESTS] => количество новых посетителей  за сегодня
    [TODAY_FAVORITES] => количество посетителей, добавивших сайт в
                         "Избранное", за сегодня

    [YESTERDAY_HITS] => количество хитов за вчера
    [YESTERDAY_SESSIONS] => количество сессий за вчера
    [YESTERDAY_EVENTS] => количество событий за вчера
    [YESTERDAY_HOSTS] => количество хостов за вчера
    [YESTERDAY_GUESTS] => суммарное количество посетителей за вчера
    [YESTERDAY_NEW_GUESTS] => количество новых посетителей за вчера
    [YESTERDAY_FAVORITES] => количество посетителей, добавивших сайт в
                             "Избранное", за вчера

    [B_YESTERDAY_HITS] => количество хитов за позавчера
    [B_YESTERDAY_SESSIONS] => количество сессий за позавчера
    [B_YESTERDAY_EVENTS] => количество событий за позавчера
    [B_YESTERDAY_HOSTS] => количество хостов за позавчера
    [B_YESTERDAY_GUESTS] => суммарное количество посетителей за позавчера
    [B_YESTERDAY_NEW_GUESTS] => количество новых посетителей за позавчера
    [B_YESTERDAY_FAVORITES] => количество посетителей, добавивших сайт в
                               "Избранное", за позавчера

    [PERIOD_HITS] => количество хитов за установленный период времени
                     (filter[DATE1], filter[DATE2])
    [PERIOD_SESSIONS] => количество сессий за установленный период времени
    [PERIOD_EVENTS] => количество событий за установленный период времени
    [PERIOD_NEW_GUESTS] => количество новых посетителей за установленный
                           период времени
    [PERIOD_FAVORITES] => количество посетителей, добавивших сайт в
                          "Избранное", за установленный период времени

    [ONLINE_GUESTS] => количество посетителей в online
)

См. также

  • CUserOnline::GetGuestCount
  • Отчет "Сводная статистика"

Примеры использования

<?
// получим данные по посещаемости сайта
$arr = CTraffic::GetCommonValues();

echo "Всего хитов: ".$arr["TOTAL_HITS"];
echo "Сегодня хитов: ".$arr["TODAY_HITS"];

echo "Всего хостов: ".$arr["TOTAL_HOSTS"];
echo "Сегодня хостов: ".$arr["TODAY_HOSTS"];

echo "Всего посетителей: ".$arr["TOTAL_GUESTS"];
echo "Сегодня посетителей: ".$arr["TODAY_GUESTS"];
echo "Посетителей в онлайн: ".$arr["ONLINE_GUESTS"];
?>


GetDailyList

CTraffic::GetDailyList

CDBResult
CTraffic::GetDailyList(
 string &by = "s_date",
 string &order = "desc",
 array &max_min,
 array filter = array(),
 bool &is_filtered,
 string get_maxmin = "Y"
)

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

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_id - ID записи;
  • s_date - дата;
  • s_hits - количество хитов;
  • s_hosts - количество хостов;
  • s_sessions - количество сессий;
  • s_events - количество событий;
  • s_guests - количество посетителей;
  • s_new_guests - количество новых посетителей;
  • s_favorites - количество посетителей, добавивших сайт в "Избранное".
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
max_min Ссылка на массив содержащий максимальную и минимальную даты из выбранного результирующего списка. Структура данного массива:
Array
(
    [DATE_FIRST] => минимальная дата
    [MIN_DAY] => день минимальной даты (1-31)
    [MIN_MONTH] => месяц минимальной даты (1-12)
    [MIN_YEAR] => год минимальной даты

    [DATE_LAST] => максимальная дата
    [MAX_DAY] => день максимальной даты (1-31)
    [MAX_MONTH] => месяц максимальной даты (1-12)
    [MAX_YEAR] => год максимальной даты
)
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • ID* - ID записи;
  • ID_EXACT_MATCH - если значение равно "N", то при фильтрации по ID будет искаться вхождение;
  • DATE1 - начальное значение интервала для поля "дата";
  • DATE2 - конечное значение интервала для поля "дата";
  • HITS_1 - начальное значение интервала для поля "количество хитов";
  • HITS_2 - конечное значение интервала для поля "количество хитов";
  • HOSTS_1 - начальное значение интервала для поля "количество хостов";
  • HOSTS_2 - начальное значение интервала для поля "количество хостов";
  • SESSIONS_1 - начальное значение интервала для поля "количество сессий";
  • SESSIONS_2 - конечное значение интервала для поля "количество сессий";
  • EVENTS_1 - начальное значение интервала для поля "количество событий";
  • EVENTS_2 - конечное значение интервала для поля "количество событий";
  • GUESTS_1 - начальное значение интервала для поля "количество посетителей";
  • GUESTS_2 - конечное значение интервала для поля "количество посетителей";
  • NEW_GUESTS_1 - начальное значение интервала для поля "количество новых посетителей";
  • NEW_GUESTS_2 - конечное значение интервала для поля "количество новых посетителей";
  • FAVORITES_1 - начальное значение интервала для поля "количество посетителей добавивших сайт в "Избранное"";
  • FAVORITES_2 - конечное значение интервала для поля "количество посетителей добавивших сайт в "Избранное";
  • SITE_ID* - ID сайта;
  • SITE_ID_EXACT_MATCH - если значение равно "N", то при фильтрации по SITE_ID будет искаться вхождение.
* - допускается сложная логика
is_filtered | Флаг отфильтрованности результирующего списка. Если значение равно "true", то список был отфильтрован.
get_maxmin | Если значение данной переменной равно "Y", то в параметр max_min будет возвращен соответствующий массив содержащий максимальную и минимальную даты из выбранного результирующего списка.

Структура возвращаемой записи

Array
(
    [ID] => ID записи
    [DATE_STAT] => дата
    [DAY] => день (1-31)
    [MONTH] => месяц (1-12)
    [YEAR] => год
    [WDAY] => номер дня недели
              (0 - понедельник,
               1 - вторник, ...
               6 - воскресенье)
    [HITS] => количество хитов
    [C_HOSTS] => количество хостов
    [SESSIONS] => количество сессий
    [C_EVENTS] => количество событий
    [GUESTS] => количество посетителей
    [NEW_GUESTS] => количество новых посетителей
    [FAVORITES] => количество посетителей, добавивших сайт в "Избранное"
    [TOTAL_HOSTS] => количество хостов
    [AM_AVERAGE_TIME] => среднее время длительности сессии
    [AM_1] => количество сессий длительность которых менее 1 минуты
    [AM_1_3] => количество сессий длительность которых от 1 до 3 минут
    [AM_3_6] => количество сессий длительность которых от 3 до 6 минут
    [AM_6_9] => количество сессий длительность которых от 6 до 9 минут
    [AM_9_12] => количество сессий длительность которых от 9 до 12 минут
    [AM_12_15] => количество сессий длительность которых от 12 до 15 минут
    [AM_15_18] => количество сессий длительность которых от 15 до 18 минут
    [AM_18_21] => количество сессий длительность которых от 18 до 21 минут
    [AM_21_24] => количество сессий длительность которых от 21 до 24 минут
    [AM_24] => количество сессий длительность которых более 24 минут
    [AH_AVERAGE_HITS] => среднее количество хитов в сессии
    [AH_1] => количество сессий в которых был только 1 хит
    [AH_2_5] => количество сессий в которых было от 2 до 5 хитов
    [AH_6_9] => количество сессий в которых было от 6 до 9 хитов
    [AH_10_13] => количество сессий в которых было от 10 до 13 хитов
    [AH_14_17] => количество сессий в которых было от 14 до 17 хитов
    [AH_18_21] => количество сессий в которых было от 18 до 21 хитов
    [AH_22_25] => количество сессий в которых было от 22 до 25 хитов
    [AH_26_29] => количество сессий в которых было от 26 до 29 хитов
    [AH_30_33] => количество сессий в которых было от 30 до 33 хитов
    [AH_34] => количество сессий в которых было более 34 хитов
)

См. также

  • CTraffic::GetCommonValues
  • Отчет "Динамика посещаемости"

Примеры использования

<?
// ограничимся данными только за декабрь 2007 года
$arFilter = array(
    "DATE1" => "01.12.2007",
    "DATE2" => "31.12.2007"
    );

// получим данные по посещаемости
$rsDays = CTraffic::GetDailyList(
    ($by="s_date"),
    ($order="desc"),
    $arMaxMin,
    $arFilter,
    $is_filtered
    );

while ($arDay = $rsDays->Fetch())
{
    echo "дата: ".$arDay["DATE_STAT"]."<br>";
    echo "количество хитов: ".$arDay["HITS"]."<br>";
    echo "количество хостов: ".$arDay["C_HOSTS"]."<br>";
    echo "количество сессий: ".$arDay["SESSIONS"]."<br>";
    echo "количество событий: ".$arDay["C_EVENTS"]."<br>";
    echo "количество посетителей: ".$arDay["GUESTS"]."<br>";
}
?>


GetPhraseList

CTraffic::GetPhraseList

CDBResult
CTraffic::GetPhraseList(
 string &by = "s_today",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 mixed limit = 10,
)

Возвращает количество поисковых фраз за весь период ведения статистики, за последние 3 дня, а также за произвольный указанный интервал времени.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • s_phrase - поисковая фраза;
  • s_today - количество поисковых фраз за сегодня;
  • s_yesterday - количество поисковых фраз за вчера;
  • s_bef_yesterday - количество поисковых фраз за позавчера;
  • s_total - суммарное количество поисковых фраз;
  • s_period - количество поисковых фраз за установленный период времени (filter[DATE1], filter[DATE2]).
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • SITE_ID - ID сайта для которого необходимо получить статистику по поисковым фразам;
  • DATE1 - начальная дата;
  • DATE2 - конечная дата.
is_filtered | Флаг отфильтрованности списка поисковых фраз. Если значение равно "true", то список был отфильтрован.
limit | Максимальное число записей результирующего списка. Если задано число >0, то число записей будет ограничено, иначе ограничений не будет.

Структура возвращаемой записи

Array
(
    [PHRASE] => поисковая фраза
    [TOTAL_PHRASES] => суммарное количество заходов
                       с данной поисковой фразой
    [TODAY_PHRASES] => сколько раз сегодня заходили
                       с данной поисковой фразой
    [YESTERDAY_PHRASES] => сколько раз вчера заходили
                           с данной поисковой фразой
    [B_YESTERDAY_PHRASES] => сколько раз позавчера заходили
                             с данной поисковой фразой
    [PERIOD_PHRASES] => сколько раз заходили с данной
                        поисковой фразой за установленный период времени
                        (filter[DATE1], filter[DATE2])
)

См. также

  • Класс "CPhrase"
  • Отчет "Сводная статистика"

Примеры использования

<?
// получим дополнительные данные за декабрь 2007 года
$arFilter = array(
    "DATE1" => "01.12.2007",
    "DATE2" => "31.12.2007"
    );

// получим список поисковых фраз и статистику по ним
$rs = CTraffic::GetPhraseList($by="s_today",
                              $order="desc",
                              $arFilter,
                              $is_filtered,
                              false);
while ($ar = $rs->Fetch())
{
    echo "поисковая фраза: ".$ar["PHRASE"]."<br>";
    echo "всего заходов с данной поисковой фразой: ".
         $ar["TOTAL_PHRASES"].
         "<br>";
    echo "сегодня: ".$ar["TODAY_PHRASES"]."<br>";
    echo "вчера: ".$ar["YESTERDAY_PHRASES"]."<br>";
    echo "позавчера: ".$ar["B_YESTERDAY_PHRASES"]."<br>";
    echo "в течение декабря 2005 года: ".
         $ar["PERIOD_PHRASES"]."<br>";
}
?>


GetRefererList

CTraffic::GetRefererList

CDBResult
CTraffic::GetRefererList(
 string &by = "ref_today",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 mixed limit = 10,
)

Возвращает количество ссылающихся сайтов за весь период ведения статистики, за последние 3 дня, а также за произвольный указанный интервал времени.

Параметры функции

Параметр | Описание
by Поле для сортировки. Возможные значения:
  • ref_server - ссылающийся сайт;
  • ref_today - количество заходов с ссылающегося сайта за сегодня;
  • ref_yesterday - количество заходов с ссылающегося сайта за вчера;
  • ref_bef_yesterday - количество заходов с ссылающегося сайта за позавчера;
  • ref_total - суммарное количество заходов с ссылающегося сайта;
  • ref_period - количество заходов с ссылающегося сайта за установленный период времени (filter[DATE1], filter[DATE2]).
оrder Порядок сортировки. Возможные значения:
  • asc - по возрастанию;
  • desc - по убыванию.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • SITE_ID - ID сайта для которого необходимо получить статистику по ссылающимся сайтам;
  • DATE1 - начальная дата;
  • DATE2 - конечная дата.
is_filtered | Флаг отфильтрованности списка ссылающихся сайтов. Если значение равно "true", то список был отфильтрован.
limit | Максимальное число записей результирующего списка. Если задано число >0, то число записей будет ограничено, иначе ограничений не будет.

Структура возвращаемой записи

Array
(
    [SITE_NAME] => ссылающийся сайт
    [TOTAL_REFERERS] => суммарное количество заходов
                        с данного ссылающегося сайта
    [TODAY_REFERERS] => количество заходов
                        с ссылающегося сайта за сегодня
    [YESTERDAY_REFERERS] => количество заходов
                            с ссылающегося сайта за вчера
    [B_YESTERDAY_REFERERS] => количество заходов
                              с ссылающегося сайта за позавчера
    [PERIOD_REFERERS] => количество заходов с ссылающегося сайта
                         за установленный период времени
                         (filter[DATE1], filter[DATE2])
)

См. также

  • Класс "CReferer"
  • Отчет "Сводная статистика"

Примеры использования

<?
// получим дополнительные данные за декабрь 2007 года
$arFilter = array(
    "DATE1" => "01.12.2007",
    "DATE2" => "31.12.2007"
    );

// получим список поисковых фраз и статистику по ним
$rs = CTraffic::GetRefererList(
    ($by="ref_today"),
    ($order="desc"),
    $arFilter,
    $is_filtered,
    false
    );

while ($ar = $rs->Fetch())
{
    echo "ссылающийся сайт: ".$ar["SITE_NAME"]."<br>";
    echo "всего заходов с данного ссылающегося сайта: ".
         $ar["TOTAL_REFERERS"]."<br>";
    echo "сегодня: ".$ar["TODAY_REFERERS"]."<br>";
    echo "вчера: ".$ar["YESTERDAY_REFERERS"]."<br>";
    echo "позавчера: ".$ar["B_YESTERDAY_REFERERS"]."<br>";
    echo "в течение декабря 2005 года: ".
         $ar["PERIOD_REFERERS"]."<br>";
}
?>


GetSumList

CTraffic::GetSumList

CDBResult
CTraffic::GetSumList(
 string data_type,
 array filter = array(),
)

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

Параметры функции

Параметр Описание
data_type Тип данных. Возможные значения:
  • hour - данные в разрезе по часам;
  • weekday - данные в разрезе по дням недели;
  • month - данные в разрезе по месяцам.
filter Массив для фильтрации результирующего списка. В массиве допустимы следующие ключи:
  • SITE_ID - ID сайта для которого необходимо получить статистику по ссылающимся сайтам;
  • DATE1 - начальная дата;
  • DATE2 - конечная дата.

Структура возвращаемой записи

В зависимости от значения параметра data_type, структура возвращаемой записи различная.

  • при получении данных в разрезе по часам (data_type=hour):
    Array
(
    [HOUR_HOST_0] => число хостов, зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_HOST_23] => число хостов, зафиксированных с 23:00 до 0:00

    [HOUR_SESSION_0] => число сессий, зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_SESSION_23] => число сессий, зафиксированных с 23:00 до 0:00

    [HOUR_HIT_0] => число хитов, зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_HIT_23] => число хитов, зафиксированных с 23:00 до 0:00

    [HOUR_EVENT_0] => число событий, зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_EVENT_23] => число событий, зафиксированных с 23:00 до 0:00

    [HOUR_GUEST_0] => число посетителей, зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_GUEST_23] => число посетителей, зафиксированных с 23:00 до 0:00

    [HOUR_NEW_GUEST_0] => число новых посетителей, зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_NEW_GUEST_23] => число новых посетителей, зафиксированных с 23:00 до 0:00

    [HOUR_FAVORITE_0] => число посетителей, добавивших сайт в "Избранное", зафиксированных с 0:00 до 1:00 часа
    ...
    [HOUR_FAVORITE_23] => число посетителей, добавивших сайт в "Избранное", зафиксированных с 23:00 до 0:00
)
  • при получении данных в разрезе по дням недели (data_type=weekday):
    Array
(
    [WEEKDAY_HOST_0] => число хостов, зафиксированных в воскресенье
    [WEEKDAY_HOST_1] => число хостов, зафиксированных в понедельник
    ...
    [WEEKDAY_HOST_6] => число хостов, зафиксированных в субботу

    [WEEKDAY_SESSION_0] => число сессий, зафиксированных в воскресенье
    [WEEKDAY_SESSION_1] => число сессий, зафиксированных в понедельник
    ...
    [WEEKDAY_SESSION_6] => число сессий, зафиксированных в субботу

    [WEEKDAY_HIT_0] => число хитов, зафиксированных в воскресенье
    [WEEKDAY_HIT_1] => число хитов, зафиксированных в понедельник
    ...
    [WEEKDAY_HIT_6] => число хитов, зафиксированных в субботу

    [WEEKDAY_EVENT_0] => число событий, зафиксированных в воскресенье
    [WEEKDAY_EVENT_1] => число событий, зафиксированных в понедельник
    ...
    [WEEKDAY_EVENT_6] => число событий, зафиксированных в субботу

    [WEEKDAY_GUEST_0] => число посетителей, зафиксированных в воскресенье
    [WEEKDAY_GUEST_1] => число посетителей, зафиксированных в понедельник
    ...
    [WEEKDAY_GUEST_6] => число посетителей, зафиксированных в субботу

    [WEEKDAY_NEW_GUEST_0] => число новых посетителей, зафиксированных в воскресенье
    [WEEKDAY_NEW_GUEST_1] => число новых посетителей, зафиксированных в понедельник
    ...
    [WEEKDAY_NEW_GUEST_6] => число новых посетителей, зафиксированных в субботу

    [WEEKDAY_FAVORITE_0] => число посетителей, добавивших сайт в "Избранное", зафиксированных в воскресенье
    [WEEKDAY_FAVORITE_1] => число посетителей, добавивших сайт в "Избранное", зафиксированных в понедельник
    ...
    [WEEKDAY_FAVORITE_6] => число посетителей, добавивших сайт в "Избранное", зафиксированных в субботу
)
  • при получении данных в разрезе по месяцам (data_type=month):
    Array
(
    [MONTH_HOST_1] => число хостов, зафиксированных в январе
    ...
    [MONTH_HOST_12] => число хостов, зафиксированных в декабре

    [MONTH_SESSION_1] => число сессий, зафиксированных в январе
    ...
    [MONTH_SESSION_12] => число сессий, зафиксированных в декабре

    [MONTH_HIT_1] => число хитов, зафиксированных в январе
    ...
    [MONTH_HIT_12] => число хитов, зафиксированных в декабре

    [MONTH_EVENT_1] => число событий, зафиксированных в январе
    ...
    [MONTH_EVENT_12] => число событий, зафиксированных в декабре

    [MONTH_GUEST_1] => число посетителей, зафиксированных в январе
    ...
    [MONTH_GUEST_12] => число посетителей, зафиксированных в декабре

    [MONTH_NEW_GUEST_1] => число новых посетителей, зафиксированных в январе
    ...
    [MONTH_NEW_GUEST_12] => число новых посетителей, зафиксированных в декабре

    [MONTH_FAVORITE_1] => число посетителей, добавивших сайт в "Избранное", зафиксированных в январе
    ...
    [MONTH_FAVORITE_12] => число посетителей, добавивших сайт в "Избранное", зафиксированных в декабре
)

См. также

  • Отчет "Посещаемость"

Примеры использования

<?
// получим данные по посещаемости в разрезе по дням недели
$rs = CTraffic::GetSumList("weekday");
$ar = $rs->Fetch();
for ($i=0; $i<=6; $i++)
{
    switch($i)
    {
        case 0: echo "воскресенье"; break;
        case 1: echo "понедельник"; break;
        case 2: echo "вторник"; break;
        case 3: echo "среда"; break;
        case 4: echo "четверг"; break;
        case 5: echo "пятница"; break;
        case 6: echo "суббота"; break;
    }
    echo "<br>";
    echo "Хостов: ".$ar["WEEKDAY_HOST_".$i]."<br>";
    echo "Сессий: ".$ar["WEEKDAY_SESSION_".$i]."<br>";
    echo "Хитов: ".$ar["WEEKDAY_HIT_".$i]."<br>";
    echo "Посетителей: ".$ar["WEEKDAY_GUEST_".$i]."<br>";
    echo "Новых посетителей: ".$ar["WEEKDAY_NEW_GUEST_".$i]."<br>";
    echo "<br><br>";
}
?>


Класс CUserOnline

CUserOnline - класс для получения данных о недавних посетителях сайта и их сессиях.

Методы класса

Метод | Описание
GetGuestCount | Возвращает количество посетителей, проявивших активность на сайте (совершивших хит) за определённый интервал времени.
GetList | Возвращает список сессий посетителей, проявивших активность на сайте за определённый интервал времени.

См. также

  • Отчет "Кто на сайте"


GetGuestCount

CUserOnline::GetGuestCount

int
CUserOnline::GetGuestCount()

Возвращает количество посетителей, проявивших активность на сайте (совершивших хит) за определённый интервал времени. Данный интервал времени задается в настройках модуля "Статистика" в параметре "Интервал посетителей в online (сек.)".

Параметры функции

Нет параметров.

См. также

  • CTraffic::GetCommonValues

Примеры использования

<?
echo "Сейчас на сайте посетителей: ".CUserOnline::GetGuestCount();
?>


GetList

CUserOnline::GetList

CDBResult
CUserOnline::GetList(
 int &guest_counter,
 int &session_counter
)

Возвращает список сессий посетителей, проявивших активность (совершивших хит) на сайте за определённый интервал времени.

Параметры функции

Параметр | Описание
guest_counter | Ссылка на переменную, которая после выполнения функции будет содержать количество посетителей в online.
session_counter | Ссылка на переменную, которая после выполнения функции будет содержать количество сессий посетителей в online.

Структура возвращаемой записи

Array
(
    [ID] => ID сессии
    [HITS] => количество хитов сессии
    [LAST_USER_ID] => ID пользователя, под которым последний раз
                      был авторизован посетитель
    [USER_AUTH] => флаг "авторизован ли посетитель в данной сессии"
                   (Y - да; N - нет)
    [STOP_LIST_ID] => ID записи стоп-листа, под которую попал посетитель
                      (если это имело место быть)
    [GUEST_ID] => ID посетителя
    [NEW_GUEST] => флаг "новый посетитель" (Y - новый; N - вернувшийся)
    [FAVORITES] => флаг "добавлял ли посетитель сайт в "Избранное"
                   в данной сессии
    [COUNTRY_ID] => ID страны посетителя
    [COUNTRY_NAME] => название страны посетителя

    [ADV_ID] => ID рекламной кампании
    [ADV_BACK] => флаг прямого захода (N) или  возврата (Y)
                  по рекламной кампании
    [REFERER1] => идентификатор referer1 рекламной кампании
    [REFERER2] => идентификатор referer2 рекламной кампании
    [REFERER3] => дополнительный параметр рекламной кампании

    [FIRST_URL_FROM] => ссылающаяся страница,
                        с которой посетитель впервые пришел на сайт
    [URL_FROM] =>
    [FIRST_SITE_ID] =>
    [URL_LAST] => страница последнего хита сессии
    [URL_LAST_404] => флаг 404 ошибки
                      на последней странице сессии (Y - да; N - нет)
    [LAST_SITE_ID] => ID сайта на последнем хите сессии
    [IP_LAST] => IP адрес посетителя на последнем хите сессии
                 (в виде: XXX.XXX.XXX.XXX)
    [DATE_LAST] => время последнего хита

    [SESSION_TIME] => разница во времени между первым
                      и последним хитом сессии (сек.)
)

См. также

  • Отчет "Кто на сайте"

Примеры использования

<?
// получим список записей
$rs = CUserOnline::GetList($guest_counter, $session_counter);

echo "Количество посетителей в онлайн: ".$guest_counter;
echo "Количество сессий в онлайн: ".$session_counter;

// выведем все записи
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";
}
?>


Для разработчиков

Информация, представленная в данном разделе, содержит сведения о классах и методах классов модуля техподдержки, а также об этапах инсталляции модуля.


Инсталляция

Для инсталляции модуля вам необходимо выполнить следующее:

  1. Убедитесь, что версия ядра не менее, чем 3.0.5 (версию ядра можно узнать в левом нижнем углу административных страниц). Инсталлятор не даст вам установить модуль, если версия ядра не соответствует требуемой.
  2. Создайте группу ответственных за обращения и группу администраторов обращений.
  3. На странице управления модулями нажмите на кнопку Установить напротив модуля техподдержки.
  4. Установите необходимые значения следующих параметров модуля:
    Наименование параметра | Описание
    Каталог техподдержки | Путь к скриптам техподдержки в публичной части. Если вы задали этот параметр в момент инсталляции, то для каждого сайта будет создана указанная папка и туда будут скопированы все необходимые скрипты.
  5. Нажмите кнопку Установить.
  6. Создайте меню в публичной части сайта к скрипту ticket_list.php.
  7. Заполните справочник техподдержки.

Инсталляция подразумевает создание следующих таблиц в базе:

  • b_ticket – таблица обращений;
  • b_ticket_message – таблица сообщений (в каждом обращении может быть от одного и более сообщений);
  • b_ticket_dictionary – таблица справочника техподдержки;
  • b_ticket_online – таблица, содержащая сведения о том, кто и когда просматривал обращения.

После создания необходимых таблиц происходит загрузка справочных данных по умолчанию.

Когда таблицы подготовлены, происходит копирование всех необходимых скриптов для администрирования техподдержки из каталога \bitrix\modules\support\install\public\bitrix\admin\ в каталог \bitrix\admin\.

Если необходимо, то в каждом сайте происходит создание каталога, имя которого указанно в параметре Каталог техподдержки. После этого в каталоги копируются следующие файлы:

  • ticket_list.php – список обращений;
  • ticket_edit.php – редактирование одного обращения;
  • ticket_message_edit.php – редактирование сообщения.

Вышеописанные файлы будут скопированы из каталога \bitrix\modules\support\install\public\.


Классы модуля поддержки

CTicket

Kласс для работы с обращениями.

Методы класса

Метод | Описание
Set | Создает новое обращение, либо обновляет существующее.
GetList | Возвращает список обращений с использованием фильтра.
GetByID | Возвращает одно обращение по его ID.
GetMessageList | Возвращает сообщений в одном обращении.
GetMessageByID | Возвращает одно сообщение по его ID.

CTicketDictionary

Kласс для работы со справочником техподдержки.

Методы класса

Метод | Описание
GetList | Возвращает список записей справочника с использованием фильтра.
GetByID | Возвращает одну запись справочника по ее ID.


CTicket

CTicket - класс для работы с обращениями.

Методы класса

Метод | Описание
Set | Создает новое обращение, либо обновляет существующее.
GetList | Возвращает список обращений с использованием фильтра.
GetByID | Возвращает одно обращение по его ID.
GetMessageList | Возвращает сообщений в одном обращении.
GetMessageByID | Возвращает одно сообщение по его ID.


Delete

CTicket::Delete

record set
CTicket::Delete(
 int TICKET_ID,
 char(1) CHECK_RIGHTS="Y"

);

Функция удаляет обращение.

Параметры функции

Параметр | Описание
TICKET_ID | ID обращения.
CHECK_RIGHTS | "Y" - необходимо проверить право на удаление у текущего пользователя; "N" - прав проверять не надо.


DeleteMessage

CTicket::DeleteMessage

record set
CTicket::DeleteMessage(
 int MESSAGE_ID,
 char(1) CHECK_RIGHTS="Y"
);

Функция удаляет сообщение.

Параметры функции

Параметр | Описание
MESSAGE_ID | ID сообщения.
CHECK_RIGHTS | "Y" - необходимо проверить право на удаление у текущего пользователя; "N" - прав проверять не надо.


GetByID

CTicket::GetByID

record set
CTicket::GetByID(
 int ID,
 char(2) lang=LANG,
 char(1) CHECK_RIGHTS="Y",
 char(1) get_user_name="Y",
 char(1) get_dictionary_name="Y"
);

Функция возвращает данные по одному обращению.

Параметры функции

Параметр | Описание
ID | ID обращения.
lang | Двухсимвольный код языка в формате которого необходимо выбрать временные параметры обращения (время создания, изменения, закрытия); по умолчанию - код текущего сайта.
CHECK_RIGHTS | "Y" - будут выбраны только те обращения которые текущий пользователь может просматривать (по умолчанию); "N" - выбирать все обращения независимо от прав текущего пользователя.
get_user_name | "Y" - при выборке обращений будут также выбраны такие поля как OWNER_LOGIN, OWNER_NAME, RESPONSIBLE_LOGIN, RESPONSIBLE_NAME, MODIFIED_LOGIN, MODIFIED_NAME, LAST_MESSAGE_LOGIN, LAST_MESSAGE_NAME, CREATED_LOGIN, CREATED_EMAIL, CREATED_NAME, описывающие параметры пользователей имевших отношение к данному обращению; "N" - вышеперечисленные поля не будут выбраны, но зато это ускорит работу функции.
get_dictionary_name | "Y" - при выборке обращений будут также выбраны такие поля как CATEGORY_NAME, CATEGORY_SID, CRITICALITY_NAME, CRITICALITY_SID, STATUS_NAME, STATUS_SID, MARK_NAME, MARK_SID, SOURCE_NAME, SOURCE_SID, описывающие поля из справочника техподдержки; "N" - вышеперечисленные поля не будут выбраны, но зато это ускорит работу функции.

Пример массива одной строки выборки возвращаемой функцией CTicket::GetByID

Array
(
    [ID] => 647
    [LID] => ru
    [DATE_CREATE] => 17.03.2004 15:27:05
    [TIMESTAMP_X] => 19.04.2004 13:37:30
    [DATE_CLOSE] =>
    [AUTO_CLOSED] =>
    [AUTO_CLOSE_DAYS] =>
    [CATEGORY_ID] => 27
    [CRITICALITY_ID] => 8
    [STATUS_ID] => 14
    [MARK_ID] => 21
    [SOURCE_ID] =>
    [TITLE] => Импорт-экспорт в торговый каталог
    [MESSAGES] => 30
    [OWNER_USER_ID] => 166
    [OWNER_GUEST_ID] => 14649
    [OWNER_SID] =>
    [CREATED_USER_ID] => 166
    [CREATED_GUEST_ID] => 14649
    [CREATED_MODULE_NAME] => support
    [RESPONSIBLE_USER_ID] => 12
    [MODIFIED_USER_ID] => 166
    [MODIFIED_GUEST_ID] => 16218
    [MODIFIED_MODULE_NAME] => support
    [LAST_MESSAGE_USER_ID] => 166
    [LAST_MESSAGE_GUEST_ID] => 16218
    [LAST_MESSAGE_SID] =>
    [SUPPORT_COMMENTS] =>
    [OWNER_LOGIN] => ant
    [OWNER_EMAIL] => mail@server.com
    [OWNER_NAME] => Поручик Лукаш
    [RESPONSIBLE_LOGIN] => wizard
    [RESPONSIBLE_EMAIL] => mail@server.com
    [RESPONSIBLE_NAME] => Фельдкурат Кац
    [MODIFIED_LOGIN] => ant
    [MODIFIED_EMAIL] => mail@server.com
    [MODIFIED_NAME] => Поручик Лукаш
    [LAST_MESSAGE_LOGIN] => ant
    [LAST_MESSAGE_EMAIL] => mail@server.com
    [LAST_MESSAGE_NAME] => Поручик Лукаш
    [CREATED_LOGIN] => ant
    [CREATED_EMAIL] => mail@server.com
    [CREATED_NAME] => Поручик Лукаш
    [CATEGORY_NAME] => Установка и настройка
    [CATEGORY_DESC] =>
    [CATEGORY_SID] =>
    [CRITICALITY_NAME] => Средняя
    [CRITICALITY_DESC] =>
    [CRITICALITY_SID] => middle
    [STATUS_NAME] => В стадии решения
    [STATUS_DESC] =>
    [STATUS_SID] =>
    [MARK_NAME] => Ответ устраивает
    [MARK_DESC] =>
    [MARK_SID] =>
    [SOURCE_NAME] =>
    [SOURCE_DESC] =>
    [SOURCE_SID] =>
    [LAMP] => yellow
)


GetList

CTicket::GetList

record set
CTicket::GetList(
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered,
 char(1) CHECK_RIGHTS="Y",
 char(1) get_user_name="Y",
 char(1) get_dictionary_name="Y",
 char(2) lang=LANG

);

Функция предназначена для получения списка обращений в техподдержку.

Параметры функции

Параметр | Описание
by Идентификатор позволяющий задать имя поля для сортировки. Допустимы следующие значения:
  • s_id - по ID
  • s_lid - по сайту, для которого было создано обращение
  • s_lamp - по индикатору
  • s_date_create - по дате создания
  • s_timestamp - по дате изменения
  • s_date_close - по дате закрытия
  • s_owner - по автору
  • s_modified_by - по ID пользователя - изменившего обращение
  • s_title - по заголовку
  • s_responsible - по ID ответственного
  • s_messages - по количеству сообщений
  • s_category - по ID категории
  • s_criticality - по ID критичности
  • s_status - по ID статуса
  • s_mark - по ID оценки
  • s_online - по количеству пользователей
order Порядок сортировки. Допустимы следующие значения:
  • desc - по убыванию (значение по умолчанию)
  • asc - по возрастанию
arFilter Массив для фильтрации значений. В массиве допустимы следующие индексы:
  • ID - ID обращения (допускается сложная логика)
  • ID_EXACT_MATCH - "Y" - при фильтрации по ID обращения будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • LID - ID сайта
  • LID_EXACT_MATCH - "Y" - при фильтрации по ID языка будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • LAMP - массив индикаторов: "red", "yellow", "green", "green_s", "grey"
  • DATE_CREATE_1 - левая часть интервала для даты создания обращения
  • DATE_CREATE_2 - правая часть интервала для даты создания обращения
  • DATE_TIMESTAMP_1 - левая часть интервала для даты модификации обращения
  • DATE_TIMESTAMP_2 - правая часть интервала для даты модификации обращения
  • DATE_CLOSE_1 - левая часть интервала для даты закрытия обращения
  • DATE_CLOSE_2 - правая часть интервала для даты закрытия обращения
  • AUTO_CLOSE_DAYS1 - левая часть интервала для количества дней по истечении которых обращение будет автоматически закрыто при отсутствии ответа от автора
  • AUTO_CLOSE_DAYS2 - правая часть интервала для количества дней по истечении которых обращение будет автоматически закрыто при отсутствии ответа от автора
  • TICKET_TIME_1 - левая часть интервала для количества дней прошедших с даты создания до даты закрытия обращения
  • TICKET_TIME_1 - правая часть интервала для количества дней прошедших с даты создания до даты закрытия обращения
  • TITLE - заголовок обращения (допускается сложная логика)
  • TITLE_EXACT_MATCH - "Y" - при фильтрации по заголовку обращения будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • MESSAGES1 - левая часть интервала для количества сообщений в обращении
  • MESSAGES1 - правая часть интервала для количества сообщений в обращении
  • OWNER - автор обращения, поиск осуществляется по ID пользователя, логину, имени, фамилии, символному коду (допускается сложная логика)
  • OWNER_EXACT_MATCH - "Y" - при фильтрации по автору обращения будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • CREATED_BY - кем было создано обращение, поиск осуществляется по ID пользователя, логину, имени, фамилии, названии модуля из которого было создано обращение (допускается сложная логика)
  • CREATED_BY_EXACT_MATCH - "Y" - при фильтрации по создателю обращения будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • MODIFIED_BY - изменивший обращение, поиск осуществляется по ID пользователя, логину, имени, фамилии, названии модуля из которого было изменено обращение (допускается сложная логика)
  • MODIFIED_BY_EXACT_MATCH - "Y" - при фильтрации по символьному коду статуса будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • RESPONSIBLE - ответственный за обращение, поиск осуществляется по ID пользователя, логину, имени, фамилии (допускается сложная логика)
  • RESPONSIBLE_EXACT_MATCH - "Y" - при фильтрации по ответственному за обращение будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • RESPONSIBLE_ID - ID пользователя ответственного за обращение, при задании "0" будут выбраны только те обращения у которых нет ответственного
  • CATEGORY - ID категории обращения (0 - без категории)
  • CATEGORY_SID - символьный код категории обращения (допускается сложная логика)
  • CATEGORY_SID_EXACT_MATCH - "Y" - при фильтрации по символьному коду категории будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • CRITICALITY - ID критичности обращения (0 - без критичности)
  • CRITICALITY_SID - символьный код критичности обращения (допускается сложная логика)
  • CRITICALITY_SID_EXACT_MATCH - "Y" - при фильтрации по символьному коду критичности будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • STATUS - ID статуса обращения (0 - без статуса)
  • STATUS_SID - символьный код статуса обращения (допускается сложная логика)
  • STATUS_SID_EXACT_MATCH - "Y" - при фильтрации по символьному коду статуса будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • STATUS_SID_EXACT_MATCH - "Y" - при фильтрации по символьному коду оценки ответа будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • MARK - ID оценки ответов (0 - без оценки)
  • MARK_SID - символьный код оценки ответов (допускается сложная логика)
  • SOURCE - ID источника (0 - источник "web")
  • SOURCE_SID - символьный код источника (допускается сложная логика)
  • SOURCE_SID_EXACT_MATCH - "Y" - при фильтрации по символьному коду источника будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • MESSAGE - текст сообщения (допускается сложная логика)
  • MESSAGE_EXACT_MATCH - "Y" - при фильтрации по сообщению будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • LAST_MESSAGE_USER_ID - ID пользователя написавшего последнее сообщение в обращении (допускается сложная логика)
  • LAST_MESSAGE_USER_ID_EXACT_MATCH - "Y" - при фильтрации по ID пользователя написавшего последнее сообщение в обращении будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • LAST_MESSAGE_SID - символьный идентификатор написавшего последнее сообщение в обращении (если источник "email", то это может быть email, если источник "телефон", то это может быть номер телефона) (допускается сложная логика)
  • LAST_MESSAGE_SID_EXACT_MATCH - "Y" - при фильтрации по символьному идентификатору пользователя написавшего последнее сообщение в обращении будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
  • SUPPORT_COMMENTS - комментарий техподдержки, видимый в стандартных формах только для пользователей входящих в группу техподдержки
  • SUPPORT_COMMENTS_EXACT_MATCH - "Y" - при фильтрации по ID пользователя написавшего последнее сообщение в обращении будет искаться точное совпадение (по умолчанию); "N" - в противном случае будет искаться вхождение
is_filtered | Переменная возвращающая true в том случае если список результатов отфильтрован по какому либо критерию; либо false в противном случае.
CHECK_RIGHTS | "Y" - будут выбраны только те обращения которые текущий пользователь может просматривать (по умолчанию); "N" - выбирать все обращения независимо от прав текущего пользователя.
get_user_name | "Y" - при выборке обращений будут также выбраны такие поля как OWNER_LOGIN, OWNER_NAME, RESPONSIBLE_LOGIN, RESPONSIBLE_NAME, MODIFIED_LOGIN, MODIFIED_NAME, LAST_MESSAGE_LOGIN, LAST_MESSAGE_NAME, CREATED_LOGIN, CREATED_EMAIL, CREATED_NAME, описывающие параметры пользователей имевших отношение к данному обращению; "N" - вышеперечисленные поля не будут выбраны, но зато это ускорит работу функции.
get_dictionary_name | "Y" - при выборке обращений будут также выбраны такие поля как CATEGORY_NAME, CATEGORY_SID, CRITICALITY_NAME, CRITICALITY_SID, STATUS_NAME, STATUS_SID, MARK_NAME, MARK_SID, SOURCE_NAME, SOURCE_SID, описывающие поля из справочника техподдержки; "N" - вышеперечисленные поля не будут выбраны, но зато это ускорит работу функции.
lang | Двухсимвольный код языка в формате которого необходимо выбрать временные параметры обращения (время создания, изменения, закрытия); по умолчанию - код текущего сайта.

Примеры использования

<?
$FilterArr = Array(
    "find_id",
    "find_lid",
    "find_lamp",
    "find_date_create1",
    "find_date_create2",
    "find_date_timestamp1",
    "find_date_timestamp2",
    "find_date_close1",
    "find_date_close2",
    "find_close",
    "find_ticket_time_1",
    "find_ticket_time_2",
    "find_title",
    "find_messages1",
    "find_messages2",
    "find_owner",
    "find_created_by",
    "find_responsible",
    "find_responsible_id",
    "find_category_id",
    "find_criticality_id",
    "find_status_id",
    "find_mark_id",
    "find_source_id",
    "find_modified_by",
    "find_message"
    );
if (strlen($set_filter)>0) InitFilterEx($FilterArr,"TICKET_LIST","set",true); else InitFilterEx($FilterArr,"TICKET_LIST","get",true);
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"TICKET_LIST",true);
if (CheckFilter())
{
    $arFilter = Array(
        "ID"                => $find_id,
        "LID"               => $find_lid,
        "LAMP"              => $find_lamp,
        "DATE_CREATE_1"     => $find_date_create1,
        "DATE_CREATE_2"     => $find_date_create2,
        "DATE_TIMESTAMP_1"  => $find_date_timestamp1,
        "DATE_TIMESTAMP_2"  => $find_date_timestamp2,
        "DATE_CLOSE_1"      => $find_date_close1,
        "DATE_CLOSE_2"      => $find_date_close2,
        "CLOSE"             => $find_close,
        "TICKET_TIME_1"     => $find_ticket_time_1,
        "TICKET_TIME_2"     => $find_ticket_time_2,
        "TITLE"             => $find_title,
        "MESSAGES1"         => $find_messages1,
        "MESSAGES2"         => $find_messages2,
        "OWNER"             => $find_owner,
        "CREATED_BY"        => $find_created_by,
        "RESPONSIBLE"       => $find_responsible,
        "RESPONSIBLE_ID"    => $find_responsible_id,
        "CATEGORY"          => $find_category_id,
        "CRITICALITY"       => $find_criticality_id,
        "STATUS"            => $find_status_id,
        "MARK"              => $find_mark_id,
        "SOURCE"            => $find_source_id,
        "MODIFIED_BY"       => $find_modified_by,
        "MESSAGE"           => $find_message
        );
}
$tickets = CTicket::GetList($by, $order, $arFilter, $is_filtered);
?>


GetMessageByID

CTicket::GetMessageByID

record set
CTicket::GetMessageByID(
 int ID,
 char(1) CHECK_RIGHTS="Y",
 char(1) get_user_name="Y"

);

Функция возвращает данные по одному сообщению.

Параметры функции

Параметр | Описание
ID | ID сообщения.
CHECK_RIGHTS | "Y" - сообщение будет выбрано только в том случае если у пользователя есть права на это сообщение; "N" - сообщение будет выбрано независимо от прав текущего пользователя.
get_user_name | "Y" - при выборке сообщения будут также выбраны такие поля как OWNER_EMAIL, OWNER_LOGIN, OWNER_NAME, CREATED_EMAIL, CREATED_LOGIN, CREATED_NAME, MODIFIED_EMAIL, MODIFIED_LOGIN, MODIFIED_NAME, описывающие параметры пользователей имевших отношение к данному сообщению; "N" - вышеперечисленные поля не будут выбраны, но зато это ускорит работу функции.

Пример массива одной строки выборки возвращаемой функцией CTicket::GetMessageByID

Array
(
    [ID] => 3585
    [TIMESTAMP_X] => 27.04.2004 12:46:02
    [DATE_CREATE] => 13.04.2004 11:57:04
    [C_NUMBER] => 22
    [TICKET_ID] => 647
    [MESSAGE] => Хорошо, тогда как насчет такой мысли: если группа указана в загружаемом файле, то она активируется (данное поведение можно регулировать при создании схемы загрузки).
Цитирую себя же. Вспомнил вот что: деактивировать рубрику при загрузке возможность есть (соответствующая галочка при создании схемы), а активировать- нет.
Разное получается поведение. А хотелось бы одинакового
    [MESSAGE_SEARCH] => ХОРОШО, ТОГДА КАК НАСЧЕТ ТАКОЙ МЫСЛИ: ЕСЛИ ГРУППА УКАЗАНА В ЗАГРУЖАЕМОМ ФАЙЛЕ, ТО ОНА АКТИВИРУЕТСЯ (ДАННОЕ ПОВЕДЕНИЕ МОЖНО РЕГУЛИРОВАТЬ ПРИ СОЗДАНИИ СХЕМЫ ЗАГРУЗКИ).
ЦИТИРУЮ СЕБЯ ЖЕ. ВСПОМНИЛ ВОТ ЧТО: ДЕАКТИВИРОВАТЬ РУБРИКУ ПРИ ЗАГРУЗКЕ ВОЗМОЖНОСТЬ ЕСТЬ (СООТВЕТСВУЮЩАЯ ГАЛОЧКА ПРИ СОЗДАНИИ СХЕМЫ), А АКТИВИРОВАТЬ- НЕТ.
РАЗНОЕ ПОЛУЧАЕТСЯ ПОВЕДЕНИЕ. А ХОТЕЛОСЬ БЫ ОДИНАКОВОГО
    [IMAGE] => 996
    [OWNER_USER_ID] => 166
    [OWNER_GUEST_ID] => 16218
    [OWNER_SID] =>
    [SOURCE_ID] => 0
    [CREATED_USER_ID] => 166
    [CREATED_GUEST_ID] => 16218
    [CREATED_MODULE_NAME] => support
    [MODIFIED_USER_ID] => 2
    [MODIFIED_GUEST_ID] => 6221
    [OWNER_EMAIL] => mail@server.com
    [OWNER_LOGIN] => ant
    [OWNER_NAME] => Поручик Лукаш
    [CREATED_EMAIL] => mail@server.com
    [CREATED_LOGIN] => ant
    [CREATED_NAME] => Поручик Лукаш
    [MODIFIED_EMAIL] => mail@server.com
    [MODIFIED_LOGIN] => nessy
    [MODIFIED_NAME] => Vitaly Kaplich
)


GetMessageList

CTicket::GetMessageList

record set
CTicket::GetMessageList(
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered,
 char(1) CHECK_RIGHTS="Y",
 char(1) get_user_name="Y"

);

Функция предназначена для получения списка сообщений в одном обращении.

Параметры функции

Параметр | Описание
by Идентификатор позволяющий задать имя поля для сортировки. Допустимы следующие значения:
  • s_id - по ID
  • s_number - по порядковому номеру
order Порядок сортировки. Допустимы следующие значения:
  • desc - по убыванию (значение по умолчанию)
  • asc - по возрастанию
arFilter Массив для фильтрации значений. В массиве допустимы следующие индексы:
  • ID - ID сообщения (допускается сложная логика)
  • ID_EXACT_MATCH - "Y" - при фильтрации по ID сообщения будет искаться точное совпадение (по умолчанию); "N" - при фильтрации по ID сообщения будет искаться вхождение
  • TICKET_ID - ID обращения (допускается сложная логика)
  • TICKET_ID_EXACT_MATCH - "Y" - при фильтрации по ID обращения будет искаться точное совпадение (по умолчанию); "N" - при фильтрации по ID обращения будет искаться вхождение
  • IS_HIDDEN - "Y" - будут выбраны только скрытые обращения; "N" - будут выбраны все не скрытые сообщения;
  • IS_LOG - "Y" - будут выбраны только лог-записи (записи изменений); "N" - будут выбраны не лог-записи;
is_filtered | Переменная возвращающая true в том случае если список результатов отфильтрован по какому либо критерию; либо false в противном случае.
CHECK_RIGHTS Флаг необходимости проверки прав текущего пользователя:
  • Y - будут выбраны только те сообщения которые данные пользователь может просматривать (по умолчанию)
  • N - выбирать все сообщения независимо от прав текущего пользователя
get_user_name | "Y" - при выборке сообщения будут также выбраны такие поля как OWNER_EMAIL, OWNER_LOGIN, OWNER_NAME, CREATED_EMAIL, CREATED_LOGIN, CREATED_NAME, MODIFIED_EMAIL, MODIFIED_LOGIN, MODIFIED_NAME, описывающие параметры пользователей имевших отношение к данному сообщению; "N" - вышеперечисленные поля не будут выбраны, но зато это ускорит работу функции.

Примеры использования

<?
$mess = CTicket::GetMessageList($a, $b, array("TICKET_ID" => $ID, "TICKET_ID_EXACT_MATCH" => "Y"), $c, $CHECK_RIGHTS);
$mess->NavStart(50);
$messages = $mess->SelectedRowsCount();
?>


Set

CTicket::Set

int
CTicket::Set(
 array arFields,
 int &MESSAGE_ID,
 int TICKET_ID="",
 char(1) CHECK_RIGHTS="Y"

);

Функция создает новое обращение, либо модифицирует существующее в случае указания во втором параметре ID обращения. Возвращает ID созданного обращения, либо ID модифицированного обращения.

Параметры функции

Параметр | Описание
arFields Массив параметров обращения. В массиве допустимы следующие индексы:
  • *TITLE - заголовок обращения (обязательное поле при создании нового обращения)
  • MESSAGE - тело сообщения (обязательное поле при создании нового обращения)
  • IMAGE - массив описывающий загружаемое изображение; в массиве допустимые следующие индексы:
    • name - исходное имя загружаемого файла
    • type - тип загружаемого файла (например: "image/gif")
    • tmp_name - имя временного файла на сервере
    • error - код ошибки ("0" - нет ошибок)
    • size - размер загружаемого файла
    • MODULE_ID - идентификатор модуля ("support")
  • *OWNER_SID - символьный код автора обращения; можно указать любое значение идентифицирующее автора обращения - email, телефон, адрес и т.п.
  • *OWNER_USER_ID - ID автора обращения (по умолчанию - ID текущего пользователя)
  • *SOURCE_SID - символьный код источника обращения (по умолчанию - "web")
  • *CREATED_MODULE_NAME - идентификатор модуля из которого создаётся обращение (по умолчанию - "support")
  • **MESSAGE_AUTHOR_SID - символьный код автора сообщения (можно указать любое значение идентифицирующее автора сообщения - email, телефон, адрес и т.п.)
  • **MESSAGE_AUTHOR_USER_ID - ID пользователя - автора сообщения (по умолчанию - ID текущего пользователя)
  • **MESSAGE_SOURCE_SID - символьный код источника сообщения (по умолчанию - "web")
  • **MODIFIED_MODULE_NAME - идентификатор модуля из которого обращение модифицируется (по умолчанию - "support")
  • **HIDDEN - "Y" - сообщение будет добавлено как скрытое и будет видимо только сотрудникам техподдержки; "N" - сообщение будет добавлено видимым как для автора обращения так и для сотрудников техподдержки (по умолчанию)
  • CATEGORY_SID - символьный код категории
  • CRITICALITY_SID - символьный код критичности
  • STATUS_SID - символьный код статуса
  • MARK_SID - символьный код оценки ответов
  • RESPONSIBLE_USER_ID - ID пользователя ответственного за обращение
  • SUPPORT_COMMENTS - комментарий видимый только пользователям входящим в группу техподдержки
  • CLOSE - "Y" - обращение закрыть; "N" - обращение открыть
  • AUTO_CLOSE_DAYS - количество дней по истечении которых автоматически закрыть обращение если за это время от автора не поступило сообщения
* - данное поле может быть использовано для создания новых обращений
** - данное поле используется только при модификации существующих обращений.
MESSAGE_ID | ID добавленного сообщения.
TICKET_ID | ID модифицируемого обращения.
CHECK_RIGHTS | Флаг необходимости проверки прав текущего пользователя: "Y" - необходимо проверить права текущего пользователя под которым создаётся обращение либо модифицируется; "N" - обращения создавать и модифицировать независимо от прав текущего пользователя.

Примеры использования

Пример кода добавляющего новое обращение в техподдержку приходящего по EMail,
либо добавляющего новое сообщение в обращение если задан $TICKET_ID:
<?
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
CModule::IncludeModule("support");
$arFields = array(
    "CREATED_MODULE_NAME"       => "mail",
    "MODIFIED_MODULE_NAME"      => "mail",
    "OWNER_SID"                 => "user@mail.ru",
    "SOURCE_SID"                => "email",
    "MESSAGE_AUTHOR_SID"        => "user@mail.ru",
    "MESSAGE_SOURCE_SID"        => "email",
    "TITLE"                     => "title",
    "MESSAGE"                   => "message"
    );
//$TICKET_ID = 866;
$NEW_TICKET_ID = CTicket::Set($arFields, $MESSAGE_ID, $TICKET_ID, "N");
echo "MESSAGE_ID = ".$MESSAGE_ID;
?>


CTicketDictionary

CTicketDictionary - класс для работы со справочником обращений.

Методы класса

Метод | Описание
GetList | Возвращает список записей справочника с использованием фильтра.
GetByID | Возвращает одну запись справочника по ее ID.


GetByID

CTicketDictionary::GetByID

record set
CTicketDictionary::GetByID(
 int ID

);

Функция возвращает данные по одной записи справочника.

Параметры функции

Параметр | Описание
ID | ID записи.

Пример массива одной строки выборки возвращаемой функцией CTicketDictionary::GetByID

Array
(
    [ID] => 3
    [LID] => ru
    [C_TYPE] => C
    [SID] =>
    [SET_AS_DEFAULT] => N
    [C_SORT] => 500
    [NAME] => Доставка программного продукта и обновлений
    [DESCR] =>
    [RESPONSIBLE_USER_ID] => 2
    [ EVENT1] => ticket
    [ EVENT2] =>
    [ EVENT3] =>
)


GetList

CTicketDictionary::GetList

record set
CTicketDictionary::GetList(
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered

);

Функция предназначена для получения списка обращений в техподдержку.

Параметры функции

Параметр | Описание
by Идентификатор позволяющий задать имя поля для сортировки. Допустимы следующие значения:
  • s_id - по ID
  • s_c_sort - по указанному порядку сортировки
  • s_sid - по символьному коду
  • s_lis - по языку
  • s_name - по имени
  • s_responsible - по ID ответственного
  • s_dropdown - по указанному порядку сортировки и по имени
order Порядок сортировки. Допустимы следующие значения:
  • desc - по убыванию (значение по умолчанию)
  • asc - по возрастанию
arFilter Массив для фильтрации значений. В массиве допустимы следующие индексы:
  • ID - ID записи (допускается сложная логика)
  • SID - символьный код (допускается сложная логика)
  • LID - ID сайта
  • TYPE - тип записи: "C" - категория, "K" - критичность, "S" - статус, "M" - оценка ответов, "F" - часто используемые ответы, "SR" - источник
  • NAME - имя (допускается сложная логика)
  • RESPONSIBLE_ID - ID ответственного
  • RESPONSIBLE - ответственный, поиск осуществляется по ID пользователя, логину, имени, фамилии (допускается сложная логика)
  • DEFAULT - флаг "Выбирать по умолчанию"; "Y" - да, "N" - нет
is_filtered | Переменная возвращающая true в том случае если список результатов отфильтрован по какому либо критерию; либо false в противном случае.

Примеры использования

<?
$FilterArr = Array(
    "find_id",
    "find_lid",
    "find_type",
    "find_name",
    "find_sid",
    "find_responsible",
    "find_responsible_id",
    "find_default"
    );
if (strlen($set_filter)>0) InitFilterEx($FilterArr,"TICKET_DICTIONARY_LIST","set"); else InitFilterEx($FilterArr,"TICKET_DICTIONARY_LIST","get");
if (strlen($del_filter)>0) DelFilterEx($FilterArr,"TICKET_DICTIONARY_LIST");
$arFilter = Array(
    "ID"				=> $find_id,
    "LID"				=> $find_lid,
    "TYPE"				=> $find_type,
    "NAME"				=> $find_name,
    "SID"				=> $find_sid,
    "RESPONSIBLE_ID"	=> $find_responsible_id,
    "RESPONSIBLE"		=> $find_responsible,
    "DEFAULT"			=> $find_default
    );
$tdic = CTicketDictionary::GetList($by, $order, $arFilter, $is_filtered);
?>


Информация для разработчиков

Перед использованием модуля необходимо проверить установлен ли он и подключить его при помощи конструкции:

<?
if (CModule::IncludeModule("catalog"))
{
   //здесь можно использовать функции модуля
}
?>

Перед использованием какого-либо информационного блока в качестве торгового каталога необходимо проверить является ли этот информационный блок каталогом (т.е. подключен ли он к модулю торгового каталога) при помощи конструкции:

<?
if (CCatalog::GetByID($IBLOCK_ID))
{
   //здесь можно работать с информационым блоком
   //как с торговым каталогом
}
?>

Обе эти конструкции можно объеденить в одну, которая проверяет, установлен ли модуль торгового каталога (и подключает его), и можно ли использовать текущий информационный блок с кодом $IBLOCK_ID в качестве торгового каталога:

<?
if (CModule::IncludeModule("catalog")
   && CCatalog::GetByID($IBLOCK_ID))
{
   //здесь можно работать с информационым блоком
   //как с торговым каталогом
}
?>

См. также

Показ цен - показ цен торгового каталога.
Занесение в корзину - занесение товаров торгового каталога в корзину модуля продаж.


Добавление в корзину

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

Add2Basket

int
Add2Basket(
 int PRICE_ID[,
 int QUANTITY = 1[,
 array arRewriteFields = array()[,
 array arProductParams = array()]]]
);

Функция добавляет в корзину товар с кодом цены PRICE_ID в количестве QUANTITY единиц (по умолчанию одну штуку) и возвращает код позиции товара в корзине.

Параметры функции

Параметр | Описание
PRICE_ID | Код цены товара.
QUANTITY | Количество добавляемых единиц товара (по умолчанию - одна штука)
arRewriteFields | Вспомогательный параметр. Должен быть равен array()
arProductParams Свойства товара в корзине. Представляет собой массив ассоциативных массивов с ключами:
  • NAME - название свойства
  • CODE - мнемонический код свойства
  • VALUE - значение свойства

Возвращаемое значение

Код вставленной в корзину записи или False в случае ошибки.

Пример использования

<?
if (CModule::IncludeModule("sale") && CModule::IncludeModule("catalog"))
{
    if (($action == "ADD2BASKET" || $action == "BUY") && IntVal($PRICE_ID)>0)
    {
        Add2Basket(
                $PRICE_ID,
                2,
                array(),
                array(
                        array("NAME" => "Цвет", "CODE" => "CLR", "VALUE" => "красный"),
                        array("NAME" => "Размер", "VALUE" => "25")
                    )
            );
        if ($action == "BUY")
            LocalRedirect("basket.php");
    }
}
?>

Функции обратного вызова

array
CatalogBasketCallback(
 int PRODUCT_ID [,
 int QUANTITY] )

);
void
CatalogBasketOrderCallback(
 int PRODUCT_ID,
 int QUANTITY
);

Функции обратного вызова для обработки корзины и заказа. Подробнее о функциях обратного вызова смотрите в разделе помощи модуля продаж.

Add2BasketByProductID

int
Add2BasketByProductID(
 int PRODUCT_ID[,
 int QUANTITY = 1[,
 array arProductParams = array()]]
);

Функция добавляет в корзину товар с кодом PRODUCT_ID в количестве QUANTITY единиц (по умолчанию одну штуку) и возвращает код позиции товара в корзине.

Параметры функции

Параметр | Описание
PRODUCT_ID | Код товара.
QUANTITY | Количество добавляемых единиц товара (по умолчанию - одна штука)
arProductParams Свойства товара в корзине. Представляет собой массив ассоциативных массивов с ключами:
  • NAME - название свойства
  • CODE - мнемонический код свойства
  • VALUE - значение свойства

Возвращаемое значение

Код вставленной в корзину записи или False в случае ошибки.

Пример использования

<?
if (CModule::IncludeModule("sale") && CModule::IncludeModule("catalog"))
{
    if (($action == "ADD2BASKET" || $action == "BUY") && IntVal($PRODUCT_ID)>0)
    {
        Add2BasketByProductID(
                $PRODUCT_ID,
                2,
                array(
                        array("NAME" => "Цвет", "CODE" => "CLR", "VALUE" => "красный"),
                        array("NAME" => "Размер", "VALUE" => "25")
                    )
            );
        if ($action == "BUY")
            LocalRedirect("basket.php");
    }
}
?>


Показ цен

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

Функция | Описание
CDBResult GetCatalogGroups(string by, string order) | Возвращает список типов цен, отсортированный по полю by в порядке order.
array GetCatalogGroup(int CATALOG_GROUP_ID) | Возвращает тип цены кодом CATALOG_GROUP_ID.
array GetCatalogProductPrice(int PRODUCT_ID, int CATALOG_GROUP_ID) | Возвращает цену типа CATALOG_GROUP_ID для товара с кодом PRODUCT_ID.
array GetCatalogProductPriceList(int PRODUCT_ID, string by, string order) | Возвращает массив цен для товара PRODUCT_ID, отсортированный по полю by в порядке order.
array GetCatalogProduct(int PRODUCT_ID) | Возвращает товар с кодом PRODUCT_ID.
string FormatCurrency(double PRICE, string CURRENCY) | Форматирует число (цену) PRICE в соответствии с форматом, заданным для валюты CURRENCY.

GetCatalogGroups

CDBResult
GetCatalogGroups(
 string by,
 string order
);

Функция возвращает список типов цен, отсортированный по полю by в порядке order.

Параметры функции

Параметр | Описание
by | Поле для сортировки, может принимать одно из следующих значений SORT - по полю "Сортировка" (по умолчанию); NAME - по полю "Название"; ID - по полю "Код"
order | Поле для направления сортировки, может принимать одно из следующих значений ASC - в порядке увеличения величины (по умолчанию); DESC - в порядке уменьшения величины.

Возвращаемые значения

Упорядоченный набор записей типа CDBResult, каждая из которых имеет следующую структуру:

Параметр | Описание
ID | Код типа цен.
NAME | Внутреннее название типа цен.
BASE | Y - для базового типа цен, N - для всех остальных.
SORT | Поле "Сортировка" типа цен.
NAME_LANG | Название типа цен для текущего сайта.
CAN_ACCESS | Y - текущий пользователь может просматривать цены этого типа, N - цены этого типа должны быть скрыты от текущего пользователя.
CAN_BUY | Y - текущий пользователь может покупать товары по ценам этого типа, N - текущий пользователь не может покупать товары по ценам этого типа.

GetCatalogGroup

array
GetCatalogGroup(
 int CATALOG_GROUP_ID
);

Функция возвращает тип цены кодом CATALOG_GROUP_ID.

Параметры функции

Параметр | Описание
CATALOG_GROUP_ID | Код типа цены.

Возвращаемые значения

Массив той же структуры,
что и каждая запись набора, возвращаемого функцией CDBResult GetCatalogGroups(string by,
string order)

GetCatalogProductPrice

array
GetCatalogProductPrice(
 int PRODUCT_ID,
 int CATALOG_GROUP_ID
);

Функция возвращает цену типа CATALOG_GROUP_ID для товара с кодом PRODUCT_ID.

Параметры функции

Параметр | Описание
PRODUCT_ID | Код продукта.
CATALOG_GROUP_ID | Тип цены.

Возвращаемые значения

Массив следующей структуры:

Параметр | Описание
ID | Код цены.
PRODUCT_ID | Код продукта.
EXTRA_ID | Код наценки.
CATALOG_GROUP_ID | Код типа цены.
PRICE | Цена.
CURRENCY | Валюта.
CATALOG_GROUP_NAME | Название типа цены для текущего сайта.
CAN_ACCESS | Y - текущий пользователь может просматривать эту цену, N - эта цена должна быть скрыта от текущего пользователя.
CAN_BUY | Y - текущий пользователь может купить товар по этой цене, N - текущий пользователь не может купить товар по этой цене.

GetCatalogProductPriceList

array
GetCatalogProductPriceList(
 int PRODUCT_ID,
 string by,
 string order
);

Функция возвращает массив цен для товара PRODUCT_ID, отсортированый по полю by в порядке order.

Параметры функции

Параметр | Описание
PRODUCT_ID | Код товара.
by Поле для сортировки, может принимать одно из следующих значений
ID - по полю "Код" (по умолчанию);
SORT - по полю "Сортировка" типа цены;
CURRENCY - по полю "Валюта";
PRICE - по полю "Цена";
CATALOG_GROUP_ID - по полю "Код типа цены"
order Поле для направления сортировки, может принимать одно из следующих значений
ASC - в порядке увеличения величины (по умолчанию);
DESC - в порядке уменьшения величины.

Возвращаемые значения

Массив, каждый элемент которого является массивом той же структуры, что и массив, возвращаемый функцией array GetCatalogProductPrice(int PRODUCT_ID,
int CATALOG_GROUP_ID)

GetCatalogProduct

array
GetCatalogProduct(
 int PRODUCT_ID
);

Функция возвращает товар с кодом PRODUCT_ID.

Параметры функции

Параметр | Описание
PRODUCT_ID | Код товара.

Возвращаемые значения

Массив следующей структуры:

Параметр | Описание
ID | Код товара.
QUANTITY | Количество товара.
QUANTITY_TRACE | Y - отслеживать количество товара, N - не отслеживать.
WEIGHT | Вес товара.

FormatCurrency

string
FormatCurrency(
 double PRICE,
 string CURRENCY
);

Функция форматирует число (цену) PRICE в соответствии с форматом, заданным для валюты CURRENCY.

Параметры функции

Параметр | Описание
PRICE | Число, цена.
CURRENCY | Валюта.

Возвращаемое значение

Строка с числом (ценой), отформатированным в соответствии с форматом валюты.

Примеры использования функций торгового каталога

<?
// Вывод типов цен, доступных для просмотра
// для данного посетителя
$db_res = GetCatalogGroups(($b="SORT"), ($o="ASC"));
while ($res = $db_res->Fetch())
{
  if ($res["CAN_ACCESS"]=="Y")
  {
    echo $res["NAME_LANG"];
  }
}
?>

<?
// Вывод цены типа $TYPE_ID для товара $PRODUCT_ID
$arProduct = GetCatalogProduct($PRODUCT_ID);
if ($res = GetCatalogProductPrice($PRODUCT_ID, $TYPE_ID))
{
  if ($res["CAN_ACCESS"]=="Y")
  {
    echo FormatCurrency($res["PRICE"], $res["CURRENCY"]);
    echo " (цена типа ".$res["CATALOG_GROUP_NAME"].") ";
    // Если данному посетителю товар $PRODUCT_ID доступен
    // для покупки по цене типа $TYPE_ID и либо товар ещё
    // есть, либо его количество не отслеживается, то
    // можно вывести приглашение к покупке
    if ($res["CAN_BUY"]=="Y" && (IntVal($arProduct["QUANTITY"])>0 || $arProduct["QUANTITY_TRACE"]!="Y"))
    {
      echo "Можно купить";
    }
  }
}
?>

<?
// Вывод списка доступных для просмотра цен товара $PRODUCT_ID
$arProduct = GetCatalogProduct($PRODUCT_ID);
$arPrice = GetCatalogProductPriceList($PRODUCT_ID, "SORT", "ASC");
$bCanBuy = False;
for ($i = 0; $i<count($arPrice); $i++)
{
  if ($arPrice[$i]["CAN_ACCESS"]=="Y")
  {
    if ($arPrice[$i]["CAN_BUY"]=="Y" && (IntVal($arProduct["QUANTITY"])>0 || $arProduct["QUANTITY_TRACE"]!="Y"))
      $bCanBuy = True;
    echo $arPrice[$i]["CATALOG_GROUP_NAME"].": ";
    echo FormatCurrency($arPrice[$i]["PRICE"], $arPrice[$i]["CURRENCY"])."<br>";
  }
}
// Если среди цен данного товара были цены, которые доступны
// данному посетителю для покупки и либо товар ещё
// есть, либо его количество не отслеживается, то
// можно вывести приглашение к покупке
if ($bCanBuy)
{
  echo "Можно купить";
}
?>


Шаблоны экспорта (для разработчиков)

Информация, содержащаяся в этом разделе, является дополнительной к описанию шаблонов экспорта в разделе Экспорт. Детальное описание.

Шаблоны экспорта

Шаблоны должны быть расположены в каталоге /bitrix/php_interface/include/catalog_export/. Предустановленные шаблоны содержат только подключение реальных скриптов. Пользовательские шаблоны должны содержать весь код, который необходим для экспорта. В качестве шаблонов система предлагает все файлы этого каталога, оканчивающиеся на _run.php. Если в этом каталоге находится файл с таким же именем, но оканчивающийся на _setup.php, то система считает этот файл файлом дополнительных настроек (мастером экспорта) для соответствующего шаблона экспорта.

Если в начале шаблона экспорта находится тег <title> (возможно, в PHP комментариях), то содержимое этого тега принимается за название шаблона экспорта. В противном случае названием шаблона становится имя его файла.

Вы можете добавить в каталог /bitrix/php_interface/include/catalog_export/ любое количество произвольных шаблонов экспорта.

Шаблон экспорта

Шаблон экспорта представляет собой обычный PHP скрипт, в котором нет вывода данных. В этом скрипте доступны все стандартные переменные, а так же все переменные, которые установлены в мастере экспорта.

Шаблон экспорта может установить переменную $strExportErrorMessage, содержащую текстовое описание ошибок, которые произошли при выполнении экспорта. В этом случае система будет интерпретировать экспорт как неудачный и выведет содержимое переменной $strExportErrorMessage на экран.

Если после выполнения экспорта системе будет доступна переменная $SETUP_FILE_NAME, то система будет интерпретировать содержимое этой переменной как путь к файлу данных, в который был произведен экспорт. Путь может быть относительным или абсолютным. Система по окончании экспорта отобразит полный путь к файлу данных на экране.

Пример простейшего шаблона экспорта

<?
//<title>Простейший</title>
// Выведем в файл данных название выбраного инфоблока
$strName = "";

// Переменная $IBLOCK_ID должна быть установлена
// мастером экспорта или из профиля
// Переменная $SETUP_FILE_NAME должна быть установлена
// мастером экспорта или из профиля
$IBLOCK_ID = IntVal($IBLOCK_ID);

// Модули каталога и инфоблоков уже подключены
$db_res = CIBlock::GetList(Array(),
                           Array("ID"=>IntVal($IBLOCK_ID))
                           );
if ($ar_res = $db_res->Fetch())
{
    $strName = $ar_res["NAME"];
}

if (strlen($strName)>0)
{
    if ($fp = @fopen($_SERVER["DOCUMENT_ROOT"].$SETUP_FILE_NAME,
                     'wb'))
    {
        @fwrite($fp, $strName);
        @fclose($fp);
    }
    else
    {
        $strExportErrorMessage = "Ошибка открытия файла данных на запись";
    }
}
else
{
    $strExportErrorMessage = "Информационный блок не найден";
}
?>

Мастер экспорта

Мастер экспорта служит для задания дополнительных параметров экспорта (выбор экспортируемых каталогов и групп, указание пути к файлу данных и т.п.). Если дополнительные параметры шаблону экспорта не нужны, то мастер экспорта создавать не обязательно.

Мастер экспорта может быть многошаговым. В этом случае следует использовать переменную $STEP, содержащую текущий шаг мастера. На следующий шаг переменная $STEP должна переходить с увеличенным соответственно значением.

На последнем шаге переменная $FINITE должна быть установлена в значение True. Система воспринимает эту ситуацию как конец мастера экспорта и передает управление на шаблон экспорта или на сохранение профиля.

После окончания мастера экспорта должна быть доступна переменная $SETUP_FIELDS_LIST, содержащая список имен переменных, устанавливаемых мастером экспорта. Имена переменных должны быть разделены запятыми.

Если в качестве действия было вызвано создание профиля экспорта (т.е. переменная $ACTION равна EXPORT_SETUP), то после окончания мастера экспорта должна быть доступна переменная $SETUP_PROFILE_NAME, содержащая имя создаваемого профиля.

В качестве переменной, содержащей путь к файлу данных, в который производится экспорт, рекомендуется использовать переменную $SETUP_FILE_NAME. В этом случае после окончания экспорта система подскажет пользователю полный путь к файлу данных.

Пример простейшего мастера экспорта

<?
$strMyError = "";

if ($STEP>1)
{
    $IBLOCK_ID = IntVal($IBLOCK_ID);
    if ($IBLOCK_ID <= 0)
    {
        $strMyError .= "Инфоблок не выбран.<br>";
    }

    if (strlen($SETUP_FILE_NAME) <= 0)
        $strMyError .= "Не указан файл данных.<br>";

    if ($ACTION=="EXPORT_SETUP" && strlen($SETUP_PROFILE_NAME)<=0)
        $strMyError .= "Не указано имя профиля<br>";

    if (strlen($strMyError) > 0)
    {
        $STEP = 1;
    }
}

echo ShowError($strMyError);

if ($STEP==1)
{
    ?>
    <form method="post" action="<?echo $APPLICATION->GetCurPage() ?>">
        Выберите инфоблок:
        <select name="IBLOCK_ID">
        <?
        $db_res = CIBlock::GetList(Array("iblock_type"=>"asc",
                                   "name"=>"asc"));
        while ($res = $db_res->Fetch())
        {
            ?>
            <option value="<?echo $res["ID"] ?>"
            <?if (IntVal($res["ID"]) == $IBLOCK_ID)
                  echo " selected";?>><?echo $res["NAME"];?></option>
            <?
        }
        ?>
        </select><br>

        Укажите имя файла данных:
        <input type="text" name="SETUP_FILE_NAME"
         value="<?echo (strlen($SETUP_FILE_NAME)>0) ?
                        htmlspecialchars($SETUP_FILE_NAME) :
                        "/upload/file.csv" ?>" size="50">
        <br>

        <?if ($ACTION=="EXPORT_SETUP"):?>
            Имя профиля:
            <input type="text" name="SETUP_PROFILE_NAME"
             value="<?echo htmlspecialchars($SETUP_PROFILE_NAME)?>"
             size="30">
            <br>
        <?endif;?>

        <?//Следующие переменные должны быть обязательно установлены?>
        <input type="hidden" name="lang" value="<?echo $lang ?>">
        <input type="hidden" name="ACT_FILE"
         value="<?echo htmlspecialchars($_REQUEST["ACT_FILE"]) ?>">
        <input type="hidden" name="ACTION" value="<?echo $ACTION ?>">
        <input type="hidden" name="STEP" value="<?echo $STEP + 1 ?>">
        <input type="hidden" name="SETUP_FIELDS_LIST"
         value="IBLOCK_ID,SETUP_FILE_NAME">
        <input type="submit"
         value="<?echo ($ACTION=="EXPORT") ?
                        "Экспортировать" :
                        "Сохранить";?>">
    </form>
    <?
}
elseif ($STEP==2)
{
    // Второй шаг не нужен, говорим "передать управление дальше"
    $FINITE = True;
}
?>


Кастомизация импорта из CommerceML, каталог

Формат обмена коммерческой информацией CommerceML имеет строго определённую структуру. Поэтому импорт данных из этого формата на сайт производится без дополнительных вопросов и настроек. Между тем иногда возникает потребность несколько изменить логику импорта и / или физический смысл некоторых полей файла CommerceML. В этом случае для изменения логики загрузки данных можно воспользоваться специальным механизмом "мутации" данных.

Примечание. Подробно структура CommerceML описана на официальном сайте стандарта http://www.commerceml.ru

Допускается мутация свойств товаров, параметров и свойств элемента инфоблока, который является товаром, а так же параметров товара как такового. Мутация каждого из элементов осуществляется независимо с помощью специальных функций, которые должны быть реализованы в файле
/bitrix/php_interface/include/1c_mutator.php
(файл необходимо создать, если его ещё нет).

Мутация свойств

catalog_property_mutator_1c();

Для мутации свойств необходимо создать функцию с таким именем и реализовать в ней логику изменения свойств товаров. Эта функция будет вызвана непосредственно после создания (обновления) всех свойств из файла CommerceML.
В функции можно получить доступ к следующим переменным, которые могут / должны быть использованы и / или изменены:
$IBLOCK_ID - код инфоблока,
$tmpid - код текущего импорта,
$strError - строка для оповещения об ошибке,
$STT_PROP_ERROR - счетчик ошибок при создании свойств,
$STT_PROP_ADD - счетчик успешно созданных свойств,
$STT_PROP_UPDATE - счетчик успешно обновленных свойств,
$arProperties - массив соответствий между внешним и внутренним кодами свойства, ключами в котором являются внешние коды свойств, а значениями - соответствующие внутренние; этот массив должен быть соответствующим образом изменен при изменении набора свойств.

Пример использования

<?
// Создадим функцию, которая будет добавлять или обновлять свойство
// "Оригинальный номер", которого нет в CommerceML файле
function catalog_property_mutator_1c()
{
   global $IBLOCK_ID, $tmpid, $strError, $STT_PROP_ERROR, $STT_PROP_ADD, $STT_PROP_UPDATE, $arProperties;

   $ibp = new CIBlockProperty;
   $PROP_XML_ID = "ORIGINOMER";
   $PROP_NAME = "Оригинальный номер";
   $PROP_MULTIPLE = "N";
   $PROP_DEF = "";

   $res = CIBlock::GetProperties($IBLOCK_ID, Array(), Array("XML_ID"=>$PROP_XML_ID, "IBLOCK_ID"=>$IBLOCK_ID));
   $bNewRecord_tmp = False;
   if ($res_arr = $res->Fetch())
   {
      $PROP_ID = $res_arr["ID"];
      $res = $ibp->Update($PROP_ID,
         Array(
            "NAME" => $PROP_NAME,
            "MULTIPLE" => $PROP_MULTIPLE,
            "DEFAULT_VALUE" => $PROP_DEF,
            "TMP_ID" => $tmpid
            )
         );
   }
   else
   {
      $bNewRecord_tmp = True;
      $arFields = Array(
         "NAME" => $PROP_NAME,
         "ACTIVE" => "Y",
         "SORT" => "500",
         "DEFAULT_VALUE" => $PROP_DEF,
         "XML_ID" => $PROP_XML_ID,
         "TMP_ID" => $tmpid,
         "MULTIPLE" => $PROP_MULTIPLE,
         "IBLOCK_ID" => $IBLOCK_ID
      );

      $PROP_ID = $ibp->Add($arFields);
      $res = (IntVal($PROP_ID)>0);
   }

   if (!$res)
   {
      $strError .= "Ошибка загрузки свойства [".$PROP_ID."] \"".$PROP_NAME."\" (".$PROP_XML_ID."): ".$ibp->LAST_ERROR.".<br>";
      $STT_PROP_ERROR++;
   }
   else
   {
      if ($bNewRecord_tmp) $STT_PROP_ADD++;
      else $STT_PROP_UPDATE++;

      $arProperties[$PROP_XML_ID] = $PROP_ID;
   }
}
?>

Мутация параметров и свойств товара

array
catalog_property_mutator_1c(
   array &arLoadProduct,
   object &xProductNode,
   bool bInsert
);

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

Параметры функции

Параметр | Описание
arLoadProduct Массив параметров товара, которые были бы сохранены, если бы не было функции мутации. Типичный массив имеет структуру
Array(
"MODIFIED_BY" => код текущего пользователя,
"IBLOCK_SECTION" => массив групп, в которых лежит товар,
"IBLOCK_ID" => код информационного блока,
"NAME" => "название товара",
"XML_ID" => "внешний код товара",
"TMP_ID" => "код текущего импорта",
"PROPERTY_VALUES" => массив свойств товара
);
Структура совпадает со структурой массива, который используется для сохранения элемента информационного блока. Для более подробного описания смотрите соответствующую статью из API модуля инфоблоков.
xProductNode | Объект класса XMLNode, указывающий на элемент CommerceML файла, который соответствует текущему товару.
bInsert | Флаг, который имеет значение True, если это новый товар, и False - в противном случае.

Возвращаемое значение

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

Пример использования

<?
// Создадим функцию, которая будет обновлять нестандартное свойство
// "Оригинальный номер", значения которого идут как атрибуты элемента
// Товар в CommerceML файле, и делать товар активным
// Кроме того запишем "Оригинальный номер" без пробелов в поле описания
// товара для предварительного просмотра
function catalog_product_mutator_1c(&$arLoadProduct, &$xProductNode, $bInsert)
{
   global $arProperties;

   $sOriginomer = $xProductNode->GetAttribute("ОригинальныйНомер");
   $sOriginomer1 = preg_replace("/\s/i", "", $sOriginomer);

   $arLoadProduct["PREVIEW_TEXT"] = $sOriginomer1;
   $arLoadProduct["PROPERTY_VALUES"][$arProperties["ORIGINOMER"]][] = $sOriginomer;
   return $arLoadProduct;
}
?>

Мутация параметров товара как такового

array
catalog_offer_mutator_1c(
   array &arLoadOffer,
   object &xOfferNode
);

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

Параметры функции

Параметр | Описание
arLoadOffer | Массив параметров товара как такового, которые были бы сохранены, если бы не было функции мутации. Типичный массив имеет структуру array( "ID" => код товара, которому принадлежит предложение, "QUANTITY" => количество товара на складе ) Структура совпадает со структурой массива, который используется для сохранения параметров товара в каталоге. Для более подробного описания смотрите соответствующую статью из API модуля Торгового каталога.
xOfferNode | Объект класса XMLNode, указывающий на элемент CommerceML файла, который соответствует текущему предложению.

Возвращаемое значение

Функция должна вернуть новый массив параметров для сохранения свойств товара как такового

Пример использования

<?
// Установим флаг "Уменьшать количество товаров при заказе"
function catalog_offer_mutator_1c(&$arLoadOffer, &$xOfferNode)
{
   $arLoadOffer["QUANTITY_TRACE"] = "Y";
   return $arLoadOffer;
}
?>


Классы модуля каталога

Классы

  • CCatalog
  • CCatalogDiscount
  • CCatalogGroup
  • CCatalogProduct
  • CCatalogProductGroups
  • CExtra
  • CPrice
  • Классы модуля каталога


Классы модуля каталога

Классы::Классы модуля каталога

Важно!Модуль торгового каталога является надстройкой к модулю информационных блоков и не работает самостоятельно.

В каталоге товаров дерево групп и товары с набираемыми свойствами формируются средствами модуля информационных блоков. С помощью методов класса CCatalogProduct к товару (элементу каталога) пристегивается дополнительная запись, задающая значения свойств, специфичных для товара (вес, количество на складе и т.п.).

Следующие PHP классы используются в модуле каталога.

Классы

Класс | Описание
CCatalog | Содержит методы для подключения/отключения информационного блока к модулю торгового каталога (т.е. для указания, что информационный блок является каталогом).
CCatalogDiscount | Класс для управления скидками.
CCatalogGroup | Класс для управления типами цен торгового каталога.
CCatalogProduct | Класс для управления свойствами (параметрами) товара, которые относятся к товару как к таковому (вес, количество на складе и т.п.).
CCatalogProductGroups | Класс для управления свойствами групп товаров.
CExtra | Класс для управления наценками к базовой цене товара.
CPrice | Класс для работы с ценами товаров (т.е. с предложениями).


CCatalog

Методы класса

Метод | Описание
GetList | Функция возвращает результат выборки записей из каталога в соответствии со своими параметрами.
Update | Функция изменяет параметры записи с кодом ID в таблице привязывания информационного блока к модулю Торгового Каталога.
Add | Функция служит для добавления новой записи в таблицу привязывания информационного блока к модулю Торгового Каталога.
Delete | Функция удаляет привязку информационного блока с кодом ID к торговому каталогу. При этом удаляются так же параметры товаров и предложения, относящиеся к этому каталогу. Описания товаров, относящиеся к элементу информационного блока, остаются неизменными.
GetByID | Возвращает массив параметров каталога, включая некоторые параметры, относящиеся к информационному блоку.


Add

CCatalog::Add

bool
CCatalog::Add(
 array arFields
);

Функция служит для добавления новой записи в таблицу привязывания информационного блока к модулю Торгового Каталога.

Параметры функции

Параметр Описание
arFields Массив параметров привязки; должен иметь следующий вид:
$arFields = array(
   "IBLOCK_ID" => [код инфоблока],
   "YANDEX_EXPORT" => [флаг "экспортировать в Яндекс.Товары" Y/N],
   "SUBSCRIPTION" => [флаг "Продажа контента" Y/N],
);

Возвращаемые значения

Возвращает true в случае успешного добавления записи и false - в противном случае.


Delete

CCatalog::Delete

bool
CCatalog::Delete(
 int ID
);

Функция удаляет привязку информационного блока с кодом ID к торговому каталогу. При этом удаляются так же параметры товаров и предложения, относящиеся к этому каталогу. Описания товаров, относящиеся к элементу информационного блока, остаются неизменными.

Параметры функции

Параметр | Описание
ID | Код информационного блока - каталога.

Возвращаемые значения

Возвращает true в случае успешного добавления записи и false - в противном случае.


GetByID

CCatalog::GetByID

array
CCatalog::GetByID(
 int ID
);

Возвращает массив параметров каталога, включая некоторые параметры, относящиеся к информационному блоку

Параметры функции

Параметр | Описание
ID | Код каталога - инфоблока.

Возвращаемые значения

Возвращает ассоциативный массив с ключами

Ключ | Описание
SUBSCRIPTION | Флаг "Продажа контента"
IBLOCK_ID | Код информационного блока.
IBLOCK_TYPE_ID | Тип информационного блока.
NAME | Название информационного блока.
YANDEX_EXPORT | флаг "экспортировать в Яндекс.Товары"


GetList

CCatalog::GetList

CDBResult
CCatalog::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле каталога, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи каталога. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле каталога.

Пример фильтра:
array("SUBSCRIPTION" => "Y")
Этот фильтр означает "выбрать все записи, в которых значение в поле SUBSCRIPTION (флаг "Продажа контента") равно Y".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи каталога. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле каталога. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращает объект класса CDBResult, содержащий коллекцию ассоциативных массивов с ключами:

Ключ | Описание
ID | Код информационного блока.
IBLOCK_ID | Код информационного блока.
IBLOCK_TYPE_ID | Тип информационного блока.
SUBSCRIPTION | Флаг "Продажа контента".
NAME | Название информационного блока.
YANDEX_EXPORT | флаг "экспортировать в Яндекс.Товары"

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


Update

CCatalog::Update

bool
CCatalog::Update(
 int ID,
 array arFields
);

Функция изменяет параметры записи с кодом ID в таблице привязывания информационного блока к модулю Торгового Каталога.

Параметры функции

Параметр | Описание
ID | Код записи для изменения.
arFields Ассоциативный массив новых параметров записи, ключами с котором являются названия параметров, а значениями - новые значения.
Допустимые ключи:
  • YANDEX_EXPORT - флаг "экспортировать в Яндекс.Товары" [Y/N];
  • SUBSCRIPTION - флаг "Продажа контента" [Y/N].

Возвращаемые значения

Возвращает true в случае успешного изменения записи и false - в противном случае.


CCatalogDiscount

Методы класса

Метод | Описание
Add | Метод добавляет новую скидку в соответствии с данными из массива arFields.
Delete | Метод удаляет скидку с кодом ID.
SetCoupon | Метод добавляет код купона coupon в массив доступных для получения скидки купонов текущего покупателя. Система вычисляет минимальную для данного покупателя цену товара с учётом всех его скидок и купонов.
GetCoupons | Метод возвращает массив доступных для получения скидки купонов текущего покупателя. Система вычисляет минимальную для данного покупателя цену товара с учётом всех его скидок и купонов.
ClearCoupon | Метод очищает возвращает массив доступных для получения скидки купонов текущего покупателя. Система вычисляет минимальную для данного покупателя цену товара с учётом всех его скидок и купонов.
GetDiscountByPrice | Метод вычисляет скидку на цену с кодом productPriceID товара для пользователя, принадлежащего группам пользователей arUserGroups.
GetDiscountByProduct | Метод вычисляет скидку на товар с кодом productID для пользователя, принадлежащего группам пользователей arUserGroups.
GetByID | Метод выбирает параметры скидки по ее коду ID.
GetList | Функция возвращает результат выборки записей скидок в соответствии со своими параметрами.
GetDiscountGroupsList | Функция возвращает результат выборки записей с информацией о привязке скидок к группам пользователей в соответствии со своими параметрами.
GetDiscountCatsList | Функция возвращает результат выборки записей с информацией о привязке скидок к типам цен в соответствии со своими параметрами.
GetDiscountProductsList | Функция возвращает результат выборки записей с информацией о привязке скидок к товарам в соответствии со своими параметрами.
GetDiscountSectionsList | Функция возвращает результат выборки записей с информацией о привязке скидок к группам товаров в соответствии со своими параметрами.
Update | Метод изменяет параметры скидки с кодом ID в соответствии с данными из массива arFields.


Add

CCatalogDiscount::Add

bool
CCatalogDiscount::Add(
 array arFields
);

Метод добавляет новую скидку в соответствии с данными из массива arFields.

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой скидки, ключами в котором являются названия параметров, а значениями - соответствующие значения. Допустимые ключи:
  • SITE_ID - сайт;
  • ACTIVE - флаг активности;
  • NAME - название скидки;
  • COUPON - код купона;
  • SORT - индекс сортировки;
  • MAX_DISCOUNT - максимальная величина скидки;
  • VALUE_TYPE - тип скидки (P - в процентах, F - фиксированная величина);
  • VALUE - величина скидки;
  • CURRENCY - валюта;
  • RENEWAL - флаг "Скидка на продление";
  • ACTIVE_FROM - дата начала действия скидки;
  • ACTIVE_TO - дата окончания действия скидки;
  • PRODUCT_IDS - массив кодов товаров, на которые действует скидка (если скидка действует не на все товары);
  • SECTION_IDS - массив кодов групп товаров, на которые действует скидка (если скидка действует не на все группы товары);
  • GROUP_IDS - массив кодов групп пользователей, на которые действует скидка (если скидка действует не на все группы пользователей);
  • CATALOG_GROUP_IDS - массив кодов типов цен, на которые действует скидка (если скидка действует не на все типы цен).

Возвращаемые значения

Метод возвращает код вставленной записи или false в случае ошибки.


ClearCoupon

CCatalogDiscount::ClearCoupon

void
CCatalogDiscount::ClearCoupon();

Метод очищает возвращает массив доступных для получения скидки купонов текущего покупателя. Система вычисляет минимальную для данного покупателя цену товара с учётом всех его скидок и купонов.

Параметры функции

Без параметров.

Возвращаемые значения

Метод не возвращает значений.


Delete

CCatalogDiscount::Delete

bool
CCatalogDiscount::Delete(
 int ID
);

Метод удаляет скидку с кодом ID.

Параметры функции

Параметр | Описание
ID | Код удаляемой записи.

Возвращаемые значения

Метод возвращает true в случае успешного удаления и false в случае ошибки.


GetByID

CCatalogDiscount::GetByID

array
CCatalogDiscount::GetByID(
 int ID
);

Метод выбирает параметры скидки по ее коду ID.

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров скидки с ключами:

  • ID - код записи;
  • SITE_ID - сайт;
  • ACTIVE - флаг активности;
  • NAME - название скидки;
  • COUPON - код купона;
  • SORT - индекс сортировки;
  • MAX_DISCOUNT - максимальная величина скидки;
  • TIMESTAMP_X - дата последнего изменения записи;
  • VALUE_TYPE - тип скидки (P - в процентах, F - фиксированная величина);
  • VALUE - величина скидки;
  • CURRENCY - валюта;
  • RENEWAL - флаг "Скидка на продление";
  • ACTIVE_FROM - дата начала действия скидки;
  • ACTIVE_TO - дата окончания действия скидки.


GetCoupons

CCatalogDiscount::GetCoupons

array
CCatalogDiscount::GetCoupons();

Метод возвращает массив доступных для получения скидки купонов текущего покупателя. Система вычисляет минимальную для данного покупателя цену товара с учётом всех его скидок и купонов.

Параметры функции

Без параметров.

Возвращаемые значения

Метод возвращает массив купонов текущего пользователя.


GetDiscountByPrice

CCatalogDiscount::GetDiscountByPrice

bool
CCatalogDiscount::GetDiscountByPrice(
 int productPriceID[,
 array arUserGroups = array()[,
 string renewal = "N"[,
 string siteID = false]]]
);

Метод вычисляет скидку на цену с кодом productPriceID товара для пользователя, принадлежащего группам пользователей arUserGroups.

Параметры функции

Параметр | Описание
productPriceID | Код цены.
arUserGroups | массив групп, которым принадлежит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
renewa | Флаг "Продление подписки".
siteID | Сайт (по умолчанию текущий).

Возвращаемые значения

Метод возвращает массив ассоциативных массивов скидок или false в случае ошибки. В массиве содержится ассоциативный массив параметров максимальной процентной скидки (если есть) и ассоциативный массив параметров максимальной фиксированной скидки (если есть).

Пример использования

<?
$dbPrice = CPrice::GetList(
    array("QUANTITY_FROM" => "ASC", "QUANTITY_TO" => "ASC",
          "SORT" => "ASC"),
    array("PRODUCT_ID" => $ID),
    false,
    false,
    array("ID", "CATALOG_GROUP_ID", "PRICE", "CURRENCY",
          "QUANTITY_FROM", "QUANTITY_TO")
);
while ($arPrice = $dbPrice->Fetch())
{
    $arDiscounts = CCatalogDiscount::GetDiscountByPrice(
            $arPrice["ID"],
            $USER->GetUserGroupArray(),
            "N",
            SITE_ID
        );
    $discountPrice = CCatalogProduct::CountPriceWithDiscount(
            $arPrice["PRICE"],
            $arPrice["CURRENCY"],
            $arDiscounts
        );
    $arPrice["DISCOUNT_PRICE"] = $discountPrice;

    echo "<pre>&quot;;
    print_r($arPrice);
    echo &quot;</pre>";
}
?>


GetDiscountByProduct

CCatalogDiscount::GetDiscountByProduct

bool
CCatalogDiscount::GetDiscountByProduct(
 int productID = 0[,
 array arUserGroups = array()[,
 string renewal = "N"[,
 array arCatalogGroups = array()[,
 string siteID = false]]]
);

Метод вычисляет скидку на товар с кодом productID для пользователя, принадлежащего группам пользователей arUserGroups.

Параметры функции

Параметр | Описание
productID | Код товара arUserGroups - массив групп, которым принадлежит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
renewal | Флаг "Продление подписки"
arCatalogGroups | Массив типов цен, для которых искать скидку.
siteID | Сайт (по умолчанию текущий)

Возвращаемые значения

Метод возвращает массив ассоциативных массивов скидок или false в случае ошибки. В массиве содержится ассоциативный массив параметров максимальной процентной скидки (если есть) и ассоциативный массив параметров максимальной фиксированной скидки (если есть).

Пример использования

<?
$arDiscounts = CCatalogDiscount::GetDiscountByProduct(
        150,
        $USER->GetUserGroupArray(),
        "N",
        2,
        SITE_ID
    );
?>


GetDiscountCatsList

CCatalogDiscount::GetDiscountCatsList

CDBResult
CCatalogDiscount::GetDiscountCatsList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей с информацией о привязке скидок к типам цен в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле записи, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле записи.

Пример фильтра:
array("!DISCOUNT_ID" => 15)
Этот фильтр означает "выбрать все записи, в которых значение в поле DISCOUNT_ID (код скидки) не равно 15".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле записи. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

  • ID - код записи;
  • DISCOUNT_ID - код скидки;
  • CATALOG_GROUP_ID - код типа цены.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


GetDiscountGroupsList

CCatalogDiscount::GetDiscountGroupsList

CDBResult
CCatalogDiscount::GetDiscountGroupsList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле записи, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле записи.

Пример фильтра:
array("!GROUP_ID" => 5)
Этот фильтр означает "выбрать все записи, в которых значение в поле GROUP_ID (код группы пользователей) не равно 5".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле записи. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

  • ID - код записи;
  • DISCOUNT_ID - код скидки;
  • GROUP_ID - код группы пользователей.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


GetDiscountProductsList

CCatalogDiscount::GetDiscountProductsList

CDBResult
CCatalogDiscount::GetDiscountProductsList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей с информацией о привязке скидок к товарам в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле записи, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле записи.

Пример фильтра:
array("!DISCOUNT_ID" => 15)
Этот фильтр означает "выбрать все записи, в которых значение в поле DISCOUNT_ID (код скидки) не равно 15".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле записи. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

  • ID - код записи;
  • DISCOUNT_ID - код скидки;
  • PRODUCT_ID - код товара.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


GetDiscountSectionsList

CCatalogDiscount::GetDiscountSectionsList

CDBResult
CCatalogDiscount::GetDiscountSectionsList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле записи, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле записи.

Пример фильтра:
array("!DISCOUNT_ID" => 15)
Этот фильтр означает "выбрать все записи, в которых значение в поле DISCOUNT_ID (код скидки) не равно 15".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле записи. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

  • ID - код записи;
  • DISCOUNT_ID - код скидки;
  • PRODUCT_ID - код товара.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


GetList

CCatalogDiscount::GetList

CDBResult
CCatalogDiscount::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле скидки, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле скидки.

Пример фильтра:
array("!DISCOUNT_ID" => 15)
Этот фильтр означает "выбрать все записи, в которых значение в поле DISCOUNT_ID (код скидки) не равно 15".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются скидки. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле скидки. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

  • ID - код записи;
  • SITE_ID - сайт;
  • ACTIVE - флаг активности;
  • NAME - название скидки;
  • COUPON - код купона;
  • SORT - индекс сортировки;
  • MAX_DISCOUNT - максимальная величина скидки;
  • TIMESTAMP_X - дата последнего изменения записи;
  • VALUE_TYPE - тип скидки (P - в процентах, F - фиксированая величина);
  • VALUE - величина скидки;
  • CURRENCY - валюта;
  • RENEWAL - флаг "Скидка на продление";
  • ACTIVE_FROM - дата начала действия скидки;
  • ACTIVE_TO - дата окончания действия скидки;
  • PRODUCT_ID - код товара, на который дается скидка;
  • SECTION_ID - код группы товаров, на которую дается скидка;
  • GROUP_ID - код группы пользователей, на которую дается скидка;
  • CATALOG_GROUP_ID - код типа цен, на который дается скидка.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выберем все скидки для данного товара

$dbProductDiscounts = CCatalogDiscount::GetList(
    array("SORT" => "ASC"),
    array(
            "+PRODUCT_ID" => $PRODUCT_ID,
            "ACTIVE" => "Y",
            "!>ACTIVE_FROM" => $DB->FormatDate(date("Y-m-d H:i:s"),
                                               "YYYY-MM-DD HH:MI:SS",
                                               CSite::GetDateFormat("FULL")),
            "!<ACTIVE_TO" => $DB->FormatDate(date("Y-m-d H:i:s"),
                                             "YYYY-MM-DD HH:MI:SS",
                                             CSite::GetDateFormat("FULL")),
            "COUPON" => ""
        ),
    false,
    false,
    array(
            "ID", "SITE_ID", "ACTIVE", "ACTIVE_FROM", "ACTIVE_TO",
            "RENEWAL", "NAME", "SORT", "MAX_DISCOUNT", "VALUE_TYPE",
    "VALUE", "CURRENCY", "PRODUCT_ID"
        )
    );
while ($arProductDiscounts = $dbProductDiscounts->Fetch())
{
    * * *
}
?>


SetCoupon

CCatalogDiscount::SetCoupon

bool
CCatalogDiscount::SetCoupon(
 string coupon
);

Метод добавляет код купона coupon в массив доступных для получения скидки купонов текущего покупателя. Система вычисляет минимальную для данного покупателя цену товара с учётом всех его скидок и купонов.

Параметры функции

Параметр | Описание
coupon | Код купона.

Возвращаемые значения

Метод возвращает true в случае успешного добавления кода купона и false в случае ошибки.


Update

CCatalogDiscount::Update

bool
CCatalogDiscount::Update(
 int ID,
 array arFields
);

Метод изменяет параметры скидки с кодом ID в соответствии с данными из массива arFields.

Параметры функции

Параметр | Описание
ID | Код скидки.
arFields Ассоциативный массив параметров новой скидки, ключами в котором являются названия параметров, а значениями - соответствующие значения. Допустимые ключи:
  • SITE_ID - сайт;
  • ACTIVE - флаг активности;
  • NAME - название скидки;
  • COUPON - код купона;
  • SORT - индекс сортировки;
  • MAX_DISCOUNT - максимальная величина скидки;
  • VALUE_TYPE - тип скидки (P - в процентах, F - фиксированная величина);
  • VALUE - величина скидки;
  • CURRENCY - валюта;
  • RENEWAL - флаг "Скидка на продление";
  • ACTIVE_FROM - дата начала действия скидки;
  • ACTIVE_TO - дата окончания действия скидки;
  • PRODUCT_IDS - массив кодов товаров, на которые действует скидка (если скидка действует не на все товары);
  • SECTION_IDS - массив кодов групп товаров, на которые действует скидка (если скидка действует не на все группы товары);
  • GROUP_IDS - массив кодов групп пользователей, на которые действует скидка (если скидка действует не на все группы пользователей);
  • CATALOG_GROUP_IDS - массив кодов типов цен, на которые действует скидка (если скидка действует не на все типы цен).

Возвращаемые значения

Метод возвращает код измененной записи или false в случае ошибки.


CCatalogGroup

Методы класса

Метод | Описание
Add | Функция добавляет новый тип цен. При этом сохраняются как языкозависимые параметры типа, так и параметры, которые не зависят от языка. Так же есть возможность указать группы пользователей, члены которых могут просматривать и покупать товары по ценам этого типа.
Delete | Функция удаляет тип цены с кодом ID. При этом цены этого типа так же удаляются. Базовый тип цен удалить невозможно.
GetBaseGroup | Функция возвращает код и внутреннее название базового типа цен. Результат работы функции кэшируется, поэтому повторные вызовы этой функции в рамках одной страницы не приводят к дополнительным запросам базы данных.
GetByID | Функция возвращает параметры типа цен с кодом ID, включая языкозависимые параметры для языка lang
GetGroupsList | Функция возвращает записи из таблицы связей между типами цен и группами пользователей сайта по фильтру arFilter
GetList | Функция возвращает результат выборки записей из типов цен каталога в соответствии со своими параметрами.
Update | Функция изменяет параметры типа цены с кодом ID на значения из массива arFields. При этом сохраняются как языкозависимые параметры типа, так и параметры, которые не зависят от языка. Так же есть возможность указать группы пользователей, члены которых могут просматривать и покупать товары по ценам этого типа.


Add

CCatalogGroup::Add

int
CCatalogGroup::Add(
 array arFields
);

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

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров типа цены, ключами которого являются названия параметров, а значениями - новые значения.
Допустимые параметры:
  • NAME - внутреннее название типа цены;
  • SORT - индекс сортировки;
  • USER_GROUP - массив кодов групп пользователей, члены которых могут видеть цены этого типа;
  • USER_GROUP_BUY - массив кодов групп пользователей, члены которых могут покупать товары по ценам этого типа;
  • USER_LANG - ассоциативный массив языкозависимых параметров типа цены, ключами которого являются коды языков, а значениями - названия этого типа цены на соответствующем языке.

Возвращаемые значения

Возвращает код добавленного типа цены или false в случае ошибки

Пример использования

<?
$arFields = array(
   "NAME" => "retail",
   "SORT" => 100,
   "USER_GROUP" => array(2, 4),   // видят цены члены групп 2 и 4
   "USER_GROUP_BUY" => array(2),  // покупают по этой цене
                                  // только члены группы 2
   "USER_LANG" => array(
      "ru" => "Розничная",
      "en" => "Retail"
      )
);

$ID = CCatalogGroup::Add($arFields);
if ($ID<=0)
   echo "Ошибка добавления типа цены";
?>


Delete

CCatalogGroup::Delete

bool
CCatalogGroup::Delete(
 int ID
);

Функция удаляет тип цены с кодом ID. При этом цены этого типа так же удаляются. Базовый тип цен удалить невозможно.

Параметры функции

Параметр | Описание
ID | Код удаляемого типа цены.

Возвращаемые значения

Возвращает true в случае успешного удаления и false - в противном случае


GetBaseGroup

CCatalogGroup::GetBaseGroup

array CCatalogGroup::GetBaseGroup();

Функция возвращает код и внутреннее название базового типа цен. Результат работы функции кэшируется, поэтому повторные вызовы этой функции в рамках одной страницы не приводят к дополнительным запросам базы данных.

От цены базового типа расчитываются цены других типов, если они указаны с использованием системы наценок. Понятие базового типа цены используется только в административной части и не оказывает влияния на публичную часть.

Возвращаемые значения

Функция возвращает ассоциативный массив с ключами:

Ключ | Описание
ID | Код базового типа цен.
NAME | Внутреннее название базового типа цен.


GetByID

CCatalogGroup::GetByID

array
CCatalogGroup::GetByID(
 int ID,
 string lang = LANGUAGE_ID
);

Функция возвращает параметры типа цен с кодом ID, включая языкозависимые параметры для языка lang

Параметры функции

Параметр | Описание
ID | Код типа цены.
lang | Код языка, по умолчанию равен текущему языку.

Возвращаемые значения

Возвращает ассоциативный массив со следующими ключами:

Ключ | Описание
ID | Код типа цены.
NAME | Внутреннее название типа цены.
BASE | Флаг (Y/N) является ли тип базовым.
SORT | Индекс сортировки.
CAN_ACCESS | Флаг (Y/N) имеет ли текущий пользователь право на видеть цены этого типа.
CAN_BUY | Флаг (Y/N) имеет ли текущий пользователь право покупать товары по ценам этого типа.
NAME_LANG | Название типа цены на языке lang

Пример использования

<?
$rn = CCatalogGroup::GetByID($ID);
if ($rn["CAN_ACCESS"]=="Y")
   echo "Вы можете видеть цены типа ".$rn["NAME_LANG"]."<br>";
if ($rn["CAN_BUY"]=="Y")
   echo "Вы можете покупать товары по ценам типа ".$rn["NAME_LANG"]."<br>";
?>


GetGroupsList

CCatalogGroup::GetGroupsList

CDBResult
CCatalogGroup::GetGroupsList(
 array arFilter = Array()
);

Функция возвращает записи из таблицы связей между типами цен и группами пользователей сайта по фильтру arFilter

Параметры функции

Параметр Описание
arFilter Фильтр задается в виде ассоциативного массива, ключами в котором являются названия полей, а значениями - условия на значения.
Допустимые ключи:
  • CATALOG_GROUP_ID - код типа цен;
  • GROUP_ID - код группы пользователей;
  • BUY - флаг со значениями: Y - запись о разрешении пользователям данной группы покупать товары по ценам данного типа, N - запись о разрешении пользователям данной группы видеть цены данного типа;
  • ID - код записи

Возвращаемые значения

Объект класса CDBResult, содержащий набор ассоциативных массивов с ключами

Ключ | Описание
ID | Код записи.
CATALOG_GROUP_ID | Код типа цен.
GROUP_ID | Код группы пользователей.
BUY | Флаг со значениями: Y - запись о разрешении пользователям данной группы покупать товары по ценам данного типа, N - запись о разрешении пользователям данной группы видеть цены данного типа.

Пример использования

<?
// Выберем коды типов цен, по которым все пользователи
// (т.е. группа 2) могут покупать товары
$db_res = CCatalogGroup::GetGroupsList(array("GROUP_ID"=>2, "BUY"=>"Y"));
while ($ar_res = $db_res->Fetch())
{
   echo $ar_res["CATALOG_GROUP_ID"].", ";
}
?>


GetList

CCatalogGroup::GetList

CDBResult
CCatalogGroup::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле цен каталога, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи типов цен каталога. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле цен каталога.

Пример фильтра:
array("SUBSCRIPTION" => "Y")
Этот фильтр означает "выбрать все записи, в которых значение в поле SUBSCRIPTION (флаг "Продажа контента") равно Y".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи типов цен каталога. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле типов цен каталога. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код типа цены.
NAME | Внутреннее название типа цены.
BASE | Флаг (Y/N) является ли тип базовым.
SORT | Индекс сортировки.
CAN_ACCESS | Флаг (Y/N) имеет ли текущий пользователь право видеть цены этого типа.
CAN_BUY | Флаг (Y/N) имеет ли текущий пользователь право покупать товары по ценам этого типа.
NAME_LANG | Название типа цены на языке lang.

Пример использования

<?
// Выберем типы цен с внутренним именем retail
$dbPriceType = CCatalogGroup::GetList(
        array("SORT" => "ASC"),
        array("NAME" => "retail")
    );
while ($arPriceType = $dbPriceType->Fetch())
{
    echo $arPriceType["NAME_LANG"]." - ".$arPriceType["CAN_ACCESS"]."<br>";
}
?>


Update

CCatalogGroup::Update

bool
CCatalogGroup::Update(
 int ID,
 array arFields
);

Функция изменяет параметры типа цены с кодом ID на значения из массива arFields. При этом сохраняются как языкозависимые параметры типа, так и параметры, которые не зависят от языка. Так же есть возможность указать группы пользователей, члены которых могут просматривать и покупать товары по ценам этого типа.

Параметры функции

Параметр | Описание
ID | Код изменяемого типа цены.
arFields Ассоциативный массив параметров типа цены, ключами которого являются названия параметров, а значениями - новые значения. Допустимые параметры:
  • NAME - внутреннее название типа цены;
  • SORT - индекс сортировки;
  • USER_GROUP - массив кодов групп пользователей, члены которых могут видеть цены этого типа;
  • USER_GROUP_BUY - массив кодов групп пользователей, члены которых могут покупать товары по ценам этого типа;
  • USER_LANG - ассоциативный массив языкозависимых параметров типа цены, ключами которого являются коды языков, а значениями - названия этого типа цены на соответствующем языке.

Возвращаемые значения

Возвращает true в случае успешного изменения параметров типа цени и false - в случае ошибки.

Пример использования

<?
$arFields = array(
   "NAME" => "retail",
   "SORT" => 100,
   "USER_GROUP" => array(2, 4),   // видят цены члены групп 2 и 4
   "USER_GROUP_BUY" => array(2),  // покупают по этой цене
                                  // только члены группы 2
   "USER_LANG" => array(
      "ru" => "Розничная",
      "en" => "Retail"
      )
);

if (!CCatalogGroup::Update($ID, $arFields))
   echo "Ошибка добавления типа цены";
?>


CCatalogProduct

Методы класса

Метод | Описание
Add | Функция добавляет (или обновляет) параметры товара к элементу каталога.
CountPriceWithDiscount | Метод приминяет к цене price в валюте currency наибольшую скидку из массива arDiscounts.
Delete | Функция удаляет из элемента каталога свойства, относящиеся к товару.
GetList | Функция возвращает результат выборки записей товаров в соответствии со своими параметрами.
GetByIDEx | Функция по коду товара ID возвращает все параметры этого товара, включая относящиеся к товару как к элементу информационного блока.
GetByID | Функция по коду товара ID возвращает массив параметров товара (которые относятся к товару как к таковому).
GetNearestQuantityPrice | Функция по коду товара ID возвращает массив параметров товара (которые относятся к товару как к таковому).
GetOptimalPrice | Метод возвращает параметры наименьшей цены товара productID в количестве quantity для посетителя, входящего в группы пользователей arUserGroups.
QuantityTracer | Уменьшает количество на складе товара с кодом PRODUCT_ID на величину DELTA_QUANTITY, если указанное количество есть на складе и у товара установлен флаг "уменьшать количество товара при заказе".
Update | Функция обновляет параметры товара, относящиеся к товару как к таковому.


Add

CCatalogProduct::Add

bool
CCatalogProduct::Add(
 array arFields
);

Функция добавляет (или обновляет) параметры товара к элементу каталога

Параметры функции

Параметр Описание
arFields Ассоциативный массив, ключами которого являются названия параметров товара, а значениями - новые значения параметров.
Допустимые ключи:
  • ID - Код товара (элемента каталога - обязательный);
  • QUANTITY - Количество товара на складе;
  • QUANTITY_TRACE - Флаг (Y/N) "уменьшать ли количество при заказе";
  • WEIGHT - вес единицы товара
  • PRICE_TYPE - тип цены (S - одноразовый платеж, R - регулярные платежи, T - пробная подписка)
  • RECUR_SCHEME_TYPE - тип периода подписки ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год)
  • RECUR_SCHEME_LENGTH - длина периода подписки
  • TRIAL_PRICE_ID - код товара, для которого данный товар является пробным
  • WITHOUT_ORDER - флаг "Продление подписки без оформления заказа"

Возвращаемые значения

Возвращает true в случае успешного обновления параметров и false в противном случае.


CountPriceWithDiscount

CCatalogProduct::CountPriceWithDiscount

array
CCatalogProduct::CountPriceWithDiscount(
 double price,
 string currency,
 array arDiscounts
);

Метод приминяет к цене price в валюте currency наибольшую скидку из массива arDiscounts.

Параметры функции

Параметр | Описание
price | Цена.
currency | Валюта цены.
arDiscounts массив ассоциативных массивов скидок. Имеет вид:
array(
        array(
                "VALUE_TYPE" => "тип скидки
                                (P - в процентах,
                                 F - фиксированная сумма)",
                "VALUE" => "величина скидки",
                "CURRENCY" => "валюта",
                "MAX_DISCOUNT" => "максимальный размер скидки"
            ),
        array(
                "VALUE_TYPE" => "тип скидки
                                (P - в процентах,
                                 F - фиксированная сумма)",
                "VALUE" => "величина скидки",
                "CURRENCY" => "валюта",
                "MAX_DISCOUNT" => "максимальный размер скидки"
            ),
        * * *
    )

Возвращаемые значения

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

Пример использования

<?
// Для товара с кодом $ID выведем различные цены (по типу и количеству), по
// которым данный товар может быть куплен текущим пользователем

$dbPrice = CPrice::GetList(
        array("QUANTITY_FROM" => "ASC", "QUANTITY_TO" => "ASC", "SORT" => "ASC"),
        array("PRODUCT_ID" => $ID),
        false,
        false,
        array("ID", "CATALOG_GROUP_ID", "PRICE", "CURRENCY", "QUANTITY_FROM", "QUANTITY_TO")
    );
while ($arPrice = $dbPrice->Fetch())
{
    $arDiscounts = CCatalogDiscount::GetDiscountByPrice(
            $arPrice["ID"],
            $USER->GetUserGroupArray(),
            "N",
            SITE_ID
        );
    $discountPrice = CCatalogProduct::CountPriceWithDiscount(
            $arPrice["PRICE"],
            $arPrice["CURRENCY"],
            $arDiscounts
        );
    $arPrice["DISCOUNT_PRICE"] = $discountPrice;

    echo "<pre>";
    print_r($arPrice);
    echo "</pre>";
}
?>


Delete

CCatalogProduct::Delete

bool
CCatalogProduct::Delete(
 int ID
);

Функция удаляет из элемента каталога свойства, относящиеся к товару

Параметры функции

Параметр | Описание
ID | Код товара (элемента каталога)

Возвращаемые значения

Возвращает true в случае успешного удаления и false в противном случае


GetByID

CCatalogProduct::GetByID

array
CCatalogProduct::GetByID(
 int ID
);

Функция по коду товара ID возвращает массив параметров товара (которые относятся к товару как к таковому)

Параметры функции

Параметр | Описание
ID | Код товара.

Возвращаемые значения

Ассоциативный массив параметров товара с ключами

Ключ | Описание
ID | Код товара.
QUANTITY | Количество на складе.
QUANTITY_TRACE | Флаг (Н/Т) "уменьшать количество при оформлении заказа"
WEIGHT | Вес единицы товара.
PRICE_TYPE | Тип цены (S - одноразовый платеж, R - регулярные платежи, T - пробная подписка).
RECUR_SCHEME_TYPE | Тип периода подписки ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год).
RECUR_SCHEME_LENGTH | Длина периода подписки.
TRIAL_PRICE_ID | Код товара, для которого данный товар является пробным.
WITHOUT_ORDER | Флаг "Продление подписки без оформления заказа".
TIMESTAMP_X | Дата последнего изменения записи.

Пример использования

<?
$ID = 5;
$ar_res = CCatalogProduct::GetByID($ID);
echo "<br>Товар с кодом ".$ID." имеет следующие параметры:<pre>";
print_r($ar_res);
echo "</pre>";
?>


GetByIDEx

CCatalogProduct::GetByIDEx

array
CCatalogProduct::GetByIDEx(
 int ID
);

Функция по коду товара ID возвращает все параметры этого товара, включая относящиеся к товару как к элементу информационного блока.

Параметры функции

Параметр | Описание
ID | Код товара.

Возвращаемые значения

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

Пример использования

<?
$ID = 5;
$ar_res = CCatalogProduct::GetByIDEx($ID);
echo "<br>Товар с кодом ".$ID." имеет следующие параметры:<br><pre>";
print_r($ar_res);
echo "</pre>";
?>


GetList

CCatalogProduct::GetList

CDBResult
CCatalogProduct::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей товаров в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле товара, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи товара. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле товара.

Пример фильтра:
array("SUBSCRIPTION" => "Y")
Этот фильтр означает "выбрать все записи, в которых значение в поле SUBSCRIPTION (флаг "Продажа контента") равно Y".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи типов товара. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле типов товара. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Объект класса CDBResult, содержащий записи в виде ассоциативных массивов параметров товара с ключами

Ключ | Описание
ID | Код товара.
QUANTITY | Количество на складе.
QUANTITY_TRACE | Флаг (Н/Т) "уменьшать количество при оформлении заказа"
WEIGHT | Вес единицы товара.
PRICE_TYPE | Тип цены (S - одноразовый платеж, R - регулярные платежи, T - пробная подписка)
RECUR_SCHEME_TYPE | Тип периода подписки ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год)
RECUR_SCHEME_LENGTH | Тлина периода подписки.
TRIAL_PRICE_ID | Код товара, для которого данный товар является пробным.
WITHOUT_ORDER | Флаг "Продление подписки без оформления заказа"

Пример использования

<?
// Выведем коды 10 товаров с самым большим количеством на складе
// из тех, количество которых при заказе должно уменьшаться
$ind = 0;
$db_res = CCatalogProduct::GetList(
        array("QUANTITY" => "DESC"),
        array("QUANTITY_TRACE" => "Y"),
        false,
        array("nTopCount" => 10)
    );
while (($ar_res = $db_res->Fetch()) && ($ind < 10))
{
    echo $ar_res["ID"].", ";
    $ind++;
}
?>


GetNearestQuantityPrice

CCatalogProduct::GetNearestQuantityPrice

int
CCatalogProduct::GetNearestQuantityPrice(
 int productID[,
 int quantity = 1[,
 array arUserGroups = array()]]
);

Функция по коду товара ID возвращает массив параметров товара (которые относятся к товару как к таковому)

Параметры функции

Параметр | Описание
productID | Код товара.
quantity | Количество, ближайшее продаваемое количество к которому необходимо найти.
arUserGroups | массив групп, которым принадлежит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()

Возвращаемые значения

Количество товара, доступное для покупки.

Пример использования

<?
$arPrice = CCatalogProduct::GetOptimalPrice($productID, $quantity, $USER->GetUserGroupArray(), $renewal);
if (!$arPrice || count($arPrice) <= 0)
{
    if ($nearestQuantity = CCatalogProduct::GetNearestQuantityPrice($productID, $quantity, $USER->GetUserGroupArray()))
    {
        $quantity = $nearestQuantity;
        $arPrice = CCatalogProduct::GetOptimalPrice($productID, $quantity, $USER->GetUserGroupArray(), $renewal);
    }
}
?>


GetOptimalPrice

CCatalogProduct::GetOptimalPrice

array
CCatalogProduct::GetOptimalPrice(
 int productID[,
 int quantity = 1[,
 array arUserGroups = array()[,
 string renewal = "N"[,
 array arPrices = array()[,
 string siteID = false]]]]]
);

Метод возвращает параметры наименьшей цены товара productID в количестве quantity для посетителя, входящего в группы пользователей arUserGroups.

Параметры функции

Параметр | Описание
productID | Код товара.
quantity | Приобретаемое количество.
arUserGroups | массив групп, которым принадлежит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
renewal | "Y", если вычисляется для продления товара (продажа контента), "N" в остальных случаях.
arPrices Массив цен. Если он установлен, то пересчет идет не по ценам из базы данных, а по ценам из этого массива. Представляет собой массив ассоциативных массивов с ключами:
  • ID - код цены;
  • PRICE - цена;
  • CURRENCY - валюта;
  • CATALOG_GROUP_ID - код типа цен.
siteID | Сайт, для которого производится вычисление. Если парамерт равен false, то берется текущий сайт.

Возвращаемые значения

Массив вида:

array(
 "PRICE" => массив_параметров_минимальной_цены,
 "DISCOUNT_PRICE" => минимальная_цена_в_базовой_валюте,
 "DISCOUNT" => массив_параметров_максимальной_доступной_скидки
)

Пример использования

<?
$arPrice = CCatalogProduct::GetOptimalPrice($productID, $quantity, $USER->GetUserGroupArray(), $renewal);
if (!$arPrice || count($arPrice) <= 0)
{
    if ($nearestQuantity = CCatalogProduct::GetNearestQuantityPrice($productID, $quantity, $USER->GetUserGroupArray()))
    {
        $quantity = $nearestQuantity;
        $arPrice = CCatalogProduct::GetOptimalPrice($productID, $quantity, $USER->GetUserGroupArray(), $renewal);
    }
}
echo "<pre>";
print_r($arPrice);
echo "</pre>";
?>


QuantityTracer

CCatalogProduct::QuantityTracer

bool
CCatalogProduct::QuantityTracer(
 int PRODUCT_ID,
 int DELTA_QUANTITY
);

Уменьшает количество на складе товара с кодом PRODUCT_ID на величину DELTA_QUANTITY, если указанное количество есть на складе и у товара установлен флаг "уменьшать количество товара при заказе"

Параметры функции

Параметр | Описание
PRODUCT_ID | Код товара.
DELTA_QUANTITY | Число, на которое нужно уменьшить количество товара на складе.

Возвращаемые значения

Возвращает true в случае успешного уменьшения и false - в противном случае

Пример использования

<?
// Уменьшим количество на складе товара 5 на 12 штук
CCatalogProduct::QuantityTracer(5, 12);
?>


Update

CCatalogProduct::Update

bool
CCatalogProduct::Update(
 int ID,
 array arFields
);

Функция обновляет параметры товара, относящиеся к товару как к таковому

Параметры функции

Параметр | Описание
ID | Код товара.
arFields Ассоциативный массив, ключами которого являются названия параметров товара, а значениями - новые значения параметров.
Допустимые ключи:
  • QUANTITY - Количество товара на складе;
  • QUANTITY_TRACE - Флаг (Y/N) "уменьшать ли количество при заказе";
  • WEIGHT - вес единицы товара;
  • PRICE_TYPE - тип цены (S - одноразовый платеж, R - регулярные платежи, T - пробная подписка);
  • RECUR_SCHEME_TYPE - тип периода подписки ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год);
  • RECUR_SCHEME_LENGTH - длина периода подписки;
  • TRIAL_PRICE_ID - код товара, для которого данный товар является пробным;
  • WITHOUT_ORDER - флаг "Продление подписки без оформления заказа".

Возвращаемые значения

Возвращает true в случае успешного обновления параметров и false в противном случае.


CCatalogProductGroups

Методы класса

Метод | Описание
Add | Метод добавляет новую запись с информацией о связи товара и группы пользователей, к которой пользователь привязывается при покупке товара, в соответствии с данными из массива arFields.
Delete | Метод удаляет информацию о связи товаров и группы пользователей, к которой пользователь привязывается при покупке товара.
GetByID | Метод выбирает параметры информации о связи между товаром и группами пользователей по коду информации ID.
GetList | Функция возвращает результат выборки записей информации о связи товаров и групп пользователей, к которым пользователь привязывается при покупке товара, в соответствии со своими параметрами.
Update | Метод изменяет параметры записи с кодом ID информации о связи товаров и групп пользователей, к которым пользователь привязывается при покупке товара, в соответствии с данными из массива arFields.


Add

CCatalogProductGroups::Add

bool
CCatalogProductGroups::Add(
 array arFields
);

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

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров новой информации о связи товаров и групп пользователей, ключами в котором являются названия параметров, а значениями - соответствующие значения. Допустимые ключи:
  • PRODUCT_ID - код товара;
  • GROUP_ID - код группы пользователей;
  • ACCESS_LENGTH - длина периода, на который пользователь привязывается к группе пользователей при покупке товара (0 - навсегда);
  • ACCESS_LENGTH_TYPE - тип периода, на который пользователь привязывается к группе пользователей при покупке товара ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год).

Возвращаемые значения

Метод возвращает код вставленной записи или false в случае ошибки.


Delete

CCatalogProductGroups::Delete

bool
CCatalogProductGroups::Delete(
 int ID
);

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

Параметры функции

Параметр | Описание
ID | Код удаляемой записи.

Возвращаемые значения

Метод возвращает true в случае успешного удаления и false в случае ошибки.


GetByID

CCatalogProductGroups::GetByID

array
CCatalogProductGroups::GetByID(
 int ID
);

Метод выбирает параметры информации о связи между товаром и группами пользователей по коду информации ID.

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

Метод возвращает ассоциативный массив параметров информации о временном доступе с ключами:

  • ID - код записи;
  • PRODUCT_ID - код товара;
  • GROUP_ID - код группы пользователей;
  • ACCESS_LENGTH - длина периода, на который пользователь привязывается к группе пользователей при покупке товара (0 - навсегда);
  • ACCESS_LENGTH_TYPE - тип периода, на который пользователь привязывается к группе пользователей при покупке товара ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год).


GetList

CCatalogProductGroups::GetList

CDBResult
CCatalogProductGroups::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

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

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле записи, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • >= - значение поля меньше или равно передаваемой в фильтр величины;
  • >= - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле заказов.

Пример фильтра:
array("PRODUCT_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле PRODUCT_ID (код товара) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле записи. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

  • ID - код записи;
  • PRODUCT_ID - код товара;
  • GROUP_ID - код группы пользователей;
  • ACCESS_LENGTH - длина периода, на который пользователь привязывается к группе пользователей при покупке товара (0 - навсегда);
  • ACCESS_LENGTH_TYPE - тип периода, на который пользователь привязывается к группе пользователей при покупке товара ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год);
  • GROUP_ACTIVE - флаг активности группы пользователей;
  • GROUP_NAME - название группы пользователей.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.


Update

CCatalogProductGroups::Update

bool
CCatalogProductGroups::Update(
 int ID,
 array arFields
);

Метод изменяет параметры записи с кодом ID информации о связи товаров и групп пользователей, к которым пользователь привязывается при покупке товара, в соответствии с данными из массива arFields.

Параметры функции

Параметр | Описание
ID | код записи
arFields Ассоциативный массив параметров новой информации о связи товаров и групп пользователей, ключами в котором являются названия параметров, а значениями - соответствующие значения. Допустимые ключи:
  • PRODUCT_ID - код товара;
  • GROUP_ID - код группы пользователей;
  • ACCESS_LENGTH - длина периода, на который пользователь привязывается к группе пользователей при покупке товара (0 - навсегда);
  • ACCESS_LENGTH_TYPE - тип периода, на который пользователь привязывается к группе пользователей при покупке товара ("H" - час, "D" - сутки, "W" - неделя, "M" - месяц, "Q" - квартал, "S" - полугодие, "Y" - год).

Возвращаемые значения

Метод возвращает код измененной записи или false в случае ошибки.


CExtra

Методы класса

Метод | Описание
Add | Добавляет новую запись в таблицу наценок.
Delete | Удаляет запись наценки из базы. Цены, которые были заданы в виде наценки от базовой цены, становятся заданными абсолютным значением. Сама величина цены не меняется.
GetByID | Функция возвращает параметры наценки по ее коду ID
GetList | Функция возвращает список наценок, отсортированый по полю by в направлении order
SelectBox | Функция возвращает HTML код для отображения выпадающего списка (select) наценок. Функция кэширует список наценок, поэтому ее повторный вызов на одной странице не приводит к дополнительным запросам базы данных.
Update | Функция обновляет параметры наценки с кодом ID на значения из массива arFields.


Add

CExtra::Add

bool
CExtra::Add(
 array arFields
);

Добавляет новую запись в таблицу наценок

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров записи с ключами:
  • NAME - название наценки;
  • PERCENTAGE - процент наценки (может быть как положительным, так и отрицательным)

Возвращаемые значения

Возвращает true в случае успешного сохранения и false - в противном случае


Delete

CExtra::Delete

bool
CExtra::Delete(
 int ID
);

Удаляет запись наценки из базы. Цены, которые были заданы в виде наценки от базовой цены, становятся заданными абсолютным значением. Сама величина цены не меняется.

Параметры функции

Параметр | Описание
ID | Код наценки.

Возвращаемые значения

Возвращается true в случае успешного удаления и false - в противном случае


GetByID

CExtra::GetByID

array
CExtra::GetByID(
 int ID
);

Функция возвращает параметры наценки по ее коду ID

Параметры функции

Параметр | Описание
ID | Код наценки.

Возвращаемые значения

Возвращается ассоциативный массив с ключами

Ключ | Описание
ID | Код наценки.
NAME | Название наценки.
PERCENTAGE | Процент наценки.


GetList

CExtra::GetList

CDBResult
CExtra::GetList(
 string &by,
 string &order
);

Функция возвращает список наценок, отсортированый по полю by в направлении order

Параметры функции

Параметр Описание
by Переменная, содержащая название поля, по которому должен быть отсортирован список наценок. Допустимые значения:
  • NAME - по названию (по умолчанию);
  • PERCENTAGE - по проценту наценки
order Переменная, содержащая направление сортировки. Допустимые значения:
  • ASC - по возрастанию (по умолчанию);
  • DESC - по убыванию

Возвращаемые значения

Объект класса CDBResult, содержащий ассоциативные массивы с ключами:

Ключ | Описание
ID | Код наценки.
NAME | Название наценки.
PERCENTAGE | Процент наценки.


SelectBox

CExtra::SelectBox

string
CExtra::SelectBox(
 string sFieldName,
 string sValue,
 string sDefaultValue = "",
 string JavaChangeFunc = "",
 string sAdditionalParams = ""
);

Функция возвращает HTML код для отображения выпадающего списка (select) наценок. Функция кэширует список наценок, поэтому ее повторный вызов на одной странице не приводит к дополнительным запросам базы данных.

Параметры функции

Параметр | Описание
sFieldName | Название выпадающего списка (атрибут name)
sValue | Начальное значение.
sDefaultValue | Название особого значения, относящееся к пустому значению наценки (например, "Все" или "Нет")
JavaChangeFunc | JavaScript обработчик события OnChange списка. Если указана пустая строка, то событие OnChange не обрабатывается.
sAdditionalParams | Дополнительные атрибуты тега <select>

Возвращаемые значения

Возвращает HTML код для вывода выпадающего списка наценок

Пример использования

<?
echo CExtra::SelectBox("CAT_EXTRA",
                       2,
                       "Не установлено",
                       "ChangeExtra()",
                       "class='typeselect'");
?>


Update

CExtra::Update

bool
CExtra::Update(
 int ID,
 array arFields
);

Функция обновляет параметры наценки с кодом ID на значения из массива arFields.

Параметры функции

Параметр | Описание
ID | Код.
arFields Ассоциативный массив новых параметров наценки с ключами:
  • NAME - название наценки;
  • PERCENTAGE - процент наценки (может быть как положительным, так и отрицательным);
  • RECALCULATE - если имеет значение Y, то будут автоматически пересчитаны все цены, которые заданы этой наценкой

Возвращаемые значения

Возвращает значение true в случае успешного сохранения наценки и false - в противном случае


CPrice

Методы класса

Метод | Описание
Add | Функция добавляет новое ценовое предложение (новую цену) для товара.
Delete | Функция удаляет ценовое предложение с кодом ID
GetBasePrice | Функция возвращает базовую цену товара с кодом PRODUCT_ID. Базовая цена - это цена базового типа цен.
SetBasePrice | Функция устанавливает базовую цену товара с кодом PRODUCT_ID. Базовая цена - это цена базового типа цен.
GetByID | Функция возвращает ценовое предложение по его коду ID
GetList | Функция возвращает результат выборки записей цен в соответствии со своими параметрами.
GetListEx | Функция возвращает результат выборки записей цен в соответствии со своими параметрами.
Update | Функция изменяет параметры ценового предложения (цены) для товара с кодом ID на значения из массива arFields.


Add

CPrice::Add

bool
CPrice::Add(
 array arFields
);

Функция добавляет новое ценовое предложение (новую цену) для товара

Параметры функции

Параметр Описание
arFields Ассоциативный массив параметров ценового предложения. Допустимые параметры:
  • PRODUCT_ID - код товара;
  • EXTRA_ID - код наценки;
  • CATALOG_GROUP_ID - код типа цены;
  • PRICE - цена;
  • CURRENCY - валюта цены;
  • QUANTITY_FROM - количество товара, начиная с приобретения которого действует эта цена;
  • QUANTITY_TO - количество товара, при приобретении которого заканчивает действие эта цена.

    Если необходимо, чтобы значения параметров QUANTITY_FROM и QUANTITY_TO не были заданы, необходимо указать у них в качестве значения false либо не задавать поля QUANTITY_FROM и QUANTITY_TO в Update вообще.

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

Возвращаемые значения

Возвращает значение true в случае успешного сохранения цены и false - в противном случае

Пример использования

<?
// Установим для товара с кодом 15 цену типа 2 в значение 29.95 USD
$PRODUCT_ID = 15;
$PRICE_TYPE_ID = 2;

$arFields = Array(
    "PRODUCT_ID" => $PRODUCT_ID,
    "CATALOG_GROUP_ID" => $PRICE_TYPE_ID,
    "PRICE" => 29.95,
    "CURRENCY" => "USD",
    "QUANTITY_FROM" => 1,
    "QUANTITY_TO" => 10
);

$res = CPrice::GetList(
        array(),
        array(
                "PRODUCT_ID" => $PRODUCT_ID,
                "CATALOG_GROUP_ID" => $PRICE_TYPE_ID
            )
    );

if ($arr = $res->Fetch())
{
    CPrice::Update($arr["ID"], $arFields);
}
else
{
    CPrice::Add($arFields);
}
?>


Delete

CPrice::Delete

bool
CPrice::Delete(
 int ID
);

Функция удаляет ценовое предложение с кодом ID

Параметры функции

Параметр | Описание
ID | Код предложения.

Возвращаемые значения

Возвращает значение true в случае успешного удаления и false - в противном случае.

Пример использования

<?
// Удалим цену с кодом 11
CPrice::Delete(11);
?>


GetBasePrice

CPrice::GetBasePrice

array
CPrice::GetBasePrice(
 int PRODUCT_ID[,
 int quantityFrom = false[,
 int quantityTo = false]]
);

Функция возвращает базовую цену товара с кодом PRODUCT_ID. Базовая цена - это цена базового типа цен.

Параметры функции

Параметр | Описание
PRODUCT_ID | Код товара.
quantityFrom | Количество товара, начиная с приобретения которого действует эта цена.
quantityTo | Количество товара, при приобретении которого заканчивает действие эта цена.

Возвращаемые значения

Возвращает ассоциативный массив с ключами:

Код | Описание
ID | Код ценового предложения.
PRODUCT_ID | Код товара.
EXTRA_ID | Код наценки.
CATALOG_GROUP_ID | Код типа цены.
PRICE | Базовая цена.
CURRENCY | Валюта базовой цены.
QUANTITY_FROM | Количество товара, начиная с приобретения которого действует эта цена.
QUANTITY_TO | Количество товара, при приобретении которого заканчивает действие эта цена.

Пример использования

<?
$ar_res = CPrice::GetBasePrice(11, 1, 10);
echo "Базовая цена товара с кодом 11 (при приобретении от ".
      $ar_res["QUANTITY_FROM"]." до ".
      $ar_res["QUANTITY_TO"]." единиц товара) равна ".
      $ar_res["PRICE"]." ".$ar_res["CURRENCY"]."<br>";
echo "Отформатированая базовая цена: ".
      CurrencyFormat($ar_res["PRICE"], $ar_res["CURRENCY"]);
?>


GetByID

CPrice::GetByID

array
CPrice::GetByID(
 int ID
);

Функция возвращает ценовое предложение по его коду ID

Параметры функции

Параметр | Описание
ID | Код предложения.

Возвращаемые значения

Возвращается ассоциативный массив с ключами

Ключ | Описание
ID | Код предложения.
PRODUCT_ID | Код товара.
EXTRA_ID | Код наценки.
CATALOG_GROUP_ID | Код типа цены.
PRICE | Цена.
CURRENCY | Валюта.
CAN_ACCESS | Флаг (Y/N), может ли текущий пользователь видеть эту цену.
CAN_BUY | Флаг (Y/N), может ли текущий пользователь покупать по этой цене.
CATALOG_GROUP_NAME | Название группы цен на текущем языке.
TIMESTAMP_X | Дата последнего изменения записи.
QUANTITY_FROM | Количество товара, начиная с приобретения которого действует эта цена.
QUANTITY_TO | Количество товара, при приобретении которого заканчивает действие эта цена.

Пример использования

<?
$ID = 11;
$arPrice = CPrice::GetByID($ID);
echo "Цена типа ".$arPrice["CATALOG_GROUP_NAME"].
     " на товар с кодом ".$ID.": ";
echo CurrencyFormat($arPrice["PRICE"],
                    $arPrice["CURRENCY"])."<br>";
echo "Вы ".(($arPrice["CAN_ACCESS"]=="Y") ?
            "можете" :
            "не можете")." видеть эту цену";
?>


GetList

CPrice::GetList

CDBResult
CPrice::GetList(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей цен в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле цены, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи типов цены. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле типов цены.

Пример фильтра:
array("PRODUCT_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле PRODUCT_ID (код товара) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи типов цены. Массив имеет вид:
array("название_поля1", "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле типов цены. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код предложения.
PRODUCT_ID | Код товара.
EXTRA_ID | Код наценки.
CATALOG_GROUP_ID | Код типа цены.
PRICE | Цена.
CURRENCY | Валюта.
CAN_ACCESS | Флаг (Y/N), может ли текущий пользователь видеть эту цену.
CAN_BUY | Флаг (Y/N), может ли текущий пользователь покупать по этой цене.
CATALOG_GROUP_NAME | Название группы цен на текущем языке.
TIMESTAMP_X | Дата последнего изменения записи.
QUANTITY_FROM | Количество товара, начиная с приобретения которого действует эта цена.
QUANTITY_TO | Количество товара, при приобретении которого заканчивает действие эта цена.

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
// Выведем цену типа $PRICE_TYPE_ID товара с кодом $PRODUCT_ID

$db_res = CPrice::GetList(
        array(),
        array(
                "PRODUCT_ID" => $PRODUCT_ID,
                "CATALOG_GROUP_ID" => $PRICE_TYPE_ID
            )
    );
if ($ar_res = $db_res->Fetch())
{
    echo CurrencyFormat($ar_res["PRICE"], $ar_res["CURRENCY"]);
}
else
{
    echo "Цена не найдена!";
}
?>


GetListEx

CPrice::GetListEx

CDBResult
CPrice::GetListEx(
 array arOrder = array(),
 array arFilter = array(),
 array arGroupBy = false,
 array arNavStartParams = false,
 array arSelectFields = array()
);

Функция возвращает результат выборки записей цен в соответствии со своими параметрами.

Параметры функции

Параметр Описание
arOrder Массив, в соответствии с которым сортируются результирующие записи. Массив имеет вид:
array(
"название_поля1" => "направление_сортировки1",
"название_поля2" => "направление_сортировки2",
. . .
)
В качестве "название_поляN" может стоять любое поле цены, а в качестве "направление_сортировкиX" могут быть значения "ASC" (по возрастанию) и "DESC" (по убыванию).

Если массив сортировки имеет несколько элементов, то результирующий набор сортируется последовательно по каждому элементу (т.е. сначала сортируется по первому элементу, потом результат сортируется по второму и т.д.).

Значение по умолчанию - пустой массив array() - означает, что результат отсортирован не будет.
arFilter Массив, в соответствии с которым фильтруются записи типов цены. Массив имеет вид:
array(
"[модификатор1][оператор1]название_поля1" => "значение1",
"[модификатор2][оператор2]название_поля2" => "значение2",
. . .
)
Удовлетворяющие фильтру записи возвращаются в результате, а записи, которые не удовлетворяют условиям фильтра, отбрасываются.

Допустимыми являются следующие модификаторы:
  • ! - отрицание;
  • + - значения null, 0 и пустая строка так же удовлетворяют условиям фильтра.
Допустимыми являются следующие операторы:
  • >= - значение поля больше или равно передаваемой в фильтр величины;
  • > - значение поля строго больше передаваемой в фильтр величины;
  • <= - значение поля меньше или равно передаваемой в фильтр величины;
  • < - значение поля строго меньше передаваемой в фильтр величины;
  • @ - значение поля находится в передаваемом в фильтр разделенном запятой списке значений;
  • ~ - значение поля проверяется на соответствие передаваемому в фильтр шаблону;
  • % - значение поля проверяется на соответствие передаваемой в фильтр строке в соответствии с языком запросов.
В качестве "название_поляX" может стоять любое поле типов цены.

Пример фильтра:
array("PRODUCT_ID" => 150)
Этот фильтр означает "выбрать все записи, в которых значение в поле PRODUCT_ID (код товара) равно 150".

Значение по умолчанию - пустой массив array() - означает, что результат отфильтрован не будет.
arGroupBy Массив полей, по которым группируются записи типов цены. Массив имеет вид:
array("название_поля1",
      "группирующая_функция2" => "название_поля2", . . .)
В качестве "название_поляN" может стоять любое поле типов цены. В качестве группирующей функции могут стоять:
  • COUNT - подсчет количества;
  • AVG - вычисление среднего значения;
  • MIN - вычисление минимального значения;
  • MAX - вычисление максимального значения;
  • SUM - вычисление суммы.
Если массив пустой, то функция вернет число записей, удовлетворяющих фильтру.

Значение по умолчанию - false - означает, что результат группироваться не будет.
arNavStartParams Массив параметров выборки. Может содержать следующие ключи:
  • "nTopCount" - количество возвращаемых функцией записей будет ограничено сверху значением этого ключа;
  • любой ключ, принимаемый методом CDBResult::NavQuery в качестве третьего параметра.
Значение по умолчанию - false - означает, что параметров выборки нет.
arSelectFields Массив полей записей, которые будут возвращены функцией. Можно указать только те поля, которые необходимы. Если в массиве присутствует значение "*", то будут возвращены все доступные поля.

Значение по умолчанию - пустой массив array() - означает, что будут возвращены все поля основной таблицы запроса.

Возвращаемые значения

Возвращается объект класса CDBResult, содержащий набор ассоциативных массивов с ключами:

Ключ | Описание
ID | Код предложения.
PRODUCT_ID | Код товара.
EXTRA_ID | Код наценки.
CATALOG_GROUP_ID | Код типа цены.
PRICE | Цена.
CURRENCY | Валюта.
TIMESTAMP_X | Дата последнего изменения записи.
QUANTITY_FROM | Количество товара, начиная с приобретения которого действует эта цена.
QUANTITY_TO | Количество товара, при приобретении которого заканчивает действие эта цена.
CATALOG_GROUP_BASE | Флаг "Базовая" типа цены.
CATALOG_GROUP_NAME | Название группы цен на текущем языке.
CATALOG_GROUP_SORT | Индекс сортировки типа цены.
GROUP_BUY | Флаг "Разрешена покупка по этой цене"

Если в качестве параметра arGroupBy передается пустой массив, то функция вернет число записей, удовлетворяющих фильтру.

Пример использования

<?
$dbProductPrice = CPrice::GetListEx(
        array(),
        array("PRODUCT_ID" => $ID),
        false,
        false,
        array("ID", "CATALOG_GROUP_ID", "PRICE", "CURRENCY", "QUANTITY_FROM", "QUANTITY_TO")
    );
?>


SetBasePrice

CPrice::SetBasePrice

bool
CPrice::SetBasePrice(
 int PRODUCT_ID,
 float PRICE,
 string CURRENCY[,
 int QUANTITY_FROM = 0[,
 int QUANTITY_TO = 0]]
);

Функция устанавливает базовую цену товара с кодом PRODUCT_ID. Базовая цена - это цена базового типа цен.

Параметры функции

Параметр | Описание
PRODUCT_ID | Код товара.
PRICE | Новая базовая цена.
CURRENCY | Валюта новой базовой цены.
QUANTITY_FROM | Количество товара, начиная с приобретения которого действует эта цена.
QUANTITY_TO | Количество товара, при приобретении которого заканчивает действие эта цена.

Возвращаемые значения

Возвращает значение true в случае успешного сохранения цены и false - в противном случае.


Update

CPrice::Update

bool
CPrice::Update(
 int ID,
 array arFields
);

Функция изменяет параметры ценового предложения (цены) для товара с кодом ID на значения из массива arFields.

Параметры функции

Параметр | Описание
ID | Код ценового предложения.
arFields Ассоциативный массив новых параметров ценового предложения, ключами в котором являются названия полей предложения, а значениями - новые значения.
Допустимые ключи:
  • PRODUCT_ID - код товара;
  • EXTRA_ID - код наценки;
  • CATALOG_GROUP_ID - код типа цены;
  • PRICE - цена;
  • CURRENCY - валюта цены
  • QUANTITY_FROM - количество товара, начиная с приобретения которого действует эта цена. Если не хотим ;
  • QUANTITY_TO - количество товара, при приобретении которого заканчивает действие эта цена.

    Если необходимо, чтобы значения параметров QUANTITY_FROM и QUANTITY_TO не были заданы, необходимо указать у них в качестве значения false либо не задавать поля QUANTITY_FROM и QUANTITY_TO в Update вообще.

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

Возвращаемые значения

Возвращает значение true в случае успешного сохранения цены и false - в противном случае

Пример использования

<?
// Установим для товара с кодом 15 цену типа 2 в значение 29.95 USD
$PRODUCT_ID = 15;
$PRICE_TYPE_ID = 2;

$arFields = Array(
    "PRODUCT_ID" => $PRODUCT_ID,
    "CATALOG_GROUP_ID" => $PRICE_TYPE_ID,
    "PRICE" => 29.95,
    "CURRENCY" => "USD",
    "QUANTITY_FROM" => 1,
    "QUANTITY_TO" => 10
);

$res = CPrice::GetList(
        array(),
        array(
                "PRODUCT_ID" => $PRODUCT_ID,
                "CATALOG_GROUP_ID" => $PRICE_TYPE_ID
            )
    );

if ($arr = $res->Fetch())
{
    CPrice::Update($arr["ID"], $arFields);
}
else
{
    CPrice::Add($arFields);
}
?>


Update

Управление структурой

  • Визуальный редактор
  • События


Визуальный редактор

Визуальный редактор, входящий в состав модуля "Управление структурой" предоставляет API, использование которого позволяет добавлять в редактор функциональные элементы, определённые пользователем, а также настраивать и изменять функционал редактора. Рассматриваемые методы могут использоваться на страницах, где подключается визуальный редактор, после его непосредственного подключения.

Предоставляемое API функционирует на уровне JavaScript, поэтому вызовы функций должны осуществляться внутри тегов <script></script>.
Ошибки, допущенные при использовании API, могут привести к нарушению нормальной работы визуального редактора.

  • Добавление панелей задач
  • Добавление парсеров
  • Глобальный объект oBXEditorUtils


Объект BXNodeElement

Экземпляры объекта BXNodeElement передаются в качестве параметра обработчикам событий при описании пользовательских панелей задач. Класс этого объекта используется для внутреннего представления "искуственных" элементов, используемых для замены некоторых фрагментов кода на иконки в визуальном режиме.

Свойства

Метод Описание
arAttributes Массив, содержит два важных элемента
Индекс | Описание
__bxtagname | Содержит искуственное имя тега, которое задается при создании искуственного элемента
__bxcontainer | Содержит сериализованное представление параметров элемента.

Пример

//....

//pNode - экземпляр объекта BXNodeElement
alert(pNode.arAttributes["__bxtagname"]);

//....
Сведения об остальных свойствах объекта будут предоставленны позднее.


Добавление панелей задач

API визуального редактора предусматривает возможность добавления пользовательских панелей задач в визуальный редактор. Данная возможность позволяет подключить к редактору практически произвольный функционал. Подключение панели задач происходит в два этапа:

  1. Объявление класса панели задач
  2. Добавление панели задач путём вызова метода addTaskBar() глобального объекта oBXEditorUtils

1. Объявление класса панели задач

Для обявления класса панели задач необходимо придерживаться стандартных правил описания классов в JavaScript. Учитывая тот факт, что в синтаксисе языка JavaScript не предусмотренно специального синтаксиса для описания классов, для этих целей используются функции.
В теле описываемой функции, используя синтаксис объявления функциональных литералов, определяются методы класса, как свойства объекта prototype.

Для обеспечения взаимодействия с API визуального редактора, при обявлении класса можно использовать:

  • обработчики стандартных событий
  • свойства класса-родителя
  • методы класса-родителя

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

Обработчики стандартных событий

Обработчик | Описание
OnTaskbarCreate() | Выполняется при создании панели задач. Позволяет сформировать визуальное представление панели а также выполнить все подготовительные действия
OnTaskbarRemove() | Выполняется при удалении панели задач. Может применяться для очистки памяти от созданных объектов, обявленных событий, для предотвращения утечек памяти
OnElementDragEnd(object oElement) | Выполняется при перетаскивании элемента из списка, сформированного методами формирования стандартных панелей задач (ряд методов класса родителя). Параметр oElement является экземпляром объекта BXNodeElement, наследующим свойства объекта node DOM, кроме того обладающим рядом специальных свойств, позволяющих его однозначно идентифицировать.
UnParseElement(object oElement) Выполняется при переключении визуального редактора из визуального режима в режим редактирования кода или смешанный режим. Параметр oElement является объектом BXNodeElement, наследующим ряд свойств объекта node DOM, кроме того обладающим рядом специальных свойств, позволяющих его однозначно идентифицировать.
Возвращает код, на который следует заменить искомый элемент, или false, если замена не требуется.
ВАЖНО! Данный обработчик вызывается для каждого нестандартного визуального элемента, поэтому для нахождения нужного элемента необходимо реализовывать проверку атрибута __bxtagname элемента. Например:
CustomTaskbar.prototype.UnParseElement = function(node)
{
    if (node.arAttributes["__bxtagname"] == '__customtag1')
        return '<?MyPHPFunction(0)?>'
    if (node.arAttributes["__bxtagname"] == '__customtag1')
        return '<?MyPHPFunction(1)?>'
    if (node.arAttributes["__bxtagname"] == '__customtag2')
        return '<?MyPHPFunction(2)?>'

    return false;
}

Свойства и методы класса-родителя

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

Например:
function CustomTaskbar()
{
    var oTaskbar = this;
    CustomTaskbar.prototype.OnTaskbarCreate = function ()
    {
        var pDataCell = oTaskbar.CreateScrollableArea(oTaskbar.pDataCell);
        //......
    }
    //....
}

Свойства класса-родителя

Свойство | Описание
pDataCell | Область панели задач, доступная для формирования интерфейса.

Методы класса-родителя

Метод Описание
object
CreateScrollableArea(
object nodeElement
); 		Метод, создающий прокручиваемую область внутри элемента nodeElement, являющегося объектом node DOM и возвращает ее в виде ссылки на объект node DOM.
bool
DisplayElementList(
array arElements,
object oCont
); 		Метод создает стандартный список элементов на основе передаваемого ему массива, и прикрепляет его к контейнеру oCont, который является объектом node DOM. Возвращает true в случае успешного завершения операции, false - в противном случае. oCont не должен содержать других элементов кроме списка.
Передаваемый в качестве параметра массив arElements является индексным, каждый его элемент является ассоциативным массивом и имеет следующую структуру:
Индекс | Описание
string name | Имя элемента
string title | Название элемента, отображается в списке
string tagname | Имя тега. Используется для отображения данных в панели свойств а также для обработки элемента при переключении в режим просмотра кода
string icon | Путь к файлу иконке, которая будет отображаться в списке
bool isGroup true - если элемент является группой;
false - если элемент не является группой;
array params | Массив параметров. Поддерживаются также ассоциативные и вложенные массивы.
array childElements | Массив, указывается для элементов, являющихся группами. Каждый элемент этого массива также является массивом со структурой, идентичной структуре элемента, описанной в этой таблице.
Пример создания списка элементов приведен ниже.
*На текущем этапе поддерживаются структуры описания элементов с двухуровневой вложенностью.
bool
RemoveElementList(
object oCont
); 		Метод, удаляет список элементов из контейнера oCont. Возвращает true в случае успешного завершения операции, false - в противном случае.
bool
AddElement(
array oElement,
object oCont,
[string sPath],
[int orderInd]
); 		Добавляет элемент в список элементов. Используется для добавления элементов в список. oElement - массив имеющий структуру элемента списка(см. метод DisplayElementList()).
oCont - контейнер, в котором находится список элементов.
sPath - необязательный параметр,определяет глубину вложенности добавляемого элемента путём указания пути, состоящего из перечисленных через запятую имен элементов-групп.Если он не указан или в качестве параметра передана пустая строка, используется самый верхний уровень вложенности.
orderInd определяет, каким по порядку будет добавлен элемент на заданый уровень вложенности. Если orderInd равен -1 или не задан, элемент вставляется в конец списка.
Возвращает true в случае успешного завершения операции, false - в противном случае.
bool
RemoveElement(
string elName,
object oCont,
[string sPath]
); 		Удаляет элемент c именем elName из списка элементов, находящегося в контейнере oCont.
sPath - необязательный параметр,определяет глубину вложенности удаляемого элемента путём указания пути, состоящего из перечисленных через запятую имен элементов-групп.Если он не указан или в качестве параметра передана пустая строка, используется самый верхний уровень вложенности.
Возвращает true в случае успешного завершения операции, false - в противном случае.

Использование других методов и средств API

Кроме описанных выше методов класса-родителя, при описании класса панели задач можно использовать определённые методы API визуального редактора, для упрощения решения стандартных задач.

Добавление обработчика элементов для панели свойств

Средствами API можно добавить обработчик для панели свойств визуального редактора, реализуя, таким образом, возможность отображения и редактирование свойств произвольных элементов.
Для добавления обработчика для панели свойств необходимо воспользоваться методом addPropertyBarHandler() глобального объекта oBXEditorUtils:

2. Добавление панели задач

Для добавления обявленной панели задач в визуальный редактор необходимо вызвать метод addTaskBar глобального объекта oBXEditorUtils:

Описание:

void
oBXEditorUtils.addTaskBar(
 string className,
 int taskbarSetPos,
 string taskbarTitle,
 array params
);

Более подробное описание метода приведено в его описании. Параметры:
Параметр | Описание
className | Имя класса панели задач.
taskbarSetPos Параметр, определяющий положение панели задач, относительно области редактирования:
0 | Вверху, над областью редактирования
1 | Слева от области редактирования
2 | Справа от области редактирования
3 | Внизу, под областью редактирования
taskbarTitle | Название панели задач, отображается в заголовке.
params | Дополнительные параметры

Пример добавления панели задач в редактор

<script>

function CustomTaskbar()
{
    var pDataCell;
    var oTaskbar = this;

    CustomTaskbar.prototype.OnTaskbarCreate = function ()
    {
        //Создание прокручиваемой области
        pDataCell = oTaskbar.CreateScrollableArea(oTaskbar.pDataCell);
        //Добавление обработчика панели свойств для элемента "_customtag2"
        oBXEditorUtils.addPropertyBarHandler('_customtag2',this.ShowProperties);
        //Отображение списка элементов
        this.DisplayTree();
    }

    CustomTaskbar.prototype.DisplayTree = function()
    {
        //Создание массива элементов
        var arElements = [];
        var _arElement = [];
        _arElement['name'] = 'group1';
        _arElement['title'] = 'Group 1';
        _arElement['tagname'] = '';
        _arElement['icon'] = '';
        _arElement['isGroup'] = true;
        _arElement['params'] = [];
        _arElement['childElements'] = [];
            var __arElement = [];
            __arElement['name'] = 'el_1_1';
            __arElement['title'] = 'Element 1.1';
            __arElement['tagname'] = '_customtag';
            __arElement['icon'] = '/images/icon1.gif';
            __arElement['isGroup'] = false;
            __arElement['params'] = [];
            __arElement['childElements'] = [];
            _arElement['childElements'].push(__arElement);

            __arElement = [];
            __arElement['name'] = 'el_1_2';
            __arElement['title'] = 'Element 1.2';
            __arElement['tagname'] = '_customtag2';
            __arElement['icon'] = '/images/icon2.gif';
            __arElement['isGroup'] = false;

                ___arPar = [];
                ___arPar[0] = {name:'param0',title:'Параметр0',value:'value0'};
                ___arPar[1] = {name:'param1',title:'Параметр1',value:'value1'};
                ___arPar[2] = {name:'param2',title:'Параметр2',value:'value2'};
            __arElement['params'] = ___arPar;
            __arElement['childElements'] = [];

            _arElement['childElements'].push(__arElement);

        arElements.push(_arElement);

        _arElement = [];
        _arElement['name'] = 'el_2';
        _arElement['title'] = 'Element 2';
        _arElement['tagname'] = '_customtag';
        _arElement['icon'] = '/images/icon3.gif';
        _arElement['params'] = [];
        _arElement['isGroup'] = false;
        _arElement['childElements'] = [];
        arElements.push(_arElement);

        //Добавление списка элементов к прокручиваемой области
        oTaskbar.DisplayElementList(arElements,pDataCell);
    }

    //Обработчик панели свойств для элемента _customtag2
    CustomTaskbar.prototype.ShowProperties = function(_bNew, _pTaskbar, _pElement)
    {
        // _pTaskbar.pCellProps - прокручиваемая область панели свойств
        var arParams = oBXEditorUtils.getCustomNodeParams(_pElement);
        var _input,_div;
        var __saveParams = function(e)
        {
            for (var _i=0; _i<arParams.length;_i++)
            {
                _input = document.getElementById('__param_'+arParams[_i].name);
                arParams[_i].value = _input.value;
            }

            //oBXEditorUtils.setCustomNodeParams(_pElement,arParams);
        }

        if (_bNew)
        {
            oBXEditorUtils.BXRemoveAllChild(_pTaskbar.pCellProps);
            for (var _i=0;_i<arParams.length;_i++)
            {
                _input = document.createElement('INPUT');
                _input.type = 'text';
                _input.id = '__param_'+arParams[_i].name;
                _input.value = arParams[_i].value;
                _input.onblur = __saveParams;

                _div = document.createElement('DIV');
                _div.id = '__vd_'+arParams[_i].name;
                _div.innerHTML = arParams[_i].title;
                _div.appendChild(_input);
                _pTaskbar.pCellProps.appendChild(_div);
            }
        }
        else
        {
            for (var _i=0;_i<arParams.length;_i++)
            {
                _input = document.createElement('INPUT');
                _input.type = 'text';
                _input.id = '__param_'+arParams[_i].name;
                _input.value = arParams[_i].value;
                _input.onblur = __saveParams;

                _div = document.getElementById('__vd_'+arParams[_i].name);
                _div.innerHTML = arParams[_i].title;
                _div.appendChild(_input);
            }
        }
    }

    CustomTaskbar.prototype.UnParseElement = function(node)
    {
        if (node.arAttributes["__bxtagname"] == '_customtag')
            return '<?SomeSuperFunction(3)?>'
        if (node.arAttributes["__bxtagname"] == '_customtag2')
            return '<?SomeSuperFunction(1)?>'

        return false;
    }

    CustomTaskbar.prototype.OnElementDragEnd = function(oEl)
    {
        if (oEl.getAttribute('__bxtagname') == '_customtag')
        {
            oEl.parentNode.removeChild(oEl);
            oTaskbar.insertHTML('snippet');
            alert('Был вставлен произвольный элемент');
        }
        else if(oEl.getAttribute('__bxtagname') == '_customtag2')
            alert('Был вставлен другой произвольный элемент');

    }
}

//Добавление панели задач
oBXEditorUtils.addTaskBar('CustomTaskbar',2,"Help",[]);

</script>


Добавление парсеров

API визуального редактора предусматривает возможность добавления парсеров в визуальный редактор. Данная возможность позволяет включить свои обработчики в процесс разбора кода редактируемого документа на этапе формирования его визуального представления (в момент загрузки документа и при переключении из режима редактирования кода в визуальный режим).

Средствами API визуального редактора можно подключить парсеры(обработчики) трех видов.
В совокупности они позволяют наиболее эффективно реализовывать пользовательскую обработку документа на этапе формирования визуального отображения документа. Виды:
  • Парсер исходного кода документа (Content Parser)
  • Парсер фрагментов PHP-кода (PHP Parser)
  • Обработчик визуального отображения средствами DOM (DOM Handler)
Рассмотрим подробнее каждый из них.

Content Parser

Позволяет обработать документ на уровне его исходного кода.

Подключения парсера проходит в два этапа:
  1. Объявление функции-обработчика
  2. Добавление парсера, путём вызова метода addContentParser() глобального объекта oBXEditorUtils

Объявление функции-обработчика

Функция-обработчик (собственно сам парсер) должна быть объявлена в области видимости вызова метода addContentParser(). Объявленной функции передается единственный строковый аргумент - код документа. В теле функции происходит обработка кода и возврат измененного значения. Если возвращаемое значение равно false, изменения не вносятся.

Добавление парсера

Осуществляется путём вызова метода addContentParser() глобального объекта oBXEditorUtils

Пример

<script>

function CustomContentParser(str)
{
    //... манипуляции с кодом
    return str;
}

//Добавление парсера
oBXEditorUtils.addContentParser(CustomContentParser);

</script>

PHP Parser

Добавление парсера этого вида позволяет обрабатывать все PHP-фрагменты в коде.
При обработке кода документа все распознанные фрагменты кода последовательно передаются на обработку всем подключенным парсерам. Если парсер возвращает неизмененный фрагмент или false (для проверки используется условие строгого соответствия), то фрагмент передается на обработку следующему парсеру. В качестве второго, небязательного параметра при подключении парсера можно указать его порядок в "очереди" на получение фрагмента кода. Однако встроенные парсеры визуального редактора обрабатывают php в первую очередь.
Подключения парсера проходит в два этапа:
  1. Объявление функции-обработчика
  2. Добавление парсера путём вызова метода addPHPParser() глобального объекта oBXEditorUtils

Объявление функции-обработчика

Функция-обработчик (собственно сам парсер) должна быть объявлена в области видимости вызова метода oBXEditorUtils.addPHPParser(). Объявленной функции передается единственный строковый аргумент - код документа. В теле функции происходит обработка кода и возврат измененного значения. Если возвращаемое значение равно false, изменения не вносятся.
При обработке фрагмента, для упрощения решения стандартных процедур можно использовать методы объекта oBXEditorUtils.PHPParser.

Добавление парсера

Осуществляется путём вызова метода addPHPParser() глобального объекта oBXEditorUtils

Пример

<script>

function CustomPHPParser(str)
{
    //... манипуляции с кодом
    return str;
}

//Добавление парсера
oBXEditorUtils.addPHPParser(CustomPHPParser);

</script>

При добавлении парсеров исходного кода документа (Content Parser) и фрагментов PHP-кода (PHP Parser) следует обратить внимание, что вносимые изменения должны быть корректным HTML-кодом, т.к. в случае ошибки визуальный редактор может работать некорректно.

DOM Handler

Добавление обработчика документа на уровне DOM позволяет упростить редактирование свойств элементов, уже после их представления в визуальном режиме.
При обявлении функции-обработчика допускается использование всех стандартных средств работы с DOM.
Подключения обработчика проходит в два этапа:
  1. Объявление функции-обработчика
  2. Добавление парсера путём вызова метода addDOMHandler() глобального объекта oBXEditorUtils

Объявление функции-обработчика

Функция-обработчик должна быть объявлена в области видимости вызова метода oBXEditorUtils.DOMHandler(). Объявленной функции передается единственный аргумент - объект document, соответствующий узлу document согласно структуре DOM. В теле функции происходит обработка документа. Возвращаемые значения не учитываются.

Добавление обработчика

Осуществляется путём вызова метода addDOMHandler() глобального объекта oBXEditorUtils

Пример

<script>

function CustomDOMHandler(oDocument)
{
    //... манипуляции с документом
}

//Добавление парсера
oBXEditorUtils.addDOMHandler(CustomDOMHandler);

</script>


addPropertyBarHandler

Объект oBXEditorUtils

  • oBXEditorUtils::PHPParser
  • addContentParser
  • addDOMHandler
  • addPHPParser
  • addPropertyBarHandler
  • addTaskBar
  • BXRemoveAllChild
  • getCustomNodeParams
  • setCustomNodeParams
  • Глобальный объект oBXEditorUtils


Глобальный объект oBXEditorUtils

Для эффективного решения задач взаимодействия с API визуального редактора предусмотрен глобальный объект oBXEditorUtils. Этот объект и его подобъекты обладают рядом свойств и методов, позволяющих использовать существующий предоставляемый функционал API редактора. Задачи и параметры, привязанные к определённым структурным единицам редактора, могут быть реализованны в виде методов и свойств класса-родителя или методов других глобальных объектов API визуального редактора.

Методы

Метод | Описание
addContentParser | Добавляет функцию-обработчик для обработки содержимого документа в виде исходного кода.
addPHPParser | Добавляет функцию-обработчик для обработки всех фрагментов PHP из исходного кода документа.
addDOMHandler | Добавляет функцию-обработчик для обработки содержимого документа как DOM-структуры.
addPropertyBarHandler | Добавляет обработчик, который вызывается при формировании панели свойств для элемента с определённым именем тега
addTaskBar | Добавляет панель управления
BXRemoveAllChild | Удаляет дочерние узлы элемента
getCustomNodeParams | Возвращает массив параметров "искуственных" элементов, заменяющих определённые фрагменты кода в визуальном режиме
setCustomNodeParams | Записывает массив параметров "искуственных" элементов, заменяющих определённые фрагменты кода в визуальном режиме

Подобъекты

Подобъект | Описание
PHPParser | Добавляет функцию-обработчик для обработки содержимого документа в виде исходного кода.


addTaskBar

Используется для добавления пользовательской панели задач в визуальный редактор.
Требует предварительного объявления класса пользовательской панели задач.(см. Добавление панелей задач)

void
oBXEditorUtils.addTaskBar(
 string className,
 int taskbarSetPos,
 string taskbarTitle,
 array params
);

Параметры:
Параметр | Описание
className | Имя класса панели задач.
taskbarSetPos Параметр, определяющий положение панели задач, относительно области редактирования:
0 | Вверху, над областью редактирования
1 | Слева от области редактирования
2 | Справа от области редактирования
3 | Внизу, под областью редактирования
taskbarTitle | Название панели задач, отображается в заголовке.
params | Дополнительные параметры

Пример добавления панели задач в редактор

<script>

function CustomTaskbar()
{
    var oTaskbar = this;

    CustomTaskbar.prototype.OnTaskbarCreate = function ()
    {
        //...
    }

    CustomTaskbar.prototype.UnParseElement = function(node)
    {
        //...
    }

    CustomTaskbar.prototype.OnElementDragEnd = function(oEl)
    {
        //...
    }
}

//Добавление панели задач
oBXEditorUtils.addTaskBar('CustomTaskbar',2,"Help",[]);

</script>


BXRemoveAllChild

Удаляет все дочерние узлы элемента, передаваемого в качестве единственного параметра pNode.

void
oBXEditorUtils.BXRemoveAllChild(
 object pNode
);

Параметры:
Параметр | Описание
pNode | Узел DOM структуры документа.

Пример использования

<script>

var oTable = document.getElementById('tableId');
oBXEditorUtils.BXRemoveAllChild(oTable); //Удаляет дочерние узлы таблицы с id='tableId'

</script>


getCustomNodeParams

Возвращает параметры "искуственного" элемента* в виде массива, заменяющего некоторый фрагмент кода в документе. Используется при обработке свойств элементов при объявлении класса пользовательской панели задач.(см. Добавление панелей задач).

*В визуальном режиме некоторые фрагменты кода или другие элементы заменяются на их визуальное представление - иконки (пиктограммы). Свойства таких элементов хранятся в сериализованном виде в качестве атрибута этого элемента. Данный метод десериализует свойства и возвращает их в виде массива.
array
oBXEditorUtils.getCustomNodeParams(
 object pNode
);

Параметры:

Параметр | Описание
pNode | Узел DOM структуры документа или объект BXNodeElement, передаваемый методу UnParseElement() при описании класса пользовательской панели задач (см. Добавление панелей задач).

Возвращаемое значение

Возвращает массив. Структура массива, а также его тип (ассоциативный/неассоциативный) зависит от свойств, заданных элементу при создании или в ходе работы с ним.

Пример использования

<script>

function CustomTaskbar()
{
    var oTaskbar = this;

    CustomTaskbar.prototype.OnTaskbarCreate = function ()
    {
        //...
    }

    CustomTaskbar.prototype.ShowProperties = function(_bNew, _pTaskbar, _pElement)
    {
        //...
        var arParams = oBXEditorUtils.getCustomNodeParams(_pElement);//Возвращает массив свойств
        //...
    }

    CustomTaskbar.prototype.UnParseElement = function(node)
    {
        //...
        var arParams = oBXEditorUtils.getCustomNodeParams(node);//Возвращает массив свойств
        //...
        return false;
    }
}

</script>
См. также oBXEditorUtils.setCustomNodeParams()


setCustomNodeParams

Устанавливает свойства "искуственного" элемента*, переданные в виде массива параметров. Используется при обработке свойств элементов при объявлении класса пользовательской панели задач. (см. Добавление панелей задач).

*В визуальном режиме некоторые фрагменты кода или другие элементы заменяются на их визуальное представление - иконки (пиктограммы). Свойства таких элементов хранятся в сериализованном виде в качестве атрибута этого элемента. Данный метод сериализует массив свойств и сохраняет их.
void
oBXEditorUtils.setCustomNodeParams(
  object pNode
  array arParams
);

Параметры:

Параметр | Описание
pNode | Узел DOM структуры документа или объект BXNodeElement, передаваемый методу UnParseElement() при описании класса пользовательской панели задач (см. Добавление панелей задач).
arParams | Массив свойств. Допускаются ассоциативные и вложенные массивы.

Возвращаемое значение

Ничего не возвращает.

Пример использования

<script>

function CustomTaskbar()
{
    var oTaskbar = this;

    CustomTaskbar.prototype.OnTaskbarCreate = function ()
    {
        //...
    }

    CustomTaskbar.prototype.ShowProperties = function(_bNew, _pTaskbar, _pElement)
    {
        //...
        var _arParams = oBXEditorUtils.getCustomNodeParams(_pElement);//Возвращает массив свойств
        _arParams['value'] = 'new value';
        //...
        oBXEditorUtils.setCustomNodeParams(_pElement,_arParams);//Устанавливает массив свойств
        //...
    }

    CustomTaskbar.prototype.UnParseElement = function(node)
    {
        //...
        var arParams = oBXEditorUtils.getCustomNodeParams(node);//Возвращает массив свойств
        //...
        arParams['property'] = 'new property';
        //...
        oBXEditorUtils.setCustomNodeParams(node,arParams);//Устанавливает массив свойств
        //...
        return false;
    }
}

</script>
См. также oBXEditorUtils.getCustomNodeParams()


addContentParser

Добавляет функцию-обработчик для обработки содержимого документа в виде исходного кода.
Функция, добавленная таким образом, будет обрабатывать содержимое редактируемого документа при его загрузке, а также при переключении из режима кода, в WYSIWYG.

void
oBXEditorUtils.addContentParser(
   function handler
);

Параметры

Параметр | Описание
handler | Функция, объявленная в глобальной области видимости. В качестве единственного параметра принимает строку, содержащую содержимое контента. Должна вернуть строку (контент с внесёнными в него изменениями) или false. В случае если возвращается false, изменения в код не вносятся.


addDOMHandler

Добавляет функцию-обработчик для обработки содержимого документа как DOM-структуры. Функции, добавленные таким образом, могут обращаться к узлам редактируемого документа(в визуальном режиме), при загрузке редактируемого документа, а также при переключении из режима кода, в WYSIWYG.
Обрабатывают документ после его обработки функциями, добавленными при помощи методов addContentParser и addPHPParser.

void
oBXEditorUtils.addDOMHandler(
   function handler[,
   int orderInd]
);

Параметры

Параметр | Описание
handler | Функция, объявленная в глобальной области видимости. В качестве единственного параметра принимает ссылку на объект document редактируемого документа. Ничего не возвращает.

Пример

function myDOMHandler(oDocument)
{
    //манипуляции с документом
    var arIMG = oDocument.getElementsByTagName('IMG');
    var iLen = arIMG.length;
    for (var i=0;i>iLen;i++)
        arIMG[i].src = 'my_new_image.jpg';
}
//Добавление обработчика
oBXEditorUtils.addDOMHandler(myDOMHandler);
Данный обработчик позволяет заменить аттрибут src всех рисунков в документе на my_new_image.jpg (оставляя при этом остальные аттрибуты нетронутыми)


addPHPParser

Добавляет функцию-обработчик всех фрагментов PHP в исходном коде редактируемого документа. Функции, добавленные таким образом, будут обрабатывать фрагменты PHP кода до замены его на стандартную иконку PHP кода, при загрузке редактируемого документа, а также при переключении из режима кода, в WYSIWYG.

void
oBXEditorUtils.addPHPParser(
   function handler[,
   int orderInd]
);

Параметры

Параметр | Описание
handler | Функция, объявленная в глобальной области видимости. В качестве единственного параметра принимает строку (содержимое php-кода). Должна вернуть строку (контент с внесёнными в него изменениями) или false. В случае если возвращается false, изменения в код не вносятся. Кроме того, следует обратить внимание на то, что на обработку функции передается весь код php-фрагмента, включая открывающие и закрывающие теги.
orderInd | Позиция парсера при обработке. Необязательный параметр. По умолчанию, парсеры обрабатывают код в порядке, соответствующему очередности их подключения. Передав в orderInd, например, 0, можно добиться того, что этот обработчик будет обрабатывать код в 1-ю очередь. Но, если в последствии будет зарегестрирован ещё обработчик с orderInd=0, то он будет выполняться раньше.

Пример добавления PHP-парсера

function myPHPParser(str)
{
    //Если фрагмент PHP равен <?MyPHPFunction();?>, он заменяется на иконку
    if (str=='<?MyPHPFunction();?>')
        return '<img src="icon.gif" title="Image Title" __bxtagname="customtag">';
    return false;
}
//Добавление парсера
oBXEditorUtils.addPHPParser(myPHPParser);


addPropertyBarHandler

Добавляет обработчик handler, который будет вызываться при формировании панели свойств для элемента с именем тега tagname.
Вызов ("подсветка") панели свойств для элемента происходит автоматически при клике по нему или сразу после вставки элемента, если он вставляется из пользовательской панели задач. В качестве второго параметра методу передается функция или метод, формирующая, при необходимости, информационные параметры элемента, а также реализует возможность их редактирования. Использование в качестве параметра handler анонимных функций нежелательно.

void
oBXEditorUtils.addPropertyBarHandler(
 string tagname,
 function handler
);

Параметры:
Параметр | Описание
tagname | Имя тега, элемента
handler Функция или метод обработки события инициализации панели свойств.
Данной функции при инициализации передается три параметра:
Параметр | Описание
bool bNew | Равен true, если до этого в панели свойств отображались свойства элемента с таким же именем тега, false, если отображались свойства элемента с другим именем тега. Может использоваться для ускорения процедуры показа свойств: если подряд вызывается процедура показа свойств однотипного элемента, то при повторном показе, элементы управления можно не создавать заново, а только заполнять новыми данными.
object pTaskbar | Ссылка на объект панели свойств. Используется для формирования в ней визуального отображения свойств элемента. Важное свойство, которое может использоваться непосредственно для присоединения элементов управления и отображения: pCellProps - объект node DOM, является контейнером прокручиваемой области панели свойств.
object pElement | Ссылка на выделенный элемент. Для считывания/изменения свойств элемента можно использовать методы getCustomNodeParams() и setCustomNodeParams() глобального объекта oBXEditorUtils.

Пример добавления обработчика для панели свойств

<script>
function CustomTaskbar()
{
    var oTaskbar = this;

    CustomTaskbar.prototype.OnTaskbarCreate = function ()
    {
        //...
        //Добавление обработчика панели свойств для элемента "_customtag"
        oBXEditorUtils.addPropertyBarHandler('_customtag',this.ShowProperties);
        //...
    }

    //...

    CustomTaskbar.prototype.ShowProperties = function(_bNew, _pTaskbar, _pElement)
    {
        // _pTaskbar.pCellProps - прокручиваемая область панели свойств
        //Считывание свойств элемента
        var arParams = oBXEditorUtils.getCustomNodeParams(_pElement);
        //...
        // операции над свойствами, отображение, изменение
        //...
        //Сохранение свойств элемента
        oBXEditorUtils.setCustomNodeParams(_pElement,arParams);
    }
}
</script>


Вложенный объект oBXEditorUtils.PHPParser

Вложенный объект PHPParser глобального объекта oBXEditorUtils объединяет методы, используемые для облегчения создания PHP-парсера (см. oBXEditorUtils.addPHPParser())

Методы

Метод | Описание
cleanCode | Удаляет из PHP-кода комментарии, переводы новой строки, незначащие пробелы.
getArray | Принимает в качестве аргумента строку, в формате Array([параметры]) Возвращает массив этих параметров или пустой массив при их отсутствии. Обрабатывает также ассоциативные и вложенные массивы.
getParams | Обрабатывает строку с перечисленными через запятую параметрами, и возвращает их в виде массива. НЕ ОБРАБАТЫВАЕТ массивы в качестве параметров.
parseFunction | Обрабатывает строку, содержащую вызов php-функции, и возвращает имя функции и строку с передаваемыми ей параметрами.
parseParameters | Обрабатывает строку с перечисленными через запятую параметрами, и возвращает их в виде массива. Обрабатывает массивы в качестве параметров.
trimPHPTags | Возвращает переданный в качестве параметра фрагмент кода (без php-тегов <?php ... ?> или <? ... ?>).
trimQuotes | Возвращает переданный в качестве параметра фрагмент кода без двойные или одинарных кавычек(или другого символа) с начала и конца.


cleanCode

Удаляет из PHP-кода комментарии, переводы новой строки, незначащие пробелы. Может использоваться для упрощения анализа фрагмента PHP-кода при создании PHP-парсера.

string
oBXEditorUtils.PHPParser.cleanCode(
 string sCode
);

Параметры:

Параметр | Описание
sCode | Строка, содержащая фрагмент php-кода.

Возвращаемое значение

Возвращает строку.

Пример использования

<script>

var sCode = '$arFields   =   array('+
       '"LID" => "en", //язык'+
       '"TEXT" => "text text text", //текст'+
       '"PAYED" => "N",'+
       '"CANCELED" => "N"'+
       ');'

sCode = oBXEditorUtils.PHPParser.cleanCode(sCode);
//sCode = '$arFields=array("LID"=>"en","TEXT"=>"text text text","PAYED"=>"N","CANCELED"=>"N")';

</script>


getArray

Принимает в качестве аргумента строку, в формате Array([параметры]). Возвращает массив параметров, переданных в строке, или пустой массив, при отсутствии параметров. Корректно обрабатывает вложенные и ассоциативные массивы, возвращая соответсвующую структуру. Может использоваться для упрощения анализа фрагмента PHP-кода при создании PHP-парсера.

array
oBXEditorUtils.PHPParser.getArray(
 string sCode
);

Параметры:

Параметр | Описание
sCode | Строка, в формате Array([параметры])

Возвращаемое значение

Возвращает массив. Структура массива зависит от входного параметра.

Пример использования

<script>

var sCode = 'array("LID"=>"en","TEXT"=>"text text text","PAYED"=>"N","CANCELED"=>"N")';

arParams = oBXEditorUtils.PHPParser.getArray(sCode);
//arParams["LID"] = "en";
//arParams["TEXT"] = "text text text";
//arParams["PAYED"] = "N";
//arParams["CANCELED"] ="N";

</script>


getParams

Принимает в качестве аргумента строку, содержащую параметры (функции, или любые другие данные), перечисленные через запятую, и возвращает массив строковых значений.
НЕ ОБРАБАТЫВАЕТ массивы, т.е. все данные воспринимаются как строки.
Может использоваться для упрощения анализа фрагментов PHP-кода при создании PHP-парсера.

array
oBXEditorUtils.PHPParser.getParams(
 string sCode
);

Параметры:

Параметр | Описание
sCode | Строка, в формате param1[,param2[,...,paramN]]

Возвращаемое значение

Возвращает массив строковых значений.

Пример использования

<script>

var sCode1 = '2,"text text text",5,"N"';
var sCode2 = 'array("LID"=>"en","TEXT"=>"text text text","PAYED"=>"N","CANCELED"=>"N")';

arParams1 = oBXEditorUtils.PHPParser.getArray(sCode1);
//arParams[0] = '2';
//arParams[1] = '"text text text"';
//arParams[2] = '5';
//arParams[3] = '"N"';

arParams2 = oBXEditorUtils.PHPParser.getArray(sCode2);
//arParams[0] = 'array("LID"=>"en"';
//arParams[1] = '"TEXT"=>"text text text"';
//arParams[2] = '"PAYED"=>"N"';
//arParams[3] = '"CANCELED"=>"N")';

</script>
См. также parseParameters


parseFunction

Принимает в качестве аргумента строку, содержащую вызов php-функции в формате MyFunction([params]), и возвращает имя функции и строку с передаваемыми ей параметрами.
Может использоваться для упрощения анализа фрагментов PHP-кода при создании PHP-парсера.

object
oBXEditorUtils.PHPParser.parseFunction(
 string sCode
);

Параметры:

Параметр | Описание
sCode | Строка, в формате MyFunction([params])

Возвращаемое значение

Возвращает объект
Свойства:
Свойство | Описание
string name | Имя функции
string params | Строка, содержащая параметры передаваемые функции при вызове
Если строка не соответствует указанному формату, возвращается значение false.

Пример использования

<script>

var sCode = 'MyPHPFunction("param",$var)';

var oFunc = oBXEditorUtils.PHPParser.parseFunction(sCode);
//oFunc.name = 'MyPHPFunction';
//oFunc.params = '"param",$var';

</script>
См. также parseParameters


parseParameters

Принимает в качестве аргумента строку, содержащую параметры (функции), перечисленные через запятую; и возвращает массив, соответствующий по структуре массиву, переданному в качестве параметра.
Корректно обрабатывает массивы, в том числе ассоциативные и вложенные.
Может использоваться для обработки параметров средствами JavaScript при упрощении анализа фрагментов PHP-кода при создании PHP-парсера.

array
oBXEditorUtils.PHPParser.parseParameters(
 string sCode
);

Параметры:

Параметр | Описание
sCode | Строка, в формате param1[,param2[,...,paramN]]

Возвращаемое значение

Возвращает массив.

Пример использования

<script>

var sCode = '2,"Y",Array(1,2,"string1"),Array("name"=>"SomeName","id"=>$phpVar)';

arParams = oBXEditorUtils.PHPParser.parseParameters(sCode);
//arParams[0] = 2;
//arParams[1] = "Y";
//arParams[2][0] = 1;
//arParams[2][1] = 2;
//arParams[2][2] = "string";
//arParams[3]["name"] = "SomeName";
//arParams[3]["id"] = "$phpVar";

</script>
См. также getParams, parseParameters, parseFunction


trimPHPTags

Возвращает переданный в качестве параметра фрагмент кода без php-тегов <?php ?> или <? ?> Если фрагмент не содержит PHP-тегов, строка возвращается без изменений.
Может использоваться для упрощения анализа фрагментов PHP-кода при создании PHP-парсера.

string
oBXEditorUtils.PHPParser.trimPHPTags(
 string sCode
);

Параметры:

Параметр | Описание
sCode | Строка, фрагмент PHP-кода

Возвращаемое значение

Возвращает строку.

Пример использования

<script>

var sCode = '<?php MyPHPFunction(); ?>';

sCode = oBXEditorUtils.PHPParser.trimPHPTags(sCode);//sCode = ' MyPHPFunction(); ';

</script>
См. также trimQuotes


trimQuotes

Возвращает переданный в качестве параметра фрагмент кода без двойных или одинарных кавычек(или другого символа) с начала и конца. Если фрагмент не содержит кавычек, он возвращается без изменений.

Может использоваться для упрощения анализа фрагментов PHP-кода при создании PHP-парсера.

string
oBXEditorUtils.PHPParser.trimQuotes(
 string sCode[,
 string cSym]
);

Параметры:

Параметр | Описание
sCode | Строка, фрагмент PHP-кода
cSym | Необязательный параметр. Символ, который необходимо удалить. По умолчанию удаляются одинарные или двойные кавычки.

Возвращаемое значение

Возвращает строку.

Пример использования

<script>

var sCode1 = '"My String"';
sCode1 = oBXEditorUtils.PHPParser.trimQuotes(sCode1);//sCode1 = 'My String';

var sCode2 = "'My String'";
sCode2 = oBXEditorUtils.PHPParser.trimQuotes(sCode2);//sCode2 = "My String";

var sCode3 = '-My String-';
sCode3 = oBXEditorUtils.PHPParser.trimQuotes(sCode3,'-');//sCode3 = 'My String';

</script>
См. также trimPHPTags


Список событий

Ниже представлен список событий модуля "Управления структурой". Для регистрации обработчика укажите в качестве идентификатора модуля - "fileman".

События, связанные с визуальным HTML-редактором

Событие | Описание
OnBeforeHTMLEditorScriptsGet | Вызывается непосредственно перед подключением внешних JavaScript-файлов редактора. Позволяет добавить в список подключаемых файлов дополнительный JavaScript файл или файл стилей.
OnIncludeHTMLEditorScript | Вызывается непосредственно после подключения редактора, на странице вызова, но до его инициализации.

См. также

  • Обработка событий
  • Взаимодействие модулей


OnBeforeHTMLEditorScriptsGet

array функция-обработчик(
 string editorName
 array arEditorParams
);
Событие "OnBeforeHTMLEditorScriptsGet" вызывается перед загрузкой JavaScript и CSS файлов редактора и позволяет добавить пользовательские файлы, которые будут подгружаться после файлов визуального редактора. Создание обработчика данного представляет собой простейший способ модифицировать встроенный визуальный редактор путём расширения или переопределения текущего функционала.

Параметры

Параметр | Описание
editorName | Имя подключаемого редактора.
arEditorParams | Массив параметров подключаемого редактора.

Структура результата

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

Файлы, имена которых возвращаются в качестве элементов массивов в полях "JS" и "CSS" должны находиться в папке /bitrix/admin/htmleditor2

См. также

  • Событие "OnIncludeHTMLEditorScript"

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("fileman", "OnBeforeHTMLEditorScriptsGet", "addEditorScriptsHandler");
function addEditorScriptsHandler($editorName,$arEditorParams)
{
    // Проверяем, если подключается редактор для редактирования статических страниц
    if ($editor_name == 'filesrc')
        return array(
            "JS" => array('my_scripts.js'),
            "CSS" => array('my_styles.css')
        );

    return array();
}
?>

<?
// файл /bitrix/admin/htmleditor2/my_scripts.js
// Переопределяем стандартную панель инструментов, удаляя из нее кнопки "Настройки", "Выделить все" и "Проверка орфографии"
arToolbars['standart'] = [
    BX_MESS.TBSStandart,
        [
        arButtons['Fullscreen'], 'separator',
        arButtons['Cut'], arButtons['Copy'], arButtons['Paste'], arButtons['pasteword'], arButtons['pastetext'], arButtons['separator'],
        arButtons['Undo'], arButtons['Redo'], arButtons['separator'],
        arButtons['borders'], 'separator',
        arButtons['table'], arButtons['anchor'], arButtons['CreateLink'], arButtons['deletelink'], arButtons['image'], 'separator',
        arButtons['SpecialChar'], arButtons['spellcheck']
        ]
    ];
?>

/* файл /bitrix/admin/htmleditor2/my_styles.css
переопределяем цвет фона редактора (только для Mozilla Firefox) */
.bxedmainframe IFRAME{
    background-color: #CCCCCC;
}


OnIncludeHTMLEditorScript

функция-обработчик();
Событие "OnIncludeHTMLEditorScript" вызывается после подключения файлов визуального редактора. Может использоваться в тех случаях, когда для модификации редактора недостаточно стандартного подключения внешних JavaScript файлов (Событие "OnBeforeHTMLEditorScriptsGet").

См. также

  • Событие "OnBeforeHTMLEditorScriptsGet"

Пример функции-обработчика:

<?
// файл /bitrix/php_interface/init.php
// регистрируем обработчик
AddEventHandler("fileman", "OnIncludeHTMLEditorScript", "OnIncludeHTMLEditorHandler");
function OnIncludeHTMLEditorHandler()
{
    ?>
    <script>
    //Переопределение функции установки полноэкранного режима редактора
    BXHTMLEditor.prototype.SetFullscreen_ = BXHTMLEditor.prototype.SetFullscreen;
    BXHTMLEditor.prototype.SetFullscreen = function (bFull)
    {
        alert('My alert!');
        this.SetFullscreen_(bFull);
    }
    </script>
    <?
}
?>


Для разработчиков

Перед использованием модуля необходимо проверить установлен ли он и подключить его при помощи конструкции:

<?
if(CModule::IncludeModule("forum"))
{
   //здесь можно использовать функции модуля
}
?>

Публичная часть форума строится на высокоуровневых функциях и классах ядра форума.


Классы модуля форума

Следующие PHP классы используются в модуле форума.

Классы

Класс | Описание
CForumNew | Класс для работы с форумами.
CForumTopic | Класс для работы с темами форумов.
CForumPoints | Класс для работы со званиями (статусами) форума.
CForumPoints2Post | Класс для работы с картой соответствий между количеством сообщений пользователя на форуме и количеством баллов, которое пользователь получает за одно сообщение.
CForumUserPoints | Класс для работы с голосованиями пользователей.
CForumUser | Класс для работы с профайлами посетителей форума.
CFilterDictionary | Класс для работы cо словарями нецензурных слов.
CFilterLetter | Класс для работы cо словарями букв.
CFilterUnquotableWords | Класс для работы cо словарями cлов.
CForumPMFolder | Класс для работы папками пользователя.
CForumPrivateMessage | Класс для работы с приватными сообщениями.


Структура таблиц модуля форумов

Группы форумов

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID группы форумов. Уникален. | Int | Да |
SORT | Индекс сортировки. | Int | Да | 150

Сайтозависимые параметры групп форумов

Поле | Описание | Тип | Обяз. | Умолч.
FORUM_GROUP_ID | ID группы форумов | Int | Да |
LID | Код сайта | Char(2) | Да |
NAME | Название группы форумов | String(255) | Да |
DESCRIPTION | Описание группы форумов | String(255) | Нет |

Форумы

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID форума. Уникален. | Int | Да |
NAME | Название форума | String(128) | Да |
DESCRIPTION | Описание форума | String(255) | Нет |
SORT | Индекс сортировки | Int | Да | 150
ACTIVE | Активность форума (Y|N) | Char(1) | Да | Y
ALLOW_HTML | Разрешить вводить в качестве сообщения произвольный HTML (Y|N) | Char(1) | Да | N
ALLOW_NL2BR | Преобразовывать переводы каретки в тег <br> в режиме HTML (Y|N) | Char(1) | Да | N
ALLOW_ANCHOR | Разрешить использовать в сообщениях тег <a> / [a] (Y|N) | Char(1) | Да | Y
ALLOW_BIU | Разрешить использовать в сообщениях теги <b> / [b], <i> / [i], <u> / [u] (Y|N) | Char(1) | Да | Y
ALLOW_IMG | Разрешить использовать в сообщениях тег <img> / [img] (Y|N) | Char(1) | Да | Y
ALLOW_LIST | Разрешить использовать в сообщениях тег списка <ul> / [list] (Y|N) | Char(1) | Да | Y
ALLOW_QUOTE | Разрешить использовать в сообщениях тег цитирования <quote> / [quote] (Y|N) | Char(1) | Да | Y
ALLOW_CODE | Разрешить использовать в сообщениях тег кода <code> / [code] (Y|N) | Char(1) | Да | Y
ALLOW_FONT | Разрешить использовать в сообщениях тег <font> / [color], [font] (Y|N) | Char(1) | Да | Y
ALLOW_SMILES | Разрешить использовать в сообщениях смайлики в виде изображений (Y|N) | Char(1) | Да | Y
ALLOW_UPLOAD | Разрешить загрузку файлов, привязанных с сообщениям форума. Возможные значения: N - загрузка запрещена, Y - только файлы изображений, F - файлы с заданными в поле ALLOW_UPLOAD_EXT расширениями, A - любые файлы. | Char(1) | Да | N
MODERATION | Премодерируемость форума (Y|N) | Char(1) | Да | N
ORDER_BY | Сортировка "по умолчанию" тем форума в списке тем. Возможные значения: T - заголовок темы, N - количество сообщений в теме, A - автор темы, V - количество просмотров темы, D - дата создания темы, P - дата последнего сообщения в теме. | Char(1) | Да | P
ORDER_DIRECTION | Направление сортировки "по умолчанию" тем форума в списке тем. Возможные значения: ASC - прямой порядок, DESC - обратный порядок. | Char(4) | Да | DESC
TOPICS | Количество опубликованых тем в форуме. | Int | Да | 0
POSTS | Количество опубликованых сообщений в форуме. | Int | Да | 0
LAST_POSTER_ID | Код автора (код пользователя) последнего сообщения на форуме. | Int | Нет |
LAST_POSTER_NAME | Имя автора последнего сообщения на форуме. | String(64) | Нет |
LAST_POST_DATE | Дата последнего сообщения на форуме. | DateTime | Нет |
LAST_MESSAGE_ID | ID последнего сообщения на форуме. | Int | Нет |
ALLOW_UPLOAD_EXT | Список разделенных запятой расширений файлов, которые разрешены к загрузке. Применяется, если в поле ALLOW_UPLOAD стоит значение F. | String(255) | Нет |
FORUM_GROUP_ID | Код группы, к которой принадлежит форум. | Int | Нет |
ASK_GUEST_EMAIL | Спрашивать Email у незарегистрированого пользователя при написании сообщения (Y/N) | Char(1) | Нет | N

Связь форума с сайтами

Поле | Описание | Тип | Обяз. | Умолч.
FORUM_ID | ID форума. | Int | Да |
SITE_ID | Код сайта. | Char(2) | Да |
PATH2FORUM_MESSAGE | Шаблон пути к сообщению на форуме. Может содержать подстроки #FORUM_ID#, #TOPIC_ID# и #MESSAGE_ID#, которые должны быть заменены на реальные код форума, код темы и код сообщения. | varchar(250) | Нет |

Темы форума

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID темы форума. Уникален. | Int | Да |
TITLE | Заголовок темы | String(70) | Да |
DESCRIPTION | Описание темы. | String(70) | Нет |
STATE | Состояние темы: открыта или закрыта (Y|N). | Char(1) | Да | Y
USER_START_ID | Код автора темы. | Int | Нет |
USER_START_NAME | Имя автора темы. | String(64) | Да |
START_DATE | Дата создание темы. | DateTime | Да |
ICON_ID | Код иконки темы. | Int | Нет |
POSTS | Количество ответов на тему. | Int | Да | 0
VIEWS | Количество просмотров темы. | Int | Да | 0
FORUM_ID | ID форума, которому принадлежит тема. | Int | Да |
APPROVED | Опубликована ли тема (Y|N). Тема опубликована, если опубликовано хотя бы одно сообщение в ней. | Char(1) | Да | Y
SORT | Индекс сортировки темы | Int | Да | 150
LAST_POSTER_ID | Код автора последнего сообщения в теме. | Int | Нет |
LAST_POSTER_NAME | Имя автора последнего сообщения в теме. | String(64) | Да |
LAST_POST_DATE | Дата последнего сообщения в теме. | DateTime | Да |
LAST_MESSAGE_ID | ID последнего сообщения в теме | Int | Да |

Сообщения

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID сообщения. Уникальное. | Int | Да |
AUTHOR_ID | Код автора сообщения. | Int | Нет |
AUTHOR_NAME | Имя автора сообщения. | String(128) | Да |
AUTHOR_IP | IP автора сообщения | String(128) | Нет |
USE_SMILES | Пользователь хочет, чтобы смайлики заменялись графическими изображениями (Y|N). | Char(1) | Да | Y
POST_DATE | Дата создания сообщения. | Datetime | Да |
POST_MESSAGE | Текст сообщения. | Text | Да |
FORUM_ID | ID форума, которому принадлежит сообщение. | Int | Да |
TOPIC_ID | ID темы, которой принадлежит сообщение. | Int | Да |
APPROVED | Сообщение опубликовано (Y|N) | Char(1) | Да | Y
GUEST_ID | Код посетителя | Int | Нет |
AUTHOR_REAL_IP | Реальный IP автора сообщения. | Int | Нет |
ATTACH_IMG | Присоедененный файл. | Int | Нет |

Профайл посетителя форума

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID профайла. Уникален. | Int | Да |
USER_ID | ID пользователя. Уникален. | Int | Да |
DESCRIPTION | Описание посетителя. | String(64) | Нет |
IP_ADDRESS | IP адрес, с которого было отправлено последнее сообщение. | String(128) | Да |
AVATAR | Аватар посетителя. | Int | Нет |
NUM_POSTS | Количество сообщений посетителя на форуме. | Int | Да | 0
INTERESTS | Интересы посетителя (произвольная текстовая информация). | Text | Нет |
LAST_POST | Код последнего сообщения постетителя. | Int | Нет |
ALLOW_POST | Посетитель может писать сообщения (т.е. не забанен). | Char(1) | Да | Y
LAST_VISIT | Дата последнего посещения форума | DateTime | Да |
DATE_REG | Дата регистрации на форуме | DateTime | Да |
REAL_IP_ADDRESS | Настоящий IP адрес, с которого было написано последнее сообщение. | String(128) | Нет |
SIGNATURE | Подпись посетителя. | String(255) | Нет |
SHOW_NAME | Показывать имя и фамилию вместо логина (Y|N) | Char(1) | Да | Y
HIDE_FROM_ONLINE | Не показывать пользователя в списке "Кто сейчас на сайте" (Y/N) | Char(1) | Нет | N
POINTS | Текущее количество баллов пользователя | Int | Нет | 0

Звания (статусы) посетителей

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID звания. Уникален. |  | Да |
MIN_POINTS | Количество баллов, которое необходимо иметь для получения этого звания. | Int | Да | 0
CODE | Мнемонический код звания. | varchar(100) | Нет |
VOTES | Количество голосов, которое пользователь в этом звании может отдать за другого пользователя | Int | Да | 0

Языковые параметры званий

Поле | Описание | Тип | Обяз. | Умолч.
POINTS_ID | ID звания | Int | Да |
LID | Код языка параметров | Char(2) | Да |
NAME | Название звания | String(250) | Да |

Карта соответствий между количеством сообщений пользователя на форуме и количеством баллов за сообщение

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID записи. Первичный ключ. | Int | Да |
MIN_NUM_POSTS | Количество сообщений, которое нужно написать для получения этого количества баллов за сообщение. | Int | Да | 0
POINTS_PER_POST | Количество баллов за сообщение. Может быть дробным числом (0.1 - балл дается за 10 сообщений) | decimal(18, 4) | Да | 0

Смайлы и иконки

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID смайла. Уникален. |  | Да |
TYPE | Тип: S - смайл, I - иконка. | Char(2) | Да | S
TYPING | Варианты написания смайлов, перечисленные через пробел. | String(100) | Да |
IMAGE | Название файла изображения. | String(128) | Да |
SORT | Индекс сортировки. | Int | Да | 150
IMAGE_WIDTH | Ширина изображения. | Int | Да | 0
IMAGE_HEIGHT | Высота изображения. | Int | Да | 0

Языковые параметры смайлов

Поле | Описание | Тип | Обяз. | Умолч.
SMILE_ID | ID смайла | Int | Да |
LID | Код языка параметров | Char(2) | Да |
NAME | Название смайла | String(255) | Да |

Подписка

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID подписки | Int | Да |
USER_ID | ID подписанного пользователя | Int | Да |
FORUM_ID | Форум, на сообщения которого подписан | Int | Да |
TOPIC_ID | Тема, на сообщения которой подписан | Int | Нет |
START_DATE | Дата подписки | DateTime | Да |
LAST_SEND | ID последнего отправленного сообщения | Int | Нет |
NEW_TOPIC_ONLY | Подписка только на новые темы (Y/N) | Char(1) | Да | N
SITE_ID | ID сайта, на котором произведена подписка | Char(2) | Да | ru

Приватные сообщения

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID сообщения. Уникален. | Int | Да |
AUTHOR_ID | ID автора сообщения. | Int | Да |
USER_ID | ID получателя сообщения. | Int | Да |
FOLDER_ID | ID папки пользователя. | Int | Да |
IS_READ | Метка о прочтении. | Int | Да |
USE_SMILES | Заменять смайлики графическими изображениями (Y|N). | Int | Да |
POST_DATE | Дата создания сообщения. | DateTime | Да |
POST_SUBJ | Тема сообщения. | String(255) | Нет |
POST_MESSAGE | Текст сообщения. | Text | Нет |

Папки пользователя

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID папки. Уникален. | Int | Да |
TITLE | ID автора сообщения. | String(50) | Да |
USER_ID | ID владельца папки. | Int | Да |

Словари

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID записи. Уникален. | Int | Да |
TITLE | Имя словаря. | String(50) | Да |
TYPE | Тип словаря. | Char | Да |

Словарь букв

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID записи. Уникален. | Int | Да |
DICTIONARY_ID | ID словаря. | Int | Да |
LETTER | Буква. | String(50) | Да |
REPLACEMENT | Замена. | String(50) | Да |

Словарь слов

Поле | Описание | Тип | Обяз. | Умолч.
ID | ID записи. Уникален. | Int | Да |
DICTIONARY_ID | ID словаря. | Int | Да |
WORDS | Слово. | String(255) | Нет |
PATTERN | Шаблон. | String(255) | Нет |
REPLACEMENT | Замена. | String(255) | Нет |
DESCRIPTION | Описание. | Text | Нет |
REPLACEMENT | Замена. | String(50) | Да |
USE_IT | Задействован (Y|N). | Char | Да |


Структура таблиц модуля форумов

Классы

  • CFilterDictionary
  • CFilterLetter
  • CFilterUnquotableWords
  • CForumGroup
  • CForumMessage
  • CForumNew
  • CForumPMFolder
  • CForumPoints
  • CForumPoints2Post
  • CForumPrivateMessage
  • CForumSmile
  • CForumSubscribe
  • CForumTopic
  • CForumUser
  • CForumUserPoints
  • textparser


Класс CFilterDictionary

CFilterDictionary - класс для работы cо словарями нецензурных слов.

Методы класса

Метод | Описание
Add | Создание нового словаря.
Delete | Удаление словаря.
GetList | Получение списка словарей с возможностью фильтрации и сортировки.
Update | Изменение параметров словаря.


Add

CFilterDictionary::Add

int
    Add(
 array arFields
);

Создает новый словарь с параметрами, указанными в массиве arFields. Возвращает код созданного словаря.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Словарь". Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданного сообщения. В случае ошибки добавления возвращает False.

См. также

  • поля таблицы "Словарь".

Примеры использования

<?
$arFields = Array(
    TITLE        - > $TITLE,
    TYPE      - > $TYPE,
);
$ID = CFilterDictionary::Add($arFields);
if (IntVal($ID)<=0)
  echo "Error!";
?>


Delete

CFilterDictionary::Delete

bool

  Delete(
 int ID
);

Удаляет папку с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetList

CFilterDictionary::GetList

CDBResult
  GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount ]]]
);

Возвращает список папок по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID сообщения;
TITLE - имя словаря;
TYPE - тип словаря;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
TITLE - имя словаря;
TYPE - тип словаря;

фильтруемое поле может содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Обязательное.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • поля таблицы "Словарь"


Update

CFilterDictionary::Update

int
 Update(
 int ID,
 array arFields
);

Изменяет параметры существующего словаря с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемого словаря.

Параметры функции

Параметр | Описание
ID | Код записи, параметры которой необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Словарь".

Возвращаемое значение

Возвращает код измененного словаря. В случае ошибки изменения возвращает False.

См. также

  • поля таблицы "Словарь"


Класс CFilterLetter

CFilterLetter - класс для работы cо словарями букв.

Методы класса

Метод | Описание
Add | Создание новой записи.
Delete | Удаление записи.
GetList | Получение списка записей с возможностью фильтрации и сортировки.
Update | Изменение параметров записи.


Add

CFilterLetter::Add

int
Add(
  array arFields
);

Создает новую запись с параметрами, указанными в массиве arFields. Возвращает код созданной записи.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Словарь транслита". Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданной записи. В случае ошибки добавления возвращает False.

См. также

  • таблица "Словарь транслита"


Delete

CFilterLetter::Delete

bool
Delete(
 int ID
);

Удаляет запись с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetList

CFilterLetter::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount ]]]
);

Возвращает список записей по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID сообщения;
LETTER - имя буквы;
DICTIONARY_ID - ID словаря;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
LETTER - имя буквы;
DICTIONARY_ID - ID словаря;

фильтруемое поле может содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Обязательное.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • таблица "Словарь"
  • таблица "Словарь транслита"


Update

CFilterLetter::Update

int
Update(
 int ID,
 array arFields
);

Изменяет параметры существующей записи с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемой записи.

Параметры функции

Параметр | Описание
ID | Код записи, параметры которой необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Словарь транслита".

Возвращаемое значение

Возвращает код измененной записи. В случае ошибки изменения возвращает False.

См. также

  • таблица "Словарь транслита"


Класс CFilterUnquotableWords

CFilterUnquotableWords - класс для работы cо словарями слов.

Методы класса

Метод | Описание
Add | Создание новой записи.
Delete | Удаление записи.
GetList | Получение списка записей с возможностью фильтрации и сортировки.
Update | Изменение параметров записи.


Add

CFilterUnquotableWords::Add

int
Add(
 array arFields
);

Создает новую запись с параметрами, указанными в массиве arFields. Возвращает код созданной записи.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Словарь слов". Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданной записи. В случае ошибки добавления возвращает False.

См. также

  • таблица "Словарь слов"


Delete

CFilterUnquotableWords::Delete

bool
Delete(
 int ID
);

Удаляет запись с кодом ID.

Параметры функции

Параметр | Описание
ID | Код записи, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetList

CFilterUnquotableWords::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount ]]]
);

Возвращает список записей по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID сообщения;
WORDS - слово;
PATTERN - шаблон;
REPLACEMENT - замена;
DESCRIPTION - описание;
USE_IT - использовать этот шаблон в фильтре;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
DICTIONARY_ID - ID словаря;
WORDS - слово;
PATTERN - шаблон;
REPLACEMENT - замена;
DESCRIPTION - описание;
USE_IT - использовать этот шаблон в фильтре;

фильтруемое поле может содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Обязательное.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • таблица "Словарь"
  • таблица "Словарь букв"
  • таблица "Словарь слов"


Update

CFilterUnquotableWords::Update

int

  Update(
 int ID,
 array arFields
);

Изменяет параметры существующей записи с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемой записи.

Параметры функции

Параметр | Описание
ID | Код записи, параметры которой необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Словарь слов".

Возвращаемое значение

Возвращает код измененной записи. В случае ошибки изменения возвращает False.

См. также

  • таблица "Словарь слов"


Класс CForumGroup

CForumGroup - класс для работы с группами форумов.

Методы класса

Метод | Описание
GetList | Получение списка групп с возможностью фильтрации и сортировки.
GetByID | Получение параметров группы, не зависящих от языка, по ее коду.
GetByIDEx | Получение всех параметров группы, включая зависящие от языка, по ее коду и языку.
GetLangByID | Получение параметров группы, зависящих от языка, по ее коду и языку.
Add | Добавление новой группы.
Update | Изменение параметров группы.
Delete | Удаление группы.


Add

CForumGroup::Add

int
Add(
 array arFields
);

Создает новую группу с параметрами, указанными в массиве arFields. Возвращает код созданной группы. На добавление нового звания параметры посетителей форума не пересчитываются. Пересчет будт происходить постепенно по мере общения посетителей на форуме.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей групп. В специальное поле "LANG" заносится массив массивов полей языковых параметров групп, которые имеют аналогичную структуру.

Возвращаемое значение

Возвращает код созданной группы. В случае ошибки добавления возвращает False.

См. также

  • Поля группы

Примеры использования

<?
$arFields = array("SORT" => $SORT);
$arSysLangs = array("ru", "en");
for ($i = 0; $i<count($arSysLangs); $i++)
{
  $arFields["LANG"][] = array(
    "LID" => $arSysLangs[$i],
    "NAME" => ${"NAME_".$arSysLangs[$i]},
    "DESCRIPTION" => ${"DESCRIPTION_".$arSysLangs[$i]}
    );
}
$ID = CForumGroup::Add($arFields);
if (IntVal($ID)<=0)
  echo "Error!";
?>


Delete

CForumGroup::Delete

bool
Delete(
 int ID
);

Удаляет группу с кодом ID. Если к данной группе привязаны форумы, то она удалена не будет.

Параметры функции

Параметр | Описание
ID | Код группы, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetByID

CForumGroup::GetByID

array
GetByID(
 int ID
);

Возвращает массив не зависящих от языка параметров группы по ее коду ID.

Параметры функции

Параметр | Описание
ID | Код группы.

Возвращаемое значение

Массив параметров группы, не зависящих от языка. Если группа не найдена, то возвращается значение false.

См. также

  • Поля группы


GetByIDEx

CForumGroup::GetByIDEx

array
GetByIDEx(
 int ID,
 char(2) LANG
);

Возвращает массив всех параметров группы по ее коду ID и языку LANG.

Параметры функции

Параметр | Описание
ID | Код группы.
LANG | Сайт.

Возвращаемое значение

Массив всех параметров группы, включая зависящие от языка. Если группа не найдена, то возвращается значение false.

См. также

  • Поля группы


GetLangByID

CForumGroup::GetLangByID

array
GetLangByID(
 int GROUP_ID,
 char(2) LANG
);

Возвращает массив языковых параметров группы по ее коду GROUP_ID и языку LANG.

Параметры функции

Параметр | Описание
GROUP_ID | Код группы.
LANG | Сайт.

Возвращаемое значение

Массив параметров группы, зависящих от языка. Если группа не найдена, то возвращается значение false.

См. также

  • Поля группы


GetList

CForumGroup::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter]]
);

Возвращает список групп по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID группы;
SORT - индекс сортировки;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("sort"=>"asc")
arFilter Массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - по коду;
SORT - индекс сортировки;

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля элементов


Update

CForumGroup::Update

int
Update(
 int ID,
 array arFields
);

Изменяет параметры существующей группы с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемой группы.

Параметры функции

Параметр | Описание
ID | Код группы, параметры которой необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей групп. В специальное поле "LANG" заносится массив массивов полей языковых параметров групп, которые имеют аналогичную структуру.

Возвращаемое значение

Возвращает код измененной группы. В случае ошибки изменения возвращает False.

См. также

  • Поля группы

Примеры использования

<?
$arFields = array("SORT" => $SORT);
$arSysLangs = array("ru", "en");
for ($i = 0; $i<count($arSysLangs); $i++)
{
  $arFields["LANG"][] = array(
    "LID" => $arSysLangs[$i],
    "NAME" => ${"NAME_".$arSysLangs[$i]},
    "DESCRIPTION" => ${"DESCRIPTION_".$arSysLangs[$i]}
    );
}
$ID1 = CForumGroup::Update($ID, $arFields);
if (IntVal($ID1)<=0)
  echo "Error!";
?>


Класс CForumMessage

CForumMessage - класс для работы с сообщениями форумов.

Методы класса

Метод | Описание
GetList | Получение списка сообщений с возможностью фильтрации и сортировки.
GetListEx | Получение списка сообщений (включая связаные данные) с возможностью фильтрации и сортировки.
GetByID | Получение параметров сообщения по его коду.
GetByIDEx | Получение параметров сообщения вместе со связаными данными по его коду.
Add | Добавление нового сообщения.
Update | Изменение параметров сообщения.
Delete | Удаление сообщения.
CanUserAddMessage | Всесторонне проверяет, может ли пользователь добавить новое сообщение.
CanUserUpdateMessage | Всесторонне проверяет, может ли пользователь изменить сообщение.
CanUserDeleteMessage | Всесторонне проверяет, может ли пользователь удалить сообщение.
GetMessagePage | Возвращает страницу, на которой будет находиться заданное сообщение при постраничном показе.


Add

CForumMessage::Add

int
Add(
 array arFields [,
 string strUploadDir]
);

Создает новое сообщение с параметрами, указанными в массиве arFields. Возвращает код созданного сообщения.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей сообщения. Обязательные поля должны быть заполнены.
strUploadDir | Каталог для загрузки файлов. Должен быть задан относительно главного каталога для загрузки. Необязательный. По умолчанию равен "forum".

Возвращаемое значение

Возвращает код созданного сообщения. В случае ошибки добавления возвращает False.

Примечания

Перед добавлением сообщения следует проверить возможность добавления методом CForumMessage::CanUserAddMessage.

Для добавления и изменения сообщения и темы рекомендуется пользоваться высокоуровневой функцией ForumAddMessage.

См. также

  • Поля сообщения

Примеры использования

<?
$arFields = Array(
  "POST_MESSAGE" => $POST_MESSAGE,
  "USE_SMILES" => ($USE_SMILES=="Y") ? "Y" : "N",
  "APPROVED" => $APPROVED
  "AUTHOR_NAME" => $AUTHOR_NAME,
  "AUTHOR_ID" => $AUTHOR_ID,
  "FORUM_ID" => $FID,
  "TOPIC_ID" => $TID,
  "AUTHOR_IP" => ($AUTHOR_IP!==False) ? $AUTHOR_IP : "<no address>",
  "NEW_TOPIC" => "N"
);
$ID = CForumMessage::Add($arFields);
if (IntVal($ID)<=0)
  echo "Error!";
?>


CanUserAddMessage

CForumMessage::CanUserAddMessage

bool
CanUserAddMessage(
 int TID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, добавить новое сообщение в тему TID.

Параметры функции

Параметр | Описание
TID | Код темы, в которую пользователь хочет добавить сообщение.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на добавление сообщения. В противном случае возвращается значение false.

См. также

  • CForumMessage::CanUserUpdateMessage
  • CForumMessage::CanUserDeleteMessage

Примеры использования

<?
if (CForumMessage::CanUserAddMessage($TID, $USER->GetUserGroupArray(), $USER->GetID()))
{
    echo "You can add message!";
}
?>


CanUserDeleteMessage

CForumMessage::CanUserDeleteMessage

bool
CanUserDeleteMessage(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, удалить сообщение с кодом ID.

Параметры функции

Параметр | Описание
ID | Код сообщения, которое пользователь хочет удалить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на удаление сообщения. В противном случае возвращается значение false.

См. также

  • CForumMessage::CanUserAddMessage
  • CForumMessage::CanUserUpdateMessage

Примеры использования

<?
if (CForumMessage::CanUserDeleteMessage($ID, $USER->GetUserGroupArray(), $USER->GetID()))
{
    CForumMessage::Delete($ID);
}
?>


CanUserUpdateMessage

CForumMessage::CanUserUpdateMessage

bool
CanUserUpdateMessage(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, изменить сообщение с кодом ID.

Параметры функции

Параметр | Описание
ID | Код сообщения, которое пользователь хочет изменить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на изменение сообщения. В противном случае возвращается значение false.

См. также

  • CForumMessage::CanUserAddMessage
  • CForumMessage::CanUserDeleteMessage

Примеры использования

<?
if (CForumMessage::CanUserUpdateMessage($ID, $USER->GetUserGroupArray(), $USER->GetID()))
{
    echo "You can modify this message!";
}
?>


Delete

CForumMessage::Delete

bool
Delete(
 int ID
);

Удаляет сообщение с кодом ID.

Параметры функции

Параметр | Описание
ID | Код сообщения, которое необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.

См. также

  • Перед удалением сообщения следует проверить возможность удаления методом CForumMessage::CanUserDeleteMessage


GetByID

CForumMessage::GetByID

array
GetByID(
 int ID
);

Возвращает массив параметров сообщения по его коду ID.

Параметры функции

Параметр | Описание
ID | Код сообщения.

Возвращаемое значение

Массив параметров сообщения. Если сообщение не найдено, то возвращается значение false.

См. также

  • Поля сообщения

Примеры использования

<?
$arMessage = CForumMessage::GetByID($MID);
if ($arMessage)
{
  $TID = IntVal($arMessage["TOPIC_ID"]);
  $FID = IntVal($arMessage["FORUM_ID"]);
}
?>


GetByIDEx

CForumMessage::GetByIDEx

array
GetByIDEx(
 int ID
);

Возвращает массив параметров сообщения, а так же сопутствующие параметры, по его коду ID.

Параметры функции

Параметр | Описание
ID | Код сообщения.

Возвращаемое значение

Массив параметров сообщения, включая сопутствующие. Если сообщение не найдено, то возвращается значение false.

См. также

  • Поля сообщения

Примеры использования

<?
// Распечатаем на экран все возвращаемые параметры сообщения
$arMessage = CForumMessage::GetByIDEx($MID);
if ($arMessage)
{
  echo "<pre>";
  print_r($arMessage);
  echo "</pre>";
}
?>


GetList

CForumMessage::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount [,
 int iNum]]]]
);

Возвращает список сообщений по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
AUTHOR_NAME - имя автора сообщения;
POST_DATE - дата создания сообщения;
FORUM_ID - ID форума;
TOPIC_ID - ID темы;
APPROVED - опубликовано;
ID - ID сообщения;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
AUTHOR_NAME - имя автора сообщения;
AUTHOR_ID - ID автора сообщения;
FORUM_ID - ID форума;
TOPIC_ID - ID темы;
APPROVED - опубликовано;

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.
iNum | Ограничение числа возвращаемых записей. Если параметр iNum отличен от нуля, то возвращается не более iNum записей. Поддерживается не для всех баз данных. Если параметр не поддерживается, то его установки игнорируются. Необязательный. По умолчанию равен 0.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля сообщения

Примеры использования

<?
// выберем все опубликованные сообщения темы с кодом $TID в порядке поступления
$db_res = CForumMessage::GetList(array("ID"=>"ASC"), array("TOPIC_ID"=>$TID));
while ($ar_res = $db_res->Fetch())
{
  echo $ar_res["POST_MESSAGE"]."<br>";
}
?>


GetListEx

CForumMessage::GetListEx

CDBResult
GetListEx(
 [array arOrder [,
 array arFilter [,
 bool bCount [,
 int iNum]]]]
);

Возвращает список сообщений (включая связаные данные) по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
AUTHOR_NAME - имя автора сообщения;
POST_DATE - дата создания сообщения;
FORUM_ID - ID форума;
TOPIC_ID - ID темы;
APPROVED - опубликовано;
ID - ID сообщения;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
AUTHOR_NAME - имя автора сообщения;
AUTHOR_ID - ID автора сообщения;
FORUM_ID - ID форума;
TOPIC_ID - ID темы;
APPROVED - опубликовано;

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.
iNum | Ограничение числа возвращаемых записей. Если параметр iNum отличен от нуля, то возвращается не более iNum записей. Поддерживается не для всех баз данных. Если параметр не поддерживается, то его установки игнорируются. Необязательный. По умолчанию равен 0.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля сообщения

Примеры использования

<?
// выберем все опубликованные сообщения темы с кодом $TID в порядке обратном поступлению
$db_res = CForumMessage::GetListEx(array("ID"=>"DESC"), array("TOPIC_ID"=>$TID));
while ($ar_res = $db_res->Fetch())
{
  echo "<pre>";
  print_r($ar_res);
  echo "</pre><br>";
}
?>


GetMessagePage

CForumMessage::GetMessagePage

int
GetMessagePage(
 int ID,
 int mess_per_page,
 array arUserGroups
);

Возвращает страницу, на которой будет находиться сообщение с кодом ID для пользователя, входящего в группы arUserGroups, при постраничном показе с mess_per_page сообщениями на странице.

Параметры функции

Параметр | Описание
ID | Код сообщения.
mess_per_page | Количество сообщений на страницу. Обычно равно переменной $FORUM_MESSAGES_PER_PAGE, которая определяется модулем форума. Эта переменная инициализируется из настроек модуля форума.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray().

Возвращаемое значение

Номер страницы, на которой будет показано сообщение. Если сообщение не найдено, то возвращается значение false.

См. также

  • CDBResult::NavStart

Примеры использования

<?
if ($MID>0)
  $db_Message->NavStart($FORUM_MESSAGES_PER_PAGE, true, CForumMessage::GetMessagePage($MID, $FORUM_MESSAGES_PER_PAGE, $USER->GetUserGroupArray()));
else
  $db_Message->NavStart($FORUM_MESSAGES_PER_PAGE);
?>


Update

CForumMessage::Update

int
Update(
 int ID,
 array arFields [,
 bool skip_counts [,
 string strUploadDir]]
);

Изменяет параметры существующего сообщения с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемого сообщения.

Параметры функции

Параметр | Описание
ID | Код сообщения, параметры которого необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей сообщения.
skip_counts | Если этот параметр установлен в значение true, то при изменении сообщения не будут автоматически обсчитаны статистические данные. Это ускоряет работу функции, но создает логические ошибки в данных. Необязательный. По умолчанию равен False.
strUploadDir | Каталог для загрузки файлов. Должен быть задан относительно главного каталога для загрузки. Необязательный. По умолчанию равен "forum".

Возвращаемое значение

Возвращает код измененного сообщения. В случае ошибки изменения возвращает False.

Примечания

Перед изменением сообщения следует проверить возможность изменения методом CForumMessage::CanUserUpdateMessage.

Для добавления и изменения сообщения и темы рекомендуется пользоваться высокоуровневой функцией ForumAddMessage.

См. также

  • Поля сообщения


Класс CForumNew

CForumNew - класс для работы с форумами

Методы класса

Метод | Описание
Add | Добавление нового форума.
Delete | Удаление форума.
CanUserAddForum | Всесторонне проверяет, может ли пользователь добавить новый форум.
CanUserDeleteForum | Всесторонне проверяет, может ли пользователь удалить форум.
CanUserUpdateForum | Всесторонне проверяет, может ли пользователь изменить форум.
GetByID | Получение параметров форума по его коду.
GetByIDEx | Получение параметров форума вместе со связаными данными по его коду.
GetList | Получение списка форумов с возможностью фильтрации и сортировки.
GetListEx | Получение списка форумов (включая связаные данные) с возможностью фильтрации и сортировки.
GetSites | Получение сайтов, к которым относится форум, а так же шаблонов путей к сообщениям форума на этих сайтах.
Update | Изменение параметров форума.


Add

CForumNew::Add

int
Add(
 array arFields
);

Создает новый форум с параметрами, указанными в массиве arFields. Возвращает код созданного форума.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей форума. Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданного форума. В случае ошибки добавления возвращает False.

См. также

  • Поля форума
  • Перед добавлением форума следует проверить возможность добавления методом CForumNew::CanUserAddForum


CanUserAddForum

CForumNew::CanUserAddForum

bool
CanUserAddForum(
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, добавить новый форум.

Параметры функции

Параметр | Описание
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на добавление форума. В противном случае возвращается значение false.

См. также

  • CForumNew::CanUserUpdateForum
  • CForumNew::CanUserDeleteForum


CanUserDeleteForum

CForumNew::CanUserDeleteForum

bool
CanUserDeleteForum(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, удалить форум с кодом ID.

Параметры функции

Параметр | Описание
ID | Код форума, который пользователь хочет удалить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на удаление форума. В противном случае возвращается значение false.

См. также

  • CForumNew::CanUserAddForum
  • CForumNew::CanUserUpdateForum


CanUserUpdateForum

CForumNew::CanUserUpdateForum

bool
CanUserUpdateForum(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, изменить форум с кодом ID.

Параметры функции

Параметр | Описание
ID | Код форума, который пользователь хочет изменить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на изменение форума. В противном случае возвращается значение false.

См. также

  • CForumNew::CanUserAddForum
  • CForumNew::CanUserDeleteForum

Примеры использования

<?
if (CForumNew::CanUserUpdateForum($ID, $USER->GetUserGroupArray(), $USER->GetID()))
{
    echo "You can modify this forum!";
}
?>


Delete

CForumNew::Delete

bool
Delete(
 int ID
);

Удаляет форум с кодом ID. Перед удалением проверяет обработчики события OnBeforeForumDelete модуля forum. Если один из обработчиков вернет false, то форум удален не будет.

Параметры функции

Параметр | Описание
ID | Код форума, который необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.

См. также

  • Перед удалением форума следует проверить возможность удаления методом CForumNew::CanUserDeleteForum


GetByID

CForumNew::GetByID

array
GetByID(
 int ID
);

Возвращает массив параметров форума по его коду ID. Результаты вызова функции кешируются, поэтому повторные вызовы метода для одного и того же форума не требуют дополнительного обращения к базе данных (при условии, что кеш не сбросился в результате изменения параметров форума).

Параметры функции

Параметр | Описание
ID | Код форума.

Возвращаемое значение

Массив параметров форума. Если форум не найден, то возвращается значение false.

См. также

  • Поля форума

Примеры использования

<?
$arForum = CForumNew::GetByID($FID);
if ($arForum)
{
  echo $arForum["NAME"]."<br>";
}
?>


GetByIDEx

CForumNew::GetByIDEx

array
GetByIDEx(
 int ID
);

Возвращает массив параметров форума, а так же сопутствующие параметры, по его коду ID.

Параметры функции

Параметр | Описание
ID | Код форума.

Возвращаемое значение

Массив параметров форума, включая сопутствующие. Если форум не найден, то возвращается значение false.

См. также

  • Поля форума

Примеры использования

<?
// Распечатаем на экран все возвращаемые параметры форума
$arForum = CForumNew::GetByIDEx($FID);
if ($arForum)
{
  echo "<pre>";
  print_r($arForum);
  echo "</pre>";
}
?>


GetList

CForumNew::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter]]
);

Возвращает список форумов по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID форума;
LID - язык форума;
NAME - название форума;
ACTIVE - активность;
MODERATION - модерируемость форума;
FORUM_GROUP_ID - ID группы форума;
TOPICS - количество тем в форуме;
POSTS - количество сообщений в форуме;
LAST_POST_DATE - дата последнего сообщения;
SORT - индекс сортировки;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("SORT"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
LID - язык форума;
ACTIVE - активность форума;
ID - ID форума;
FORUM_GROUP_ID - ID группы форума;
TOPICS - количество тем в форуме;
POSTS - количество сообщений в форуме;
TEXT - подстрока в названии или описании форума;
PERMS - права на доступ к форуму (массив из двух элементов, первый из которых - это список кодов групп, в которые входит пользователь, а второй - это код права на доступ);

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля форума

Примеры использования

<?
// выведем список форумов, к которым текущий посетитель
// имеет доступ по крайней мере на чтение,
// отсортируем список сначала по индексу сортировки, а потом
// по названию форума
$arFilter = array();
if (!$USER->IsAdmin())
{
  $arFilter["PERMS"] = array($USER->GetGroups(), 'A');
  $arFilter["ACTIVE"] = "Y";
}
$arOrder = array("SORT"=>"ASC", "NAME"=>"ASC");
$db_Forum = CForumNew::GetList($arOrder, $arFilter);
while ($ar_Forum = $db_Forum->Fetch())
{
  echo $ar_Forum["NAME"]."<br>";
}
?>


GetListEx

CForumNew::GetListEx

CDBResult
GetListEx(
 [array arOrder [,
 array arFilter]]
);

Возвращает список форумов (включая связаные данные) по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID форума;
LID - язык форума;
NAME - название форума;
ACTIVE - активность;
MODERATION - модерируемость форума;
FORUM_GROUP_ID - ID группы форума;
TOPICS - количество тем в форуме;
POSTS - количество сообщений в форуме;
LAST_POST_DATE - дата последнего сообщения;
FORUM_GROUP_SORT - индекс сортировки группы, которой принадлежит форум;
SORT - индекс сортировки;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("SORT"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...]).
Подробное описание параметра смотрите в описании функции CForumNew::GetList.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля форума

Примеры использования

<?
// выведем список форумов, к которым текущий посетитель
// имеет доступ по крайней мере на чтение,
// сгруппируем список по группам форумов,
// отсортируем список сначала по индексу сортировки, а потом
// по названию форума
$arFilter = array();
if (!$USER->IsAdmin())
{
  $arFilter["PERMS"] = array($USER->GetGroups(), 'A');
  $arFilter["ACTIVE"] = "Y";
}
$arOrder = array("SORT"=>"ASC", "NAME"=>"ASC");
$db_Forum = CForumNew::GetListEx($arOrder, $arFilter);
$currentGroupID = -1;
while ($db_Forum->NavNext(true, "f_", false)):
  if ($currentGroupID != IntVal($f_FORUM_GROUP_ID))
  {
    if (IntVal($f_FORUM_GROUP_ID)>0)
    {
      $arCurForumGroup = CForumGroup::GetLangByID($f_FORUM_GROUP_ID, LANG);
      echo "<b>";
      echo htmlspecialcharsex($arCurForumGroup["NAME"]);
      echo "<b><br>";
    }
    $currentGroupID = IntVal($f_FORUM_GROUP_ID);
  }
  echo $f_NAME."<br>";
endwhile;
?>


GetSites

CForumNew::GetSites

array
CForumNew::GetSites(
 int ID
);

Функция возвращает ассоциативный массив, в котором ключами являются сайты, к которым привязан форум с кодом ID, а значениями - шаблоны пути к сообщению форума в соответствующем сайте.

Параметры функции

Параметр | Описание
ID | Код форума.

Примеры использования

// Для форума с кодом $FID получим массив реальных путей к сообщению
// с кодом $MID из темы с кодом $TID

$arForumPaths = CForumNew::GetSites($FID);
$arForumPathsCodes = array_keys($arForumPaths);
for ($i = 0; $i < count($arForumPathsCodes); $i++)
{
    $arForumPaths[$arForumPathsCodes[$i]] =
        CForumNew::PreparePath2Message($arForumPaths[$arForumPathsCodes[$i]],
                                       array("FORUM_ID"=>$FID,
                                             "TOPIC_ID"=>$TID,
                                             "MESSAGE_ID"=>$MID)
                                       );
}


Update

CForumNew::Update

int
Update(
 int ID,
 array arFields
);

Изменяет параметры существующего форума с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемого форума.

Параметры функции

Параметр | Описание
ID | Код форума, параметры которого необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей форума.

Возвращаемое значение

Возвращает код измененного форума. В случае ошибки изменения возвращает False.

См. также

  • Поля форума
  • Перед изменением форума следует проверить возможность изменения методом CanUserUpdateForum


Класс CForumPMFolder

CForumPMFolder - класс для работы папками пользователя.

Методы класса

Метод | Описание
Add | Создание новой папки пользователя.
Delete | Удаление папки пользователя.
GetList | Получение списка папок с возможностью фильтрации и сортировки.
Update | Изменение параметров папки пользователя.


Add

CForumPMFolder::Add

int
Add(
 array arFields
);

Создает новую папку с параметрами, указанными в массиве arFields. Возвращает код созданной папки.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Папка пользователя". Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданного сообщения. В случае ошибки добавления возвращает False.

См. также

  • таблица "Папка пользователя"

Примеры использования

<?
$arFields = Array(
    TITLE        - > $TITLE,
    USER_ID      - > $USER_ID,
);
$ID = CForumPMFolder::Add($arFields);
if (IntVal($ID)<=0)
  echo "Error!";
?>


Delete

CForumPMFolder::Delete

bool
Delete(
 int ID
);

Удаляет папку пользователя с кодом ID.

Параметры функции

Параметр | Описание
ID | Код папки пользователя, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetList

CForumPMFolder::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount ]]]
);

Возвращает список сообщений по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID сообщения;
USER_ID - ID владельца папки;
TITLE - имя папки пользователя;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
USER_ID - ID владельца папки;
TITLE - имя папки пользователя;

фильтруемое поле может содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Обязательное.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • таблица "Папка пользователя"


Update

CForumPMFolder::Update

int
Update(
 int ID,
 array arFields
);

Изменяет параметры существующей папки пользователя с кодом ID на параметры, указанные в массиве arFields.

Параметры функции

Параметр | Описание
ID | Код папки пользователя, параметры которой необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Папка пользователя".

Возвращаемое значение

Возвращает код измененного сообщения. В случае ошибки изменения возвращает False.

См. также

  • таблица "Папка пользователя"


Класс CForumPoints

CForumPoints - класс для работы со званиями (статусами пользователей) форума.

Методы класса

Метод | Описание
GetList | Получение списка званий с возможностью фильтрации и сортировки.
GetListEx | Получение списка званий (включая языкозависимые параметры звания) с возможностью фильтрации и сортировки.
GetByID | Получение параметров звания по его коду.
GetByIDEx | Получение параметров звания вместе с языкозависимыми параметрами по его коду.
Add | Добавление нового звания.
Update | Изменение параметров звания.
Delete | Удаление звания.
GetLangByID | Получение языкозависимых параметров звания.


Add

CForumPoints::Add

int
CForumPoints::Add(
 array arFields
);

Функция добавляет новое звание (рейтинг) в систему званий форума.

Параметры функции

Параметр | Описание
arFields | Массив атрибутов звания.

Возвращаемые значения

Код добавленного звания или false в случае ошибки.


Delete

CForumPoints::Delete

bool
CForumPoints::Delete(
 int ID
);

Удаляет звание (рейтинг) с кодом ID из системы званий форума.

Параметры функции

Параметр | Описание
ID | Код звания для удаления.

Возвращаемые значения

Возвращает True.


GetByID

CForumPoints::GetByID

array
CForumPoints::GetByID(
 int ID
);

Возвращает массив параметров звания (рейтинга) форума по его коду

Параметры функции

Параметр | Описание
ID | Код звания.

Возвращаемые значения

Возвращает ассоциативный массив с ключами

Ключ | Значение
ID | Код звания.
MIN_POINTS | Количество баллов, необходимое для получения этого звания.
CODE | Мнемонический код.
VOTES | Количество голосов, которое имеет пользователь с этим званием.

Пример использования

<?

$ar_res = CForumPoints::GetByID(3);
echo "Пользователь с этим званием может отдать ".$ar_res["VOTES"]." голос(ов)";
?>


GetByIDEx

CForumPoints::GetByIDEx

array
CForumPoints::GetByIDEx(
 int ID,
 string strLang
);

Возвращает массив параметров звания (рейтинга) форума по его коду включая языкозависимые параметры.

Параметры функции

Параметр | Описание
ID | Код звания.
strLang | Код языка.

Возвращаемые значения

Возвращает ассоциативный массив с ключами

Ключ | Значение
ID | Код звания.
MIN_POINTS | Количество баллов, необходимое для получения этого звания.
CODE | Мнемонический код.
VOTES | Количество голосов, которое имеет пользователь с этим званием.
LID | Код языка.
NAME | Название звания на языке LID.

Пример использования

<?
$ar_res = CForumPoints::GetByIDEx(3, "ru");
echo "Пользователи со званием ".$ar_res["NAME"]." могут отдать ".$ar_res["VOTES"]." голосов";
?>


GetLangByID

CForumPoints::GetLangByID

array
CForumPoints::GetLangByID(
 int POINTS_ID,
 string strLang
);

Возвращает массив языкозависимых параметров звания (рейтинга) форума по его коду.

Параметры функции

Параметр | Описание
POINTS_ID | Код звания.
strLang | Код языка.

Возвращаемые значения

Возвращает ассоциативный массив с ключами.

Ключ | Значение
POINTS_ID | Код звания.
LID | Код языка.
NAME | Название звания на языке LID.

Пример использования

<?
$ar_res = CForumPoints::GetLangByID(3, "ru");
echo "Звание с кодом ".$ar_res["POINTS_ID"]." на русском языке называется ".$ar_res["NAME"]."";
?>


GetList

CForumPoints::GetList

CDBResult
CForumPoints::GetList(
 array arOrder = array("MIN_POINTS"=>"ASC"),
 array arFilter = array()
);

Возвращает звания форума, которые удовлетворяют фильтру arFilter, упорядоченные в соответствии с порядком arOrder

Параметры функции

Параметр Описание
arOrder

Порядок сортировки записей; представляет собой ассоциативный массив, в котором ключами являются названия параметров звания, а значениями - направления сортировки.

Допустимые параметры звания для сортировки:
ID - код звания
CODE - мнемонический код
VOTES - количество голосов при голосовании
MIN_POINTS - количество баллов, которые нужны для достижения этого звания
arFilter

Фильтр на возвращаемые звания; представляет собой ассоциативный массив, в котором ключами являются названия параметров звания, а значениями - условия на эти параметры.

Допустимые параметры звания для фильтрации:
ID - код звания
CODE - мнемонический код
MIN_POINTS - количество баллов, которые нужны для достижения этого звания.

Возвращаемые значения

Возвращяется объект класса CDBResult, каждая запись которого представляет собой массив с ключами

Ключ | Значение
ID | Код звания.
MIN_POINTS | Количество баллов, необходимое для получения этого звания.
CODE | Мнемонический код.
VOTES | Количество голосов, которое имеет пользователь с этим званием.

Пример использования

// Сортировка по количеству голосов по убыванию
// при равном количестве голосов сортировка по ID по возрастанию
$arOrder = array("VOTES"=>"DESC", "ID"=>"ASC");
// Фильтр указывает, что нужно выбирать только те звания
// для получения которых нужно как минимум 50 баллов
$arFilter = array(">=MIN_POINTS"=>50);
$db_res = CForumPoints::GetList($arOrder, $arFilter);
while ($ar_res = $db_res->Fetch())
{
   echo $ar_res["ID"]."-".$ar_res["VOTES"]."<br>";
}


GetListEx

CForumPoints::GetListEx

CDBResult
CForumPoints::GetListEx(
 array arOrder = array("MIN_POINTS"=>"ASC"),
 array arFilter = array()
);

Возвращает звания форума, которые удовлетворяют фильтру arFilter, упорядоченные в соответствии с порядком arOrder

Параметры функции

Параметр Описание
arOrder

Порядок сортировки записей; представляет собой ассоциативный массив, в котором ключами являются названия параметров звания, а значениями - направления сортировки.

Допустимые параметры звания для сортировки:
ID - код звания
CODE - мнемонический код
VOTES - количество голосов при голосовании
MIN_POINTS - количество баллов, которые нужны для достижения этого звания
arFilter

Фильтр на возвращаемые звания; представляет собой ассоциативный массив, в котором ключами являются названия параметров звания, а значениями - условия на эти параметры.

Допустимые параметры звания для фильтрации:
LID - код языка (должен присутствовать в фильтре)
ID - код звания
CODE - мнемонический код
MIN_POINTS - количество баллов, которые нужны для достижения этого звания.

Возвращаемые значения

Возвращается объект класса CDBResult, каждая запись которого представляет собой массив с ключами

Ключ | Значение
ID | Код звания.
MIN_POINTS | Количество баллов, необходимое для получения этого звания.
CODE | Мнемонический код.
VOTES | Количество голосов, которое имеет пользователь с этим званием.
LID | Код языка.
NAME | Название звания на языке LID

Пример использования

// Сортировка по количеству голосов по убыванию
// при равном количестве голосов сортировка по ID по возрастанию
$arOrder = array("VOTES"=>"DESC", "ID"=>"ASC");

// Фильтр указывает, что нужно выбирать только те звания
// для получения которых нужно как минимум 50 баллов
$arFilter = array("LID"=>"ru", ">=MIN_POINTS"=>50);
$db_res = CForumPoints::GetList($arOrder, $arFilter);
while ($ar_res = $db_res->Fetch())
{
    echo $ar_res["NAME"]."-".$ar_res["VOTES"]."<br>";
}


Update

CForumPoints::Update

int
CForumPoints::Update(
 int ID,
 array arFields
);

Изменяет параметры звания с кодом ID на значения, указанные в массиве arFields.

Параметры функции

Параметр | Описание
ID | Код звания.
arFields | Массив новых значений параметров звания.

Возвращаемые значения

Функция возвращает код изменяемого звания или false в случае ошибки.


Класс CForumPoints2Post

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

Методы класса

Метод | Описание
GetList | Получение списка записей в карте соответствий с возможностью фильтрации и сортировки.
GetByID | Получение параметров записи по ее коду.
Add | Добавление новой записи.
Update | Изменение параметров записи.
Delete | Удаление записи.


Add

CForumPoints2Post::Add

int
CForumPoints2Post::Add(
 array arFields
);

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

Параметры функции

Параметр | Описание
arFields | Массив параметров записи.

Возвращаемые значения

Функция возвращает код вставленной записи или false в случае ошибки.


GetByID

CForumPoints2Post::GetByID

array
CForumPoints2Post::GetByID(
 int ID
);

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

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

Возвращает ассоциативный массив с ключами.

Ключ | Значение
ID | Код записи.
MIN_NUM_POSTS | Количество сообщений, которое пользователь должен написать на форуме для получения этого количества балов за одно сообщение.
POINTS_PER_POST | Количество балов за одно сообщение. Может иметь как целое значение, так и дробное: 2 - два бала за каждое сообщение 0.1 - одна десятая бала за каждое сообщение.


GetList

CForumPoints2Post::GetList

CDBResult
CForumPoints2Post::GetList(
 array arOrder = array("MIN_NUM_POSTS"=>"ASC"),
 array arFilter = array()
);

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

Параметры функции

Параметр Описание
arOrder

Порядок сортировки записей; представляет собой ассоциативный массив, в котором ключами являются названия параметров записи, а значениями - направления сортировки.

Допустимые параметры записи для сортировки:
ID - код записи
MIN_NUM_POSTS - количество сообщений, которое пользователь должен написать на форуме для получения этого количества балов за одно сообщение
POINTS_PER_POST - Количество балов за одно сообщение

arFilter

Фильтр на возвращаемые записи; представляет собой ассоциативный массив, в котором ключами являются названия параметров записи, а значениями - условия на эти параметры.

Допустимые параметры записи для фильтрации:
ID - код записи
MIN_NUM_POSTS - количество сообщений, которое пользователь должен написать на форуме для получения этого количества балов за одно сообщение.

Возвращаемые значения

Возвращяется объект класса CDBResult, каждая запись которого представляет собой массив с ключами.

Ключ | Значение
ID | Код записи.
MIN_NUM_POSTS | количество сообщений, которое пользователь должен написать на форуме для получения этого количества балов за одно сообщение.
POINTS_PER_POST | Количество балов за одно сообщение. Может иметь как целое значение, так и дробное: 2 - два бала за каждое сообщение 0.1 - одна десятая бала за каждое сообщение.


Update

CForumPoints2Post::Update

int
CForumPoints2Post::Update(
 int ID,
 array arFields
);

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

Параметры функции

Параметр | Описание
ID | Код изменяемой записи.
arFields | Массив новых значений параметров записи.

Возвращаемые значения

Функция возвращает код записи или false в случае ошибки.


Delete

CForumPoints2Post::Delete

bool
CForumPoints2Post::Delete(
 int ID
);

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

Параметры функции

Параметр | Описание
ID | Код записи.

Возвращаемые значения

Функция возвращает значение True.


Класс CForumPrivateMessage

CForumPrivateMessage - класс для работы с приватными сообщениями.

Методы класса

Метод | Описание
Delete | Удаление сообщения.
GetList | Получение списка сообщений с возможностью фильтрации и сортировки.
GetByID | Получение параметров сообщения по его коду.
Send | Добавление (отправка) нового сообщения.
Update | Изменение параметров сообщения.


Delete

CForumPrivateMessage::Delete

bool
Delete(
 int ID
);

Удаляет сообщение с кодом ID.

Параметры функции

Параметр | Описание
ID | Код сообщения, которое необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetByID

CForumPrivateMessage::GetByID

array
GetByID(
 int ID
);

Возвращает массив параметров сообщения по его коду ID.

Параметры функции

Параметр | Описание
ID | Код сообщения.

Возвращаемое значение

Массив параметров сообщения. Если сообщение не найдено, то возвращается значение false.

См. также

  • таблица "Приватное сообщение"

Примеры использования

<?
$arMessage = CForumPrivateMessage::GetByID($MID);
if ($arMessage)
{
  $AUTHOR_ID = IntVal($arMessage["AUTHOR_ID"]);
  $USER_ID = IntVal($arMessage["USER_ID"]);
}
?>


GetList

CForumPrivateMessage::GetList

CDBResult

  GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount ]]]
);

Возвращает список сообщений по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID сообщения;
AUTHOR_ID - ID автора сообщения;
POST_DATE - дата создания сообщения;
POST_SUBJ - тема сообщения;
POST_MESSAGE - текст сообщения;
USER_ID - ID получателя сообщения (владельца);
FOLDER_ID - ID папки;
IS_READ - метка о прочтении сообщения;
USE_SMILES - метка о разрешении использования смайликов как рисунков;
AUTHOR_NAME - имя автора сообщения;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID сообщения;
AUTHOR_ID - ID автора сообщения;
POST_SUBJ - тема сообщения;
POST_MESSAGE - текст сообщения;
USER_ID - ID получателя сообщения (владельца);
FOLDER_ID - ID папки;
IS_READ - метка о прочтении сообщения;

фильтруемое поле может содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Обязательное.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • таблица "Приватное сообщение"


Send

CForumPrivateMessage::Send

int
  Send(
 array arFields
);

Создает новое сообщение с параметрами, указанными в массиве arFields. Возвращает код созданного сообщения.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Приватное сообщение". Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданного сообщения. В случае ошибки добавления возвращает False.

См. также

  • таблица "Приватное сообщение"

Примеры использования

<?
$arFields = Array(
    AUTHOR_ID    - > $AUTHOR_ID,
    POST_DATE    - > $POST_DATE,
    POST_SUBJ    - > $POST_SUBJ,
    POST_MESSAGE - > $POST_MESSAGE,
    USER_ID      - > $USER_ID,
    FOLDER_ID    - > 1,
    IS_READ      - > "N",
    USE_SMILES   - > ($USE_SMILES=="Y") ? "Y" : "N",
    AUTHOR_NAME  - > $AUTHOR_NAME
);
$ID = CForumPrivateMessage::Send($arFields);
if (IntVal($ID)<=0)
  echo "Error!";
?>


Update

CForumPrivateMessage::Update

int
Update(
 int ID,
 array arFields
);

Изменяет параметры существующего сообщения с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемого сообщения.

Параметры функции

Параметр | Описание
ID | Код сообщения, параметры которого необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей таблицы "Приватное сообщение".

Возвращаемое значение

Возвращает код измененного сообщения. В случае ошибки изменения возвращает False.

См. также

  • таблица "Приватное сообщение"


Класс CForumSmile

CForumSmile - класс для работы со смайлами.

Методы класса

Метод | Описание
GetList | Получение списка смайлов с возможностью фильтрации и сортировки.
GetByID | Получение параметров смайла, не зависящих от языка, по его коду.
GetByIDEx | Получение всех параметров смайла по его коду и языку.
GetLangByID | Получение языковых параметров смайла по его коду и языку.
Add | Добавление нового смайла.
Update | Изменение параметров смайла.
Delete | Удаление смайла.


Add

CForumSmile::Add

int
Add(
 array arFields
);

Создает новый смайл с параметрами, указанными в массиве arFields. Возвращает код созданного смайла.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей смайла. В специальное поле "LANG" заносится массив массивов полей языковых параметров смайла, которые имеют аналогичную структуру. Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданного смайла. В случае ошибки добавления возвращает False.

См. также

  • Поля смайла


Delete

CForumSmile::Delete

bool
Delete(
 int ID
);

Удаляет смайл с кодом ID.

Параметры функции

Параметр | Описание
ID | Код смайла, который необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.


GetByID

CForumSmile::GetByID

array
GetByID(
 int ID
);

Возвращает массив параметров смайла, которые не зависят от языка, по его коду ID.

Параметры функции

Параметр | Описание
ID | Код смайла.

Возвращаемое значение

Массив параметров смайла. Если смайл не найден, то возвращается значение false.

См. также

  • Поля смайла


GetByIDEx

CForumSmile::GetByIDEx

array
GetByIDEx(
 int ID,
 char(2) LANG
);

Возвращает массив всех параметров смайла по его коду ID и языку LANG.

Параметры функции

Параметр | Описание
ID | Код смайла.
LANG | Сайт.

Возвращаемое значение

Массив всех параметров смайла. Если смайл не найден, то возвращается значение false.

См. также

  • Поля смайла


GetLangByID

CForumSmile::GetLangByID

array
GetLangByID(
 int RANK_ID,
 char(2) LANG
);

Возвращает массив языковых параметров смайла по его коду RANK_ID и языку LANG.

Параметры функции

Параметр | Описание
RANK_ID | Код смайла.
LANG | Сайт.

Возвращаемое значение

Массив языковых параметров смайла. Если смайл не найден, то возвращается значение false.

См. также

  • Поля смайла


GetList

CForumSmile::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter]]
);

Возвращает список смайлов по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID смайла;
SORT - индекс сортировки;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("SORT"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID смайла;
SORT - индекс сортировки;

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля смайла


Update

CForumSmile::Update

int
Update(
 int ID,
 array arFields
);

Изменяет параметры существующего смайла с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемого смайла.

Параметры функции

Параметр | Описание
ID | Код смайла, параметры которого необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей смайла. В специальное поле "LANG" заносится массив массивов полей языковых параметров звания, которые имеют аналогичную структуру.

Возвращаемое значение

Возвращает код измененного смайла. В случае ошибки изменения возвращает False.

См. также

  • Поля смайла


Класс CForumSubscribe

CForumSubscribe - класс для работы с подпиской на новые сообщения форума и темы.

Методы класса

Метод | Описание
GetList | Получение списка подписки с возможностью фильтрации и сортировки.
GetListEx | Получение списка подписки с возможностью фильтрации и сортировки. Дополнительно выбирает Email подписчика и имеет дополнительные возможности фильтрации.
Add | Добавление новой подписки.
Delete | Удаление подписки.
CanUserAddSubscribe | Всесторонне проверяет, может ли пользователь добавить новую подписку.
CanUserDeleteSubscribe | Всесторонне проверяет, может ли пользователь удалить подписку.


Add

CForumSubscribe::Add

int
Add(
 array arFields
);

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

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей подписки. Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданной записи. В случае ошибки добавления возвращает False.

См. также

  • Поля подписки
  • Перед добавлением подписки следует проверить возможность добавления методом CForumSubscribe::CanUserAddSubscribe


CanUserAddSubscribe

CForumSubscribe::CanUserAddSubscribe

bool
CanUserAddSubscribe(
 int FID,
 array arUserGroups,
);

Всесторонне проверяет, может ли пользователь, входящий в группы arUserGroups, добавить новую подписку на этот форум.

Параметры функции

Параметр | Описание
FID | ID форума, на который пользователь хочет добавить новую подписку.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()

Возвращаемое значение

Возвращает True, если пользователь имеет право на добавление подписки. В противном случае возвращается значение False.

См. также

  • CForumSubscribe::CanUserDeleteSubscribe


CanUserDeleteSubscribe

CForumSubscribe::CanUserDeleteSubscribe

bool

  CanUserDeleteSubscribe(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, удалить подписку с кодом ID.

Параметры функции

Параметр | Описание
ID | Код подписки, которую пользователь хочет удалить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на удаление подписки. В противном случае возвращается значение false.

См. также

  • CForumSubscribe::CanUserAddSubscribe


Delete

CForumSubscribe::Delete

bool
Delete(
 int ID
);

Удаляет подписку с кодом ID

Параметры функции

Параметр | Описание
ID | Код подписки, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.

См. также

  • Перед удалением подписки следует проверить возможность удаления методом CForumSubscribe::CanUserDeleteSubscribe


GetList

CForumSubscribe::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter]]
);

Возвращает список подписок по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
  • ID - ID подписки;
  • FORUM_ID - ID форума;
  • USER_ID - ID подписанного пользователя;
  • TOPIC_ID - ID темы;
  • START_DATE - дата подписки;
order - порядок сортировки, может принимать значения
  • ASC - по возрастанию;
  • DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC").
arFilter Массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
  • ID - ID подписки;
  • USER_ID - ID подписанного пользователя;
  • FORUM_ID - ID форума;
  • TOPIC_ID - ID темы;
  • TOPIC_ID_OR_NULL - ID темы или NULL (проверка только на "равно");
  • LAST_SEND - ID последнего отправленного сообщения;
  • LAST_SEND_OR_NULL - ID последнего отправленного сообщения или NULL (проверка только на "меньше");
Фильтруемое поле может иметь содержать перед названием тип проверки фильтра
  • "!" - не равно
  • "<" - меньше
  • "<=" - меньше либо равно
  • ">" - больше
  • ">=" - больше либо равно
Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля подписки


GetListEx

CForumSubscribe::GetListEx

CDBResult
CForumSubscribe::GetListEx(
 array arOrder = array("ID"=>"ASC"),
 array arFilter = array()
);

Функция возвращает записи из таблицы подписки на сообщения форума удовлетворяющие фильтру arFilter и упорядоченные в соответствии с сортировкой arOrder. С каждой записью идет email пользователя, которому принадлежит эта запись (т.е. email подписчика).

Параметры функции

Параметр Описание
arOrder

Порядок сортировки записей; представляет собой ассоциативный массив, в котором ключами являются названия параметров записей, а значениями - направления сортировки.

Допустимые параметры записи для сортировки:
ID - код записи
FORUM_ID - код форума, на сообщения которого осуществлена подписка
USER_ID - код пользователя-подписчика
TOPIC_ID - код темы, на сообщения которой осуществлена подписка
START_DATE - дата начала подписки
arFilter

Фильтр на возвращаемые записи; представляет собой ассоциативный массив, в котором ключами являются названия параметров записи, а значениями - условия на эти параметры.

Допустимые параметры записи для фильтрации:
ID - код подписки
USER_ID - код пользователя-подписчика
FORUM_ID - код форума, на сообщения которого осуществлена подписка
TOPIC_ID - код темы, на сообщения которой осуществлена подписка
TOPIC_ID_OR_NULL - код темы, на сообщения которой осуществлена подписка, включая пустые значения
NEW_TOPIC_ONLY - флаг, определяющий подписку только на новые темы (допустимые значения Y/N)
LAST_SEND - код последнего отправленного по данной подписке сообщения
LAST_SEND_OR_NULL - код последнего отправленного по данной подписке сообщения, включая пустые значения
PERMISSION - минимальное право на доступ к форуму, на сообщения которого осуществлена подписка

Возвращаемое значение

Возвращяется объект класса CDBResult, каждая запись которого представляет собой массив с ключами

Ключ | Значение
ID | Код подписки.
USER_ID | Код пользователя-подписчика.
FORUM_ID | Код форума, на сообщения которого осуществлена подписка.
TOPIC_ID | Код темы, на сообщения которой осуществлена подписка.
LAST_SEND | Код последнего отправленного по подписке сообщения.
NEW_TOPIC_ONLY | Флаг, означающий подписку только на новые темы (значения Y/N)
SITE_ID | Код сайта, на котором осуществлена подписка.
START_DATE | Дата подписки.
EMAIL | Email адрес пользователя-подписчика.

См. также

  • CDBResult
  • Поля подписки


Класс CForumTopic

CForumTopic - класс для работы с темами форумов.

Методы класса

Метод | Описание
GetList | Получение списка тем с возможностью фильтрации и сортировки.
GetListEx | Получение списка тем (включая связаные данные) с возможностью фильтрации и сортировки.
GetByID | Получение параметров темы по ее коду.
GetByIDEx | Получение параметров темы вместе со связаными данными по ее коду.
Add | Добавление новой темы.
Update | Изменение параметров темы.
Delete | Удаление темы.
CanUserAddTopic | Всесторонне проверяет, может ли пользователь добавить новую тему.
CanUserUpdateTopic | Всесторонне проверяет, может ли пользователь изменить тему.
CanUserDeleteTopic | Всесторонне проверяет, может ли пользователь удалить тему.
GetNeighboringTopics | Возвращает для данной темы коды предыдущей и следующей тем.
MoveTopic2Forum | Переносит тему в другой форум.


Add

CForumTopic::Add

int
Add(
 array arFields
);

Создает новую тему с параметрами, указанными в массиве arFields. Возвращает код созданной темы.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей темы. Обязательные поля должны быть заполнены.

Возвращаемое значение

Возвращает код созданной темы. В случае ошибки добавления возвращает False.

См. также

  • Поля темы
  • Перед добавлением темы следует проверить возможность добавления методом CForumTopic::CanUserAddTopic
  • Для добавления и изменения сообщения и темы рекомендуется пользоваться высокоуровневой функцией ForumAddMessage


CanUserAddTopic

CForumTopic::CanUserAddTopic

bool
CanUserAddTopic(
 int FID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, добавить новую тему в форум FID.

Параметры функции

Параметр | Описание
FID | Код форума, в который пользователь хочет добавить тему.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на добавление темы. В противном случае возвращается значение false.

См. также

  • CForumTopic::CanUserUpdateTopic
  • CForumTopic::CanUserDeleteTopic

Примеры использования

<?
if (CForumTopic::CanUserAddTopic($FID,
                                 $USER->GetUserGroupArray(),
                                 $USER->GetID()))
{
    echo "You can add topic!";
}
?>


CanUserDeleteTopic

CForumTopic::CanUserDeleteTopic

bool
CanUserDeleteTopic(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, удалить тему с кодом ID.

Параметры функции

Параметр | Описание
ID | Код темы, которую пользователь хочет удалить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на удаление темы. В противном случае возвращается значение false.

См. также

  • CForumTopic::CanUserAddTopic
  • CForumTopic::CanUserUpdateTopic

Примеры использования

<?
if (CForumTopic::CanUserDeleteTopic($ID, $USER->GetUserGroupArray(), $USER->GetID()))
{
    CForumTopic::Delete($ID);
}
?>


CanUserUpdateTopic

CForumTopic::CanUserUpdateTopic

bool
CanUserUpdateTopic(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, изменить тему с кодом ID.

Параметры функции

Параметр | Описание
ID | Код темы, которую пользователь хочет изменить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на изменение темы. В противном случае возвращается значение false.

См. также

  • CForumTopic::CanUserAddTopic
  • CForumTopic::CanUserDeleteTopic

Примеры использования

<?
if (CForumTopic::CanUserUpdateTopic($ID, $USER->GetUserGroupArray(), $USER->GetID()))
{
    echo "You can modify this topic!";
}
?>


Delete

CForumTopic::Delete

bool
Delete(
 int ID
);

Удаляет тему с кодом ID.

Параметры функции

Параметр | Описание
ID | Код темы, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.

См. также

  • Перед удалением темы следует проверить возможность удаления методом CForumTopic::CanUserDeleteTopic


GetByID

CForumTopic::GetByID

array
GetByID(
 int ID
);

Возвращает массив параметров темы по ее коду ID. Результаты вызова функции кешируются, поэтому повторные вызовы метода для одной и той же темы не требуют дополнительного обращения к базе данных (при условии, что кеш не сбросился в результате изменения параметров темы).

Параметры функции

Параметр | Описание
ID | Код темы.

Возвращаемое значение

Массив параметров темы. Если тема не найдена, то возвращается значение false.

См. также

  • Поля темы

Примеры использования

<?
$arTopic = CForumTopic::GetByID($TID);
if ($arTopic)
{
  $FID = IntVal($arTopic["FORUM_ID"]);
}
?>


GetByIDEx

CForumTopic::GetByIDEx

array
GetByIDEx(
 int ID
);

Возвращает массив параметров темы, а так же сопутствующие параметры, по ее коду ID.

Параметры функции

Параметр | Описание
ID | Код темы.

Возвращаемое значение

Массив параметров темы, включая сопутствующие. Если тема не найдена, то возвращается значение false.

См. также

  • Поля темы

Примеры использования

<?
// Распечатаем на экран все возвращаемые параметры темы
$arTopic = CForumTopic::GetByIDEx($TID);
if ($arTopic)
{
  echo "<pre>";
  print_r($arTopic);
  echo "</pre>";
}
?>


GetList

CForumTopic::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter [,
 bool bCount [,
 int iNum]]]]
);

Возвращает список тем по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID темы;
TITLE - заголовок темы;
STATE - состояние темы;
USER_START_ID - ID пользователя, который создал тему;
USER_START_NAME - имя пользователя, который создал тему;
START_DATE - дата создания темы;
POSTS - количество ответов в теме;
VIEWS - количество просмотров темы;
APPROVED - опубликованность темы;
LAST_POST_DATE - дата последнего сообщения в теме;
SORT - индекс сортировки;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("SORT"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
STATE - состояние темы;
FORUM_ID - ID форума;
ID - ID темы;
APPROVED - опубликованность;
LAST_POST_DATE - дата последнего сообщения в теме;

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.
bCount | Если параметр равен True, то возвращается только количество тем, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.
iNum | Ограничение числа возвращаемых записей. Если параметр iNum отличен от нуля, то возвращается не более iNum записей. Поддерживается не для всех баз данных. Если параметр не поддерживается, то его установки игнорируются. Необязательный. По умолчанию равен 0.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля темы

Примеры использования

<?
// выберем все опубликованные темы форума с кодом $FID,
// отсортированные сначала по индексу сортировки, а потом
// по дате последнего сообщения в теме
$db_res = CForumTopic::GetList(array("SORT"=>"ASC", "LAST_POST_DATE"=>"DESC"), array("FORUM_ID"=>$FID));
while ($ar_res = $db_res->Fetch())
{
  echo $ar_res["TITLE"]."<br>";
}
?>


GetListEx

CForumTopic::GetListEx

CDBResult
GetListEx(
 [array arOrder [,
 array arFilter [,
 bool bCount [,
 int iNum]]]]
);

Возвращает список тем (включая связаные данные) по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр | Описание
arOrder | Массив вида Array(by1=>order1[, by2=>order2 [, ..]]). Подробное описание параметра смотрите в описании функции CForumTopic::GetList.
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...]).
Подробное описание параметра смотрите в описании функции CForumTopic::GetList.
bCount | Если параметр равен True, то возвращается только количество сообщений, которое соответствует установленному фильтру. Необязательный. По умолчанию равен False.
iNum | Ограничение числа возвращаемых записей. Если параметр iNum отличен от нуля, то возвращается не более iNum записей. Поддерживается не для всех баз данных. Если параметр не поддерживается, то его установки игнорируются. Необязательный. По умолчанию равен 0.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля темы

Примеры использования

<?
// выберем все опубликованные темы форума с кодом $FID,
// отсортированные сначала по индексу сортировки, а потом
// по дате последнего сообщения в теме
$db_res = CForumTopic::GetList(array("SORT"=>"ASC", "LAST_POST_DATE"=>"DESC"), array("FORUM_ID"=>$FID));
while ($ar_res = $db_res->Fetch())
{
  echo "<pre>";
  print_r($ar_res);
  echo "</pre><br>";
}
?>


GetNeighboringTopics

CForumTopic::GetNeighboringTopics

array
CForumTopic::GetNeighboringTopics(
 int TID,
 array arUserGroups
);

Функция для темы с кодом TID возвращает коды предыдущей и следующей тем (соседних тем) форума в сортировке по дате последнего сообщения (стандартная сортировка) с учётом прав на доступ групп пользователей arUserGroups.

Параметры функции

Параметр | Описание
TID | Код темы, соседей которой необходимо получить.
arUserGroups | Массив кодов групп пользователей для учета прав на доступ. Обычно годы групп, которым принадлежит текущий пользователь.

Возвращаемые значения

Функция возвращает массив из двух элементов, первым из которых является код предадущей темы, а вторым - следующей. Если какого-либо из соседей для данной темы не существует, то вместо кода соответствующего соседа возвращается значение 0.

Пример использования

<?
// Выведем ссылки на соседние темы для темы TID с учётом прав
// текущего пользователя

list($iPREV_TOPIC, $iNEXT_TOPIC) =
    CForumTopic::GetNeighboringTopics($TID,
                                      $USER->GetUserGroupArray());

if ($iPREV_TOPIC > 0)
   echo "<a href=\"read.php?FID=".$FID."&TID=".$iPREV_TOPIC."\">";
echo "Предыдущая тема";

if ($iPREV_TOPIC > 0)
   echo "</a>";
echo " | ";

if ($iNEXT_TOPIC > 0)
   echo "<a href=\"read.php?FID=".$FID."&TID=".$iNEXT_TOPIC."\">";
echo "Следующая тема";

if ($iNEXT_TOPIC > 0)
   echo "</a>";
?>


MoveTopic2Forum

CForumTopic::MoveTopic2Forum

bool
CForumTopic::MoveTopic2Forum(
 int TID,
 int FID
);

Функция переносит тему с кодом TID в форум с кодом FID

Параметры функции

Параметр | Описание
TID | Код темы, которую необходимо перенести.
FID | Код форума, в который необходимо перенести тему.

Возвращаемые значения

Функция возвращает True в случае успешного переноса и False - в противном случае


Update

CForumTopic::Update

int
Update(
 int ID,
 array arFields [,
 bool skip_counts]
);

Изменяет параметры существующей темы с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемой темы.

Параметры функции

Параметр | Описание
ID | Код темы, параметры которой необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей темы.
skip_counts | Если этот параметр установлен в значение true, то при изменении темы не будут автоматически обсчитаны статистические данные. Это ускоряет работу функции, но создает логические ошибки в данных. Необязательный. По умолчанию равен False.

Возвращаемое значение

Возвращает код измененной темы. В случае ошибки изменения возвращает False.

См. также

  • Поля темы
  • Перед изменением темы следует проверить возможность изменения методом CanUserUpdateTopic
  • Для добавления и изменения сообщения и темы можно воспользоваться высокоуровневой функцией ForumAddMessage


Класс CForumUser

CForumUser - класс для работы с профайлами посетителей форума

Методы класса

Метод | Описание
GetList | Получение списка профайлов с возможностью фильтрации и сортировки.
GetByID | Получение параметров профайла по его коду.
GetByUSER_ID | Получение параметров профайла по коду пользователя, которому профайл принадлежит.
GetByIDEx | Получение параметров профайла вместе со связаными данными по его коду.
Add | Добавление нового профайла.
Update | Изменение параметров профайла.
Delete | Удаление профайла.
CanUserAddUser | Всесторонне проверяет, может ли пользователь добавить новый профайл.
CanUserUpdateUser | Всесторонне проверяет, может ли пользователь изменить профайл.
CanUserDeleteUser | Всесторонне проверяет, может ли пользователь удалить профайл.
GetUserRank | Возвращает звание пользователя.


Add

CForumUser::Add

int
Add(
 array arFields [,
 string strUploadDir ]
);

Создает новый профайл с параметрами, указанными в массиве arFields. Возвращает код созданного профайла.

Параметры функции

Параметр | Описание
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей профайла пользователя. Обязательные поля должны быть заполнены.
strUploadDir | Каталог для загрузки файлов. Должен быть задан относительно главного каталога для загрузки. Необязательный. По умолчанию равен "forum".

Возвращаемое значение

Возвращает код созданного профайла. В случае ошибки добавления возвращает False.

См. также

  • Поля профайла
  • Перед добавлением профайла следует проверить возможность добавления методом CForumUser::CanUserAddUser


CanUserAddUser

CForumUser::CanUserAddUser

bool
CanUserAddUser(
 array arUserGroups
);

Всесторонне проверяет, может ли пользователь, входящий в группы arUserGroups, добавить новый профайл.

Параметры функции

Параметр | Описание
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на добавление профайла. В противном случае возвращается значение false.

См. также

  • CForumUser::CanUserUpdateUser
  • CForumUser::CanUserDeleteUser


CanUserDeleteUser

CForumUser::CanUserDeleteUser

bool
CanUserDeleteUser(
 int ID,
 array arUserGroups
);

Всесторонне проверяет, может ли пользователь, входящий в группы arUserGroups, удалить профайл с кодом ID.

Параметры функции

Параметр | Описание
ID | Код профайла, который пользователь хочет удалить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на удаление профайла. В противном случае возвращается значение false.

См. также

  • CForumUser::CanUserAddUser
  • CForumUser::CanUserUpdateUser


CanUserUpdateUser

CForumUser::CanUserUpdateUser

bool
CanUserUpdateUser(
 int ID,
 array arUserGroups,
 int iUserID
);

Всесторонне проверяет, может ли пользователь с кодом iUserID, входящий в группы arUserGroups, изменить профайл с кодом ID.

Параметры функции

Параметр | Описание
ID | Код профайла, который пользователь хочет изменить.
arUserGroups | Массив групп, в которые входит пользователь. Для текущего пользователя он возвращается методом $USER->GetUserGroupArray()
iUserID | Код пользователя. Для текущего пользователя он возвращается методом $USER->GetID()

Возвращаемое значение

Возвращает True, если пользователь имеет все права на изменение профайла. В противном случае возвращается значение false.

См. также

  • CForumUser::CanUserAddUser
  • CForumUser::CanUserDeleteUser


Delete

CForumUser::Delete

bool
Delete(
 int ID
);

Удаляет профайл с кодом ID.

Параметры функции

Параметр | Описание
ID | Код профайла, которую необходимо удалить.

Возвращаемое значение

Возвращает True в случае успешного удаления, в противном случае возвращает False.

См. также

  • Перед удалением профайла следует проверить возможность удаления методом CForumUser::CanUserDeleteUser


GetByID

CForumUser::GetByID

array
GetByID(
 int ID
);

Возвращает массив параметров профайла по его коду ID. Результаты вызова функции кешируются, поэтому повторные вызовы метода для одного и того же профайла не требуют дополнительного обращения к базе данных (при условии, что кеш не сбросился в результате изменения параметров профайла).

Параметры функции

Параметр | Описание
ID | Код профайла.

Возвращаемое значение

Массив параметров профайла. Если профайл не найден, то возвращается значение false.

См. также

  • Поля профайла


GetByIDEx

CForumUser::GetByIDEx

array
GetByIDEx(
 int ID
);

Возвращает массив параметров профайла, а так же сопутствующие параметры, по его коду ID.

Параметры функции

Параметр | Описание
ID | Код профайла.

Возвращаемое значение

Массив параметров профайла, включая сопутствующие. Если профайл не найден, то возвращается значение false.

См. также

  • Поля профайла


GetByUSER_ID

CForumUser::GetByUSER_ID

array
GetByUSER_ID(
 int USER_ID
);

Возвращает массив параметров профайла по коду USER_ID пользователя, которому этот профайл принадлежит. Результаты вызова функции кешируются, поэтому повторные вызовы метода для одного и того же пользователя не требуют дополнительного обращения к базе данных (при условии, что кеш не сбросился в результате изменения параметров профайла).

Параметры функции

Параметр | Описание
USER_ID | Код пользователя.

Возвращаемое значение

Массив параметров профайла. Если профайл не найден, то возвращается значение false.

См. также

  • Поля профайла


GetList

CForumUser::GetList

CDBResult
GetList(
 [array arOrder [,
 array arFilter]]
);

Возвращает список профайлов по фильтру arFilter, отсортированый в соответствии с arOrder.

Параметры функции

Параметр Описание
arOrder Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где

by - поле для сортировки, может принимать значения
ID - ID профайла;
USER_ID - ID пользователя;
SHOW_NAME - показывать имя вместо логина;
NUM_POSTS - количество сообщений;
LAST_POST - ID последнего сообщения;
NAME - имя пользователя;
LAST_NAME - фамилия пользователя;
LOGIN - логин;
LAST_VISIT - дата последнего посещения;

order - порядок сортировки, может принимать значения
ASC - по возрастанию;
DESC - по убыванию;

Необязательный. По умолчанию равен Array("ID"=>"ASC")
arFilter массив вида array("фильтруемое поле"=>"значения фильтра" [, ...])
"фильтруемое поле" может принимать значения
ID - ID профайла;
USER_ID - ID пользователя;
RANK_ID - ID звания пользователя;
SHOW_NAME - показывать имя вместо логина;
NUM_POSTS - количество сообщений;
ALLOW_POST - разрешено писать сообщения (т.е. не забанен);

фильтруемое поле может иметь содержать перед названием тип проверки фильтра
"!" - не равно
"<" - меньше
"<=" - меньше либо равно
">" - больше
">=" - больше либо равно

Необязательное. По умолчанию записи не фильтруются.

Возвращаемое значение

Возвращается объект CDBResult

См. также

  • CDBResult
  • Поля профайла


Update

CForumUser::Update

int
Update(
 int ID,
 array arFields [,
 string strUploadDir ]
);

Изменяет параметры существующего профайла с кодом ID на параметры, указанные в массиве arFields. Возвращает код изменяемого профайла.

Параметры функции

Параметр | Описание
ID | Код профайла, параметры которого необходимо изменить.
arFields | Массив вида Array(field1=>value1[, field2=>value2 [, ..]]), где field - название поля; value - значение поля. Поля перечислены в списке полей профайла.
strUploadDir | Каталог для загрузки файлов. Должен быть задан относительно главного каталога для загрузки. Необязательный. По умолчанию равен "forum".

Возвращаемое значение

Возвращает код измененного профайла. В случае ошибки изменения возвращает False.

См. также

  • Поля профайла
  • Перед изменением профайла следует проверить возможность изменения методом CForumUser::CanUserUpdateUser


GetUserRank

CForumUser::GetUserRank

array
CForumUser::GetUserRank(
 int USER_ID,
 string strLang = false
);

Функция возвращает параметры звания пользователя по его коду USER_ID. Если Установлено значение второго параметра strLang, то возвращаются в том числе и языкозависимые параметры.

Параметры функции

Параметр | Описание
USER_ID | Код пользователя.
strLang | Код языка. Если этот параметр установлен, то возвращаются в том числе и языкозависимые параметры звания на языке с кодом strLang. Если параметр не установлен (равен false), то возвращаются только языконезависимые параметры.

Возвращаемые значения

Возвращяется ассоциативный массив с ключами

Ключ | Значение
ID | Код звания.
MIN_POINTS | Количество баллов, необходимое для получения этого звания.
CODE | Мнемонический код.
VOTES | Количество голосов, которое имеет пользователь с этим званием.
LID | Код языка (если установлен параметр strLang)
NAME | Название звания на языке LID (если установлен параметр strLang)

Пример использования

<?
// Если в глобальных настройках форума разрешено показывать звания
if (COption::GetOptionString("forum", "SHOW_VOTES", "Y")=="Y")
{
   // Выведем название звания текущего пользователя на текущем языке
   $arUserRank = CForumUser::GetUserRank($USER->GetID(), LANGUAGE_ID);
   echo $arUserRank["NAME"];
}
?>


Класс CForumNew

CForumUserPoints - класс для работы с голосованиями пользователей форума за других пользователей форума.

Методы класса

Метод | Описание
GetList | Получение списка голосований с возможностью фильтрации и сортировки.
GetByID | Получение параметров голосования по его коду.
Add | Добавление нового голосования одного из посетителей форума за другого.
Update | Изменение параметров голосования.
Delete | Удаление голосования.


Add

CForumUserPoints::Add

bool
CForumUserPoints::Add(
 array arFields
);

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

Параметры функции

Параметр | Описание
arFields | Ассоциативный массив значений параметров записи.

Возвращаемые значения

Функция возвращает код добаленной записи или false в случае ошибки.

Пример использования

<?
// Текущий пользователь отдает пользователю с кодом $UID 10 голосов

$arFields = array(
   "POINTS" => 10,
   "FROM_USER_ID" => $USER->GetID(),
   "TO_USER_ID" => $UID
);

if (CForumUserPoints::Add($arFields))
   echo "Голоса успешно отданы";
else
   echo "Ошибка голосования";
?>


Delete

CForumUserPoints::Delete

bool
CForumUserPoints::Delete(
 int FROM_USER_ID,
 int TO_USER_ID
);

Функция удаляет из голосования голоса, отданные пользователем с кодом FROM_USER_ID пользователю с кодом TO_USER_ID.

Параметры функции

Параметр | Описание
FROM_USER_ID | Код пользователя, отдавшего голос.
TO_USER_ID | Код пользователя, которому был отдан голос.

Возвращаемые значения

Функция возвращает True в случае успешного удаления и False - в случае ошибки.


GetByID

CForumUserPoints::GetByID

array
CForumUserPoints::GetByID(
 int FROM_USER_ID,
 int TO_USER_ID
);

Функция возвращает массив параметров голосования пользователя с кодом FROM_USER_ID за пользователя с кодом TO_USER_ID.

Параметры функции

Параметр | Описание
FROM_USER_ID | Код пользователя, который отдал голос.
TO_USER_ID | Код пользователя, за которого отдали голос.

Возвращаемые значения

Возвращает ассоциативный массив с ключами.

Ключ | Значение
FROM_USER_ID | Код пользователя, который отдал голос.
TO_USER_ID | Код пользователя, за которого отдали голос.
POINTS | Количество отданных голосов.
DATE_UPDATE | Дата последнего изменения записи.

Пример использования

<?
// Выведем, сколько голосов отдал текущий пользователь
// за пользователя с кодом $AID
$arUserPoints = CForumUserPoints::GetByID($USER->GetID(), $AID);
if ($arUserPoints)
{
   echo "Вы отдали за этого пользователя ".$arUserPoints["POINTS"]. " голосов";
}
?>


GetList

CForumUserPoints::GetList

CDBResult
CForumUserPoints::GetList(
 array arOrder = array("TO_USER_ID"=>"ASC"),
 array arFilter = array()
);

Возвращает голосования за посетителей форума, которые удовлетворяют фильтру arFilter, упорядоченные в соответствии с порядком arOrder.

Параметры функции

Параметр Описание
arOrder

Порядок сортировки записей; представляет собой ассоциативный массив, в котором ключами являются названия параметров голосования, а значениями - направления сортировки.

Допустимые параметры голосования для сортировки:
FROM_USER_ID - код голосовавшего посетителя
TO_USER_ID - код посетителя, за которого голосовали
POINTS - количество отданных голосов
DATE_UPDATE - дата последнего изменения записи

arFilter

Фильтр на возвращаемые голосования; представляет собой ассоциативный массив, в котором ключами являются названия параметров голосования, а значениями - условия на эти параметры.

Допустимые параметры голосования для фильтрации:
FROM_USER_ID - код голосовавшего посетителя
TO_USER_ID - код посетителя, за которого голосовали

Возвращаемые значения

Возвращяется объект класса CDBResult, каждая запись которого представляет собой массив с ключами.

Ключ | Значение
FROM_USER_ID | Код пользователя, который отдал голос.
TO_USER_ID | Код пользователя, за которого отдали голос.
POINTS | Количество отданных голосов.
DATE_UPDATE | Дата последнего изменения записи.


Update

CForumUserPoints::Update

bool
CForumUserPoints::Update(
 int FROM_USER_ID,
 int TO_USER_ID,
 array arFields
);

Изменяет параметры голосования пользователя с кодом FROM_USER_ID за пользователя с кодом TO_USER_ID на значения, указанные в массиве arFields.

Параметры функции

Параметр | Описание
FROM_USER_ID | Пользователь, который голосовал.
TO_USER_ID | Пользователь, за которого голосовали.
arFields | Массив новых значений параметров голосования.

Возвращаемые значения

Возвращает True в случае успешного изменения параметров голосования и False - в противном случае.

Пример использования

<?
// Изменим количество голосов, отданных текущим пользователем
// за пользователя с кодом $UID на 53
$arFields = array("POINTS" => 53);
if (CForumUserPoints::Update($USER->GetID(), $UID, $arFields))
   echo "Голосования успешно изменено";
else
   echo "Ошибка изменения голосования";
?>


textParser

textParser - класс, предназначенный для форматирования сообщений форума. Осуществляет замену спецсимволов и заказных тегов на реальные HTML- теги, обработку ссылок, отображение смайлов.

Методы класса

Метод | Описание
convert | Функция форматирования сообщения.


textParser::convert

string
convert(
 string strPost_message,
 array arAllow
);

Функция форматирования текста.

Параметры функции

Параметр | Описание
strPost_message | Форматируемое сообщение.
arAllow Массив параметров форматирования сообщения. Имеет структуру, идентичную массиву ALLOW - переменной класса CForum. Содержит следующие параметры, которые могут принимать значения Y и N:
  • HTML - в тексте могут содержаться любые HTML теги,
  • ANCHOR - разрешен тег <a>,
  • BIU - разрешены теги <b>, <i>, <u>,
  • IMG - разрешен тег <img>,
  • QUOTE - разрешен тег цитирования <quote>,
  • CODE - разрешен тег показа кода <code>,
  • FONT - разрешен тег <font>,
  • LIST - разрешены теги <ul>, <li>,
  • SMILES - показ смайликов в виде картинок,
  • NL2BR - заменять переводы каретки на тег <br> при разрешении принимать любые HTML теги.

Примеры использования

<?
$parser = new textParser();  // создаем экземпляр класса textParser
$arAllow = $Forum->ALLOW;    // заполняем массив параметров форматирования
                             // из массива переменной-члена класса CForum,
                             // эти два массива имеют идентичную структуру
$arAllow["SMILES"] = "N";    // переопределяем (запрещаем) показ смайликов
                             // в виде картинок
echo $parser->convert($strMessage, $arAllow);  // форматируем и выводим сообщение
?>


Функции для использования в публичной части

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

Функция | Описание
ForumCurrUserPermissions | Возвращает права текущего посетителя на доступ к форуму.
ForumSubscribeNewMessages | Подписка текущего пользователя на новые сообщения заданной темы.
ForumAddMessage | Добавление и изменение нового сообщения и темы.
ForumModerateMessage | Публикация и скрытие сообщения.


ForumAddMessage

int
ForumAddMessage(
 string MESSAGE_TYPE,
 int FID,
 int TID,
 int MID,
 array arFieldsG,
 &string strErrorMessage,
 &string strOKMessage [,
 int iFileSize]
);

Добавляет или изменяет сообщение (и возможно тему) форума. В переменную, передаваемую в параметре strErrorMessage дописывает ошибки, которые произошли при работе функции. В переменную, передаваемую в параметре strOKMessage дописывает сообщения об успехах, которые произошли при работе функции.

Параметры функции

Параметр | Описание
MESSAGE_TYPE | Тип работы функции. Может принимать следующие значения: NEW - создание новой темы и добавление в нее сообщения, EDIT - изменение сообщения (и темы, если на это есть права), REPLY - новое сообщение в существующую тему.
FID | Код форума, в который добавляется новая тема. Актуален для типа работы NEW, в остальных случаях восстанавливается из кода темы.
TID | Код темы, в которую добавляется сообщение. Актуален для типа работы REPLY, в остальных случаях восстанавливается из кода сообщения. Для добавления новой темы должен быть равен 0.
MID | Код сообщения, которое необходимо изменить. Актуален для типа работы EDIT. В остальных случаях должен быть равен 0.
arFieldsG | Массив параметров сообщения и темы. Должен содержать следующие ключи POST_MESSAGE - тело сообщения, TITLE - заголовок темы (если NEW или EDIT и разрешено изменение темы), AUTHOR_NAME - имя автора сообщения, DESCRIPTION - описание темы (если NEW или EDIT и разрешено изменение темы), ICON_ID - иконка темы (если NEW или EDIT и разрешено изменение темы), USE_SMILES - разрешено заменять смайлики на их графические изображения, ATTACH_IMG - присоединенный файл - массив со структурой элементов массива $_FILES
strErrorMessage | Переменная, в которую функция дописывает сообщения об ошибках, которые произошли при ее работе.
strOKMessage | Переменная, в которую функция дописывает сообщения об успехах, которые произошли при ее работе.
iFileSize | Максимальный размер загружаемых файлов в байтах. Не обязательный параметр, по умолчанию равен 50000 (байт).

Возвращаемое значение

Возвращает ID сообщения, если функция отработала без ошибок. В противном случае возвращает False.


ForumCurrUserPermissions

char(1)
ForumCurrUserPermissions(
 int FID
);

Возвращает код права текущего посетителя на доступ к форуму по его коду FID.

Параметры функции

Параметр | Описание
FID | Код форума.

Возвращаемое значение

Возвращает код права текущего посетителя на доступ к форуму. Список возможных значений:
  • A - нет доступа - текущий пользователь не должен видеть этого форума
  • E - чтение - текущий пользователь может читать этот форум, но не может писать в него
  • I - ответ - текущий пользователь может отвечать на существующие в форуме темы, но не может создавать новые темы
  • M - новая тема - текущий пользователь может как отвечать на существующие темы, так и создавать новые
  • Q - модерирование - текущий пользователь может модерировать форум, т.е. производить те действия, которые не повлекут реальной потери данных. Например, модератор может скрыть или показать сообщение, но не может отредактировать или удалить его. Модераторы получают копии всех сообщений форума по почте
  • U - редактирование - текущий пользователь может в полном объеме управлять чужими сообщениями на форуме
  • Y - полный доступ - текущий пользователь имеет полный доступ к форуму, включая доступ к настройкам форума и прав доступа
Администраторы сайта всегда имеют полный доступ ко всем форумам.

См. также

  • Пользовательская документация, раздел Сервисы > Форум > Создание и редактирование форума.


ForumModerateMessage

bool
ForumModerateMessage(
 int MID,
 char(1) TYPE,
 &string strErrorMessage,
 &string strOKMessage
);

Публикует или скрывает сообщение с кодом MID. В переменную, передаваемую в параметре strErrorMessage дописывает ошибки, которые произошли при работе функции. В переменную, передаваемую в параметре strOKMessage дописывает сообщения об успехах, которые произошли при работе функции.

Параметры функции

Параметр | Описание
MID | Код сообщения для публикации или скрытия.
TYPE | Возможные значения: "SHOW" - публиковать сообщение, "HIDE" - скрыть сообщение.
strErrorMessage | Переменная, в которую функция дописывает сообщения об ошибках, которые произошли при подписке.
strOKMessage | Переменная, в которую функция дописывает сообщения об успехах, которые произошли при подписке.

Возвращаемое значение

Возвращает True, если работа функции завершена без ошибок. В противном случае возвращает False.


ForumSubscribeNewMessages

bool
ForumSubscribeNewMessages(
 int FID,
 int TID,
 &string strErrorMessage,
 &string strOKMessage
);

Подписывает текущего посетителя на новые сообщения темы TID, если она задана. Иначе подписывает на новые сообщения всего форума FID. В переменную, передаваемую в параметре strErrorMessage дописывает ошибки, которые произошли при подписке. В переменную, передаваемую в параметре strOKMessage дописывает сообщения об успехах, которые произошли при подписке.

Параметры функции

Параметр | Описание
FID | Код форума, на сообщения которого подписывается текущий пользователь.
TID | Код темы. Если задан, то происходит подписка только на новые сообщения этой темы.
strErrorMessage | Переменная, в которую функция дописывает сообщения об ошибках, которые произошли при подписке.
strOKMessage | Переменная, в которую функция дописывает сообщения об успехах, которые произошли при подписке.

Возвращаемое значение

Возвращает True, если подписка прошла успешно. В противном случае возвращает False.