Jet\UI_dataGrid
Complex element for displaying lists of data. So the "classic" one that displays a header with a list of columns, current data and controls for data paging.
As it is not a completely trivial element, it consists of several elements:
- Columns (column definition)
Columns must be defined. See the addColumn method. - Header
The header displays the column titles and has a separate subrenderer. See header() method. - Body
The body displays the data itself, it also has a separate subrenderer. See the body() method. - Footer
The footer shows mainly paging controls. The footer also has a separate subrenderer. See footer() method.
Inherited from Jet\UI_Renderer_Single
Example of use
It is important to emphasize that this component is only responsible for displaying the grid. Nothing more and nothing less. How the logic will work, i.e. where and how the application will get the data to display, how it will be paged and so on is not addressed by the UI component. That is a matter for your application, and other Jet components.
If you're looking for a comprehensive thing to handle data display as a whole, Jet has a solution in the form of Jet\DataListing that covers everything and of course uses UI_dataGrid for the display itself. I recommend using just Jet\DataListing.
But in the following demonstration we will show how to use this UI component directly - without the superstructure. The sample is a simple overview of users - registered visitors of the site (or customers ...):
namespace JetApplication;
use Jet\Data_Paginator;
use Jet\Http_Request;
use Jet\Tr;
use Jet\UI_dataGrid;
$GET = Http_Request::GET();
$grid = new UI_dataGrid();
$paginator = new Data_Paginator(
current_page_no: $GET->getInt('page_no', 1),
items_per_page: 25,
URL_creator: function( int $page_no ) : string {
return Http_Request::currentURI( ['page_no'=>$page_no] );
}
);
$grid->setPaginator( $paginator );
$users = Auth_Visitor_User::getList();
$grid->setData( $users );
$grid->addColumn('username', Tr::_('Username'));
$grid->addColumn('locale', Tr::_('Users language'));
Of course, the grid must be passed to the view and then displayed in the view script. But before that you need to define the renderers for the columns. The view hide can look like this:
namespace JetApplication;
use Jet\MVC_View;
use Jet\UI;
use Jet\UI_dataGrid;
/**
* @var MVC_View $this
* @var UI_dataGrid $grid
*/
$grid = $this->getRaw('grid');
$grid->getColumn('username')->setRenderer(function( Auth_Visitor_User $user ) {
echo $user->getUsername();
});
$grid->getColumn('locale')->setRenderer(function( Auth_Visitor_User $user ) {
$locale = $user->getLocale();
if($locale) {
echo UI::flag($locale).UI::locale($locale);
}
});
echo $grid;
Overview of methods
Method | Meaning of |
---|---|
public addColumn( string $name, string $title ) : UI_dataGrid_column |
Creates a column definition with a specific name (parameter $name - used to identify the column) and with a specific title (parameter $title). Returns instance of the column definition (which also serves as the column title renderer). |
public hasColumn( string $name ) : bool |
Verifies that the grid has a certain column defined. Useful for grids with dynamically generated column lists. So in a situation where, for example, the user can define what he wants to see in the data list. |
public getColumns( ) : UI_dataGrid_column[] |
Returns a list of defined columns. |
public getColumn( string $name ) : UI_dataGrid_column |
Returns the definition of a specific column. |
public setData( DataModel_Fetch_Instances|array $data ) : void |
Sets the data to be displayed in the list. |
public getData( ) : iterable |
Returns the data to be displayed in the list. |
public setSortUrlCreator( callable $sort_url_creator ) : static |
Sets up a URL controller creator. Prototype creator:
function( string $column_name, bool $desc ) : string
|
public getSortUrlCreator( ) : callable |
Returns the sort URL creator. See setSortUrlCreator method. |
public getSortURL( string $column_name, bool $desc=false ) : string |
Using the creator (see the setSortUrlCreator method) generates a URL for sorting a specific column in the specified order. |
public setSortBy( string $sort_by ) : static |
Sets the column the data is sorted by. The $sort_by parameter is the column name, but with a prefix. The prefixes are the - and + characters, which specify the sorting direction. The "-" character is the descending sort, the "+" character is the ascending sort. |
public getSortBy( ) : string |
Returns the current shift. See the setSortBy method. |
public setPaginator( Data_Paginator $paginator ) : static |
Sets up an instance of the data paginator. |
public getPaginator( ) : Data_Paginator|null |
Returns an instance of the data paginator. |
public header( ) : UI_dataGrid_header |
Access to grid header renderer |
public body( ) : UI_dataGrid_body |
Access to the grid body renderer |
public footer( ) : UI_dataGrid_footer |
Access to the grid footer renderer |