Компонент: Юникат

Материал из Smart Core Wiki

Версия от 19:40, 16 января 2015; Digi (Обсуждение | вклад)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)
Перейти к: навигация, поиск

Содержание

Ссылки по теме

ВНИМАНИЕ! эта статья требует доработки! информация на ней может быть не актуальной.

Юниакат является компонентом, который могут включать модули и использовать его для организации какиих-то своих каталогизированных данных.

Архитектура

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

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

Экземпляры

Логический экземпляр каталога. Он может включать в себя несколько структур древовидных категорий.

Например в одной БД можно хранить как информацию «Новостей», так и «Фотогалереи», так и «Каталог продукции», у всех у них будут отдельные наборы данных, структура и т.д. («entity» - сущность, логический экземпляр)


Методы для работы с экземплярами:

Создать новый экземляр каталога.
createEntity($name, $title, $language_id = false)
Обновить свойства экземпляра.
updateEntity($entity_id, $name, $title, $media_collection_id)

Структуры

Структура массива structures в таблице entities.

$structures = array(
	// в этом случае порядок следования ключей, является их приоритетом т.е. первый 
        // является первичным каталогом.
	// Значение entryes, указывает какое кол-во связей с разными категориями может иметь 
        // запись. Это например удобно
	//	для построения тэгов, где можно указать, что связей может быть бесконечное 
        //      кол-во. а также можно ограничить до кокого-то фиксированого кол-ва, 
	//	например не более 3-х вхождений в каталог.
	//  - multi - множесвенный выбор.
	//  - single - одиночный выбор.
	//  - [$int] - максимально возможное кол-во связей.
	// @todo можно вхождения числом задавать :) тогда получается:
        // 0 - любое, 1 - одиночное, а [$int] оставить как есть т.е. множественное с лимитом.
	0 => array(
		'id' => 1,
		'name' => 'rubric',
		'table' => '{DB_PREFIX}categories_s1_e1_rubrics',
		'required' => true, // Должно быть выбрано хотябы одна категория в этой структуре.
		'entries' => 3,
		'descr' => 'Это рубрики',
		),
	1 => array(
		'id' => 4,
		'name' => 'geo',
		'table' => 'geo_base',
		'required' => true,
		'entries' => 'single',
		'descr' => 'Иерархическая гео база',
		),
	2 => array(
		'id' => 3,
		'name' => 'tag',
		'table' => 'global_tags',
		'required' => false,
		'entries' => 'multi',
		'descr' => 'Облаго тэгов',
		),
);

Категории

Древовидная, логическая структура, предназаначенная для группировки записей. В одном экземпляре каталога должна быть одна корневая категория в которую уже будут добавляться записи и другие категории.

У корневой категории pid = 0, также у неё всегда пустая часть УРИ и её нельзя удалить.

А все вложенные категории обязаны иметь не числовой сегмент УРИ, уникальный для той категории в которой она находится.

@todo разобраться и задокументировать почему это вдруг uri_part'ы должны быть не числовыми, имхо логичнее будет, если юзер ввел число, то оно должно замениться на ид самой записи.

ВНИМАНИЕ! не актуально.

Древовидная структура, Например как «Рубрики» у 2ГИС-а. В модуле «Новости» структура может не применяться в полной мере т.к. там нужны плоские ленты новостей. У каждого элемента структуры может быть своё описание и картинка. (может быть сделать просто теже самые свойства, что мы цепляем на записи, но прицеплять какой-то произвольный набор свойств на элементы структуры?)

getCatagoriesTree $start_from_category_id
$max_deph
Получить список всех категорий начиная с $start_from_category_id и максимальной вложенностью $max_deph.
getCategoryInfo $pid
$title
$uri_part
Получить информацию о категории.
createCategory $pid
$title
$uri_part
Создать новую категорию.
updateCategory $id
$data
Обновить свойства категории.

Записи

В таблице items хранятся все записи, но без данных, здесь указываются только базовая информация, такая как: uri_part, id создателя и дата создания.

