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

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 - символьный идентификатор вопроса или поля веб-формы; синоним - CODE;
    • 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 Максимальное количество результатов, которые войдут в результирующий список. По умолчанию ограничивает выборку 5000 строками.

Параметр необязательный.

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

<?
// 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>";
}


Пользовательские комментарии

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

Для этого нужно всего лишь авторизоваться на сайте

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

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
0
Александр Мельников
Сообщение не промодерировано, возможны ошибки и неточности.
Цитата
$is_filtered
всегда NULL, если по коду посмотреть, то он вообще не используется

http://bxapi.ru/src/?module_id=form&name=CFormResult::GetList
0
Антон Антипов
По последнему параметру (limit), в методе происходит следующая обработка:
Код
... 
if ($records_limit===false)
{
 $records_limit = "LIMIT ".intval(COption::GetOptionString("form","RECORDS_LIMIT"));
}  
...
т.е. если limit == false, то ограничение есть и приравнено к значению "Максимальное кол-во записей, выбираемых в SQL запросах:" в настройках модуля "Веб-формы"

0
serjramone
Если необходимо найти результаты у которых поле|вопрос не заполнен, то фильтр будет примерно таким:

Код
$arFields[] = array(
   "CODE"              => "FIELD_NAME",                  // код поля по которому фильтруем
   "FILTER_TYPE"       => "text",                         // фильтруем по числовому полю
   "PARAMETER_NAME"    => "USER",                      // фильтруем по введенному значению
   "VALUE"             => "~_",                                  // значение по которому фильтруем
   "EXACT_MATCH"       => "N"                              // ищем точное совпадение
);


$arFilter = array (
   "FIELDS" => $arFields,
   "STATUS_ID" => 45,       //отфильтровать необходимо результаты в статусе с ID = 45
);

$rsResults = CFormResult::GetList($FORM_ID, $by = 's_id', $order = 'asc', $arFilter, $is_filtered, 'N', false);
 
© «Битрикс», 2001-2024, «1С-Битрикс», 2024
Наверх