Back to home page
Il Jester
My little dream is in developing

DM Table

Posted on / Davide/Projects

DM Table is not a real plugin, but a class for creating tables. It is a table generator, customizable and suitable for any PHP project. Being a generic class, it is cross-script, so it can be adapted and used on different types of content platform (CMS).

However, the package also includes DM_Table_WP, which is a class prepared specifically for Wordpress and ClassicPress. DM_Table WP is not an extension of DM_Table, but uses a DM_Table instance.

Preliminary note: all past values ​​should be sanitized and escaped

DM_Table basic usage

First of all, it is necessary to establish where the class is located. We use require or better, require_once:

require_once dirname(__DIR__) . '/dm-table/classes/class-dm-table.php';

After that, we create an instance:

$instance = new Dm_Table;

Base url

We define the base url, and that is the link that points to our file where we have instantiated the class or is localized your table (eg example.php).

$instance->setBaseUrl( $url = '' );
$your_url = 'http://mysite/example.php'; // The url where the table script is located 
$instance->setBaseUrl( $your_url );

Sortable

We set sortable select, based on values if you want:

$instance->setSortable( $args = array(),  $input = null, $submit = null );
$instance->setSortable(
	array(
          'orderby' => array( 'orderby', 'ID' ),        // values are: action name and default value
          'order'   => array( 'order', 'asc', 'desc' )  // values are: action name, default value and alt value
	),
	DM_Table::input(
	  'select',
          array(
		'name'  => 'orderby',                                      // name of action
		'value' => DM_Table::action( INPUT_GET, 'orderby', '-1' ), // you can use $_GET['orderby'] or filter_input( INPUT GET, 'orderby' )
		'choices' => array(
			'ID' 	    => 'ID',
			'email'     => 'Email',
			'username'  => 'Username'
		)
	   )
	),
	DM_Table::input(
		'submit',
		array(
			'value' => 'Order'
		)
	)
);

Search

To build search action.

$instance->setSearch( $args = array(), $input = null, $submit = null );

The same explanations apply for sortable, with the due differences in the example, in particular with regards to $args where only one argument is passed with an array as a value.

$instance->setSearch(
	array(
		'search' => array( 'search_action', '' ) // values are: action name and default value
	),
	DM_Table::input(
		'search',
		array(
			'name'  => 'search_action', // name of action
			'value' => DM_Table::action( INPUT_GET, 'search_action', '' ), // you can use $_GET['search_action'] or filter_input( INPUT GET, 'search_action' )
			'id'    => 'mysearch_id',
			'class' => 'mysearch_class',
			'placeholder' => 'Find...'
		)
	),
	DM_Table::input(
		'submit',
		array(
			'value' => 'Search'
		)
	)
);

Filters

With filters, we get results based on the established conditions.

$instance->setFilters( $inputs = array(), $submit = null );

Filters can be more than one. For this reason, the first argument of setFilters will be an array of inputs. As an example. Note that $args argument is moved into the inputs array. In the example, we have two filters: by “color” and by “city”.

Important, the “filter” and “input” keys must be called proper “filter” and “input”!

$instance->setFilters(
	array(
		'color' => array(
			'filter' => array( 'color', '-1' ), // values are: action name and default value (ex $args argument)
			'input' => DM_Table::input(
				'select',
				array(
					'name' => 'color', // name of action
					'value' => DM_Table::action( INPUT_GET, 'color', '-1' ), // you can use $_GET['color'] or filter_input( INPUT GET, 'color' )
					'choices' => array(
						'-1' 		=> 'Color Filter',
						'red'  		=> 'Red',
						'yellow'  	=> 'Yellow',
						'blue'  	=> 'Blu',
						'white' 	=> 'White'
					)
				)
			)
		),
		'city' => array(
			'filter' => array( 'city', '-1' ), // values are: action name and default value
			'input' => DM_Table::input(
				'select',
				array(
					'name' => 'city', // name of action
					'value' => DM_Table::action( INPUT_GET, 'city', '-1' ), // you can use $_GET['city'] or filter_input( INPUT GET, 'city' )
					'choices' => array(
						'-1' 		=> 'City Filter',
						'rome'  		=> 'Rome',
						'paris'			=> 'Paris',
						'london'		=> 'London',
						'new_york'		=> 'New York'
					)
				)
			)
		)
	),
	DM_Table::input(
		'submit',
		array(
			'value' => 'Filter'
		)
	)
);

Actions

In the table, we need a select for actions. There he is!

