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

Взаимодействие с данным компонентом осуществляется путем создания экземпляра класса xtables\components\TableView\Tableview и вызова его двух публичных методов get() и getSearchForm().

Метод get() возвращает таблицу, построенную с использованием переданных в TableView параметров настройки, getSearchForm() - форму поиска, также построенную на основании указанных параметров.

use xtables\components\TableView\TableView;

$table = new TableView($params);

/**
 * @return string html table with all data according to settings in current Particular agent
 */
$mainTable = $table->get();

/**
 * @return string html search for for directly adding to page
 */
$searchForm = $table->getSearchForm();
    

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

dbc (string)

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

'dbc' => 'pgsql'

table_sample (string)

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

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

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

'table_sample' => '/config/table/table-specific.html'

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

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

• в качестве ключа - полное название, включающее название sql таблицу и столбец, в качестве значения - наименование колонки, как оно будет отображаться на странице.
• в качестве ключа - callable функция, в качестве значения массив:
  • (string) name - наименование колонки, как оно будет отображаться на странице;
  • (string) rearrange - если необходимо осуществлять сортировку по столбцу, где применяется функция, то необходимо определить полное название, включающее название sql таблицы и столбец, по которому будет сортироваться, в данном параметре;
  • (array) params - массив с параметрами, которые будут переданы в callable функцию; если в качестве параметра будет указано полное название, включающее название sql таблицу и столбец через точку, то в качестве параметра будет передано соответствующее значение из выборки из базы данных;
  • (string) css_classes - ячейке таблицы будут добавлены css классы, указанные здесь через пробел;
  • (string) css_style - если необходимо прямо указать какие-то инлайн стили, то можно указать их в строке здесь, например: width: 80px; font-weight: bold.
• 'del_button' - системная кнопка удалить: удаляет запись, при наличии в настройках сохраняет лог, обновляет ajax dispatcher, если компонент загружен с его использованием, либо обеспечивает переход по адресу, указанному в параметре 'path_after_del'; для использование этой системной кнопки необходимо определить в выборке select поле с первичным id, в противном случае будет сгенерировано сообщение об ошибке;

'structure' => [
    'outgoing_docs.number' => 'Исх. номер',
    'outgoing_docs.reg_date' => 'Дата регистрации',
    'app\some\class::someMethod' => [
        'name' => 'Statistics',
        'rearrange' => 'outgoing_docs.some_column',
        'params' => [
            'outgoing_docs.some_column',
            'outgoing_docs.else_column',
            'some_param'
        ],
        'css_classes' => 'some-class hidden-sm',
        'css_style' => 'widht: 80px; font-size: 24pt'
    ],
    'del_button'
]
    

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

Массив параметров для выборки из sql таблиц, необходимо указывать полное название (sql таблица + колонка через точку).

По умолчанию, если имя колонки имеет в своем составе date, то к нему применяются правила даты, если time - правила даты и времени; если поле не имеет в своем имени подобных обозначений, но необходимо форматировать выводимые данные как дату, то можно в качестве ключа к соответствующей колонке подставить date или time.

'select' => [
    'outgoing_docs.number',
    'outgoing_docs.reg_date',
    'date' => 'outgoing_docs.some_column' // need to format as date
]
    

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

Название sql таблицы и столбца для первичной сортировки (используется при выводе таблицы на экран и формирования sql cache); если не определено, то используется сортировка по первичному ключу id таблицы, определяемой в параметре 'table', в порядке убывания (рекомендуется)

'pre_order' => 'outgoing_docs.id DESC'
    

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

Основная таблица выборки

'table' => 'outgoing_docs'
    

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

Дополнительные таблицы, по которым может быть выполнен JOIN

'table_add' => 'LEFT JOIN outgoing_docs as outgoing_docs2 '
    . 'ON outgoing_docs.repeated_id = outgoing_docs2.id '
    . 'LEFT JOIN projects ON '
    . 'outgoing_docs.project_id = projects.id'
    

distinct_ids (bool)

