HTML Macro
 | Allows inserting HTML or XHTML in wiki pages |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Table of contents
Description
Allows inserting HTML or XHTML in wiki pages.
Usage
Parameters definition
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| wiki | yes | true/false | false | Indicate if the wiki syntax (including other macros) inside the macro is evaluated or not. If true then the content of the macro is parsed as markup content (written in the syntax of the current page) and rendered back as XHTML in the macro. Then the whole content is output as XHTML. |
| clean | yes | true/false | true | Indicate if the user input must be converted to valid XHTML or not. 14.1+ Cleaning is adapted according to the HTML version used in the rendering process, defaulting to HTML 5. This means that in most cases tags like <video> are supported. 14.6+ This parameter is always true (it cannot be set to false) if the user doesn't have Script Rights, see the Security section. |
Examples
Interpreted wiki syntax
<table>
<tr>
<td>
* listitem
</td>
</tr>
</table>
{{/html}}
Result
|
Escaped wiki syntax
**some escaped text**
{{/html}}
Result
**some escaped text**
Security
14.6+ If the author of the HTML macro doesn't have script right or the transformation context is restricted (e.g., for comments or old revisions of documents), cleaning is always enabled regardless of the passed parameters. Further, in this case, cleaning is configured to use a special restricted mode that enables a sanitizer filter. The sanitizer follows the rules configured in the XML module. In the default configuration, it uses a list of allowed HTML tags and attributes that prevent dangerous content like scripts or iframes.
Limitations
Using the HTML macro has some limitations and thus it's recommended to use wiki markup as much as possible (since it doesn't suffer from the issues listed below):
- If you use local links, and you later rename the page pointed at, the link will get broken
- If you use a Renderer that doesn't support HTML, all the content inside the HTML macro will be discarded (as of this writing, this will happen if you use the LaTeX Exporter for example)
- Any extension that looks at the XDOM to perform some behavior may not work. For example the URL Normalizer extension will not be able to convert a local link into a wiki link (even if `wiki=true`)
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.rendering:xwiki-rendering-macro-html 15.4):
- org.xwiki.rendering:xwiki-rendering-syntax-xhtml 15.4
- org.xwiki.rendering:xwiki-rendering-syntax-annotatedxhtml 15.4
- org.xwiki.rendering:xwiki-rendering-syntax-html5 15.4
- org.xwiki.rendering:xwiki-rendering-syntax-annotatedhtml5 15.4
- org.xwiki.rendering:xwiki-rendering-api 15.4
- org.xwiki.rendering:xwiki-rendering-transformation-macro 15.4
