3 Aug
2009
3 Aug
'09
5:56 p.m.
Hi Asiri,
On Mon, Aug 3, 2009 at 5:08 PM, Asiri Rathnayake <asiri.rathnayake(a)gmail.com
wrote:
Hi all,
This is about implementing back-end support for macro categories. My
understanding of macro categories and it's implementation is bit vague at
this point, hopefully this email will set things straight.
Basically, the aim of categories is to make it easy for users to find
relevant macros when they try using them. If/when the list of macros becomes
too big to fit on one screen (20+ macros), using categories will make it
easier to find the right macro.
I think we only need one level of categories (no subcategories) as of today.
This would allow us to scale approximately up to 10 categories * 8 macros =
80 macros. Once we reach that number of macros, we'll have to find
additional ways to let users find macros anyway (most probably through a
search in macros).
To understand the usefulness of macro categories, have a look at confluence
macro browser:
http://confluence.atlassian.com/display/DOC/Working+with+the+Macro+Browser
We can identify several categories by looking at confluence but XWiki will
need several other categories as well. I can think of few XWiki macro
categories:
* Presentation - Macros that allow presenting document content with various
styles. Like box & code macros
* Document content - Macros that add stuff into a wiki page, like image,
video & office macros.
+ the footnote macro
* Scripting - HTML, Velocity, Groovy, Ruby etc.
Could also be named "Development"
* Visualization / Reporting - Chart macro and the
like.
* External content - Macros that fetch content from external sources. Like
Rss macro.
* Development - Macros in development / introductory stage.
Could be renamed "under development" or "in progress". I'm not
sure we want
to display unfinished macros in the macro dialog box though (ideally we
wouldn't), which means we'd have to let users specify whether their macro is
ready for publication or not.
I'm pretty sure there are more categories to consider (please list them).
Now for the real questions that are troubling me:
* Should these categories be statically defined inside the rendering
module?
This would mean that the macro author gets to select which category his
macro belogs to, which in turn means we should have a method like:
MacroCategory getCategory() inside the Macro interface. Using this
information MacroManager will present different macro categories to the
outside world.
We could make the categories static at first, but we'll quickly run into
either of 2 issues:
- someone wants to add a new macro and doesn't find a category that fits
- there are too many macros in a given category
Thus it would be better if we could make the list of macro categories
configurable.
* The other approach is to keep this categorization inside some wiki pages
and allow administrators to manipulate it: Create /
Edit categories, assign
macros to categories etc. I'm not sure what problems this would create when
implementing macro browser though.
That's the approach I'd favor. Macro categories would be defined from the
administration interface. The user who creates a new macro would select the
category that fits best from that list of categories. Since right now an
user has to have programming rights to create new macros and that
programming rights have to be granted by an admin, we can expect that the
user will be able to ask the admin for a new category should the need arise.
That could be implemented through a static list in a XClass. We'd need to
add a good-looking administration interface to define the list of
categories.
* Another (very hackish) approach would be to use the component role hint in
the same fashion it is used to specify macros for
different syntaxes.
I think this is enough to get the discussion started.
Thank you very much for your input.
- Asiri
Guillaume
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Guillaume Lerouge
Product Manager - XWiki
Skype: wikibc
Twitter: glerouge
http://guillaumelerouge.com/