В случае, если необходимо убирать из показа записи с повторяющимися id, нужно включить параметр 'distinct_ids' и указать в нем в качестве значения полное название sql таблица + столбец через точку идентификаторов, по которым будет проводится проверка на совпадение (по данному полю должна проводится сортировка).

'distinct_ids' => 'some_table.id'
    

path (string)

Url, который подставляется в ссылки пагинации и сортировки столбцов.

'path' => 'outgoing/journal'
    

path_after_del (string)

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

'path_after_del' => '/some/url'
    

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

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

В качестве параметров редактирования могут быть определены:

• array 'access' - если нужно ограничить показ всех элементов редактирования определенным группам пользователей, то нужно использовать данный параметр, указав:
  • массив уровней доступа или строка с одним уровней доступа;
  • массив для вызова callable функции:
    func - название callable функции;
    params - параметры (если в качестве параметров будут указаны sql таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);
  При использовании данного параметра ограничения доступа кеширование уровня output
  автоматически отключается, независимо от значения параметра no_cache.
• string | array callback - если необходимо выполнить какую-нибудь callable функцию после осуществления обновления данных, то необходимо указать ее в данном параметре в виде:
  • строки с именем функции, включая namespance
  • если нужно передать параметры в функцию, то необходимо указать массив:
    func - имя функции;
    params - массив с параметрами;
• string | array 'reset_cache' - по умолчанию при обновлении данных происходит очистка кэша текущей sql таблицы; если необходимо очищать дополнительные таблицы, то нужно включить данный параметр и добавить названия таких дополнительных таблиц;
• array '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 таблица + колонка через точку, соответствующие выборке из БД, то будут подставлены соответствующие значения);
    При использовании данного параметра ограничения доступа кеширование уровня output
    автоматически отключается, независимо от значения параметра no_cache.
  • 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'
    ]
]
    

cell_link (array)

Добавление ссылок на ячейках с указанием полных sql названий ячейки (таблица + столбец) с параметрами: url, get параметры, дополнительные css классы и css идентификатор. См. CellAction.

'cell_link' => [
    'outgoing_docs.number' => [
        'path' => 'outgoing/card',
        'params' => [
            'id' => 'outgoing_docs.id'
        ],
        'css_classes' => 'ajax'
        'css_id' => 'some_id',
        'target' => '_blank'
    ],
    'outgoing_docs2.number' => [
        'path' => 'outgoing/card',
        'params' => [
            'id' => 'outgoing_docs.repeated_id'
        ]
    ]
]
    

non_sort_columns (array)

Массив с названиями столбцов (таблица + столбец), по котором не нужно добавлять возможность сортировки (по умолчанию добавляестя ко всем столбцам)

'non_sort_columns' => [
    'outgoing_docs.address',
    'outgoing_docs.content'
]
    

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

Предусловия выборки из таблиц; при осуществлении поиска предусловия заменяются значениями из формы поиска в случае их совпадения

'pre_condition' => [
    'outgoing_docs.number' => "outgoing_docs.number != 0"
]
    

onpage (int)

Количество записей, которое показывается на одной странице; может устанавливаться в 'onpage' в конфигурационном файле /config/congig.php для всех таблиц глобально и в настройках каждой таблицы персонально для нее; по умолчанию используется значение 200 записей, оно же установлено в качестве максимального

'onpage' => 100
    

page_range (int)

Количество страниц слева и справа от текущей в строке пагинации; может устанавливаться в 'page_range' в конфигурационном файле /config/congig.php для всех таблиц глобально и в настройках каждой таблицы персонально для нее; по умолчанию используется значение 5.

'page_range' => 7
    

seek_result_limit (int)

Количество записей в одной выборке, если данный параметр отсутствует, то по умолчанию установлено значение в 50 000 записей, минимальное значение равно 1, максимальное - 500 000 записей в одном срезе данных (sql LIMIT).
При построении пагинации не используется OFFSET (смещение). Пагинация строится на кешируемых массивах резолютирующих идентификаторов, которые обеспечивают быстроту при больших объемах данных.
Таким образом тяжелый запрос только производит выборку id и помещает их в кэш.

