Основные сведения
Главный модуль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, поэтому фильтрация по нескольким значениям множественного свойства может дать дублирование.
- Поля перечисленные для сортировки будут автоматически добавлены в параметр arSelectFields или в arGroupBy, если указана группировка записей.
Параметры функции
| Параметр | Описание |
|---|---|
| arOrder | Массив вида Array(by1=>order1[, by2=>order2 [, ..]]), где by - поле для сортировки, может принимать значения:
|
| arFilter | Массив вида array("фильтруемое поле"=>"значения фильтра" [, ...]). "фильтруемое поле" может принимать значения:
Необязательное. По умолчанию записи не фильтруются. |
| arGroupBy | Массив полей для группировки элемента. Если поля указаны, то выборка по ним группируется (при этом параметр arSelectFields будет проигнорирован), а в результат добавляется поле CNT - количество сгруппированных элементов. Если указать в качестве arGroupBy пустой массив, то функция вернет количество элементов CNT по фильтру. Группировать можно по полям элемента, а также по значениям его свойств. Для этого в качестве одного из полей группировки необходимо указать PROPERTY_<PROPERTY_CODE>, где PROPERTY_CODE - код свойства или мнемонический код.
Необязательное. По умолчанию false - записи не группируются. |
| arNavStartParams | Параметры для постраничной навигации и ограничения количества выводимых элементов. массив вида "Название параметра"=>"Значение", где название параметра
"nTopCount" - ограничить количество сверху "bShowAll" - разрешить вывести все элементы при постраничной навигации "iNumPage" - номер страницы при постраничной навигации "nPageSize" - количество элементов на странице при постраничной навигации "nElementID" - ID элемента который будет выбран вместе со своими соседями. Количество соседей определяется параметром nPageSize. Например: если nPageSize равно 2-м, то будут выбраны максимум 5-ть элементов. Соседи определяются порядком сортировки заданным в параметре arOrder (см. выше) . При этом действуют следующие ограничения:
Если передать в параметр arNavStartParams пустой массив, то ставится ограничение на 10 выводимых элементов. |
| arSelectFields | Массив возвращаемых полей элемента. Список полей элемента, а также можно сразу выводить значения его свойств. Обязательно должно быть использовано поле IBLOCK_ID, иначе не будет работать корректно. Кроме того, также в качестве одного из полей необходимо указать PROPERTY_<PROPERTY_CODE>, где PROPERTY_CODE - ID или мнемонический код. В результате будет выведены значения свойств элемента в виде полей PROPERTY_<PROPERTY_CODE>_VALUE - значение; PROPERTY_<PROPERTY_CODE>_ID - код значения у элемента; PROPERTY_<PROPERTY_CODE>_ENUM_ID - код значения (для свойств типа список).
При установленном модуле торгового каталога можно выводить и цены элемента. Для этого в качестве одного из полей необходимо указать CATALOG_GROUP_<PRICE_CODE>, где PRICE_CODE - ID типа цены. Так же есть возможность выбрать поля элементов по значениям свойства типа "Привязка к элементам". Для этого необходимо указать PROPERTY_<PROPERTY_CODE>.<FIELD>, где PROPERTY_CODE - ID или мнемонический код свойства привязки, а FIELD - поле указанного в привязке элемента. См. ниже "Поля связанных элементов для сортировки". Можно выбрать и значения свойств элементов по значениям свойства типа "Привязка к элементам". Для этого необходимо указать PROPERTY_<PROPERTY_CODE>.PROPERTY_<PROPERTY_CODE2>, где PROPERTY_CODE - ID или мнемонический код свойства привязки, а PROPERTY_CODE2 - свойство указанного в привязке элемента. По умолчанию выводить все поля. Примечание 1: если в массиве используются свойство, являющееся множественным, то для элементов, где используются несколько значений этого свойства, будет возвращено несколько записей вместо одной. Для решения этой проблемы инфоблоки нужно перевести в Режим хранения свойств в отдельных таблицах, в этом случае для свойства будет отдаваться массив значений. Либо можно не указывать свойства в параметрах выборки, а получать их значения на каждом шаге перебора выборки с помощью _CIBElement::GetProperties(). Примечание 2: Если в массиве указаны поля DETAIL_PAGE_URL, SECTION_PAGE_URL или LIST_PAGE_URL, то поля необходимые для правильной подстановки шаблонов URL'ов будут выбраны автоматически. Но только если не была задана группировка. Примечание 3: если необходимо выбрать данные о рейтингах для выбранных элементов, то для этого в массиве необходимо указать следующие поля: RATING_TOTAL_VALUE, RATING_TOTAL_VOTES, RATING_TOTAL_POSITIVE_VOTES, RATING_TOTAL_NEGATIVE_VOTES, RATING_USER_VOTE_VALUE. |
Рассмотрим несколько частных случаев фильтрации:
- $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 - при фильтрации элементов проверяется наличие заданной подстроки свойствах.
Фильтр со сложной логикой
Параметр arFilter может содержать вложенные фильтры. Ключом массива вложенного фильтра должно быть число. Например:- $arFilter = array("NAME" => "A%", array(..<здесь пары "поле" => "фильтр">...), "IBLOCK_ID" => $IBLOCK_ID);
Так же условия фильтра могут объединяться не только по условию "И", но и "ИЛИ". Для этого в качестве фильтруемого поля надо указать "LOGIC". Может принимать два значения: "AND" и "OR". По умолчанию - "AND". Например выберем маленькие зрелые и большие не зрелые апельсины:
$arFilter = array(
"IBLOCK_ID" => $IBLOCK_ID,
"SECTION_CODE" => "orange",
"INCLUDE_SUBSECTIONS" => "Y",
array(
"LOGIC" => "OR",
array("<PROPERTY_RADIUS" => 50, "=PROPERTY_CONDITION" => "Y"),
array(">=PROPERTY_RADIUS" => 50, "!=PROPERTY_CONDITION" => "Y"),
),
);
В этом примере фильтр по свойствам апельсинов является подфильтром инфоблока фруктов.
Поля связанных элементов
- ID - числовой идентификатор элемента;
- TIMESTAMP_X - время последней модификации в полном формате сайта;
- MODIFIED_BY - идентификатор пользователя вносившего последние правки;
- DATE_CREATE - время создания элемента в полном формате сайта
- CREATED_BY - идентификатор пользователя создавшего элемент;
- IBLOCK_ID - числовой идентификатор инфоблока элемента;
- ACTIVE - активность (Y|N);
- ACTIVE_FROM - начало активности в полном формате сайта;
- ACTIVE_TO - окончание активности в полном формате сайта;
- SORT - значение сортировки;
- NAME - имя элемента;
- PREVIEW_PICTURE - идентификатор изображения;
- PREVIEW_TEXT - текст анонса;
- PREVIEW_TEXT_TYPE - тип текста анонса (html|text);
- DETAIL_PICTURE - идентификатор изображения;
- DETAIL_TEXT - детальное описание;
- DETAIL_TEXT_TYPE - тип детального описания (html|text);
- SHOW_COUNTER - счетчик показов;
- SHOW_COUNTER_START - время первого показа элемента в полном формате сайта;
- CODE - символьный код элемента;
- TAGS - теги;
- XML_ID - внешний идентификатор;
- IBLOCK_SECTION_ID - минимальный идентификатор раздела элемента (если задан);
- IBLOCK_TYPE_ID - идентификатор типа инфоблока;
- IBLOCK_CODE - символьный код инфоблока;
- IBLOCK_NAME - название инфоблока;
- IBLOCK_EXTERNAL_ID - внешний код инфоблока;
- DETAIL_PAGE_URL - путь к элементу;
- LIST_PAGE_URL - путь к списку элементов;
Возвращаемое значение
Возвращается объект CIBlockResult.См. также
Примеры использования
<?
$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>";
}
?>
Пользовательские комментарии
Пользовательские комментарии не являются официальной документацией. Ответственность за их использование несет сам пользователь.Добавлять комментарии могут только зарегистрированные пользователи. Сообщения для просмотра появляются после модерации.
 | ||
