HTML Macro

Last modified by Admin on 2024/10/01 00:24

cogAllows inserting HTML or XHTML in wiki pages
TypeJAR
Category
Developed by

XWiki Development Team

Rating
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

Description

Allows inserting HTML or XHTML in wiki pages.

Usage

{{html wiki="true"|"false" clean="true"|"false"}}...{{/html}}

Parameters definition

NameOptionalAllowed valuesDefault valueDescription
wikiyestrue/falsefalseIndicate 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.
cleanyestrue/falsetrueIndicate if the user input must be converted to valid XHTML or not. XWiki 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. XWiki 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

{{html wiki="true"}}
<table>
 <tr>
   <td>
      * listitem
   </td>
 </tr>
</table>
{{/html}}

Result

  • listitem

Escaped wiki syntax

{{html}}
**some escaped text**
{{/html}}

Result

**some escaped text**

Security

XWiki 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 16.8.0):

Get Connected