'seek_result_limit' => 10000
    

use \xtables\components\TableView\model\TableCache;

TableCache::resetCache('some_sql_table');
TableCache::resetCache(['some_sql_table', 'some_sql_table2']);

TableCache::resetAllCache();
        

no_cache (bool)

В случае, если необходимо отключить использование кэша в конкретной таблице, нужно включить параметр 'no_cache'.

'no_cache' => true
    

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' => 'Да'
    ],
]
    

comp_cell (array)

Используется для построения композитных ячеек, то есть ячеек, включающих в себя значения нескольких столбцов. Построение осуществляется классом xtables\base\CompositeCell; подробности по способам замены см. CompositeCell

'comp_cell' => [
    'outgoing_docs.number' => [
        'delimiter' => ' от ',
            'value' => [
            'outgoing_docs.number',
            ' от ',
            'outgoing_docs.reg_date'
        ]
    ],
]    
    

action (array)

Добавление иконок в первый столбец (создается при наличии хотя бы одной иконки) для каких-то действий. Подробнее см. IconAction.

'action' = [
    'icon_add' => [
        'title' => 'Добавление исх. к вх. номеру',
        'path' => $this->params['icon_path_back'],
        'icon' => '<i class="fa fa-plus"></i>',
        'css_classes' => 'ajax',
        'params' => [
            'id' => 'outgoing_docs.id',
            'icon_for_id' => $this->params['icon_for_id']
        ]
    ]
]
    

helper (array)

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

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

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

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

Массив параметров формы поиска: url для передачи данных формы, необходимые для поиска поля:

• array add_condition - массив с условиями, которые необходимо добавлять при любом непустом значении из условий поиска, вводимых пользователем (добавлять условия поиска, соединяемые через AND, лучше массивом простых значений, это позволит эффективно удалить все дубликаты);

  
  'add_condition' => [
      "incoming_docs.active = 1",
      "incoming_docs.valid = 1"
  ]
  

  предустановленное значение поиска pre_condition отключается при введении пользователем любых поисковых значений, поэтому если необходимо использовать какие-то предустановленные дополнительные условия поиска, то необходимо использовать параметр add_condition;
• array inputs - html поле в виде обычного input для ввода произвольного текста, минимальное количество символов для ввода ограничено 3; количество полей не ограничено; в качестве значения может быть установлено:
  • строка с полным наименованием ячейки (sql таблица + колонка через точку);
  • массив с параметрами:
    • string name - строка с полным наименованием ячейки (sql таблица + колонка через точку);
    • string css_classes - строка с наименованиями css классов, которые должны быть добавлены к input, например: для включения показа календаря для ввода даты нужно добавить полю класс 'date', даты и времени - 'date-time';
    • string css_id - строка с названием css идентификатора для добавления к input;
    • string|callable condition - по умолчанию поиск осущетвляетс по условию содержит LIKE, минимальное количество символов составляет 3;
      в случае, если это необходимо изменить, то должен быть определен данный параметр со значениями:
      • equal - поиск будет определяться по точному вхождению по условию равно, ограничение на минимальное количество символов применяться не будет;
      • not_equal - поиск будет определяться по точному вхождению по условию не равно, ограничение на минимальное количество символов применяться не будет;
      • если в качестве значения указана функция callable, то будет осуществлен ее вызов, в нее будут переданы два параметра:
        1. название ключа данного параметра (как правило, таблица + ячейка через точку),
        2. введенный поисковый запрос;
        функция должна возвратить поисковое уловие, которое будет подставлено в запрос; это условие НЕ БУДЕТ подтвергаться дополнительно фильтрации, это необходимо учитывать, лучше возвращать список id для поиска

    
    'inputs' => [
        'projects.name' => 'Проект',
        'outgoing_docs.number' => [
            'name' => 'Исходящий номер',
            'css_classes' => 'date',
            'css_id' => 'some_id',
            'condition' => 'equal'
        ],
        'outgoing_docs.number' => [
            'name' => 'Исходящий номер',
            'condition' => '\SomeClass\In\Namespace::callableFunction'
        ]
    ]
    
    public static function callableFuction($key, $value, $back = []) {
        $result = Db::getConnect()->prepare("SELECT id FROM some_table WHERE some_column LIKE ?");
        $result->execute(['%' . $value . '%']);
        while ($data = $result->fetch(\PDO::FETCH_ASSOC)) {
            $back[] = $data['id'];
        }
        return 'some_table_primary.id IN (' . implode(',', $back) . ')';
    }
                        