Данные свойств записей храняться все в отдельных таблицах, имена таблиц имеют следующий формат:

items_{entity_id}_{propery_name}

Любая запись может принадежать любому кол-ву категорий в любой структуре в пределах экземпляра, также каждая запись обдалает уникальным uri_part в пределах своего экземпляра каталога. Это реализуется через таблицу items_structures_relation.


Методы для работы с записями:

Добавление записи.
createItem($data)
Мягкое удаление записи.
deleteItem($item_id)
Удалить свойство записи по имени свойства.
deleteItemProperty($item_id, $property_name)
Получение данных записи.
getItem($item_id, array $options = null)
Получение списка записей.
getItems(array $options = null, $return_items_count = false)
Получить общее кол-во записей.
getItemsCount(array $options = null)
Получить прототип записи.
getItemPrototype($structures = array(), $is_admin = false)
Получить значение свойства записи, по имеени свойства.
getItemValue($item_id, $property_name)
Проверка записи на доступность.
isItemExist($var) // @toto сделать!.
Обновление записи.
updateItem($data)

Формат массива $options

Для выборки записей.

$options = array(
	// Запросить список категорий структур в которые включена запись.
	'get_structures' => true,
	// Указать структуры и категории в которых надо сделать выборку.
	// Также можно вообще не указывать никаких значений, тогда выберутся записи на основе правил 
        // is_inheritance в экземпляре и структурах.
	// Перечисление категорий для структур делается через запятую, например: '1, 4, 77'.
	// Также возможно указание значение 'all', в это случае выберутся все записи структуры 
        // не зависимо от категорий.
	'structure' => array(
		0 => true, // Выбирать или нет записи привязанные напрямую к экземпляру.
                           // (по умолчанию принимается значение is_inheritance из таблицы entities).
		1 => '1,4,77',
		2 => 'all',
		3 => false,
		),
	// Выбрать записи с флагом is_active. (1, 0, 'all')
	// 1|true - только активные (по умолчанию)
	// 0|false - только не активные
	// 'all' - все записи
	'is_active' => 1,
	// Выбрать только свойста предназначенные для отображения в админке.
	'only_admin_properties' => 0
	// Выбрать записи с флагом is_deleted. (1, 0, 'all')
	// 1|true - только удалённые
	// 0|false - только не удалённые (по умолчанию)
	// 'all' - все записи
	'is_deleted' => 0,
	// Сортировка по указанным полям.
	'order' => array(
		'i.item_id' => 'ASC', // Имена полей начинающиеся с 'i.' является 
                                      // ключевымы и сортировка выполняется из таблицы item.
		'datetime' => 'DESC', 
		),
	// Фильтры.
	'filter' => array(
		// Сокращенный формат.
		array('date_start', '>=', '2010-10-26 22:53:05'),
		// Если добавляется еще одно условие на одно и тоже свойство, то оно
		// в запросе учавствует как условие OR и оборачивается в скобки.
		// Доступны следующие форматы условий без третьего операнда:
		// - IS NULL
		// - IS NOT NULL
		array('date_start', 'IS NULL'),
		// Развернутый формат.
		array( 
			'property' => 'date_end',
			'comparison' => '<=',
			'value' => '2010-10-28 16:48:03',
			),
		),
	// Окончание у ссылок на записи. Не может быть равен '/' т.к. в этом случае 
        // будет считаться, что это категория.
	'link_postfix' => '.html',
	// Постраничность. (развернутый формат)
	'paginator' => array(
		'items_per_page' => 10,
		'current_page' => 1,
		),
	// Сокращенный формат.
	// * где, первое число указывает на кол-во записей которые надо отобразить
        // (0 = все записи), а второе на номер страницы.
	'page' => array(0, 1),
);

Свойства

Свойства описывают какими типами данных может обладать запись. При создании новой записи в какой либо категории, методом getItemPrototype($category_id) можно получить список свойств доступных для записей в данной категории. Предположим создадим группу «Габариты» со следующими свойствами:

Еще создадим группу «Холодильная камера» с свойствами:

