---

CardNew может использоваться для создания новых записей в sql таблицах БД.

---

Взаимодействие с данным компонентом осуществляется путем создания экземпляра класса xtables\components\CardNew\CardNew и вызова публичных методов:

• get() - возвращает полностью готовую форму карточки, построенную с использованием переданных в CardNew параметров настройки
• в случае необходимости построения карточки по индивидуальному шаблону необходимо использовать методы:
  • getData() - возвращает массив данных, которые могут быть добавлены в индивидуальный шаблон; массив состоит из блоков:
    • 'structure' - массив, в котором ключами будут выступать полные наименования sql таблица + колонка согласно настройкам; в данном массиве данные для вывода карточки в представлении будут представлены в виде массива:
      • 'name' - имя для данных (включая подсказку, если она требуется согласно настройкам);
      • 'value' - поле ввода согласно настроечным параметрам (input, select, textarea, radio, checkbox);
    • остальные значения могут быть при необходимости использованы, но это не является обязательным, так как они добавляются автоматически; среди них:
      • 'hidden_inputs' - блок hidden inputs, согласно настроечным параметрам;
      • 'ajax_dispatcher' - имя ajDi, необходимо для правильного функционирования карточки;
      • 'popup_menu' - созданное popup menu, если оно присутствует в параметрах настройки;
      • 'card_title' - заголовок карточки согласно настройкам.
      и другие...

    Пример выходного массива:

    
    [
        'structure' => [
            'incoming_docs.number' => [
                'name' => 'Number',
                'value' => 'input, textarea, select, checkbox',
            ],
        ],
        'hidden_inputs' => [
            '' => '',
            '' => ''
        ],
        'ajax_dispatcher' => 'ajdi_name',
        'popup_menu' => 'popup menu in tags',
        'card_title' => 'card title or Card',
        ...
    ]
                        

  • getForm() - возвращает готовую форму карточки; в данный метод в качестве параметров должно быть обязательно передано тело карточки $formBody;
    может быть отредактирована кнопка Save через массив параметров $saveButton:
    • 'css_classes' - css классы через пробел;
    • 'content' - содержимое кнопки, включая иконку.
    • 'not_hidden' - в случае, если данный параметр определен как true, то кнопка не будет скрыта; по умолчанию кнопка скрыта.

    
    $saveButton = [
        'css classes' => 'some_classes',
        'content' => 'Save ......',
        'not_hidden' => true
    ]
                        

Создание карточки по стандартному шаблону:

use xtables\components\CardNew\CardNew;

$card = new CardNew($params);

/**
 * @return string html card with all data according to settings in current app component
 */
$somecard = $card->get();
    

Создание карточки по индивидуальному шаблону:

use xtables\components\CardNew\CardNew;

