• View
• Edit
• History
• Attach
• Print
• Backlinks

CSVInclude

Goal

Large, complex tables are a pain to maintain in mark-up (wiki or HMTL). It would be nice to have a straightforward way to maintain tables in a spreadsheet tool and then include them directly into the wiki.

Solution

Put CSVInclude.php in the PmWiki cookbook/ directory (you may have to create it).

Add the following line to local/config.php:

 include_once("cookbook/CSVInclude.php");

Use mark-up like [:attachcsv <csvfile>:] to include a CSV file in your wiki page. (See Usage Notes below for more options.)

Discussion

Wiki mark-up is great for simple tables but they get hairy to create and maintain where there are a lot of columns or the cell contents are long. In these cases, it really is more natural to maintain the table contents in a spreadsheet tool and simply include the table into the wiki.

The CSVInclude cookbook file allows you to upload a CSV file you've exported from a spreadsheet and have it appear as part of your wiki page. Cells can contain wiki mark-up just as if the text were between the "||" (double pipe) mark-up in a simple wiki table. This also means that you can't use block mark-up in your tables (i.e. no bullets, headers or indentation).

Why CSV vs. Excel or SYLK or something like that? Well CSV is pretty much the lowest common denominator for spreadsheet file formats and because there are CSV parsing routines already in PHP. Also, dealing with Excel or some more "advanced" file format would involve resolving formulas and multiple sheets within the same file, which I really don't want to deal with. It's also reasonable to edit CSV by hand or post process CSV by hand in a text editor, which is pretty much impossible in other formats.

The CSVInclude currently uses Table mark-up, if for no other reason, because advanced table mark-up is currently not available for PmWiki2. It's also a nice choice because of mark-up goodies like headers and alignment which would be a lot more work in the advanced table mark-up. In general, it seems that the Table mark-up matches with CSV pretty well.

I haven't done extensive testing with all the possible CSV output that may be possible. In particular I've only really tested this with CSV output from OpenOffice, so feedback on how it works (and doesn't work) with other spreadsheets would be much appreciated.

Usage Notes

Getting The CSV File In-line

1. Create a spreadsheet with your favourite spreadsheet tool (OpenOffice for instance), and export it as text (CSV) format. The important thing is that cells should be separated by comas (,) and delimited by double quotes (").
2. On some wiki page add mark-up to include the CSV table. The simplest format is
   [:attachcsv <csvfilename>:]
   but see below for the full syntax
3. Save the page to get see an unresolved Attach:<csvfilename> link, which will take you to the file upload page.
4. Upload the CSV file
5. Click the page title link at the top of the upload page to get back to the original page
6. Checkout your table as part of the wiki page

Wiki Page Mark-up

The full mark-up is as follows: :[:attachcsv <csvfilename>'<table attributes>':]

Maybe some example would help:

• [:attachcsv pnl.csv:] — include the PnL table into the page
• [:attachcsv pnl.csv'border=1 cellpadding=3 cellspacing=0':] — put thin border around cells
• [:attachcsv pnl.csv'class=pnltable':] — apply CSS class "pnltable" to table appearance

Mark-up within CSV tables

The contents of the CSV file are inlined into the wiki text of the page, so you can include wiki mark-up in your CSV cells. Anything that will work between double bar table mark-up in the wiki will work within the cells of the CSV table.

A couple of special mark-ups are available in the CSV table:

• To join a cell with the previous one (create a colspan) put <<del>> as the only text in the cell (same as leaving a simple table cell empty)
• using a pair of backslashes (\\) within the text of a cell will create a line break
• any sequences of pipe characters (||...) are escaped (i.e. they don't "magically" create sub cells within the table)

See Also

• ExcelPaste - cut-and-paste data from Excel
• Text2Tbl - Convert structured text (including CSV) into either simple tables or advanced table directives

Contributor

LarryBaltz