CardView может использоваться для показа расширенной информации по записи в таблице (формирования карточки).
В карточке может отображаться информация из основной таблицы, а также связанная с данной карточкой информация из других таблиц.
Связь таблиц осуществляется через стандартные возможности карточки.
Записи основной таблицы могут быть отредактированы прямо в карточке.
AjaxDispatcher
. В этом случае автоматически после отправки формы и сохранения
обновленных данных (в случае редактирования карточки) произойдет загрузка карточки в том же элементе DOM.
Если вызов компонента будет осуществлен обычным образом, то
после сохранения обновленных данных произойдет http переадресация на ту же карточку.
Взаимодействие с данным компонентом осуществляется путем создания экземпляра класса
xtables\components\CardView\CardView
и вызова публичных методов:
get()
- возвращает полностью готовую форму карточки, построенную с использованием переданных в CardView параметров настройки
getData()
- возвращает массив данных, которые могут быть добавлены в индивидуальный шаблон;
массив состоит из блоков:
'structure'
- массив, в котором ключами будут выступать полные наименования sql таблица + колонка (если они
присутствуют в выборке из таблицы) или числовые ключи (если нет); в данном массиве данные для вывода карточки в
представлении будут представлены в виде массива:
'name'
- имя для данных (включая подсказку и IconAction иконку, если они требуются согласно
настройкам);
'value'
- полностью готовое отформатированное согласно настроечным параметрам значение в блоке div
с элементом редактирования внутри (input, select, textarea, radio, checkbox);
если не отключено создание кеш, то при обнаружении выходного кеша здесь будет подставлено значениеЕсли в качестве ключа в настроечном массиве
'structure'
будет передано значение, которое отсутствует в выборке из sql таблицы, то оно будет проигнорировано и замено в выходном массиве на числовой ключ, а в нем в параметре'name'
- на значение'full_row'
.
'cache'
и запрос в базу данных производиться не будет;
'hidden_inputs'
- блок hidden inputs, необходим для правильного функционирования карточки;
'ajax_dispatcher'
- имя ajDi, необходим для правильного функционирования карточки;
'popup_menu'
- созданное popup menu, если оно присутствует в параметрах настройки;
'card_title'
- заголовок карточки согласно настройкам.
Пример выходного массива:
[
'structure' => [
'incoming_docs.number' => [
'name' => 'Number',
'value' => 'some data',
],
0 => [
'name' => 'full_row',
'value' => 'some value'
],
1 => [
'name' => 'Some name',
'value' => 'value as result of callable'
]
],
'hidden_inputs' => [
'' => '',
'' => ''
],
'ajax_dispatcher' => 'ajdi_name',
'popup_menu' => 'popup menu in tags',
'card_title' => 'card title or Card'
]
getForm()
- возвращает готовую форму карточки; в данный метод в качестве параметров
должно быть обязательно передано тело карточки $formBody
;$saveButton
,
$cancelButton
:
'css_classes'
- css классы через пробел;
'content'
- содержимое кнопки, включая иконку.
'not_hidden'
- в случае, если данный параметр определен как true
,
то кнопка не будет скрыта; по умолчанию кнопка скрыта.
$saveButton = [
'css classes' => 'some_classes',
'content' => 'Save ......',
//'not_hidden' => true
]
'no_cache' => true
,
то метод getData()
возвратит в качестве значения массива structure
значение 'cache'
, если кеш будет обнаружен. В классе проекта это значение должно быть учтено, так как
данные не будут запрашиваться из базы данных и построить индивидуальный шаблон в этом случае не получится,
что вызовет ошибку. Соответственно необходимо только вызвать метод getForm()
,
в который в этом случае в качестве параметра можно передать ''
, false
или NULL
.
Пример построения карточки по индивидуальному шаблону с учетом кеша.
use xtables\components\CardView\CardView;
$this->card = new CardView($params);
$data = $this->card->getData();
$cardBody = (isset($data['structure']) and $data['structure'] !== 'cache')
? parent::cardSample($data) : '';
return $this->card->getForm($cardBody);
Создание карточки по стандартному шаблону:
use xtables\components\CardView\CardView;
$card = new CardView($params);
/**
* @return string html card with all data according to settings in current app component
*/
$somecard = $card->get();
Создание карточки по индивидуальному шаблону:
use xtables\components\CardView\CardView;
$card = new CardView($params);
/**
* @return array ready card data to use in specific card samples for making cardBody
*/
$data = $card->getData();
$cardBody = $this->someMethodForCreate($data);
/**
* @param string $cardBody main card content in html tags
* @param array $saveBut 'css_classes' and 'content' if need change standart one
* @param array $cancelBut 'css_classes' and 'content' if need change standart one
* @return string ready card in html tags
*/
$someCard = $this->getForm($cardBody);
Настроечные параметры для генерации новой карточки должны быть составлены в виде ассоциативного массива (или объекта), который передается в конструктор данного компонента. Рекомендуется помещать их в отдельном файле.
date
- для даты; time
- для даты и времени.
add_log
condition_id
edit
pre_condition
pre_order
search
select
structure
table
table_add
dbc (string)
Название подключения к БД из пула подключений в файле config.php
.
Если не указано, то выборка будет производиться из первой по списку БД.
'dbc' => 'pgsql'
card_sample (string)
Карточка строится с использованием шаблона, находящегося в настройках в файле /config/card/card.html
. При необходимости
данный шаблон может быть отредактирован.
Если нужно построить карточку на дополнительных шаблонах, то нужно определить параметр
card_sample
, указав в нем относительный путь до файла со специфичным шаблоном карточки
от базового каталога, соответствующего константе XTABLES_BASE
. Это является дополнительной и более простой возможностью
к построению полностью индивидуальной карточки с использованием метода данного компонента getData()
, описанного выше.
При построении специальных шаблонов нужно руководствоваться требованиями, указанными в файле с базовым шаблоном таблицы
/config/card/card.html
. Можно разместить дополнительные шаблоны в том же каталоге, что и базовый, либо в другом.
html
.
Расширение значения не имеет, так как не учитывается. Важно использовать шаблоны, находящиеся в тегах <!--{}-->
в базовом шаблоне.
'card_sample' => '/config/card/card-specific.html'
table (string) передача во входных параметрах блокируется
Основная sql таблица выборки.
'table' => 'incoming_docs'
table_add (string) передача во входных параметрах блокируется
Дополнительные таблицы, по которым может быть выполнен JOIN
'table_add' => 'LEFT JOIN outgoing_docs ON incoming_docs.outgoing_id = outgoing_docs.id '
. 'LEFT JOIN users ON incoming_docs.user_id = users.id'
structure (array) передача во входных параметрах блокируется
Массив параметров для построения карточки:
'hr'
- значение-параметр для вставки пустой строки-разделителя меньшей высоты;
'del_button'
- системная кнопка удалить (ячейки ряда карточки будут объединены, иконка
будет выровнена по центру): удаляет запись, при наличии в настройках сохраняет лог, обновляет ajax dispatcher,
если компонент загружен с его использованием, либо обеспечивает переход по адресу, указанному в параметре
'path_after_del'
;
'name'
- название колонки, как оно будет отображаться на странице;'params'
- массив параметров, если будет использовано полное наименование (sql таблица + колонка через точку),
то в функцию будет передано значение, полученное в результате общей выборки при формировании карточки, либо
свободное значение, которое будет передано в качестве параметра в callable функцию.
'css_id'
- название css идентификатора, которым помечен div, в котором расположены данные;
'css_classes'
- названия классов через пробел, которые будут добавлены к div, в котором
расположены данные.
'structure' => [
'incoming_docs.number' => 'Входящий номер',
'incoming_docs.reg_date' => 'Дата регистрации',
'<img src="some-image.png">',
'hr',
'incoming_docs.from_who' => 'От кого',
'\app\SomeClass::callableTest' => [
'name' => 'Some name',
'params' => [
'incoming_docs.id'
],
'css_id' => 'some-id'
],
'incoming_docs.address' => 'Контакты',
'incoming_docs.content' => 'Содержание',
'del_button'
]
select (array) передача во входных параметрах блокируется
Массив параметров для выборки из sql таблиц, необходимо указывать полное название (sql таблица + колонка через точку).
По умолчанию, если имя колонки имеет в своем составе date
, то к нему
применяются правила даты, если time
- правила даты и времени; если поле не имеет в своем имени подобных
обозначений, но необходимо форматировать выводимые данные как дату, то можно
в качестве ключа к соответствующей колонке подставить date
или time
.
'select' => [
'incoming_docs.number',
'incoming_docs.reg_date',
'incoming_docs.from_who',
'incoming_docs.address',
'incoming_docs.content',
'date' => 'outgoing_docs.some_column' // need to format as date
]
comp_cell (array)
Массив из полных названий (таблица + столбец), которые должны быть заменены композитными данными, то есть данными, составленными из нескольких
других столбцов, предопределенных значений и разделителей. Формирование композитных данных осуществляет класс
xtables/base/CompositeCell
См. подробнее CompositeCell
'comp_cell' => [
'outgoing_docs.number' => [
'delimiter' => ' от ',
'value' => [
'outgoing_docs.number',
'outgoing_docs.reg_date'
]
]
]
condition_id (int) передача во входных параметрах блокируется
Значение id
запрашиваемой записи.
'condition_id' => $this->params['id']
no_cache (bool)
В случае, если необходимо отключить использование кэша в конкретной таблице, нужно включить
параметр 'no_cache'
.
'no_cache' => true
path_after_del (string)
Обеспечивает переход по указанному адресу после выполнения удаления с использованием системной кнопки Удалить, если компонент загружен без использования ajax_dispatcher. По умолчанию используется корневой веб адрес.
'path_after_del' => '/some/url'
card_title (string)
Название, которое отображается в верхней части карточки
'card_title' => 'Карточка'
path (string)
Url вызова карточки
'path' => 'incoming/card'
edit (array with array values) передача во входных параметрах блокируется
Массив параметров для активации на полях (ячейках) возможностей их редактирования.
'access'
- если нужно ограничить показ всех элементов редактирования определенным группам пользователей,
то необходимо использовать данный параметр, указав:
func
- название callable функции;params
- параметры (если в качестве параметров будут указаны sql таблица + колонка через точку,
соответствующие выборке из БД, то будут подставлены соответствующие значения);
output
no_cache
.
callback
- если необходимо выполнить какую-нибудь callable функцию после осуществления обновления данных,
то необходимо указать ее в данном параметре в виде:
func
- имя функции;params
- массив с параметрами;
'reset_cache'
- по умолчанию при обновлении данных происходит очистка кэша текущей sql таблицы;
если необходимо очищать дополнительные таблицы, то нужно включить данный параметр и добавить названия таких дополнительных
таблиц;
'items'
- массив с элементами карточки, в котором ключами
выступают полные имена колонок (sql таблица + колонка через точку), а значениями - массивы с настройками:
'type'
- тип элемента html
формы; поддерживаются input
, textarea
,
radio
, checkbox
, select
;
'values'
- массив со значениями для элементов radio
, checkbox
, select
;
'css_id'
- добавление идентификатора css
;
'css_classes'
- добавление классов css
'max_len'
- максимальная длина поля (количество символов); для ограничения используется js; на странице показывается
оставшееся допустимое к вводу количество символов;
'access'
- если нужно ограничить показ данного поля, нужно определить данный параметр указав:
func
- название callable функции;params
- параметры (если в качестве параметров будут указаны sql таблица + колонка через точку,
соответствующие выборке из БД, то будут подставлены соответствующие значения);
output
no_cache
.
'sql_type'
- по умолчанию, если имя колонки имеет в своем составе date
, то к нему
применяются правила даты, если time
- правила даты и времени; если поле не имеет в своем имени подобных
обозначений, то можно использовать данный параметр, присвоив ему значения date
или time
.
Массив параметров для определения полей для редактирования данных. Поддерживаются html формы input (text, checkbox, radio), textarea, select.
Может использовать автокомплит на поле ввода, который проверяет на наличие значений в определенном столбце определенной sql
таблицы. Автокомплит обеспечивается классом xtables\base\Autocomplete
(подробности настройки см. Autocomplete).
К ячейке могут добавляться css идентификаторы и классы. Если необходимо сделать поле обязательным к заполнению, то необходимо
добавить ему класс required
. Таким образом, если в результате редактирования такое поле становится пустым,
сохранение карточки блокируется JS
Имеется возможность показывать пользователю количество доступных для ввода символов (если поле имеет ограниченный размер).
При вводе символов показывается остаток, который последовательно меняет свой цвет на желтый (осталось 20 и менее) и красный (достингнут 0).
После этого ввод символов блокируется JS.
'edit' => [
'access' => ['some_group', 'else_group'], // for all edit fields
// 'access' => [
// 'func' => 'some\callable::func',
// 'params' => [
// 'sql_table.column',
// 'sql_table.column2',
// 'some_free_value'
// ]
//],
'reset_cache' => ['some_else_table', 'some_else_table2'], // 'some_else_table'
'callback' => [
'func' => 'some\Func::name',
'params' => [
'param',
'else'
]
],
// 'callback' => 'some\Func::name',
'items' => [
'sql_table.column' => [
'type' => 'select',
'values' => [
'' => '',
'' => '',
],
//'access' => ['some_group', 'else_group'] // for this field only
// 'access' => [
// 'func' => 'some\callable::func',
// 'params' => [
// 'sql_table.column',
// 'sql_table.column2',
// 'some_free_value'
// ]
//],
],
'sql_table.column2' => [
'type' => 'textarea',
'css_id' => 'autocomplete1',
'max_len' => 200,
'css_classes' => 'required'
],
'sql_table.column2' => [
'type' => 'input',
//'sql_type' => 'date'
]
]
]
add_log (array) передача во входных параметрах блокируется
При необходимости осуществления записи информации о редактировании записей в таблице в лог можно
использовать массив параметров 'add_log'
:
'table'
- название sql таблицы-лога, в которую нужно сохранить информацию об истории;
по умолчанию, если не указано, то будет использоваться log_base
;
'event'
- описание события:event
в json encoded строке;
при совпадении с названием столбцов в редактировавшейся записи
в истории будет использоваться введенное пользователем значение; если нет, то ключ будет проигнорирован;
таким образом, в лог будут попадать только реально редактировавшиеся данные из определенного в параметре списка
полей.
log_base
.
'add_log' => [
//'table' => 'log_table_name', // if not defined will be 'log_base'
'event' => [
'some_table.some_column' => 'name to save in log',
'some_table.some_column2' => 'name2 to save in log'
]
]
replace (array with array values)
Используется для замены каких-либо значений из БД на другие, например,
может возникнуть необходимость заменять цифру 1 на слово Да или
какое-то слова латинскими буквами на слово русскими (unicode) буквами.
Замена осуществляется классом xtables\base\ReplaceCell
;
подробности по способам замены см. ReplaceCell
Возможны варианты замены: конкретное значение на конкретное значение;
any_int
- любая цифра меняется на заданное значение;
any_string
- любое значение меняется на заданное значение;
empty
- пустое значение меняется на заданное
значение.
'replace' => [
'some_table.some_column' => [
'function' => [
'name' => '\app\SomeClass::someFunction',
'params' => [
'some_table.some_column',
'some_param',
'else_param'
]
],
'numpad' => 6,
'empty' => 'пустое значение',
'any_int' => 'число',
'any_string' => 'строка',
'some_current_value' => 'Да'
],
]
action_cell (array with array values)
Массив полей, на которые должны быть добавлены иконки (например, для обеспечения привязки к карточке данных из других таблиц).
Также может быть добавлено значение unfix
, которое производит очистку записи (например, о привязке другой таблицы).
Подробно см. IconAction.
Необходимо создать массив 'action_cell
, в котором ключами выступают полные имена колонок
(sql таблица + колонка через точку), а значениями - массивы с настройками:
'access'
- если нужно ограничить показ данного поля, нужно определить данный параметр, указав:
func
- название callable функции;params
- параметры (если в качестве параметров будут указаны sql таблица + колонка через точку,
соответствующие выборке из БД, то будут подставлены соответствующие значения);
output
no_cache
.
'action'
- массив настроек IconAction. Подробно см. IconAction.
'action_cell' => [
'sql_table_column' => [
'access' => ['some_group'],
// 'access' => [
// 'func' => 'some\callable::func',
// 'params' => [
// 'sql_table.column',
// 'sql_table.column2',
// 'some_free_value'
// ]
//],
'action' => [
'card_icon2' => [
'title' => 'Прикрепление исходящего номера',
'path' => '/outgoing/journal/',
'icon' => '<i class="fa fa-anchor"></i>',
//'access' => ['some_group', 'else_group'], // or callable
// 'access' => [
// 'func' => 'some\callable::func',
// 'params' => [
// 'sql_table.column',
// 'sql_table.column2',
// 'some_free_value'
// ]
//],
'params' => [
'icon_path_back' => '/incoming/adddoc',
'icon_for_id' => 'incoming_docs.id', // app will get data from db query
'icon_add' => 1
],
'clear' => [
'icon_add' => [
'outgoing_docs.id' => ['incoming_docs.outgoing_id']
]
]
],
'unfix' => [
'title' => 'Очистить',
'path' => '/xtables-card/unfix',
'icon' => '<span class="close">×</span>',
'params' => [
'icon_for_id' => 'incoming_docs.id', // app will get data from db query
'table' => 'incoming_docs',
'columns' => 'incoming_docs.outgoing_id',
'value' => 0
]
]
]
]
]
cell_link (array)
Добавление ссылок на ячейках с указанием полных sql названий ячейки (таблица + столбец) с параметрами: url, get параметры, дополнительные css классы
'cell_link' => [
'outgoing_docs.number' => [
'path' => 'outgoing/card',
'params' => [
'id' => 'outgoing_docs.id'
],
'css_classes' => 'ajax'
],
'outgoing_docs2.number' => [
'path' => 'outgoing/card',
'params' => [
'id' => 'outgoing_docs.repeated_id'
]
]
]
helper (array)
Пояснительные подсказки, обозначаемые знаком вопроса
'items'
- массив с подсказами, ключами в котором являются полные названия
sql таблица + столбец через точку, значением текст подсказки;
'access'
- если нужно ограничить показ меню определенным группам пользователей,
то используйте данный параметр, указав:
func
- название callable функции;params
- параметры (если в качестве параметров будут указаны sql таблица + колонка через точку,
соответствующие выборке из БД, то будут подставлены соответствующие значения);
output
no_cache
.
'helper' => [
'items' => [
'outgoing_docs.number' => 'Нажмите на номер, чтобы '
. 'перейти в карточку исходящего документа'
],
'access' => ['some_user_group', 'else_group'] // or callable such as shown above
]
popup_menu (array)
Горизонтальное меню в верхней части карточки.
'title'
- название или иконка, отображаемое в кнопке меню; по умолчанию используется иконка:
'items'
- массив с пунктами меню (ссылки с названиями); для разделителя используйте значение 'divider'
;
'access'
- если нужно ограничить показ меню определенным группам пользователей, то используйте данный параметр,
указав:
func
- название callable функции;params
- параметры;
output
no_cache
.
'popup_menu' => [
'title' => 'some_text_icon', // some text or icon
'items' => [
'<a href="/incoming/newcard">Новая запись</a>',
'<a href="/incoming/journal">Таблица</a>'
],
'access' => ['some_user_group', 'else_group'] // or callable
]
Если необходимо создать несколько групп кнопок, то нужно каждый из указанных массивов обернуть в массив.
'popup_menu' => [
[
'title' => 'some_text_icon', // some text or icon
'items' => [
'<a href="/incoming/newcard">Новая запись</a>',
'<a href="/incoming/journal">Таблица</a>'
],
'access' => ['some_user_group', 'else_group']
],
[
'title' => 'some_text_icon', // some text or icon
'items' => [
'<a href="/incoming/newcard">Новая запись</a>',
'<a href="/incoming/journal">Таблица</a>'
],
'access' => ['some_user_group', 'else_group']
]
]
Пример карточки с вызовом через ajaxDispatcher (без иконок для связи таблиц):
Пример карточки с вызовом через ajaxDispatcher без использования стандарного шаблона в виде таблицы: