tea & toast

Well this week's topic is MoinMoin's free wiki service. Nick has set up 2 wiki servers http://wiki.toasttechnology.com.au and http://wiki.soasuccessplus.com and as a new technology on board for our company, i'm at the forefront to get it looking like a part of us.

My first theme was the Toast Wiki... and i found developement difficult. Using the default html that is generated i was able to adjust the design somewhat, add our own background and with some CSS absolute positioning i was able to re-arrange the elements to something a little more friendly, however as with lots of css positioning it was fraught with dangers, especially resizing.

So I had no choice but to learn how MoinMoin theme work, and learn a little python. Scary stuff, especially when there is very little documentation, and when i say little it's like the internet of the 90's, where you learn by cracking open notepad and looking and fiddling with what other people have done. Yes, a painful process, and somewhat short sighted on MoinMoin's team considering the very basic help for creating themes, I myself would add to it, but am afraid i know quite little after my experience.

MoinMoin's theme set-up isn't too bad, it has a basic default theme it'll output you can see at http://moinmoin.wikiwikiweb.de/MoinMoinWiki , the design is rather dull with pastel blues and greys, so it's easy to brighten it up with css, but when it comes to putting the search in a less awkward place than top right, or changing the menu from a dropdown list to small icons... it's not so easy! You need to jump into a python file and override the methods.

Now i actually think overriding the methods is a great idea, basically there's a method for each portion of the theme, such as header, footer, editbar, iconbar etc. The problem is, you don't know what it calls already, and i couldn't seem to find any documents to let me know what methods a method would call to create itself, so i ended up studying other themes.

I think out of all the simple things you might want to change, it would be the header and footer, so you can add one or two extra divs, images, or change where elements appear so you don't have to push css so far.

So here's the exciting little bits i found when rearranging the header and footer. You'll need to grab someone else's python file to start you off or follow the instructions, then it's just a matter of moving this code around;

    def header(self, d, **kw):

        html = [
            # Pre header custom html
            self.emit_custom_html(self.cfg.page_header1),
            
            # Header

            self.logo(), #logo defined in the configure setings

            self.title(d), #title defined in the configure settings
            self.trail(d), #breadcrumbs of where the user has visited

            self.navibar(d), #the tabs, or permanent links the user had put on,
                             #or that have been set up in the config

            self.username(d), #user options such as login, their name, and preferences
            self.searchform(d), #search box with titles and text buttons
            self.editbar(d), #the seciont people can use to edit the page,
                             #the default includes a dropdown with more actions

            self.msg(d), #where notifications that you edits have been saved are shown
            
            # Post header custom html (not recommended)
            self.emit_custom_html(self.cfg.page_header2),
            
            # Start of page
            self.startPage(),
        ]
        return u'\n'.join(html)

So we have a bit of code there, but not to be concerned, really we're mostly interested in the code in the middle, i've put comments next to each line to try to explain what each method is. Now it's as simple as arranging the lines of code, from self.logo() to self.msg(d) . If you want to leave anything it, just cut it, such as the annoying breadcrumbs - they are useful but may not fit in with everyone's needs.

That's pretty simple, but i need a tag around the whole head so i can control it a bit more, well thankfully this is pretty simple too! All you have to do is add a line with u' at the beginning and ', at the end. So if we want a new div tag we'd add u'<div id="footer">', before self.logo(), and probably want the header to finish before our message so just above we'd add u'</div>', to close off our tag.

Hey that was easy! Yeah it is, infact you can re-arrange any part of the output, or remove parts or move them into other sections, and won't have to really learn any python. But if you decide you don't like the contents of any of the methods, such as you don't like the editbar, and want to change the dropdown into something else, well that's a lot harder, and i suggest grabbing some of the original source - i managed to find it for the modern theme, it wasn't the most recent version so the code was helpful in some cases but not all. Most importantly it contained the names of the methods i needed for sections i wanted to change.

You want a little more help? Oh well i guess i can help, - here's the footer method;

    def footer(self, d, **keywords):
        html = [
            self.endPage(),
             self.emit_custom_html(self.cfg.page_footer1),

            self.editbar(d), #edit bar including drop down, same as the one in header

            self.credits(d), #credits as defined in the config
                             #the default links are "moinmoin powered" and "python powered"
                             #and are at the very bottom of the page

            self.emit_custom_html(self.cfg.page_footer2),
        ]
        return u''.join(html)

Yeap only 2 methods to play with in the footer, but you could move the searchform from the header to the footer like i did, get rid of the credits if you don't find them appropriate, or close a tag you opened in the header so you could affect the content of the page. Quite useful isn't it?

In most cases, unless you are drastically changing how the moin moin works, these 2 sections of the theme are what you will be changing, and really just re-arranging the code, or adding a few lines to put out more formatting.

I hope someone else working in the world of moinmoin find this little bit of information helpful in making moinmoin themes! If you are interested in how i did the icon menu, well you can call iconbar(), but unfortunately you will have to override the iconbar method and code in your own output, it took me awhile, so if you're interested drop me a comment and i'll post some help or code!

Alex - now a MoinMoin themer