$card = new CardNew($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'

newcard_sample (string)

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

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

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

'newcard_sample' => '/config/card/newcard-specific.html'

table (string) передача во входных параметрах блокируется

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

'table' => 'incoming_docs'
    

structure (array with array values) передача во входных параметрах блокируется

Массив параметров для определения полей для ввода данных. Поддерживаются html формы input, textarea, select, radio, checkbox.

В качестве ключей выступают полные названия колонк (sql таблица + колонка через точку), в качестве значений - массив параметров:

• 'name' - название, как оно будет отображаться на странице;
• 'type' - тип элемента html формы; поддерживаются input, textarea, radio, checkbox, select; либо скрытый элемент hidden, данные которого предустанавливаются и не должны вводиться пользователем;
• 'values' - массив со значениями для элементов radio, checkbox, select;
• 'css_id' - добавление идентификатора css;
• 'css_classes' - добавление классов css
• 'value' - предустановленное значение поля, например, для элементов с типом hidden или массив параметров для composite_number;
• 'max_len' - максимальная длина поля (количество символов); для ограничения используется js; на странице показывается оставшееся допустимое к вводу количество символов; при вводе символов показывается остаток, который последовательно меняет свой цвет на желтый (осталось 20 и менее) и красный (достингнут 0); после этого ввод символов блокируется JS;
• 'access' - если нужно ограничить показ данного поля, нужно определить данный параметр, указав:
  • массив уровней доступа или строка с одним уровней доступа;
  • массив для вызова callable функции:
    func - название callable функции;
    params - параметры (если в качестве параметров будут указаны sql таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);
• string 'sql_type' - по умолчанию, если имя колонки имеет в своем составе date, то к нему применяются правила даты, если time - правила даты и времени; если поле не имеет в своем имени подобных обозначений, то можно использовать данный параметр, присвоив ему значения date или time.

Если данные должны быть вставлены с какими-то предопределенными значениями, которые не вводит пользователь, то можно использовать в настройке тип hidden
Может использовать автокомплит на поле ввода, который проверяет на наличие значений в определенном столбце определенной sql таблицы. Автокомплит обеспечивается классом xtables\base\Autocomplete (подробности настройки см. Autocomplete).
К ячейке могут добавляться css идентификаторы и классы. Если необходимо сделать поле обязательным к заполнению, то необходимо добавить ему класс required

'structure' => [
        'some_table.group' => [
            'name' => 'Тип документа',
            'type' => 'select',
            'values' => [
                '' => '',
                '' => '',
            ]
        ],
        'some_table.group2' => [
            'name' => 'Тип документа',
            'type' => 'radio',
            'values' => [
                '' => '',
                '' => '',
            ]
        ],
        'some_table.group3' => [
            'name' => 'Тип документа',
            'type' => 'checkbox',
            'values' => [
                '' => '',
                '' => '',
            ]
        ],
        'some_table.from_who' => [
            'name' => 'От кого',
            'type' => 'textarea',
            'css_id' => 'autocomplete1',
            'max_len' => 200,
            'css_classes' => 'required'
        ],
        'some_table.address' => [
            'name' => 'Адрес',
            'type' => 'input'
        ],
        'some_table.reg_date' => [
            'type' => 'hidden',
            'value' => date("d.m.Y")
        ],
        'some_table.number' => [
            'type' => 'hidden',
            'value' => [
                'names' => [
                    'group',
                    date("Y") => 'predefined',
                    'id'
                ],
                'delimiter' => '/'
            ]
        ],
        'some_table.some_column' => [ // need to format as date when insert to db
            'type' => 'input',
            'css_classes' => 'date',
            'sql_type' => 'date'
        ]
    ]
    

Композитные значения как параметр structure

При создании новой записи имеется возможность добавления композитного значения, то есть строки, состоящей из вводимых пользователем при заполнении новой карточки данных, данных predefined, предопределенных в настройках, и автоматически создаваемого в базе данных id (primary autoincrement), разделенные знаком разделителя delimiter.

Для использования данного вида нужно составить параметр insert следующим образом:

• 'type' - параметр 'hidden'
• 'value' - массив с параметрами:
  • 'names' - массив с параметрами (значения в итоговом результате будут расставлены так, как они расположены в данном массиве, какие-либо специальные обозначения типов параметров не требуются xTables разберет их самостоятельно):
    
    • названия sql колонок (с таблицами или без в зависимости от того, как указаны все другие значения выше);
    • id - если нужно подставить автоматический инкремент базы данных, то в качестве значения нужно использовать id (можно использовать в разных местах несколько раз); автоинкремент будет поставлен в том месте, где он расположен в массиве;
    • пользовательские функции callable, возвращающие строку как результат своего выполнения, которая может быть добавлена в композитное значение; если в функцию нужно передать массив параметров, то нужно обозначить функцию в качестве ключа, а массив параметров в качестве значения; xTables проверит массив параметров и если найдет в нем наименования sql колонок, совпадающие с имеющимися в настройках, то подставит в них введенные с клиента значения; использование 'id' для подстановки автоинкрементного значения в параметрах функции не поддерживается;
    • любые значения, которые будут добавлены в композитное значение как предопределенные;
  • 'delimiter' - что использовать в качестве разделителя между каждым значением из массива names и автоматическим id

'structure' => [
    'some_table.whom' => [
        'type' => 'input'
    ],
    'some_table.outgoing_number_composite' => [
        'type' => 'hidden',
        'value' => [
            'names' => [
                'whom',
                'some_manual_value',
                '\app\SomeClass::newCompositeTest',
                '\app\SomeClass::newCompositeTest' => [
                    [
                        'some_table.whom',
                        'some_manual_value'
                    ]
                ],
                'id', // use id for update with autoincrement
                'some_manual_value_else',
                'some_table.content'
            ],
            'delimiter' => '/'
        ]
    ]
]
    

card_title (string)

Название, которое отображается в верхней части карточки

'card_title' => 'Новая карточка'
    

callback (string|array)

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

• строки с именем функции, включая namespance
• если нужно передать параметры в функцию, то необходимо указать массив:
  func - имя функции;
  params - массив с параметрами;

'callback' => [
    'func' => 'some\Func::name',
    'params' => [
        'param',
        'else'
    ]
],
// 'callback' => 'some\Func::name',
    

path (string)

Url для вызова новой карточки.

'path' => 'incoming/newcard'
    

path_after (string)

Путь для перехода после сохранения новой карточки.

'path_after' => 'incoming/card'
    

reload (boolean)

Если содержимое загружается с помощью ajaxDispatcher, то по умолчанию после создания новой карточки на той же странице будет загружаться созданная карточка. Если необходимо, чтобы после создания, форма новой карточки перезагружалась (без перезагрузки страницы), то нужно включить параметр reload со значением true (только при загрузке содержимого аякс-диспетчером).

'reload' => true
    

reset_cache (string|array)

По умолчанию при обновлении данных происходит очистка кэша текущей sql таблицы; если необходимо очищать дополнительные таблицы, то нужно включить данный параметр и добавить названия таких дополнительных таблиц.

'reset_cache' => ['some_else_table', 'some_else_table2'], // 'some_else_table'
    

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']
]
    

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

'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']
    ]
]
    

helper (array)

Пояснительные подсказки, обозначаемые знаком вопроса

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

'helper' => [
    'items' => [
        'number' => 'Введите данные номера в поле'
    ],
    'access' => ['some_user_group', 'else_group']
]
    

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'
    ]
]
    

---

Пример новой карточки с вызовом через ajaxDispatcher: