Bitrix Site Manager

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
);

The function returns active elements of the information block type defined by type. The elements returned are active within the current site.

Parameters

ParameterDescription
type Type of information blocks to search for elements.
TypesInc Allows to set the filter that describes information blocks included in the selection. The filter uses the ID or mnemonic code of an information block as the match criteria. You can use either a single value or an array of values here.
This parameter is optional. By default, all elements of information blocks of the matching type is selected.
Example: "product_news".
TypesExc Similar to TypesInc, but sets the filter to exclude the matching information blocks. 
This parameter is optional. By default, all elements of information blocks of the matching type is selected.
Example: Array("company_news", "product_news", 22).
Order Optional sort order. Array of the format Array(by1=>order1[, by2=>order2 [, ..]]) where by is the field for sorting. The field can have the following values:
  • sort - sort weight;
  • timestamp_x - modification date;
  • name - name;
  • id - element ID;
  • active_from - date the element is active from;
  • active_to - date until which the element is active.
order is the sort order. Can be asc for ascending sorts or desc for descending.

Default value is Array("sort"=>"asc"). Full list of sorting fields and additional information can be found in CIBlockElement::GetList()
cnt Maximum number of the returned records. Optional. All records are returned by default.
arFilter Optional additional filter by fields in the form of Array("Filtered field"=>"Value", ...). The Filtered field can be the following:
  • ID - by the ID;
  • ACTIVE - by the active state (Y|N);
  • NAME - by names (wildcards [%_] allowed);
  • PREVIEW_TEXT - by short text (wildcards [%_] allowed);
  • DETAIL_TEXT - by detailed description (wildcards [%_] allowed);
  • SEARCHABLE_CONTENT - by all searchable content. This includes title, short and detailed descriptions (wildcards [%_] allowed);
  • CODE - by mnemonic identifier (wildcards [%_] allowed);
  • SORT - by sort weight;
  • EXTERNAL_ID - by external ID (wildcards [%_] allowed);
  • TIMESTAMP_X - by modification date;
  • DATE_CREATE - by creation date;
  • DATE_ACTIVE_FROM - by date of beginning of the active state;
  • DATE_ACTIVE_TO - by the date the active state expires;
  • ACTIVE_DATE - do filter by active state dates (DATE_ACTIVE_FROM and DATE_ACTIVE_TO), can be Y or N;
  • IBLOCK_ID - by the information block ID;
  • IBLOCK_CODE - by the information block mnemonic code (wildcards [%_] allowed);
  • IBLOCK_LID - by language (wildcards [%_] allowed);
  • IBLOCK_TYPE - by the block type (wildcards [%_] allowed);
  • IBLOCK_ACTIVE - by the block active state (wildcards [%_] allowed);
  • SECTION_ID - by the parent section;
  • PROPERTY_<property_ID> - by the property value. Wildcards ([%_]) allowed. When searching the "LIST" properties, the search is performed by the ID, not by value ;
  • PROPERTY_<property_ID>_VALUE - by the values for the "LIST" properties. Wildcards ([%_]) allowed. The search is performed by the string value, not by the ID;
  • CATALOG_<CATALOG_FIELD>_<PRICE_TYPE> - by the field CATALOG_FIELD of the price type PRICE_TYPE (price type code). CATALOG_FIELD can be PRICE - price, CURRENCY - currency.
All the filter fields except SECTION_ID and ACTIVE_DATE may have the conditions specified before the name.

The fields SECTION_ID and ACTIVE_DATE may have negation sign ("!") before the name.

The "filter values" are a single value or an array.

The default parameter value is an empty array.
Full list of sorting fields and additional information can be found in CIBlockElement::GetList()
arSelect Array containing the element fields to retrieve. Allows to get the property values immediately. To do so, set the name of one of the fields to PROPERTY_<PROPERTY_CODE> where PROPERTY_CODE is the ID or mnemonic code. The result will contain values of the element properties as fields:
  • PROPERTY_<PROPERTY_CODE>_VALUE - property value;
  • PROPERTY_<PROPERTY_CODE>_ID - element value ID;
  • PROPERTY_<PROPERTY_CODE>_ENUM_ID - value ID (for properties of the LIST type).
Obtaining the element price values is also possible if the Commercial Catalog module is installed. Set one of the fields to CATALOG_GROUP_<PROPERTY_CODE> where PROPERTY_CODE is the ID of the price type.

By default, all the element fields are retrieved.
arGroupBy Array of fields for grouping. If specified, the selection becomes grouped by these fields, and the result contains the CNT field (number of grouped elements). If an empty array is passed, the function returns the number of elements in the CNT field.

Grouping is possible by the element fields as well as the property values. If the latter is the case, set one of the grouping fields to PROPERTY_<PROPERTY_CODE> where PROPERTY_CODE is the ID or mnemonic code of the properties.

Optional. By default, records are not grouped.

Return Values

The function returns an instance of CIBlockResult with active elements, i.e. those having the flag Active set, valid active period and pertaining to the active parent information blocks of the current site.

Remarks

To facilitate handling the function return values, you can use the method CDBResult::GetNext() returning an array of the information block element fields. All fields returned by this method are HTML compliant and safe. Variables #SITE_DIR#, #IBLOCK_ID#, #EXTERNAL_ID# and #ID# are replaced with their corresponding values (fields LIST_PAGE_URL and DETAIL_PAGE_URL). If the result is empty or the end of collection is reached, false is returned. Other methods of the CDBResult class can also be used, but keep in mind that they do not substitute variables like #SITE_DIR# with their values.

See Also

  • CIBlockElement::GetList()
  • Fields of information block elements
  • GetIBlockElementList
  • Example


    <?
    if(CModule::IncludeModule("iblock"))
    {
       // select 15 elements of the type "news" 
       // from the information block "company_news"
       $items = GetIBlockElementListEx("news", "company_news", Array(), 
                                       Array("DATE_ACTIVE_FROM"=>"DESC", 
                                             "SORT"=>"ASC", 
                                             "NAME" => "ASC"), 
                                       15);
    
       // page navigation
       $items->NavPrint("Company news");
       // loop on news
       while ($arItem = $items->GetNext())
       {
         // display a link to the detailed view
          echo "<a href='".$aritem["detail_page_url"]."'>".$aritem["name"]."</a>";
         // display data
          echo $arItem["DATE_ACTIVE_FROM"]."<br>";
         // display the preamble image with the link to the detailed view
          echo ShowImage($arItem["PREVIEW_PICTURE"], 100, 100, 
                         "border='0'", $arItem["DETAIL_PAGE_URL"]);
         // display the preamble
          echo $arItem["PREVIEW_TEXT"]."<hr>";
       }
       $items->NavPrint("Company news");
    }
    ?>
    

    <?
    // Display news for today (DATE_ACTIVE_FROM >= today):
    $items = GetIBlockElementListEx("news", Array(), Array(), 
                  Array("SORT"=>"ASC", "ID" => "DESC"), 15,
                  Array(
                    ">=DATE_ACTIVE_FROM"=>date($DB->DateFormatToPHP(CSite::GetDateFormat("SHORT")))
                  )
              );
    
    // Display news for yesterday (DATE_ACTIVE_FROM >= yesterday && DATE_ACTIVE_FROM < today):
    $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")))
                  )
              );
    
    // Display news for 01.01.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))
                  )
              );
    ?>