Author: vmassol
Date: 2007-12-17 17:49:21 +0100 (Mon, 17 Dec 2007)
New Revision: 6391
Modified:
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/render/macro/XWikiCodeMacro.java
Log:
Added more javadoc to explain how the Code Macro works.
Modified:
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/render/macro/XWikiCodeMacro.java
===================================================================
---
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/render/macro/XWikiCodeMacro.java
2007-12-17 16:31:01 UTC (rev 6390)
+++
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/render/macro/XWikiCodeMacro.java
2007-12-17 16:49:21 UTC (rev 6391)
@@ -51,6 +51,27 @@
import java.io.IOException;
import java.io.Writer;
+/**
+ * The Code Macro renders its content as is but pretty printed according to
the language passed as parameter. Supporting
+ * escaping Radeox, Velocity and Groovy wasn't trivial. Here's how it's
currently implemented (waiting for a better
+ * implementation):
+ * <ol>
+ * <li>The first renderer to execute is the MacroMappingRenderer. That's
because it's registered first in
+ * [EMAIL PROTECTED]
com.xpn.xwiki.render.DefaultXWikiRenderingEngine#DefaultXWikiRenderingEngine(com.xpn.xwiki.XWiki,
com.xpn.xwiki.XWikiContext)}}.
+ * The code macro is registered in the macros.txt file used by the
MacroMappingRenderer and thus it is processed
+ * by the macro mapping feature. Since it recognizes it's a radeox macro,
it calls the Radeox Renderer's
+ * [EMAIL PROTECTED]
com.xpn.xwiki.render.XWikiRadeoxRenderer#convertMultiLine(String, String,
String, String, com.xpn.xwiki.render.XWikiVirtualMacro,
com.xpn.xwiki.XWikiContext)}
+ * method. This method has a hack and verifies if the macro to render is
the code macro. If so it escapes Velocity
+ * and Groovy special characters ($, #, <% and %>) so that when the
Velocity and Radeox renderers execute they do
+ * not process its content.</li>
+ * <li>We also don't want the Radeox renderer to render the code macro's
content. We do this by having a special Radeox
+ * Filter ([EMAIL PROTECTED] com.xpn.xwiki.render.filter.CodeRemoveFilter}
that is defined before all other filters in
+ * the
<code>META-INF/services/com.xpn.xwiki.render.filter.XWikiFilter</code> file and
that removes the content of
+ * the code macro. The other filters then execute. The last but one
defined filter is
+ * [EMAIL PROTECTED] com.xpn.xwiki.render.filter.CodeRestoreFilter} which
puts back the content of the code macro and the last
+ * filter is the [EMAIL PROTECTED] com.xpn.xwiki.render.filter.CodeFilter}
filter which calls this macro.</li>
+ * </ol>
+ */
public class XWikiCodeMacro extends CodeMacro
{
public XWikiCodeMacro()
_______________________________________________
notifications mailing list
notifications@xwiki.org
http://lists.xwiki.org/mailman/listinfo/notifications
