DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:columns

Columns Plugin

Compatible with DokuWiki

  • 2015-08-10 "Detritus" unknown
  • 2014-09-29 "Hrun" yes
  • 2014-05-05 "Ponder Stibbons" unknown
  • 2013-12-08 "Binky" yes

plugin Arrange information in multiple columns.

Last updated on
2015-05-30
Provides
Syntax
Repository
Source

Tagged with boxes

This is a reworked and extension version of the original plugin developed by Michael Arlt.

The plugin allows to organize Wiki page contents into multiple columns using manually inserted column breaks. Width of the columns and text alignment within them are fully configurable. For creation of complex layouts, sections of columns can be nested one into another.

Download and Installation

Download and install the plugin using the Plugin Manager using the following URL. Refer to Plugins on how to install plugins manually.

Syntax

Basics

The minimal syntax is simply add two lines around your information and enter your column breaks.

<columns 100% 50% - ->

First column text (50% width).

<newcolumn>

Second column text.

<newcolumn>

Third column text.

</columns>

The first attribute of the <columns> tag is the width of the column set. The following attributes are for the columns. If you do not want to specify a value for the table- or column-width use “-” instead.

The column breaks are specified with <newcolumn> tag, which may also take optional attributes described below. In the original plugin the breaks were specified with ~~NEWCOL~~ and for compatibility reasons it is still possible to configure the plugin to use this tag, but some of the newer features will be disabled.

Extended Syntax

Apart from the width, each column may have a number of additional attributes that specify formatting of the column contents. These attributes should be specified in front of the column width:

<columns 100% first column attributes 50% second column attributes ->

First column text.

<newcolumn>

Second column text.

</columns>

With these extra attributes the columns declaration gets more and more cluttered. To prevent that you can specify column attributes in the <newcolumn> tag. In this case the order of the attributes and column width is not important:

<columns 100% first column attributes 50%>

First column text.

<newcolumn second column 25% attributes>

Second column text.

<newcolumn>

Third column text.

</columns>

Column Alignment

By default the text in the columns is justified but alignment for each column can be specified explicitly. There are few ways to so. The most simple one is by adding asterisks on either side of the column width specification. The asterisk indicates non-justified side of the text block, so to achieve left alignment add the asterisk on the right side.

<columns 100% 25% 25%* *-* *->

First column with justified text.

<newcolumn>

Second column is aligned on the left side.

<newcolumn>

Third column is center-aligned.

<newcolumn>

Fourth column is aligned on the right side.

</columns>

Alternatively the alignment can be specified with separate attributes. This approach allows to define both horizontal and vertical alignment. There are four attributes for horizontal alignment (left, center, right and justify) and three for the vertical (top, middle and bottom). There may be multiple alignment attributes per column:

<columns 100% left 50% right bottom ->

First column is aligned on the left side.

<newcolumn>

Second column is aligned to the right-bottom corner.

</columns>

All attributes can be abbreviated to the first letter, the single letter attributes may be merged together:

<columns 100% l 50%>

First column is aligned on the left side.

<newcolumn rb>

Second column is aligned to the right-bottom corner.

<newcolumn m *-*>

Simple alignment syntax is still supported.
Contents of the third column is centered both ways.

</columns>

Headings

The headings within column sets are specified the using the standard DokuWiki syntax:

<columns 100% 50% ->

===== Heading =====

Content of the first column.

<newcolumn>

Content of the second column.

</columns>

By default plugin puts the content within a column without explicitly specifying the section level. This works fine when the entire column set belongs to a single section but can produce unexpected results when the headings are used within the set:

====== Level 1 Heading ======

<columns 100% 50% ->

Implicit level 1 content.

===== Level 2 Headline 1 =====

Level 2 content.

<newcolumn>

Implicit level 1 content that should be in level 2 section.

===== Level 2 Headline 2 =====

Level 2 content.

</columns>

You can force the beginning of the second column to be in level 2 by specifying continue attribute (or shorthand ...):

====== Level 1 Heading ======

<columns 100% 50% ->

Implicit level 1 content.

===== Level 2 Headline 1 =====

Level 2 content.

<newcolumn continue>

Level 2 content.

===== Level 2 Headline 2 =====

Level 2 content.

