Documentation

This page is designed to document the functions, options, and advanced usage of TablePress and is more of technical nature, to suit the needs of developers and programmers.

For more general information about the plugin, please see the Plugin Info page. There is a page with Frequently Asked Questions as well, that should also be interesting to plugin users.

The Shortcode [table id=N /]

The Shortcode [table id=N /] is used to display a table in a post, on a page, or in a text-widget. It can either be entered manually or automatically using the “Table” button in the editor toolbar when editing a post or page.

The Shortcode can have the following parameters. All parameters can simply by added to the Shortcode (in arbitrary order), e.g.

[table id=1 alternating_row_colors=false column_widths="40px|50px|30px|40px" /]

If a parameter is added, it overwrites the corresponding Table Option from the “Edit” screen of that table!

For most use cases, it is recommended to change the setting in question by using the corresponding checkbox on the “Edit” screen of the table.

id (string) (required)
The ID of the table to show (can be seen on the “All Tables” or the “Edit” screen).
column_widths (string) (optional)

string with column widths, separated by the |-symbol (pipe)
examples:

column_widths="40px|50px|30px|40px"

or

column_widths="20%|60%|20%"
alternating_row_colors (boolean) (optional)
whether the table shall get alternating row colors (“zebra striping”) (see the CSS classes odd and even)
row_hover (boolean) (optional)
whether table rows shall be highlighted with a different background color, if the mouse hovers over them
table_head (boolean) (optional)
whether the first row will get <th> HTML tags inside a <thead> HTML tag
first_column_th (boolean) (optional)
whether the first column will get <th> HTML tags (there is no checkbox for this on the “Edit” screen!)
table_foot (boolean) (optional)
whether the last row will use <th> HTML tags inside a <tfoot> HTML tag
print_name (boolean) (optional)
whether the name of the table shall be printed above/below the table
print_name_position (string) (optional)
position for printing the table name: can be “above” or “below”
print_description (boolean) (optional)
whether the description of the table shall be printed above/below the table
print_description_position (string) (optional)
position for printing the table description: can be “above” or “below”
use_datatables (boolean) (optional)
whether the DataTables JavaScript library (a jQuery plugin) shall be used with this table (will only work, if the first row gets <th> HTML tags (either by the setting on the table’s “Edit” screen or by the Shortcode parameter)
datatables_sort, datatables_paginate, datatables_lengthchange, datatables_filter, datatables_info (boolean) (optional)
whether the corresponding feature of the DataTables JS library shall be activated for this table (more information in the DataTables section or on the DataTables website)

show_rows, hide_rows, show_columns, hide_columns (string) (optional)

These parameters can be used to overwrite visibility settings in the backend on a per-Shortcode basis.
Example:

[table id=2 hide_columns="1,2,3" show_rows="4,5,6" /]

will hide the first three columns and show rows 4, 5 and 6, regardless on what visibility setting they have in the backend. Instead of adding each row or column number manually, there’s also a parameter value “all” that will affect all rows/columns. They can also be used at the same time, if needed:

hide_columns="3,4,5" show_columns="8,9"
cellspacing, cellpadding, border (integer) (optional)

Corresponds to the parameters in

<table cellspacing="0" cellpadding="0" border="0"><tr><td>...</td></tr></table>

By default those are not set as the setting can be better influenced with CSS. In some rare cases they might necessary though.

The Shortcode [table-info id=N /]

The Shortcode [table-info id=N field="<field-name>"/] can be used to display table meta data in a post, page, or text widget.

You can show this data in the same way as tables by using the Shortcode

[table-info id=N field="<field-name>" /]

The Shortcode has three parameters:

id (string) (required)
The ID of the table that has the Custom Data Field
field (string) (required)
The name of a meta field (see below)
format
only possible value: raw. Only applies to the default field last_modified and will return the raw datetime format instead of the pretty string.

Possible values for field are:

name
The name of the table with ID id
description
The description of the table with ID id
last_modified
The time of the last modification of the table with ID id, if the format parameter is set to raw, a datetime string will be returned, otherwise a pretty string
last_editor
The author who last modified the table with ID id

Example of three Shortcodes in action (i.e. in a post or on a page near a table):

The table [table-info id=2 field="name" /] was last modified at [table-info id=2 field="last_modified" format="raw" /] by [table-info id=2 field="last_editor" /].

will produce something similar to

The table Demo Table was last modified at 2012-12-30 15:20:21 by TobiasBg.

There’s a also a Template Tag Function for this Shortcode available:

<?php tablepress_table_info( 'id=1&field=name' ); ?>

It works exactly as the Template Tag Function described below, with the parameters from this section.

Template Tag Functions

To show a table in places not covered by the Shortcode (e.g. in your page footer or in the sidebar) you can use the Template Tag Function tablepress_print_table( $query );. It can be added to any part of your theme (between PHP brackets: <?php and ?>).
The parameter $query can be a string in the form of a query string in a URL or other WordPress functions like wp_list_pages(), or it can be a an array with the query parameters and values.
If you don’t want to immediately print the table, but just get the output, use tablepress_get_table( $query );, which works the same way.

The possible parameters are the same as for the Shortcode.

Example with $query as a string:

<?php tablepress_print_table( 'id=1&use_datatables=true&print_name=false' ); ?>

Example with $query as an array (recommended and easier to read):

<?php tablepress_print_table( array( 'id' => '1', 'use_datatables' => true, 'print_name' => false ) ); ?>

There’s a also a Template Tag Function for the Shortcode [table-info id=N field="<field-name>" /] available:

<?php tablepress_print_table_info( "id=1&field=name" ); ?>

or

<?php tablepress_print_table_info( array( 'id' => '1', 'field' => 'name' ) ); ?>

It works exactly as the Template Tag Function described above, with the parameters from the section about the [table-info] Shortcode.

Table Options

Each table has individual options that only concern that table. They can be changed on the table’s “Edit” screen. All of them may be overwritten by the corresponding parameters of the Shortcode (Remember: If an option is set as a Shortcode parameter, it has preference over the corresponding option on the table’s “Edit” screen.)

The following options are available:

Alternating row colors
If enabled, every odd row will get the additional CSS class odd, every even row will get the class even. (Those classes have a different background color applied to them by the default CSS. There’s an example on how to change these colors in the FAQ.)
Row Highlighting
If enabled, the background color of all cells of the row that is currently hovered with the mouse cursor is changed to highlight the row. (There’s an example on how to change the color in the FAQ.)
Table Head Row
If this is activated, all cells in the first displayed row will be encapsuled by the <th> instead of the <td> HTML tag and the row will be put inside a <thead> HTML tag. This is mandatory for using any of the JS libraries functions!
Table Foot Row
If this is activated, all cells in the last displayed row will be encapsuled by the <th> instead of the <td> HTML tag and the row will be put inside a <tfoot> HTML tag.
Table Name
If enabled, the Name of the Table will be printed above/below the table inside a <h2> HTML tag, which has the CSS class tablepress-table-name. The position can be selected from “above” or “below”.
Table Description
If activated, the Description of the Table will be printed above/below the table inside a <span> HTML tag, which has the CSS class tablepress-table-description. The position can be selected from “above” or “below”.
Use JavaScript library
This option is only available, if the option “Table Head Row” is checked. If enabled, certain features of the DataTables JavaScript library can be enabled. See the DataTables section for more.

Plugin Options

The plugin has the following general “Plugin Options”. They affect the global plugin behavior in different areas.

Frontend Options influence the output and used features of tables in pages, posts, or text widgets.

Custom CSS
If you want to change the style of tables, you can enter those additional commands into the “Custom CSS” textarea. There are examples on how to change certain style aspects in the FAQ.
Plugin Language
With this setting you can change the language, TablePress is shown in, while the rest of WordPress will remain in the original language. This can be useful, if you want to use a special translation of the plugin, because it is more complete or better understandable.
Admin menu entry
Use this setting to move the menu entry “TablePress” (by default in the middle of the menu) to another location in the WordPress Admin Menu.

CSS selectors, Styling

Every table gets certain CSS classes and an HTML ID that can be used for styling. Add your styling commands to the “Custom CSS” textarea on the “Plugin Options” screen.

There are examples for the most common tasks on the FAQ page.

CSS classes are attached as <element class="class-name">...</element> to an <element>, IDs are attached as <element id="html-id">...</element>.

CSS classes (use them as

.class { 
/* your CSS */ 
}
tablepress (class of <table>)
Every table has this class.
tablepress-id-<ID> (class of <table>)
Every table has this class (with its ID for <ID>).
row-<number> (class of <tr>)
Every row gets this. <number> is the number of the row displayed, no matter if it is a heading row or data row. Counting always starts at 1.
column-<number> (class of every <th> or <td>)

<number> is the number of the column the cell belongs to. It will be a class of every <th> and <td> element.
Use this for styling column widths!
Example:

.tablepress .column-2 { 
	width: 200px; 
}

There’s another example in the FAQ. Important: If you use both the .column-X and the .row-X selectors at the same time, the .row-X has to stand before the .column-X (because it is given to the <tr> which encloses the <td>).

odd and even (classes of every <tr>)
If the Table Option “Alternating row colors” (or the Shortcode parameter) is enabled, every row will get one of these classes, depending on whether it is an odd or even row. Use the classes to actually style the alternating background colors. There’s an example to do this in the FAQ
tablepress-table-name (classes of <h2>)
If the Table Option “Print Table Name” is enabled, the Name of the Table will be printed above or below the table inside a <h2> HTML tag, which has this class.
tablepress-table-description (classes of <span>)
If the Table Option “Print Table Description” is enabled, the Description of the Table will be printed above or below the table inside a <span> HTML tag, which has this class.

CSS/HTML IDs (use them as

#html-id { 
/* your CSS */ 
}
tablepress-<ID>-no-<number> (ID of <table>)
Every table gets an ID like this. <ID> stands for the ID used in the “All Tables” list of TablePress. <number> is the count/occurance of that table on the page up to this point. (E.g. if you display the same table (with the same <ID>) twice on your site (e.g. once in a post and the second time in the sidebar), the first one will have no -no-... and the second one will have <number> = 2. This means, that these HTML IDs are not very reliable to be used for styling, as they might change depending on the occurance of the same table on the page again. These IDs are used to invoke the JavaScript library’s calls (if activated for this occurance of the table).

Features of the DataTables JavaScript Library

The DataTables JavaScript library (a jQuery plugin) is an additional feature (add-on) to TablePress. It was written by Allan Jardine and has its own Documentation.

It can add features like sorting, pagination (with length change feature), scrolling, and filtering/searching to a table. To enable those, check the corresponding checkboxes on the table’s “Edit” screen.

You may decide for each table individually whether you want to use the DataTables library for it (see the section Table Options for more), and you can select the desired features individually.
The library’s JavaScript file is located in the subfolder “js” of the plugin folder. It uses the jQuery library (which is included in WordPress and will be loaded automatically in the head every page your site).

You can add custom commands or parameters from the DataTables Documentation into the “Custom Commands” textfield. You can also use certain Plugin Hooks in a custom plugin to add your own commands (see the TablePress Extensions for some examples).

Plugin Hooks, Actions, and Filters

TablePress has a large number of WordPress Plugin Hooks (Actions and Filters) in its source code. They provide easy and well established methods to add new features and enhancements to the plugin, or to alter plugin behavior. A more detailed explanation can be found in the WordPress Codex.

There are some examples on how to use these hooks on the Extensions page.

The advantage of using these hooks in contrast to modifying the plugin’s source files is that the changes will still work after upgrading the plugin, and that they can be maintained separately.

Import and Export Formats

TablePress can import and export tables from and to the following formats:

CSV (Character-separated Values)
Every row is in a new line, every column is separated by a character (like “;” (semicolon), “,” (comma), or “\tab” (tabulator)). The plugin will try to determine the used separation character automatically. See the Wikipedia article for more information on the CSV format.
HTML (Hypertext Markup Language)
The plugin will import the first occurance of a HTML table (enclosed in <table></table>). It will not recognize or import tables with “colspan” or “rowspan” attributes in its cells!
JSON (JavaScript Object Notation)
TablePress can import tables from JSON that represents a plain two-dimensional array of strings, where each string represents the content of a cell. It can also import its custom and more advanced JSON format, as created during the export. See the Wikipedia article for more information on the JSON format.

Source Code

The plugin’s source code is freely available in the ZIP file that can be downloaded from the plugin’s page in the WordPress Plugin Repository. It is Open Source and licensed as Free Software under GNU General Public License 2 (GNU GPL 2).

The main development takes place in a Git repository on GitHub.

Top