====== Операции по загрузке объектов ======


==== Основы загрузки в системе Limb ====

Итак, Вы познакомились с основами Limb. Идея активных объектов сайта, помещенных в объектное дерево, занимает центральное место в Limb. Вполне обоснованным является вопрос: "Как можно запросить все эти объекты?". Этот маленький раздел документации предоставит некоторые ответы.

==== Загрузчик (Fetcher) ====

В Limb все запросы к объектам сайта выполняются через специальный механизм //загрузчика//.

Обычно выделяют 2 типа операций загрузки:
  * запрос на единичный объект
  * запрос на множество объектов

Есть несколько способов оьратиться к дереву объектов:
  * через путь в дереве
  * через идентификатор объекта (node_id)
  * через набор элементов (set of nodes)
  * через URI текущего запроса 
 
Загрузчик не только получает объекты сайта, но также применяет [[.access_policy| Систему прав]] и возвращает **ТОЛЬКО** доступные для текущего пользователя объекты сайта.

//Для Вашего удобства все методы выборки (загрузки) могут быть вызваны через уникально именованные глобальные функции.//


==== Подробности ====
Перед описанием доступных методов загрузки необходимо кратко описать сам механизм загрузки в Limb.

То, что выполняет загрузчик, может быть представлено последовательностью следующих шагов:

  * Найти объект сайта в объектном дереве на основе какого-либо критерия.
  * Применить правила политики доступа с целью определения доступности запрошенного объекта.
  * Вызвать указанный для объекта сайта метод **fetch()** для обеспечения корректной загрузки специфичных для объкта данных. Только в редких случаях Вам потребуется переопределять базовое поведение объекта сайта. Это относится только ко сложным объектам сайта (content objects). Поэтому мы выделили только несколько таких вариантов. Один из них - загрузка объекта изображения, когда Вам необходимо загрузить дополнительную информацию о вариантах изображения.
  * Вызвать указанный для объекта метод **count()**, чтобы позволить объекту сайта подсчитать общее количество загруженных объектов. Limb никогда не получает полный результирующий набор: это может быть смертельно для PHP. Все операции выборки ограничены на уровне базы данных. Это очень важно, так как позволяет использовать очень эффективные, ограничненные по количеству, запросы. В общем, архитектура системы не подразумевает, что Вам потребуется переопределить базовое поведение.


==== Жажда скорости ====
Медлительность объектов в PHP хорошо известна, объекты значительно увеличивают нагрузку. Именно по этой причине все операции загрузки возвращают массивы, а не объекты.

Такое поведение оказалость особенно полезным для шаблонов WACT. 
Массивы объектов попадают в компоненты шаблона и Вы можете естественным способом обращаться к атрибутам объекта.

Вы также можете легко превратить эти массивы в полноценные объекты, вызвав специальную функцию:
<code>
 wrap_with_site_object($fetched_data) 
</code> 

//В документации мы ссылаемся на  **загруженные объекты**, а не на  **загруженные массивы** - мы надеемся это ни кого сильно не запутает//


==== Запрос к единичному объекту ====

В классе загрузчика (fetcher class) есть три метода, позволяющие загрузить единичный объект сайта:

=== загрузка объекта по идентификатору узла (node id) === 

<code>
  fetch_one_by_node_id($node_id)
</code>

возвращает загруженный объект, связанный с указанным в $node_id значением идентификатора узла

=== загрузка объекта по пути ===

<code php>
 fetch_one_by_path($path)
</code>

возвращает загруженный объект, связанный с заданным путем (например, объект сайта, связанный с путем '/root/article/1' может быть загружен вызовом fetch_one_by_path('/root/article/1'))

=== Загрузка запрошенного объекта ===      
<code php>
 fetch_mapped_by_url()
</code>
возвращает объект связанный с URL запроса. Также можно получить объект через обычный URL к объекту 
<code>
 http://domain.com/root?node_id=$id.
</code>


==== Загрузка множества объектов (набора) ====

Загрузка множества объектов отличается от загрузки единичного. С целью увеличения скорости, так как возвращаются однородные объекты и вызывать методы загрузки и подсчета для каждого слишком накладно, методы //выборки// и //подсчета// вызываются только для одного //загрузчика// - объект сайта.

Что это значит? На практике редко нужны все уникальные атрибуты всех объектов в загружаемом наборе (например, различные варианты изображений объекта изображения)
Технически это возможно, однако... попробуйте представить, что произойдет, если загрузить все дерево объектов!

Есть 4 метода для одновременной загрузки группы объектов сайта:

=== Загрузка объектов одного класса === 
<code>
fetch($loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch')
</code>
возвращает набор выбранных объектов, загруженных объектом $loader_class_name (обычно 'объект сайта'!) через вызов его метода загрузки ($fetch_method). В переменную $counter записывается общее число загруженных элементов. Переменная $params позволяет Вам определить предел, смещение и т.д.

Пример:
<code>
$params = array('limit' => 10, 'offset' => 1);
$counter = 0;
$users =& fetch('user_object', $counter, $params);
</code>

=== Загрузка ветви дерева === 
<code>
fetch_sub_branch($path, $loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch_by_ids')
</code>
возвращает набор выбранных объектов, загруженных объектом класса $loader_class_name(обычно 'объект сайта') из дерева объектов начиная с размещения в $path, через его метод $fetch_method. В переменную $counter записывается общее число выбранных элементов. Переменная $params позволяет Вам определить предел, смещение и т.д. 

Пример:
<code>
$params = array('limit' => 10, 'offset' => 1, 'depth' => 1);
$counter = 0;
$user_groups =& fetch_sub_branch('/root/user_groups', 'user_group', $counter, $params);
</code>

=== Загрузка по идентификаторам узлов (node_ids) ===
<code>
fetch_by_node_ids($node_ids, $loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch_by_ids')
</code>

возвращает набор выбранных объектов, загруженных объектом класса $loader_class_name(обычно 'объект сайта'), указанных через массив идентификаторов узлов $node_ids через вызов метода $fetch_method. В переменную $counter записывается общее число выбранных элементов. Переменная $params позволяет Вам определить предел, смещение и т.д.

Пример:
<code>
$counter = 0;
$user_groups =& fetch_by_node_ids(array(10,11), 'user_group', $counter);
</code>

=== Загрузка по идентификаторам объектов === 
<code>
fetch_by_ids($object_ids, $loader_class_name, &$counter, $params = array(), $fetch_method = 'fetch_by_ids')
</code>

возвращает набор выбранных объектов, загруженных объектом класса $loader_class_name(обычно 'объект сайта') указанных через массив идентификаторов объектов $object_ids через вызов метода $fetch_method. В переменную $counter записывается общее число выбранных элементов. Переменная $params позволяет определить предел, смещение и т.д.

Пример:
<code php>
 $counter = 0;
 $user_groups =& fetch_by_ids(array(100,81), 'user_group', $counter);
</code>