Howto: Writing own macro, a guide on example "ImageMap"
Contents
Introduction
Scanning through the MoinMoin page, I realized that there is plenty of documentation on almost any level of detail. But I have not found example-driven coding introductions for newbies.
If I am wrong, feel free to list such docs here! Or tell me where to move/link this document...
All those gurus seem to think that Python is rather easy to learn and self-explanatory, and so should be all written code, too. I agree with the Python one, but with every larger programming project, the latter becomes more and more false. At least without proper introduction.
But the gurus cannot experience this fact by themselves because they have grown into the project and even with growing project size they still know the deeper dependencies. Even with the best of will, they also can't see the real probelms that beginners encounter. So they are willing to patiently answer the many reasonable questions that arise practically. But this tends to grow to splattered piecemeal hints on this and that aspect.
Sure - everyone beginning coding on MoinMoin has a unique story, but I think there will be much in common. Hopefully this document helps on such common introduction difficulties.
With some support of the many others, this document can be integrated into already existing/to be written pages.
For whom is this?
- First of all: for me! (Andreas Hüwel)
I am currently working through MoinMoin and one day I will smile at the simple tasks I had so much trouble with...
- Surely for everyone already with some experience on programming, but somewhat new to
You have plans with MoinMoin beyond standard installation or all the available
MarketPlaces. In addition to all the many functionality, there still is something you must do yourself!
You wish to really learn Python and you think MoinMoin is a worthy prey...
Even for you experienced MoinMoin developers who are a bit curious how dumb this newbie is aproaching ../CodingOnMoinMoin.
Maybe you watch the many cliffs I encounter, just because your code is not well enough documented...
Then read on...
Prior steps
This Howto will guide you through the steps to get your own macro working. Several versions, each with improved code quality and functionality. After you got through, you should be able to understand and write your own extensions.
First let's assume you have read the MoinDev pages (about MoinDev/PluginConcept, MoinDev/CodeStructure etc...) Maybe you have not understood all in detail, but you have got some basic grasp. But you do not just wish to read on forever - you want to get on, step by step...
So you already know you should put your own macro in .../share/mywikiinstance/data/plugin/macro/. You have also tried your first own test macro Helloworld.py (Well, if you have not done it yet, why not try it NOW? 
), which you did by stealing from http://moinmoin.wikiwikiweb.de/HelpOnMacros. And it seemed so easy!
If you dare, you also could look into the MoinMoin CVS repository yourself (where all the core developers put their newest magic MoinMoin code), e.g.: MoinMoin/wikiaction.py.
But slowly you feel: you should enter the scene with some own stuff... and learn online while doing...
Recommended resources/tools
Browser
So you could get a multi-file texteditor at hands (I use Kate) to view the existing code itself. It should support syntax highlighting and use 4 spaces as indentation in Python mode!
Bookmark (and look at!) the already generated online docs for MoinMoin:
Later you eventually will want some tools for convenient documentation generation for self-written code:
use e.g. epydoc(gui)-tools (download from Python).
- Some more ideas? What else could I need to start?
O.K. I think we simply can go on with these...
The guided example: macro ImageMap
Well, I have something to code: An ImageMap inlined into pages. And some parameters to allow for some flexible areas. Here are the details: ./ImageMap
This ImageMap macro shall be about displaying attachments as images and overlay it with a linked map. This feature is well-known from HTML...
For this job I have to review some sources of the MoinMoin distribution .../lib/pythonX.Y/site-packages/MoinMoin/
Let's look in file "wikiaction.py": What I learn from the code comments:
- "attach" is treated as an "action" on a page (if enabled by settings) done via menu-item and URL-interpretation.
And it is also called by a macro inside page content attachment:
To all MoinMoin help page maintainers: where is the syntax of the macro [[attachment:]] described? It should be listed in http://moinmoin.wikiwikiweb.de/HelpOnMacros, even if it is only a pseudo-macro! Maybe there are some more suchlike macros that are not really documented anwhere!?
There is no attachment macro. HelpOnActions/AttachFile has some documentation.
Well, for the normal page editor it is used as macro. On pages, where (s)he explicitly invites people to add there attachments. So what I miss on the mentioned page is e.g. full syntax, parameters etc... And I still believe all entities used inside pages, like [[XXX]] or whatever_call: must be listed on the HelpOnMacros page. And if only by linking on a seperate HelpOnPseudoMacros page. I mean the full syntax description for the page editor. I bet there are more of these pseudo-macros. Well this becomes off topic here
- Maybe you should stick with existing terms. I think this can be solved by adding a few links to some pages and enhancing the available pages. Feel free.
It's always good to look for existing macros/code, to start with (as a first codebase). So I find macro/Action.py and action/AttachFile.py. There I can find some more hints on the internals.
You also may look into my review of the code - here you find my comments to better understand the code... later...
O.K. from reading MoinDev I know that I better try to use the "formatter" to generate the needed HTML output instead of hacking my own HTML tags straight into my code. So lets keep this in mind: this shall be my long term coding goal. But first I definitely am lucky if my code does anyhow do some useful stuff, without deep understanding of all existing code.
Admitted: After some first steps, then I really should rewind myself and learn how to more intensively use the existing MoinMoin code, like formatter/base.py
Then I was told by a good MoinMoin soul AlexanderSchremmer, that attachment: is a "pseudo-macro", I should look into the parser. Huh?
Then I find in parser/wiki.py some hints: "class Parser: Object that turns Wiki markup into HTML".
O.K. after a quick overview I know: a "pseudo-macro" is macro stuff in pages that does not get executed as a macro but somewhere else. And as we saw: [[attachment:]] is an "action", that also can be inlined into pages.
More coming..