mod_csv

mod_csv is a module to publish CSV files as HTML. It was motivated by a project where the Client is preparing timetables in Microsoft Excel, and wishes to publish them to the Web. He can of course save from Excel (or indeed any other spreadsheet) as CSV, and mod_csv is the remaining step in publishing these files to the web.

It is an upload handler, so files are converted on upload and stored as HTML.

It is not designed to be generalised or feature-rich. It is merely designed to meet the needs of a single project - and released in case it may meet the needs of other projects.

How to use it

mod_csv converts CSV to HTML. The primary function is to convert spreadsheet data to HTML tables. But webpages are usually more than just tables. So mod_csv supports some additional features. Firstly the web developer or system administrator sets up a template for published pages, and optionally defines macros for authors to use. Secondly authors can can use a small set of controls in their spreadsheets to define the published pages.

System Setup

The task of the system administrator is to create a template for the published HTML pages at the site, and (optionally but recommended) an associated CSS stylesheet to determine their presentation. You may also set up system macros for use by authors. Please see the configuration directives, example and notes below.

Publishing for Authors

Authors can control the published HTML pages by inserting reserved characters at the start of a line or cell in the spreadsheet as follows:

Control Lines

Any line in the spreadsheet beginning with one of the reserved characters is given a special interpretation:

+ starts an HTML Table
- ends an HTML Table
=word in the first cell treats word as a macro, and expands it as defined in the configuration, with the contents of the second cell replacing the %s in the example.
: causes the row to be printed with <tr class="special"> instead of plain <tr>.

Control Cells

By default, tables are marked up with the first cell in a row as <th scope="row"> and all other cells as <td>. The control ! as the first character in a cell causes it to be marked as a note, using <td class="note">, regardless of its position in the row.

Template and Local Macros

See the example and notes below.

Example

<Location	/publisher/csv>
	# protect it - authentication details omitted for brevity

	SetHandler	csv
	SetInputFilter	tmpfile-filter;upload-filter
	UploadField	csv

	CSVBaseURL	http://www.example.com/timetables/
	CSVBasePath	/usr/www/www.example.com/timetables
	CSVTemplate	/etc/www/www.example.com/timetable-template
	CSVMacro	caption	<caption>%s</caption>
	CSVMacro	heading	<h2>%s</h2>
	CSVMacro	subheading	<h3>%s</h3>
	CSVMacro	note		<p>%s</p>
</Location>

Notes

The Input Filters and the UploadField directive are implemented by mod_upload.
The Template file is a complete HTML file, with a single line
<<DATA>>
that will be replaced by the uploaded CSV on publication. In fact it is not limited to HTML: other XML or SGML markup may be used, provided they are compatible with HTML Tables.

Configuration Directives

CSVBaseURL

Syntax: CSVBaseURL basepath

HTTP base URL for published files.

CSVBasePath

Syntax: CSVBasePath basepath

Filesystem base path for published files.

CSVTemplate

Syntax: CSVTemplate template-file

Template file for generated HTML pages.

CSVMacro

Syntax: CSVMacro varname expansion

Defines a macro and its expansion for use in the uploaded files.

Availability

mod_csv.c source code is available under the GNU General Public License (GPL). As with other opensource modules, we can consider alternative licenses by request.