|
Задача: Получить ID элемента с максимальным количеством просмотров из нескольких инфоблоков.
Решение:
| ||
 |
|
Из системы обнолений:
Версия 8.0.4 Внимание! Изменение логики работы API. Теперь в результате CIBlockElement::GetList с фильтром по CATALOG_SHOP_QUANTITY_* также будут присутствовать товары, для которых не задана цена для требуемого диапазона. |
 | ||
|
Вывести архив из просроченных элементов. (news.list)
| ||
 | ||
|
Задача: Фильтрация "от" и "до" по свойству типа "Дата/Время".
Проблема: Свойство типа Дата/Время хранится в БД как строковое с датой в формате YYYY-MM-DD HH:MI:SS. Решение: Перед фильтрацией обязательно сконвертировать дату из формата сайта в формат, используемый для хранения.
| ||
 | ||||||
Будет работать только для даты формата "дд.мм.гггг чч:мм:сс" Правильнее в "<DATE_ACTIVE_TO" поставить:
Это и есть текущее время в формате сайта.
Вообще не рекомендую пользовать без надобности. Сильно грузит систему. | ||||||
|
| ||
|
Задача: Осуществить выборку элементов инфоблока, чтобы в возвращаемом результате находилось 5 случайных элементов.
Решение:
| ||
|
|
|
Задача: настроить фильтр для свойства типа Дата/Время.
Решение: Свойство типа Дата/Время "внутре" хранится как строковое с датой в формате YYYY-MM-DD HH:MI:SS. Соответственно сортировка по значению такого свойства будет работать корректно, а вот значение для фильтрации формируется примерно так: $cat_filter[">"."PROPERTY_available"] = date("Y-m-d"); |
 |
|
Недавно обнаружил, что если задать разным свойствам одинаковый символьный код, но в разном регистре, то при работе сортировки по одному из свойств (например, PROPERTY_rating) будет возникать ошибочная ситуация (элементы в списке задублируются, сортировки не будет).
|
|
| ||
|
В первом примере использования метода можно добавить вывод свойств для каждого элемента. Удобно использовать, не прибегая к GetPropery.
| ||
|
|
|
Есть еще такое полезное поле фильтрации как CATALOG_QUANTITY - количество товара на складе, для инфоблоков-каталогов товара.
|