wiki:TablePlugin/docs

Version 13 (modified by jonny, 2 years ago) (diff)

--

TablePlugin Documentation

TablePlugin uses a similar style to the FlatTablePlugin that was originally developed. The inspiration for the TablePlugin originated from the FlatTablePlugin. A number of issues where present with the FlatTablePlugin, such as no wiki formatting support amongst other things.

TablePlugin provides improved readability and syntax for building up complex tables within a wiki. The headings and rows are now defined in the same way, this helps with the readability aspect, even for very complex tables that can be defined using the TablePlugin.

The TablePlugin supports the following items within the cells:

  • Lists
  • Wiki Markup
  • HTML
  • Web links
  • Nesting (including nesting of the TablePlugin itself)
  • Full CSS support (fully customisable heading and row cells)
  • Flexible heading/column definition styles, multi-line or comma-separated
  • etc...

Keywords

There are a number of keywords that are used within the TablePlugin macro that define various elements of the table. The keywords are preceded with the @ character to distinguish them.

The keywords:

  • @table - used when you want to define a table style or apply a custom table style to a new table.
  • @css - used to define a new style
  • @column - used to introduce a column.
  • @row - used to introduce a row
  • @<cell_name> - named as part of the @column definition.

The last keyword @<cell_name> is variable. It is based on the names you give the cells in your @column definition. This is covered in more detail below in the Table Definition section.

Table Definition

The following example will not focus on any types of styles. The TablePlugin provides a default style (which can be edited if required) that will always be used if no specific style is applied to the table. We will focus on the bare minimum markup required to setup a new table. Comments are included as part of the codeblock to further explain the markup and how to use it.

{{{
#!table
#!This is a comment line, the above is the macro used by trac to determine that the TablePlugin should be used to render the following text.
#!All comment lines begin with #!

#!-- First, we need to tell the table that it should be styled using the default style.

@table (@default)

#!-- Next, we need to setup our column names, using the @column keyword, so that we can add data to them.
#!-- Define the three columns to use: task, details, status

@column task
@column details
@column status

#!-- Using the column names above (task, details, status), we can add the data.
#!-- As mentioned in the keywords list above, these names can be anything you want.
#!-- This first row will be the headers for the table.

@task: Task
@details: Details
@status: Status

#!-- The next row will be the rest of the data that relates to Task, Details of the Task and the Status.

@task: Task 1
@details: Details of Task 1.
@status: Complete

#!-- Remaining rows below...

@task: Task 2
@details: Details of Task 2.
@status: Complete

@task: Task 3
@details: Details of Task 3.
@status: Not Complete

#!-- More rows added below if required... No limit on the amount of data.

}}}

From this example, you can see that the layout is very simple to setup and easy to read. Readability was a big factor when designing this markup.

Basically, after the columns are defined, you add your data and save the table. The default styles will be used.

The above, pasted into a trac page with the TablePlugin enabled will display the following:

simple table with default styles

Table Styles

The table styles are stored as part of a trac page. This trac page should be setup by the TablePlugin the first time it runs. It creates a page wiki/TablePluginStyles that contains a default table style along with a CSS header style for the tables heading.

There are two different types of styles:

  • Table Styles
  • CSS Styles

Both styles use the following naming conventions: @TYPE NAME (@STYLE): DATA

Table Styles define a full set of styles that can be applied to a table. They are written in CSS.

Table Styles are defined and written as follows:

@table table_style_name:

This allows the individual to create different table styles depending on what type of data they want to represent.

CSS Styles define individual styles that can be applied to individual elements of a table. They are also written in CSS.

CSS Styles are written as follows:

@css header:
    font-weight: bold;
    text-align: center;

Written as pure CSS, under the @css <NAME>: definition.

This @header style can then be applied to any of the following elements:

  • @row
  • @column
  • @<cell_name>

In the above example, we could do the following to the first row (which corresponds to the header). The other data has been omitted for brevity.

#!... <snip> ...

@row (@header)
@task: Task
@details: Details
@status: Status

#!... <snip> ...

This will now enforce centering of the text along with making it bold for that entire row of data. Any other valid CSS can be used here as well. For example, background: green; could also be added to make the header cells background green.

Usage

Attachments (1)

Download all attachments as: .zip