</columns>

ODT Export

Starting from version 2009-08-22 the plugin supports export to OpenDocument Format via Open Office Export plugin. Just as in the case of XHTML rendering, the columns layout is implemented with tables. While most of the columns formatting can be exported to an ODT document, there are some limitations:

  • Horizontal alignment of the columns is not supported. According to the ODF specification the text alignment should be applied on a paragraph level and there is no way to specify it for a table column.
  • The ODF specification has very limited support for relative units in the width attributes, so the relative units are converted into the absolute ones:
    • em — converted to points (pt) using coarse approximation based on the default paragraph font size as specified in styles.xml.
    • % — converted to page width units (typically cm). This conversion works reliably only on the top-level column blocks. If you plan to export nested columns to ODT it is better to define width of all blocks (width of the table) as 100%, and widths of the individual columns in some absolute units (e.g. cm, in, etc.)

Configuration

The plugin adds a section to DokuWiki configuration page. There are three settings that can be configured:

  • plugin.columns.kwcolumns — Name of the columns section tag. Default value depends on the Wiki language.
  • plugin.columns.kwnewcol — Name of the new column tag. Default value depends on the Wiki language.
  • plugin.columns.wrapnewcol — A flag indicating if the new column tag is wrapped into angle brackets. The flag is checked by default. By un-checking it you can make the plugin syntax fully compatible with the original version of plugin but you will loose number of advanced features.

Technical Details

The plugin wraps contents of the columns set into an HTML table. This results in a number of limitations:

  • Explicit column breaks are required to separate the table cells.
  • The table may overlap with Table of Contents and I see no way to make the text in the table cells to flow around TOC. The only option seems to be to disable TOC with ~~NOTOC~~.
  • It was reported that table borders show up in exported PDF. (2010/09/24)

In principle, the headings should not be supported within any syntax mode except of the baseonly, namely within plugin modes. So what the plugin does is against the rules, and you can expect some glitches here and there. For instance, I can imagine some compatibility problems with plugins that manipulate the instruction list around section_open and section_close instructions (e.g. Uparrow, Edit Section Reorganizer). Yet, it should behave better than Micheal's original plugin. One manifestation of such “better behavior” is that headings from the column sets show up in the TOC.

Version History

2015-05-30

  • Fixed default text alignment (justify).

2012-10-13

  • Fixed compatibility with Adora Belle default template.

2012-09-23

  • Fixed compatibility issue with PHP 5.4.
  • Improved compatibility with DokuWiki Angua.

2009-08-30

  • Added CSS style sheet for printing
  • More appropriate placement of the section edit buttons. If columns start with a heading, the buttons are placed at the end of the column where the section text ends instead of the start of the next column.

2009-08-22

  • Added support for ODT export
  • Fixed Include plugin compatibility
  • Fixed crash in case of too many columns specified in the <columns ... > tag
  • Fixed broken page layout if the first heading happens to be inside of a column

2009-03-29

  • Added section continuation support
  • Fixed section edit issue
  • Fixed in-line columns handling

2009-03-15 (beta)

  • Added support for headings within the columns
  • Added vertical alignment support
  • New extended syntax
  • The plugin is split into syntax and action plugins

2009-01-31

  • Fixed alignment of tables within a column

2008-10-08

  • Added nesting support
  • Removed extra margin at the bottom of the columns block, which together with paragraph margin of the column content often caused double margin

2008-09-29

  • Added Spanish localization (thanks to Digna Gonzalez Otero)
  • Added Russian localization

2008-09-14

  • Added extended syntax to specify text alignment in the columns
  • To make the syntax fully compatible with the original plugin, the angle brackets around the new column keyword can be disabled from the configuration manager

2008-08-23

  • Fixed issue with the backlinks
  • Columns styling is moved from configuration to style.css file
  • Slightly different syntax: the new column keyword is wrapped in angle brackets (i.e. <columns> … <newcolumn> … </columns>)

2007-10-22 (Michael Arlt)

  • First public release
  • All desired features of the author are implemented

Bugs and Feature Requests

Please report bugs or feature requests at the https://github.com/dwp-forge/columns/issues.

plugin/columns.txt · Last modified: 2015-05-30 18:47 by pan One