Bitrix Site Manager

CFormResult::GetList

record set
CFormResult::GetList(
 int FORM_ID,
 varchar &by,
 varchar &order,
 array arFilter=array(),
 boolean &is_filtered
 char(1) CHECK_RIGHTS="Y"
);

The method is used to get a list of form results with respect to the current user permissions. The list returned is the selection from the database (a record set) with the result fields. Use the function CForm::GetResultAnswerArray get the form questions, fields and their values.

Parameters

ParameterDescription
FORM_ID Form ID.
by Allows to specify the name of the field by which the sorting is to be performed. The following values allowed:
  • s_id - by result ID
  • s_date_create - by the creation date
  • s_timestamp - by the modification date (default)
  • s_user_id - by the user ID
  • s_guest_id - by the visitor ID (Statistics module)
  • s_session_id - by the session ID (Statistics module)
  • s_status - by the status ID
order Sort order. The following values apply:
  • desc - descending (default)
  • asc - ascending
arFilter Array used as the values filter. The following key names apply:
  • ID - result ID (complex logics allowed)
  • ID_EXACT_MATCH - set to "Y" for exact match searches or to "N" to let ID match partially;
  • STATUS - status ID
  • STATUS_ID - status ID (complex logics allowed)
  • STATUS_ID_EXACT_MATCH - set to "Y" for exact match searches or to "N" to let status ID match partially;
  • TIMESTAMP_1 - minimum modification date in the format of the current site;
  • TIMESTAMP_2 - maximum modification date in the format of the current site;
  • DATE_CREATE_1 - minimum creation date in the format of the current site;
  • DATE_CREATE_2 - maximum creation date in the format of the current site;
  • REGISTERED - is the result creator a registered user (Y/ N)
  • USER_AUTH - is the result creator authorized (Y/ N)
  • USER_ID - ID of a user who created the result (complex logics allowed)
  • USER_ID_EXACT_MATCH - set to "Y" for exact match searches or to "N" to let user ID match partially;
  • GUEST_ID - ID of a visitor as the result creator (visitor ID is assigned by the Statistics module) (complex logics allowed)
  • GUEST_ID_EXACT_MATCH - set to "Y" for exact match searches or to "N" to let visitor ID match partially;
  • SESSION_ID - session ID of a visitor (session ID is assigned by the Statistics module) (complex logics allowed)
  • SESSION_ID_EXACT_MATCH - set to "Y" for exact match searches or to "N" to let session ID match partially;
  • FIELDS - array of arrays describing a single field used to filter answers and fields.

    IMPORTANT!
    This array can contain only fields with the flag Use in result filter set.

    These arrays allow the following fields.
    • CODE - code of the field by which the result is filtered
    • PARAMETER_NAME - type of data by which the result is filtered:
      • USER - user-supplied text
      • ANSWER_TEXT - by ANSWER_TEXT
      • ANSWER_VALUE - by ANSWER_VALUE
    • VALUE - value by which the result is filtered (complex logics allowed)
    • FILTER_TYPE - filter type, defines the data type:
      • integer - treat data as integers (only used with PARAMETER_NAME = [ USER | ANSWER_TEXT | ANSWER_VALUE ])
      • text - treat data as text (only used with PARAMETER_NAME = [ USER | ANSWER_TEXT | ANSWER_VALUE ])
      • date - treat data as a date (only used with PARAMETER_NAME = USER)
      • answer_id - filter by matching ID of an answer only (PARAMETER_NAME does not matter)
    • PART - if FILTER_TYPE = [ integer | date ], this field is required to have one of the following values:
      • 0 - match exactly;
      • 1 - left part of the range ("from");
      • 2 - right part of the range ("to");
    • EXACT_MATCH - if the type is "text", this filed may be one of the following:
      • Y - match exactly;
      • N - allow partial matches (default).
is_filtered Contains true on return if the results has been filtered, or false otherwise.
CHECK_RIGHTS If set to "Y", user permissions will be checked when adding a result. If "N", no checks are performed.

Example

Sample PHP code used to define the array arFilter:


$arFilter = array(
    "ID"                   => "1 | 2"
    "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", // match ID or login name exactly
    "GUEST_ID"             => "4456 | 7768",
    "SESSION_ID"           => "456456 | 778768",
    "FIELDS"               => array(
        0 => array(
            "CODE"              => "GAME_ID",       // code of the filtering field
            "FILTER_TYPE"       => "integer",       // filter by integer field
            "PARAMETER_NAME"    => "USER",          // filter by user text
            "VALUE"             => $arGame["ID"],   // value to filter by
            "PART"              => 0                // exact match
            ),
        1 => array(
            "CODE"              => "GAME_NAME",     // code of the filtering field
            "FILTER_TYPE"       => "text",          // filter by integer field
            "PARAMETER_NAME"    => "USER",          // filter by user text
            "VALUE"             => "Tetris",        // value to filter by
            "EXACT_MATCH"       => "Y"              // exact match
            )
        2 => array(
            "CODE"              => "GENRE_ID",      // code of the filtering field
            "FILTER_TYPE"       => "integer",       // filter by integer field
            "PARAMETER_NAME"    => "ANSWER_VALUE",  // filter by ANSWER_VALUE
            "VALUE"             => "3",             // value to filter by
            "PART"              => 1                // from
            ),
        3 => array(
            "CODE"              => "GENRE_ID",      // code of the filtering field
            "FILTER_TYPE"       => "integer",       // filter by integer field
            "PARAMETER_NAME"    => "ANSWER_VALUE",  // filter by ANSWER_VALUE
            "VALUE"             => "6",             // value to filter by
            "PART"              => 2                // to
            )
        )
    );

Example



$arFilter = array(
    "STATUS_ID" => "9 | 10",                   // filter results with status 9 or 10
    "FIELDS"    => array(
        0 => array(
            "CODE"           => "GAME_ID",     // code of the filtering field
            "FILTER_TYPE"    => "integer",     // filter as integer
            "PARAMETER_NAME" => "USER",        // filter by user text
            "VALUE"          => $arGame["ID"], // value to filter by
            "PART"           => 0              // exact match
            ),
        )
    );
$rsComments = CFormResult::GetList($arForm["ID"], 
                                   ($by="s_timestamp"), 
                                   ($order="desc"), 
                                   $arFilter, $is_filtered);