И на последок создадим группу «Духовка» с свойствами:

Далее предположим в каталоге есть категория «Бытовая техника», к ней подключаем группу «Габариты». Затем в «Бытовой технике» создаём подкатегории «Холодильники» и «Электроплиты». К категории «Холодильники» привязываем группу свойств «Холодильная камера», а в категорию «Электроплиты», группу свойств «Духовка».

Предположим в категорию «Холодильники» мы решили добавить новую запись, тогда метод getItemPrototype нам вернёт 2 группы свойств - «Габариты» и «Холодильники» т.е. он подтягивает группы свойств по наследованию. Несмотря на то, что свойства группируются, их имена должны быть уникальными в пределах одного экземпляра каталога.

Одно свойство может входить только в одну группу. При выводе детальной информации о записи, можно показывать свойства по группам, а можно все свойства одним списком.

Типы данных, которые присущи какой либо записи. Например в 2ГИС-е свойства записи, это: 1) заголовок 2) баннер 3) краткое описание 4) адрес 5) контакты 6) время работы. А вот «Рубрики» это уже связующие качества записи со структурой. В модуле «Новости» свойства обычно это: 1) загловок 2) картинка в списке 3) аннотация 4) полный текст.

Свойства могут быть следующих типов:

  1. Строка [string]
  2. Текст [text]
  3. Группа переключателей [radio]
  4. Флажок [checkbox]
  5. Выпадающий список [dropdown]
  6. Множественный список [multiselect]
  7. Дата [date]
  8. Изображение [image]
  9. Файл [file]

Параметры свойств

Задаются в формате YAML

# Значение по умолчанию 
# Предумсмотрен ряд служебных значений:
#  null
#  datetime
#  date({some_params}) - выполняется выражение {some_params} PHP функцией date().
default: null
 
# Элемент формы с этим полем будет выключен.
disabled: false
 
# Список для выбора, примеряется в форматах select, multiselect, radiogroup.
options:
    key1: val1
    key2: val2
 
# Валидаторы
validators:
    max_width:  максимальная ширина картинки
    max_height: минимальная ширина картинки
    min_width:  максимальная высота картинки
    min_height: минимальная высота картинки
    max_size:   максимальный размер загружаемого файла
    max_lenghth: максимальная длина строки или текста
    min_lenghth: минимальная длина строки или текста
    max_val: максимальное значение числа 
    max_val: минимальное значение числа 
 
# Действия выполняемые с данными после загрузки и прохождения валидации.
filters:
    img_resize: # в сначала указывается имя фильтра, оно включает в себя сами к
        width:
        height:
        fit: inside, outside или fill
        scale: down, up или any

Таблицы

Юникат будет работать с определённым набором таблиц, но каждый модуль будет иметь возможность использовать свои таблицы, они будут выделяться по префиксу, например news_items или gallery_items... по уполчанию, юникат будет применять префикс «unicat_», а также возможно применение без префикса, но тогда очень желательно применять отдельную БД, чтобы таблицы юниката не смешивались с таблицами движка.

  1. entities — Экземпляры каталогов, например экземляр "новости" и "каталог продукции".
  2. items — Записи.
  3. items_structures_relation — Связи записей с категориями структур.
  4. items_structures_relation_single — Связи записей с категориями структур (для учета одиночных)
  5. properties — Свойства записей.
  6. properties_groups – Группы свойств.
  7. properties_groups_structures_relation – Привязка групп свойств к структурам.
  8. properties_groups_translation – Переводы названий свойств полей.
  9. properties_translation – Переводы названий свойств.

Права доступа

  1. Управление экземпляром каталога (создание, редактирвание, удаление).
  2. Управление свойствами (создание, редактирование, удаление свойств и групп свойств).
  3. Управление категориями (создание, редактирвание, удаление, привязка групп свойств).
  4. Добавление записей.
  5. Редактирование своих записей.
  6. Редактирование чужих записей.
Личные инструменты
Пространства имён
Варианты
Действия
Основные разделы
Ссылки
Навигация
Инструменты