[{TableOfContents }]

!!Table plugin

This plugin implements additional table formatting for JSPWiki :
* extra syntax to merge cells horizontally and/or vertically (aka colspan and rowspan)
* multi-line table editing to ease the entry of complex table data, such as nested tables
* additional formatting for odd/even rows, headers, etc.
* auto-numbering of rows
* client-side sorting of tables

! Usage:
[{Table <table-parameters>

... body with table definition, don't forget to put an empty line before this body
or use the full syntax when your searchPath was not modified 
(see [How to install|9])
[{brushed.jspwiki.tableplugin.Table <table-parameters>

... body with table definition ...

! Table Plugin parameters :

* __escape : <string>__ ,  escape special characters which normally are interpreted 
  as table syntax.
  The first character after the 'escape string' will be passed unprocessed to the output.
  This also allows you to call other plugins inside table cells. (see example [3])
  \\The default 'escape' string is '~'.
* __rowNumber : <integer>__ , row number starts counting at this value, default = 0 
  (used in conjunction with '#' syntax)
* __style : <css-style>__ , add formatting to the table 
  e.g. {{style:'border=2px solid black;'}}
* __dataStyle : <css-style>__ , format all data cells 
  (prefixed by single pipe signs '|')
* __headerStyle :  <css-style>__ , format all header cells 
  (prefixed by double pipe signs '||')
* __evenRowStyle :  <css-style>__  , format the even rows, 
  e.g. {{evenRowStyle='background: #ffff00;'}}
* __oddRowStyle :  <css-style>__  . format the odd rows, 
  e.g. {{oddRowStyle='color: red;'}}

!Table syntax

The table plugin supports  the standard JSPWiki table syntax :
* a new line of text starting with a pipe sign '|' indicates the start of 
  a new table row. 
* every line corresponds with a horizontal row of the table, containing one 
  or more table cells.
** a single pipe signs ('|') starts a new data cell. 
** a double pipe signs ('||') starts a header cell with different formatting.
* end the table with a line which does not start with a pipe sign.

Following syntax is also supported:
* use '|<' or '||<' to collapse a cell with the previous cell so 
  it __spans multiple columns__.
* use '|^' or '||^' to collapse a cell with the cell above so that 
  it __spans multiple rows__.
* use '|( <css-style> ) ' to add specific __formatting__ to a cell.
* use '#' inside a table cell to display the current row number. 
  (__auto row numbering__)

   |Nr |A |< |C |<
   |#  |a |b |c |d
   |#  |^ |b |^ |d
   | Nr | A     | C     |
   | 1  | a | b | c | d |
   +----+   +---+   +---+
   | 2  |   | b |   | d |


! Multi-line table editing

This feature was implemented to overcome the limitation of having 
to edit a complete table row on a single line of text.

* When the line contains only one cell, it is assumed that 
  the table cell is continued on the next line. 
  (this is multi-line table editing)
** When the next line starts with '|' or '||', a new cell 
   on the same row is started.\\
   Otherwise the line is added to the previous table cell
** All subsequent lines starting with '| or '||' are merged 
   into the same table row.
** An empty line ends the table row.
* When more than one table cell is encountered on the same line, 
  single-line editing is assumed, using the standard wiki syntax.

This way, it should be more easy to have lots of text, and even wiki markup, 
merged into one table-cell. Table cells are listed underneath each other,
similar to a bulleted list.

You can combine this multi line syntax with the '|<', '|^' and '#' 
stuff as well as mix it with the more compact standard wiki table syntax.

   || Heading 1 
   || Heading 2

   | ''Gobble'' starts a new row!
   * and some more text with wiki markup, all in the same table cell
   * and the name of this page [{$pagename}~]
   | Bar

   | [Main]     
   | [SandBox]

! Table sorting

Tables can become sortable, when following conditions apply:
* all cells on the first row should be header cells (double pipe {{||}})
* the other rows should only contain data cells (single pipe {{|}} )
* none of the cells may use colspan or rowspan
* all table rows should count the same amount of cells or columns

Sort the table by clicing the header cell of a column; 
Click again to toggle the sort direction of the column.

You will need to install the excellent 
[tablesort.js|http://webfx.eae.net/dhtml/tablesort/tablesort.js] from Erik Arvidsson. 
More info and a demo is available on [http://webfx.eae.net/dhtml/tablesort/demo.html].


!!Installation Instructions [how to install|#9]

* Copy {{Table.jar}} to the folder {{/WEB-INF/lib/}} 
* Modify the plugin searchPath in your {{WEB-INF/jspwiki.properties}} and make
  sure there are no spaces between the different entries. Example:
       jspwiki.plugin.searchPath = brushed.jspwiki.tableplugin
* Restart JSPWiki

Additional stuff when you want to use the table sort functionality
* Copy [tablesort.js|http://webfx.eae.net/dhtml/tablesort/tablesort.js] 
  to your template directory (e.g. {{templates/default/tablesort.js}} )
* Add a reference to the tablesort.js in e.g. your {{templates/default/header.jsp}} file

       <script src="templates/<wiki:TemplateDir/>/cssinclude.js" type="text/javascript"></script>
       <script src="templates/<wiki:TemplateDir/>/tablesort.js" type="text/javascript"></script> <!-- add this line -->

''SS - The latest distribution doesn't have a header.jsp -- it has a commonheader.jsp. Also, the
relative URL shown doesn't work if you're using ShortViewURLConstructor -- I suggest inserting <wiki:BaseURL/> at the beginning, like this:''
<script src="<wiki:BaseURL/>templates/<wiki:TemplateDir/>/tablesort.js" type="text/javascript"></script> 

* Add following css to the {{jspwiki.css}} located in that same template directory.
  \\Note: when sort is on, the header cells located on the first row, are
  encapsulated inside a THEAD element. The arrow class is used to display an up or
  down arrow indicating the sort direction of the column which was clicked.
  .arrow { font-family: webdings; 
           font-weight: normal;  // be careful, dont remove
           color:       black; 
           overflow:    hidden;
  .wikitable thead td,
  .wikitable th { /*give same formatting to header cells */ }
  .sortable thead { cursor:pointer; }


I don't know if this is the right place, 
but I have trouble to get this TablePlugin to work. 
I copied the Table.jar to my WEB-INF\lib directory, 
but if I just use the new Syntax I get normal Tables, 
not the ones which are described on this page.

Do I have to use a special Syntax or make known that I 
do want to use the plugin Syntax? 
Maybe, someone can help me out on this and/or post 
more detailed installation  instructions.

Thanks a lot,

-- What you describe should be sufficient. Just copy the jar and restart the JSPWiki application in your web server.

I wanted to try the sortable table but I got only a plain looking regular table. Here is what I used:
Table example:


|blouse|1234|A piece of clothing
|oil|234324|Industrial material
|cake|9987|Delicious foo

The generated html:
  Table example:
<p><table border='1' class='wikitable sortable' onclick="sortColumn(event)" > 
<td>A piece of clothing</td>
<td>Industrial material</td>
<td>Delicious foo</td>
It looks like the plugin did its job but there is still something missing in the CSS/JavaScript part. The html source had no mention of the tablesort.js file.

Any ideas? I did all the extra steps like copying the .js file and updating my .css file.\\
I am using the latest JSPWiki v2.1.144-alpha with the mrg template. I made the suggested changes to the jspwiki.css, perhaps I should have modified a different .css file?

;:Yep, you are right. I forgot to mention in the install section that you need to add a reference to the {{tablesort.js}}. I updated the [How To Install section|9] -- [DF|DirkFrederickx]

;:The above suggests that we should have a way for JSPWiki to pick up automatically any Javascripts as well, after they have been dropped in /scripts/... --[JanneJalkanen]

;:Thanks DF. I tried your instructions for the mrg template and it didn't work - same old behavior as before. Since the .jsp structure in this template is quite different from the one in the default template I had to make some adaptations, but I ''think'' I did it right... And I agree with Janne, it would be great to have a solution that is transparent to the template you're using! -- [NascifAbousalhNeto]

Hi, I added the table.jar to the web-inf\lib directory, but I try out the table plugin, I get this error - "An unknown exception javax.servlet.jsp.JspException was caught by Error.jsp"

Sometimes, intermittently, the whole page has only one line that says "org.apache.log4j...". Should I copy log4j.jar into the lib directory as well?

New version of Table plugin loaded, dd. 29 mar 2005 -- [DF|DirkFrederickx]