GetList
Description
CIBlockResult CIBlockElement::GetList( array arOrder = Array("SORT"=>"ASC"), array arFilter = Array(), mixed arGroupBy = false, mixed arNavStartParams = false, array arSelectFields = Array() );
Returns a list of elements filtered by arFilter. Static method.
Important! Starting from Information blocks module version 18.6.200 the method has new options to handle products, with updated method keys. Correspondingly, all CATALOG_***
parameters have deprecated.
Attention: Starting from Information blocks module version 20.5.0, the method no longer processes the keys CHECK_BP_TASKS_PERMISSIONS and TASKSTATUS.
- Intristic limitations of Oracle and MSSQL do not allow to use DISTINCT when filtering by such field types as blob, that's why filtering by several values of multiple property can result in duplicates.
- The fields, listed for sorting will be automatically added to the parameter arSelectFields or to arGroupBy, when entry grouping is specified.
See Also
Parameters
Parameter | Description | Available from version |
---|---|---|
arOrder | Array type: Array(by1=>order1[, by2=>order2 [, ..]]), where by - field for sorting. It can have the following values:
|
|
arFilter | An array of the format Array("filter field"=>"filter
value" [, ...])
where the "filtering field" can be the following:
This parameter is optional. No filtering is performed by default. Remarks The "><" modifier can be used to match the range of values. To specify the range, pass an array whose “key=>value” pairs are the lower and higher range values. For example, the following call returns all elements whose name starts with a character "A" or "B" or is between "D" and "H": $res = CIBlockElement::GetList(Array(), Array("><NAME"=>Array(Array("A", "B"), Array("D", "H")))); |
|
arGroupBy | If this parameter is not false, the returned items are grouped accordingly and the result array includes a CNT key returning
the number of grouped elements; the arSelectFields is ignored. If the arGroupBy is an empty array, the method returns the number of elements in the CNT key. The grouping can be performed by the property values instead of the element fields. To do so, specify PROPERTY_<PROPERTY_CODE> as one of the grouping fields, the PROPERTY_CODE being a property or mnemonic code. Optional. The returned items are not grouped by default (false). |
|
arNavStartParams | These parameters are used to implement breadcrumbs.
This is achieved by passing an array of pairs "parameter=>value" with the following parameters:
The default value is false which specifies to return a full selection. If arNavStartParams is an empty array, the default limit of 10 elements takes effect. |
|
arSelectFields | This array specifies the element fields and/or properties to retrieve. The IBLOCK_ID field must be specified for the method to fetch a correct result. Besides, a field in the format PROPERTY_<PROPERTY_CODE> also needs to be specifies, in which the PROPERTY_CODE is the ID or mnemonic code. This will return the element property values as the keys:
The element fields can be selected by the "Link to elements" property values by specifying PROPERTY_<PROPERTY_CODE>.<FIELD>, here the PROPERTY_CODE is the binding property ID or mnemonic code; the FIELD is the field specified in the binding. See the notes below. The element property values can also be selected by the "Link to elements" property values. Specify the required properties in the format PROPERTY_<PROPERTY_CODE>.PROPERTY_<PROPERTY_CODE2>. Here the PROPERTY_CODE is the binding property ID or mnemonic code; the PROPERTY_CODE2 is the property of a bound element. By default, all the element fields are retrieved. Parameter values are ignored when using the grouping parameter arGroupBy. Note 1: If a multiple property is specified in this parameter, the method will return multiple records for elements that contain more than one values of such property. To fix this problem, the information blocks may be set to store properties in individual tables. In this case, the method will return multiple values as an array. Another approach is to retrieve the properties by calling _CIBElement::GetProperties() on each iteration instead of using the arSelectFields.
Note 2: If this parameter specifies DETAIL_PAGE_URL, SECTION_PAGE_URL or LIST_PAGE_URL, the fields required to resolve the URL templates will be determined automatically unless grouping is in effect. Note 3: To retrieve rating data for the selected elements, use the following keys in this parameter: RATING_TOTAL_VALUE, RATING_TOTAL_VOTES, RATING_TOTAL_POSITIVE_VOTES, RATING_TOTAL_NEGATIVE_VOTES, RATING_USER_VOTE_VALUE.
|
Useful filters
- $arFilter = array("PROPERTY_CML2_SCAN_CODE") =>"" : returns all elements;
- $arFilter = array("PROPERTY_CML2_SCAN_CODE") =>false : returns all elements with empty values;
- $arFilter = array("PROPERTY_CML2_SCAN_CODE") =>"abc" : returns all elements whose scan code maches "abc" exactly;
- $arFilter = array("?PROPERTY_CML2_SCAN_CODE") =>"def" : returns all elements whose scan code contains the substring "def".
- $arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>"" : returns all elements whose CML2_SCAN_CODE property is not empty;
- $arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>false : returns only the elements with non-empty property values;
- $arFilter = array("!PROPERTY_CML2_SCAN_CODE") =>"abc" : returns all elements whose CML2_SCAN_CODE property value is not "abc";
- $arFilter = array("!?PROPERTY_CML2_SCAN_CODE") =>"def" : returns all elements whose CML2_SCAN_CODE property value does not include a "def" substring.
Using complex logic in filters
The arFilter parameter may specify nested filters in the form of an array. The nested filter array contains entries whose key is an ordinal number, and the values are the filter conditions (which can be anything including arrays).Theoretically, there is no restriction on the level of filter nesting.
The filter condition may be set to use conjunction or disjunctions logic. That is, "AND" or "OR". "AND" specifies that all of the filter conditions must be true to pass; "OR" – one of the filter conditions must be true. To specify the logic operator, use the LOGIC key.
Example
The following code selects little ripe oranges and big unripe ones:
$arFilter = array(
"IBLOCK_ID" => $IBLOCK_ID,
"SECTION_CODE" => "orange",
"INCLUDE_SUBSECTIONS" => "Y",
//the nested filter with explicitly specified logic
array(
"LOGIC" => "OR",
0 => array("<PROPERTY_RADIUS" => 50, "=PROPERTY_CONDITION" => "Y"),
1 => array(">=PROPERTY_RADIUS" => 50, "!=PROPERTY_CONDITION" => "Y"),
),
);
Fields of bound elements
- ID - the element ID;
- TIMESTAMP_X – the date and time an element was last modified, in the current website format;
- MODIFIED_BY – the ID of a user who was the last to modify an element;
- DATE_CREATE – the date and time an element was created;
- CREATED_BY - the ID of a user who created an element;
- IBLOCK_ID - the information block ID;
- ACTIVE - the element active status (Y|N);
- ACTIVE_FROM - the date and time since when an element is active, in the current website format;
- ACTIVE_TO - the latest date and time when an element is active, in the current website format;
- SORT - the sort order;
- NAME - the element name;
- PREVIEW_PICTURE - the thumbnail image ID;
- PREVIEW_TEXT - the short text;
- PREVIEW_TEXT_TYPE - type of the short text (html|text);
- DETAIL_PICTURE - the large image ID;
- DETAIL_TEXT – the detailed text;
- DETAIL_TEXT_TYPE - type of the detailed text (html|text);
- SHOW_COUNTER – the value of the impression counter;
- SHOW_COUNTER_START – the date and time of the very first impression, in the website format;
- CODE – the element symbolic code;
- TAGS – the element tags;
- XML_ID – the external ID;
- IBLOCK_SECTION_ID – the ID of the element’s parent section (if present).
- IBLOCK_TYPE_ID – the information block type ID;
- IBLOCK_CODE – the information block symbolic code;
- IBLOCK_NAME – the information block name;
- IBLOCK_EXTERNAL_ID – the information block external ID;
- DETAIL_PAGE_URL – the element page URL template as specified in the information block parameters;
- LIST_PAGE_URL – the elements list page URL template as specified in the information block parameters.
Examples
Example 1:
<? $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); } ?>
Example can be updated by adding property display for each item. It's convenient for use, without the need to implement GetProperty. In case of Iblocks 2.0, you need to add IBLOCK_ID to $arSelect.
<? $arSelect = Array("ID", "IBLOCK_ID", "NAME", "DATE_ACTIVE_FROM","PROPERTY_*");//IBLOCK_ID and ID must be specified, see description of arSelectFields above $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); $arProps = $ob->GetProperties(); print_r($arProps); } ?>
Example 2:
<? // selection of active items from $yvalue iblock, // with property value set with SRC character code // and activity start date older than 1 January 2003 // selected items can be grouped by activity date $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>"; } ?>
Example 3:
//displaying archive from expired items (news.list) $arFilter = array( "IBLOCK_ID" => $arResult["ID"], "IBLOCK_LID" => SITE_ID, "ACTIVE" => "Y", "CHECK_PERMISSIONS" => "Y", //singificantly overloads the system, but verifies access permissions "DateFormatToPHP(CLang::GetDateFormat("SHORT")), );
Example 4:
//selection of iblock items, to have 5 random items in the returned result $rs = CIBlockElement::GetList ( Array("RAND" => "ASC"), Array("IBLOCK_ID" => $IBLOCK_ID), false, Array ("nTopCount" => 5) );
Example 5:
//use subqueries for filtering by several values of multiple property CModule::IncludeModule('iblock'); $rs = CIBlockElement::GetList( array(), array( "IBLOCK_ID" => 21, array("ID" => CIBlockElement::SubQuery("ID", array("IBLOCK_ID" => 21, "PROPERTY_PKE" => 7405))), array("ID" => CIBlockElement::SubQuery("ID", array("IBLOCK_ID" => 21, "PROPERTY_PKE" => 7410))), array("ID" => CIBlockElement::SubQuery("ID", array("IBLOCK_ID" => 21, "PROPERTY_PKE" => 7417))) ), false, false, array("ID") ); while($ar = $rs->GetNext()) { echo '<pre>'; print_r($ar); echo '</pre>'; }
Example 6:
//next and previous product with account of sorting and in detail view $arrSortAlown = array('price'=> 'catalog_PRICE_1' , 'name'=> 'NAME', 'rating' => 'PROPERTY_RATING' , 'artnumber'=> 'PROPERTY_ARTNUMBER'); $_sort = isset($arrSortAlown[$_GET['sort']]) ? $arrSortAlown[$_GET['sort']] : 'NAME'; $_order = isset($_GET['order']) && $_GET['order']=='desc' ? 'DESC' : 'ASC'; $sort_url = 'sort=' .( isset($_GET['sort'])? $_GET['sort'] : 'name') .'&order='. (isset($_GET['order'])? $_GET['order'] : 'asc'); $res = CIBlockElement::GetList( array("$_sort" => $_order), Array( "IBLOCK_ID"=>$arResult["IBLOCK_ID"], "ACTIVE_DATE"=>"Y", "ACTIVE"=>"Y" , "IBLOCK_SECTION_ID" => $arResult["IBLOCK_SECTION_ID"] ), false, array("nPageSize" => "1","nElementID" => $arResult["ID"]), array_merge(Array("ID", "NAME","DETAIL_PAGE_URL"), array_values($arrSortAlown)) ); $navElement = array(); while($ob = $res->GetNext()){ $navElement[] = $ob; } //printed: <noindex> <div class="navElement" style="float:right; clear:both;"> <span class="l"> <small><a href="<?=$navElement[0]['DETAIL_PAGE_URL']?>?<?=$sort_url?>">Previous product</a></small> </span> <span class="r"> <small><a href="<?=$navElement[2]['DETAIL_PAGE_URL']?>?<?=$sort_url?>">Next product</a></small> </span> </div> </noindex>
Example 7:
//prints undue and thus inactive event notices without component updates // indicate filter name in the component and add filter itself in front of component: <? $arrFilter=Array(array( "LOGIC" => "OR", array("DATE_ACTIVE_TO"=>false), array(">DATE_ACTIVE_TO"=>ConvertTimeStamp(time(),"FULL")) )); ?>
Example 8:
//Iblock v18.6.700 now has option to sort the selected ID order, specified in the array // sort IDs as follows $ids = [115, 120, 117, 109, 128]; $rs = CIBlockElement::GetList( ['ID' => $ids], ['IBLOCK_ID' => '5', 'ID' => $ids], false, false, ['ID', 'IBLOCK_ID', 'NAME'] ); while ($ar = $rs->Fetch()) { echo $ar['ID'] . ' '; } // printed result: // 115 120 117 109 128
Example 9:
//Iblock v21.700.100 now has an added nOffset key in arNavStartParams \Bitrix\Main\Loader::includeModule('iblock'); $res = CIBlockElement::GetList( ['ID' => 'ASC'], ['IBLOCK_ID' => 2], false, ['nTopCount' => 5, 'nOffset' => 1000], ['ID', 'IBLOCK_ID', 'NAME'] ); while ($row = $res->Fetch()) { echo '<pre>', mydump($row), '</pre>'; } // nTopCount - amount // nOffset - indicated offset
Example 10. Print elements with non-empty value of list multiple property
${$FILTER_NAME}[]=array( "ID" => CIBlockElement::SubQuery("ID", array( "IBLOCK_ID" => $arParams['IBLOCK_ID'], "!=PROPERTY_".$arProp["CODE"] => false )) );
Example 11. Creating search by catalog using the field SEARCHEBLE_CONTENT.
<? CModule::IncludeModule('iblock'); $IBLOCK_ID = intval($_REQUEST['IBLOCK_ID']); $QUERY = trim($_REQUEST['q']); if($QUERY) { $arSelect = Array("ID", "NAME", "DATE_ACTIVE_FROM", "DETAIL_PAGE_URL", "PREVIEW_PICTURE"; $arFilter = Array("IBLOCK_ID"=>$IBLOCK_ID, "ACTIVE_DATE"=>"Y", "ACTIVE"=>"Y", "SEARCHABLE_CONTENT"=>'%'.$_REQUEST['q'].'%'); $res = CIBlockElement::GetList(Array(), $arFilter, false, Array("nPageSize"=>50), $arSelect); while($ob = $res->GetNextElement()) { $arFields = $ob->GetFields(); print_r($arFields); } } ?>
Example 12. For filtering by Date, i. e. from 12.09.2014 to 18.09.2014 inclusively, the filter will look as follows:
$date_from = '12.09.2014'; $date_to = '18.09.2014'; $db_el = CIBlockElement::GetList( array('ID' => 'DESC'), array( '>=DATE_CREATE' => $date_from, '<=DATE_CREATE' => $date_to . ' 23:59:59' ) );