Главная / Разработчикам / Вспомогательные классы

Коллекции в общем

Коллекции - это специальные классы для хранения списков сущностей, которые могут быть общими информационными записями, ссылками, изображениями или файлами.

В общем: если Вашему плагину или блоку нужно хранить список чего-либо, это проще сделать через коллекции.

 

Создание коллекции

Перед тем, как начать работать с любой коллекцией, ее необходимо создать. Можно как создать новую коллекцию, так и инициализировать существующую.

Чтобы создать новую коллекцию, достаточно создать объект ее класса, например:

$my_collection = new landingsItemCollection(null, $block_id);
$collection_id = $my_collection->getId();

Здесь в качестве первого параметра мы передаем null вместо идентификатора коллекции, чтобы показать, что хотим создать новую коллекцию, второй параметр можно не передавать, однако, если Вы создаете коллекцию для блока, система сможет затем удалить ее при удалении или сбросе блока по этому параметру, это удобно (недоступно в текущей версии, но просим передавать параметр). После этого можно получить идентификатор новой коллекции при помощи метода getId().

Чтобы инициализировать существующую коллекцию, просто создайте объект класса коллекции, передав идентификатор.

$my_collection = new landingsItemCollection($collection_id);
if($my_collection->getId())
{
    // Коллекция существует
}
else
{
    // Коллекция с переданным идентификатором не существует
}

 

Добавление и получение позиций

Существует два метода, чтобы добавить позиции в коллекцию:

addItems($items) // Добавить несколько позиций
addItem($item) // Добавить одну позицию

Обратите внимание на то, что должно содержаться в данных позиции. Каждая коллекция имеет список стандартных полей для позиции внутри нее (в общем случае это только name), однако, Вы можете передать любые параметры кроме сервисных (id, collection_id, sort), и они будут сохранены в подмассив extra, который вы получите при получении позиции из коллекции.

Обратите внимание на этот пример добавления:

// Добавляем
$item = array(
    'name' => 'Имя', // Стандартный параметр
    'my_custom_data' => 'test', // Нестандартный параметр
);
$item_id = $my_collection->addItem($item);

// Теперь получаем
$item_after_extraction = $my_collection->getItem($item_id);
print_r($item_after_extraction);
/*
    array(
        'id' => ..,
        'collection_id' => ..,
        'name' => 'Имя',
        'sort' => ..,
        'extra' => array(
            'my_custom_data' => 'test',
        )
    )
*/

Как видите, нестандартный параметр, который был передан при добавлении, переместился в подмассив extra. Таким образом можно хранить любые параметры, даже массивы, общей длиной json_encode не более MEDIUMTEXT.

Как видно из примера выше, извлечь позиции из коллекции можно при помощи метода:

getItems($raw = false)
getItem($item_id, $raw = false)
getItemByField($field, $value, $raw = false)

Во всех трех методах параметр raw говорит о том, положить ли нестандартные параметры в подмассив extra (false), или выдать все "Как есть", то есть, все нестандартные параметры будут находиться в элементе extra в json-строке.

 

Полезные методы

Любая коллекция имеет следующие встроенные полезные методы для работы с ней:

getFirstItem() // Достает первую по порядку сортировки позицию
updateItem($item_id, $data) // Обновляет данные позиции
deleteItem($item_id) // Удаляет позицию из коллекции
sortItems($items) // Сортирует позиции. Принимает плоский массив идентификаторов позиций array([0] => 1, [1] => 2)
clearItems() // Удалить все позиции из коллекции. Если коллекция хранит файлы, они тоже будут удалены
clear() // Удалить коллекцию. Если коллекция хранит файлы, они тоже будут удалены
makeClone() // Клонировать коллекцию и все позиции в ней. Вернет экземпляр класса-клона.

Информация