$instance->setActions( $args = array(), $input = null, $submit = null

The same explanations given for sortable apply.

$instance->setActions(
	array(
		'action' => array( 'select_action', '-1' ) // values are: action name and default value
	),
	DM_Table::input(
		'select',
		array(
			'name'  => 'select_action', // name of action
			'value' => DM_Table::action( INPUT_GET, 'select_action', '-1' ), // you can use $_GET['select_action'] or filter_input( INPUT GET, 'select_action' )
			'choices' => array(
				'-1' 		=> 'Actions',
				'delete' 	=> 'Delete',
				'edit' 		=> 'Edit'
			),
		)
	),
	DM_Table::input(
		'submit',
		array(
			'value' => 'Action'
		)
	)
);

Perpage

This is necessary to choose limit items per page. This, if you have a huge amount of data to display in the table.

$instance->setPerpage( $args = array(), $input = null, $submit = null );

As you can see the method is the same as those already seen.

$instance->setPerpage(
	array(
		'perpage' => array( 'perpage', 5 ), // name of action and default value
	),
	DM_Table::input(
		'text',
		array(
			'name' => 'perpage', // name of action
			'value'	=> DM_Table::action( INPUT_GET, 'perpage', 5 ), // you can use $_GET['perpage'] or filter_input( INPUT GET, 'perpage' )
			'class' => 'dm-perpage'
		)
	),
	DM_Table::input(
		'submit',
		array(
			'value' => 'Perpage'
		)
	)
);

Prepare data

Now we need to prepare our query, filtering, action and/or order the data based on the selections seen above.

DM_Table offers us several public properties to do this:

$instance->orderby;  // order by value
$instance->order;    // order ASC or DESC
$instance->search;   // fiter by search key
$instance->filters;  // an array of filters
   // eg. $instance->filters['color']['value'] // for color filter
   // eg. $instance->filters['city']['value']  // for city filter
$instance->action;            // action selected
$instance->input_action_name; // This property refers to the name of the reconstructed action starting from the property $instance-> action, accompanied by square brackets to trap multiple values.
$instance->perpage;           // how many items will be displayed in the table in each page. For usage, see below

After filtering our query, with result we need to prepare the paging. In this way we will also get the paging values ​​(offset and limit) that will be applied to our query.

$instance->setPagination( $args  = array() );
$instance->setPagination(
	array(
		'total_rows'   => $query_rows,                              // total number of your query rows after filtering. Argument accept array or int
		'start'        => array( 'tpage', 1 ),                      // name of page and start value
		'limit'        => array( 'tperpage', $instance->perpage ),  // name of perpage and the value obtained from select perpage
		'action_uri'   => true                                      // set true to use base_url for action pagination
	)
);

A this point, we retrieve the public properties for limit and offset:

$offset  = $instance->offset;
$limit   = $instance->limit; // aka perpage

Note. As it emerges, we have two properties that have a similar value: $instance->perpage and $instance->limit. In fact they are interchangeable. The first was designed for convenience, because is the result of action perpage and would set “limit” in setPerpage, to get $instance->limit.

At this point, we can conclude the filtering of our query with the properties $limit and $offset. The results will be used to build data table.

Columns

Before, we create columns. It is very simply. Is an array:

$columns = array(
   'action'   => '',        // we use this column for actions
   'ID'       => 'ID',      // column for IDs of item
   'username' => 'Username', // column for usernames
   'email     => 'Email'    // column for emails
);

Table Data

The query result can be an array of objects to be extracted with a while or foreach loop.

$data = array();
$users = $our_query; // In the example the query concerns a user table, composed of an array of IDs, usernames and emails.
if( !empty( $users ) ) {
    foreach( $users as $key => $user ) { // or while( $row = $users->fetch_assoc() )
	
	$data[] = array(
		'action' => DM_Table::input( 'checkbox', // this is an action for manage delete or edit row
			array(
				'name'  	=> $instance->input_action_name, // See below for description
				'value' 	=> $user['ID'],
				'class' 	=> $instance->action, // see below for description
				'id'	   	=> ( $instance->action !== '' ? $instance->action . '-' . $user['ID'] : '' )
			)
		),
		'ID' 		=> $user['ID'],
		'username' 	=> $user['username'],
		'email' 	=> $user['email']
	);

   }

}

Table Set

Now we have all the elements to set up the table.

$instance->setTable( $args = array() );
$args = array(
	'header' 		=> $columns,     // columns
	'content' 		=> $data,        // data,
	'footer'		=> true,	 // if true, we render footer as mirror header
	'raw_data'		=> $users,	 // the array of users example
	'no_data'		=> 'Sorry, no data yet!', // message for no results
	'sortable'		=> true, 	 // if yes, columns will be sortable
	'table_fixed'	        => true,	 // if yes table will be render fixed
	'table_id'		=> 'test_id',    // id for table,
	'before_list'	=> array( // create a menu before the list (available also after_list)
		'<a href="' . DM_Table::escValue( $your_url ) . '">Base</a>',
		DM_Table::SEP,
		'<span class="total-rows">Total Items: ' .DM_Table::escValue( $dm_table->total_rows ) . '</span>',
		DM_Table::SEP,
		'Other stuff!'
	),
	'scope_row' 		=> 'action', // for usability
	'column_bulk'		=> 'action', // set column bulk (remember in columns?)
	'bulk_js_callback'	=> 'toggleBulk(this)' // action js for bulk. Set false if you want to create your own.
);

$instance->setTable( $args );

The table is complete with minimal requirements. To view it:

$instance->displayTable();

Inner Row (optional)

If you want, you can insert a innered row in the table. Using this method, after DM_Table::setTable():

$instance->innerRow( $after_row = int, $class = '', $callback( $columns, $instance, $data ) );
$dm_table->innerRow( 2, 'inner-row-2', function( $columns, $instance, $users ) {  // we wont insert a row after second table row
	$user_name = $users[1]['username'];
	return '<td class="hidden-row" style="display:none; background-color: red;" colspan="' . DM_Table::escValue( $columns ) . '">This is a innered row for ' . DM_Table::escValue( $user_name ) . '</td>';
} );

Conclusions

For more details, customizations, passable arguments or values, and much more, see the class DM_Table.

For Wordpress is available in the package the class DM_Table_WP.

 Download   Donate