• array filters - фильтр с предустановленным условием выборки в виде checkbox; количество фильтров не ограничено
• array period - два html поля в виде input для ввода дат (без времени) с --- по --- для осуществления поиска по временному промежутку; количество периодов не ограничено
• array selects - html поле в виде select для осуществления поиска путем выбора одного из значений; количество селектов не ограничено
• @since 1.7.49 array hidden_not_for_search - hidden input, которые передаются во входных параметрах, однако в качестве условий поиска для TableView не используются, могут быть использованы, если дополнительные параметры необходимы во встречающем запрос методе
  Передача параметров типа hidden_not_for_search не защищается от возможной подмены на странице,
  поэтому они требуют отдельной обработки во встречающем запрос методе

'search' => [
    'path' => 'outgoing/ajax-data',
    'inputs' => [
        'outgoing_docs.id' => [
            'name' => 'ИД',
            'condition' => 'equal'
        ],
        'outgoing_docs.number' => 'Исходящий номер',
        'projects.name' => 'Проект',
        'outgoing_docs.whom' => 'Кому',
    ],
    'period' => [
        'outgoing_docs.reg_date' => 'Период регистрации',
    ],
    'filters' => [
        'filter' => [  // as filter key use free name
            'label' => 'Без ответов',
            'value' => "outgoing_docs.id NOT IN()"
        ]
    ],
    'selects' => [
        'incoming_docs.group' => [
            'label' => 'Тип',
            'values' => [
                '' => 'Все типы',
                '' => ''
            ],
        ]
    ],
    'hidden_not_for_search' => [
        'some_hidden_simple' => 'some_value',
        'else_simple' => 'else value'
    ]
],
    

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

thead_fix (boolean)

Фиксация заголовка таблицы при прокрутке страницы при значении данного параметра true.
Фиксация обеспечивается js функцией xtables.theadFix(), находящейся в файле /js/xtables.js.

'thead_fix' => true
    

highlight (array)

Возможна подсветка строки в таблице путем замены цвета фона ячеек в случае совпадения определенных условий с выборкой из sql таблицы.
@since 1.7.43 возможно добавление строки со свободной информацией css
Для использования нужно создать массив 'highlight' с параметрами:

в качестве ключа - название callable функции, которая должна вернуть строку с обозначением цвета в соответствии с правилами определения цвета css, например: red, #fff и т.п.;
как элементы массива нужно указать:

• название sql колонки (таблица + колонка через точку), значение которого будет передано в качестве параметра в функцию, если название sql колонки совпадет со значением из выборки из базы данных;
• статический параметр, который будет передан в качества параметра в функцию.

'highlight' => [
    '\app\some\SomeClass::methodName' => [
        'incoming_docs.closed',
        'incoming_docs.date'
    ],
    '\app\some\SomeClass::someFuncForHighlight' => [
        'incoming_docs.some_column_else',
        'some_static_param'
    ]
]
    

Пример callable функции:

public static function someFuncForHighlight($value) {
    if (strtotime($value) < strtotime('today')) {
        return 'yellow';
    }
}

public static function someFuncForHighlight($value) {
    if (strtotime($value) < strtotime('today')) {
        return 'text-decoration: line-through';
    }
}

short_pagination (boolean)

По умолчанию в случае наличия более одной страницы в таблице показывается полная пагинация, состоящая из указателей на номера страниц.
В случае включения параметра short_pagination будет показываться пагинация с указателями на предыдущую и следующую страницу.

'short_pagination' => true