New subject: [xwiki-users] #include<what?>

7 Apr 2006

The various kinds of #include directives have always puzzled me, but now
I think I may have a serious need to understand them.

I have seen that some of them are implemented by methods on $xwiki
(includeForm, includeTopic, in two incarnations each - with or without
rendering, I assume), but I have no understanding of why they are all
different.  Add in the parse directives and XWiki methods and I am
completely confused.

Can anyone give me a synopsis of what these are all about?  I understand
this much:  that Velocity directives are read once at parse time,
whereas methods can be invoked multiple times in a loop.

The problem I need to solve, however, may be a Velocity problem or a
caching problem.  A menu is called from the left-side navigation menu
XWiki.Menu.  I have included it via #includeTopic, and it use
#includeMacros to bring in a macro that reads a document with a list of
objects describing menu items, with a menu label, an href, and a long
description.  If the href field is a complete URL, it's output as a
plain link; if it's a local Wiki document, it's output with XWiki's
bracket syntax and its place is held in the menu as a navigational aid.
If it is also in the Web reserved for such documents, it's a submenu,
and the menu macro is called again (thanks to the earlier thread, I did
use a copy of the argument, which is call-by-reference, and saved
headaches).

All of this works just fine except the first time it's called after the
server starts.  Instead of the menu text, all I see is the invocation of
the macro.  Viewing the menu document directly (as I did when I sought
to debug it) fixes the problem for all until the next reboot.

So what is this?  I read some discussion on the velocity-user mailing
list about when and how macro templates are loaded, but didn't
understand it well; in addition, there is all this confusion about when
to include in what way.

brain[sic] 