CardView
Описание

CardView может использоваться для показа расширенной информации по записи в таблице (формирования карточки).
В карточке может отображаться информация из основной таблицы, а также связанная с данной карточкой информация из других таблиц.
Связь таблиц осуществляется через стандартные возможности карточки.

Записи основной таблицы могут быть отредактированы прямо в карточке.

Использование

Взаимодействие с данным компонентом осуществляется путем создания экземпляра класса 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;
      могут быть отредактированы кнопки Save и Cancel через массивы параметров $saveButton, $cancelButton:
      • 'css_classes' - css классы через пробел;
      • 'content' - содержимое кнопки, включая иконку.
      • 'not_hidden' - в случае, если данный параметр определен как true, то кнопка не будет скрыта; по умолчанию кнопка скрыта.
      
      $saveButton = [
          'css classes' => 'some_classes',
          'content' => 'Save ......',
          //'not_hidden' => true
      ]
                          

Пример построения карточки по индивидуальному шаблону с учетом кеша.


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);
    
Настройки

Настроечные параметры для генерации новой карточки должны быть составлены в виде ассоциативного массива (или объекта), который передается в конструктор данного компонента. Рекомендуется помещать их в отдельном файле.



dbc (string)

Название подключения к БД из пула подключений в файле config.php.
Если не указано, то выборка будет производиться из первой по списку БД.


'dbc' => 'pgsql'

card_sample (string)

Карточка строится с использованием шаблона, находящегося в настройках в файле /config/card/card.html. При необходимости данный шаблон может быть отредактирован.

Если нужно построить карточку на дополнительных шаблонах, то нужно определить параметр card_sample, указав в нем относительный путь до файла со специфичным шаблоном карточки от базового каталога, соответствующего константе XTABLES_BASE. Это является дополнительной и более простой возможностью к построению полностью индивидуальной карточки с использованием метода данного компонента getData(), описанного выше.

При построении специальных шаблонов нужно руководствоваться требованиями, указанными в файле с базовым шаблоном таблицы /config/card/card.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) передача во входных параметрах блокируется

Массив параметров для построения карточки:

  • в качестве ключа необходимо указывать полное название, включающее название sql таблицы и столбец, в качестве значения - наименование колонки, как оно будет отображаться на странице;
  • 'hr' - значение-параметр для вставки пустой строки-разделителя меньшей высоты;
  • любое значение, которое будет добавлено в карточку, при этом ячейки ряда карточки будут объединены, значение будет выровнено по центру (может быть текстом, изображением и пр.);
  • 'del_button' - системная кнопка удалить (ячейки ряда карточки будут объединены, иконка будет выровнена по центру): удаляет запись, при наличии в настройках сохраняет лог, обновляет ajax dispatcher, если компонент загружен с его использованием, либо обеспечивает переход по адресу, указанному в параметре 'path_after_del';
  • callable функцию в качестве ключа и в качестве значения параметры:
    • '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) передача во входных параметрах блокируется

Массив параметров для активации на полях (ячейках) возможностей их редактирования.

  • array 'access' - если нужно ограничить показ всех элементов редактирования определенным группам пользователей, то необходимо использовать данный параметр, указав:
    • массив уровней доступа или строка с одним уровней доступа;
    • массив для вызова callable функции:
      func - название callable функции;
      params - параметры (если в качестве параметров будут указаны sql таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);
  • string | array callback - если необходимо выполнить какую-нибудь callable функцию после осуществления обновления данных, то необходимо указать ее в данном параметре в виде:
    • строки с именем функции, включая namespance
    • если нужно передать параметры в функцию, то необходимо указать массив:
      func - имя функции;
      params - массив с параметрами;
  • string|array 'reset_cache' - по умолчанию при обновлении данных происходит очистка кэша текущей sql таблицы; если необходимо очищать дополнительные таблицы, то нужно включить данный параметр и добавить названия таких дополнительных таблиц;
  • 'items' - массив с элементами карточки, в котором ключами выступают полные имена колонок (sql таблица + колонка через точку), а значениями - массивы с настройками:
    • string 'type' - тип элемента html формы; поддерживаются input, textarea, radio, checkbox, select;
    • array 'values' - массив со значениями для элементов radio, checkbox, select;
    • string 'css_id' - добавление идентификатора css;
    • string 'css_classes' - добавление классов css
    • int 'max_len' - максимальная длина поля (количество символов); для ограничения используется js; на странице показывается оставшееся допустимое к вводу количество символов;
    • array 'access' - если нужно ограничить показ данного поля, нужно определить данный параметр указав:
      • массив уровней доступа или строка с одним уровней доступа;
      • массив для вызова callable функции:
        func - название callable функции;
        params - параметры (если в качестве параметров будут указаны sql таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);
    • string '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':

  • string 'table' - название sql таблицы-лога, в которую нужно сохранить информацию об истории; по умолчанию, если не указано, то будет использоваться log_base;
  • array 'event' - описание события:
    • ключ - полное название колонки (sql таблица + колонка через точку);
    • значение - название, как оно будет сохранено в логе истории в БД.
    данные сохраняются в логе массивом в поле event в json encoded строке; при совпадении с названием столбцов в редактировавшейся записи в истории будет использоваться введенное пользователем значение; если нет, то ключ будет проигнорирован; таким образом, в лог будут попадать только реально редактировавшиеся данные из определенного в параметре списка полей.

'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' - если нужно ограничить показ данного поля, нужно определить данный параметр, указав:
    • массив уровней доступа или строка с одним уровней доступа;
    • массив для вызова callable функции:
      func - название callable функции;
      params - параметры (если в качестве параметров будут указаны sql таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);
  • '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' - если нужно ограничить показ меню определенным группам пользователей, то используйте данный параметр, указав:
    • массив уровней доступа или строка с одним уровней доступа;
    • массив для вызова callable функции:
      func - название callable функции;
      params - параметры (если в качестве параметров будут указаны sql таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);

'helper' => [
    'items' => [
        'outgoing_docs.number' => 'Нажмите на номер, чтобы '
            . 'перейти в карточку исходящего документа'
    ],
    'access' => ['some_user_group', 'else_group'] // or callable such as shown above
]
    

popup_menu (array)

Горизонтальное меню в верхней части карточки.

  • 'title' - название или иконка, отображаемое в кнопке меню; по умолчанию используется иконка:
  • 'items' - массив с пунктами меню (ссылки с названиями); для разделителя используйте значение 'divider';
  • 'access' - если нужно ограничить показ меню определенным группам пользователей, то используйте данный параметр, указав:
    • массив уровней доступа или строка с одним уровней доступа;
    • массив для вызова callable функции:
      func - название callable функции;
      params - параметры;

'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 без использования стандарного шаблона в виде таблицы: