A way to get rich layout of wiki pages, in a simple and maintainable way

Please add comments or discuss this in /Discussion. See also MultiColumns, DruidWikiTestCase, MetaDataInMoin, ParserMarket/Frame.

Section parser is a way to have nice layout in a simple and maintainable way. To have a special section in a page, add this markup:

   1 {{{
   2 #!section
   3 #class special
   4 #format wiki
   5 Content...
   6 }}}

The parser uses the same header format used in wiki pages. This makes it natural and easy to have a section using ReStructuredText within a page, or just change the language of a section of a page. This markup will create this HTML:

<div class="section special">
<p>Content... </p>
</di>

The HTML contains only the structure, the theme CSS has total control on the rendering of the section.

The package contains a header module, planned to be included in the MoinMoin distribution. The header is also used by the SlideShow action, and may be used by other parts in the code to remove duplicate header parsing code in few places.

Section Parsers

#!section is very general and can be used for anything. But in real life we want actual names for common patterns. By using simple sub classes, we can have several types of sections, all using same code:

• The class is using multiple values in the form class="section classvalue". In the CSS you can put common rules for section and special rules for class by using .section.classvalue . See Class selectors.

Usage examples

Example: sidebar section

   1 {{{
   2 #!sidebar
   3 
   4 '''News:'''
   5  * Moin can do page sidebars now. See PageSidebars...
   6  * Release 2.0 is out! MoinMoinDownload...
   7  * More news...
   8 
   9 '''Events:'''
  10 ## include the top N items from a page
  11 [[Head(Events, items=10)
  12 
  13 '''Downloads:'''
  14 [[Include(Downloads)]]
  15 ...
  16 }}}

The sidebar is floated to the end of the page, which makes it very easy to integrate into any theme.

Example: figure section

In some pages we want to include a picture, a graph or some other graphic device that needs only small part the page width. The typical linear wiki page does not look good in this case, and harder to read.

Here is an example for a figure section:

   1 {{{
   2 #!figure
   3 #class left
   4 attachment:Orpheline.jpg
   5 
   6 Jeune Orpheline au Cimetiere.
   7 }}}

Title should be implemented as #title value so it may be used in meta data searching.

Example: switching language

We have language macros, that change the language in the page current language, but we can also use a section for that:

   1 {{{
   2 #!section
   3 #language he
   4 מלל עברי...
   5 }}}

This will create a div with lang="he" and dir="rtl".

Advantages:

• We don't have to replace the language back to the previous language. This is a problem because if you change the #language in the page header, the [[lang]] macros that supposed to go back to the page language will break.

• Can be used in searching to avoid results in certain languages.

Problems:

• There's much more markup to support than [[lang]].

• You can't have {{{}}} inside a section.

Example: meta data

Using same way to add meta data and same header module section parser uses, we can move page meta data into a section. Read more in MetaDataInMoin.

Creating new types of sections

To create new section types, just save myparser.py in wiki/plugin/parser, with this code:

   1 from section import SectionParser
   2 class Parser(SectionParser):
   3     baseClass = 'myparser'

Then add the rules in your css file:

#content .myparser {color: red; position: absolute; right: 0; top: 0}

Enjoy!

Section creation

The current formatter does not have a way to add a div with a class. The section parser uses formatter.rawHTML to render the div, which will work only for text/html formatter, while other formatter will just render the content ignoring the section meta data.

To fix this, we should add a call to the formatter API:

   1 def section(on, **attributes):

attributes may contain any HTML attribute, and will be used mainly to add class. Adding ids is a problem as there should be only one id in the html, its the same problem with startContent.

Other formatters may handle the HTML attributes or ignore them.

Update: moin 1.5.2 has text_html.div()

But sections should work also with 1.3:

   1 if hasattr(formatter, 'div'):
   2     return formatter.div(1, class=...) + content + formatter.div(0)
   3 else:
   4     return formatter.rawHTML('<div class=...>') + content + formatter.rawHTML('</div>')

Nesting Problem

Inside a {{{}}}, the current wiki parser does not let you add another {{{}}}. So if you like to have a figure with a piece of code example, you can do it only by using {{{[[Include(SomePage)]]}}} or by {{{inline:example.py}}} and like.

If you want to create complex design with nested divs - a must for some designs, you will have to use multiple pages for the nested div content.

Options

• Introducing some escaping that allows you to nest divs? Like {#{#{# becomes {{{ (and {##{##{## becomes {#{#{#). You could realise any complex layout using that system!

• Improving the wiki parser to enable nesting?
  • No, you just have to rewrite the text using a simple regex.
• Use multiple pages, the wiki is not meant to be use for complex design of multiple pages. The purpose of the section parser is have quick and easy way to get pages that look nice.

CSS classes

When you use #class value, you get class="baseClass value". baseClass is the name of the parser. To prevent clashes with names moin uses, use the cascade:

/* Moin staf */
#sidebar
.sidepanel
#page
#header
#footer

/* Content stuff */
#content .figure
#content .sidebar
#content .section

Known problems

Does not work for right to left pages with lists in Firefox 2.0.2:

• Bug #262195 fixed in the trunk, will be available in some future version of firefox.

MoinMoin 1.6 - 1.9

To get SectionParser to work with MoinMoin 1.6alpha, I found I had to replace the following line in section.py:

from MoinMoin.parser.plain import Parser

with:

from MoinMoin.parser.text_moin_wiki import Parser

No guarantees that this is correct, but it seems to work for me -- MartinSpacek

The above works for me. Here's the patch I used for 1.9:

   1 --- /home/anarcat/sections/plugin/parser/section.py     2006-01-30 08:31:00.000000000 -0500
   2 +++ section.py  2010-01-08 02:03:20.000000000 -0500
   3 @@ -108,7 +108,7 @@
   4      def importParser(self, name):
   5          Parser = importPlugin(self.request.cfg, 'parser', name, 'Parser')
   6          if Parser is None:
   7 -            from MoinMoin.parser.plain import Parser
   8 +            from MoinMoin.parser.text_moin_wiki import Parser
   9          return Parser

-- 72.0.72.144 2010-01-08 07:03:56

Download

sections-1.0.2.tgz

Install instructions included in package.

Deprecated

Just a note-- the section parser is "deprecated" and not supported / needed anymore (I guess since 1.8.0). Now you can use something like

{{{#!wiki myClassName
This content will get the class = "myClassName".
}}}

so you can define some css in your common.css / screen.css like:

.myClassName {
    font-size:20px;
    float: left;
}

Contribute

sections code is managed with Bazaar-NG. You can browse the repository or get your own branch with:

bzr get http://nirs.freeshell.org/code/sections/