#include<what?>
by THOMAS, BRIAN M (SBCSI)
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]
