HTML Tag

Description

This macro is designed as a safer alternative to the standard {html} macro in environments where untrusted users are able to add content to your site...

Many of you will have come across the limitations of the current wiki markup, and found writing user macros and Java plugins cumbersome - especially as you need Administrator rights to install them. To counter this, you will usually have had to enable the {html} and {html-include} macros which were bundled with Confluence, opening serious security loop holes which untrusted 3rd parties could abuse for their own ends.

To get round this problem, the {html-tag} macro has been created, with the following advantages:

• Only whitelisted HTML tags and attributes can be used (see usage information later for the default list)
• The whitelist can be altered by editing the whitelist.xml file contained within the macro (if required)
• Errors are clearly reported on the page through the macro framework
• Allows XHTML compliant output

By inhibiting possibly dangerous tags and attributes, it should be much safer to provide this macro to a wider audience of users. However, you should still check the whitelisted tags and attributes (see the usage information later) to check that there's nothing there of concern.

We've excluded several tags that are already well supported by Confluence in a bid to promote the use of the wiki markup where available. The usual array of table tags are included by default to allow advanced table creation and customisation. The style tag and attribute have not been included as this could lead to untrusted parties altering the rendering of your site (adding in banners for example). If you decide to relax the security restrictions to allow additional tags and attributes, this can be done simply by editing the whitelist.xml file in the jar file.

{html-tag}

Macro Syntax

{html-tag:tag=tag-name|attr-name=attr-value|attr2-name=attr2-value|...}

As the same macro cannot be nested within itself, we have created 3 states - and the tag-name is used to differenciate between them:

As this macro does not have a body, the space between them will be parsed by confluence as it would normally. Be careful with your whitespacing!

Parameters

whitelist.xml

The jar contains a whitelist.xml file which lists which tags and attributes will be allowed by this macro. For security reasons, certain tags (such as <a> and <script>) and attributes (such as "href" and "src") have been left out of the list.

The whitelisted tags and attributes available for use are visible from the usage screen, show below. The output of the usage screen will vary based on your chosen configuration.

Displaying the Whitelist

To display a usage guide at any time, use the following syntax:

{html-tag:usage}

This will display a list of all whitelisted tags and attributes as follows:

Whitelisted Tags

abbr	acronym	address	big	blockquote
caption	center	cite	code	dd
del	dfn	div	dl	dt
em	hr	ins	kbd	noscript
p	pre	q	samp	small
span	style	sub	sup	table
tbody	td	tfoot	th	thead
tr	tt	var

Whitelisted Attributes

id	class	title	style	dir
lang	width	height	accesskey	cite
cellpadding	cellspacing	summary	align	valign
abbr	colspan	rowspan

Note: The list of tags and attributes may vary depending on the whitelist.xml file contents. After installing the plugin, please display the whitelist using {html-tags:usage} to determine the exact tags and attributes that are whitelisted with the version of the plugin you are using.

Examples

Acronym tag with attributes

Outputs contents inside <acronym> tags...

{html-tag:tag=acronym|title=Cascading Style Sheets}CSS{html-tag:tag=/acronym}

Would result in the following output:

<acronym title="Cascading Style Sheets">CSS</acronym>

Usage Guide

Displays simple usage information, including list of whitelisted tags and attributes. The tags are automatically linked to w3schools.com for quick reference.

{html-tag:usage}

The output will be similar to that shown earlier on this page.

Styled DIV

Creates a div with a certain CSS class.

{html-tag:tag=div|class=cssClassName}content inside of the div{html-tag:tag=/div}

Would result in the following output:

<div class="cssClassName">content inside of the div</div>

Horizontal Rule

Creates a self-closing hr.

{html-tag:tag=hr/|width=30%}

Would result in the following output:

<hr width="30%"/>

Custom Tables

Creates a table using custom table formatting.

{html-tag:tag=table|width=100%|class=confluenceTable} {html-tag:tag=tbody} {html-tag:tag=tr}
{html-tag:tag=th|class=confluenceTh|colspan=2} *2 col heading* {html-tag:tag=/th}
{html-tag:tag=/tr} {html-tag:tag=tr}
{html-tag:tag=td|class=confluenceTd} *cell 1* {html-tag:tag=/td}
{html-tag:tag=td|class=confluenceTd} [Plugin Index] {html-tag:tag=/td}
{html-tag:tag=/tr} {html-tag:tag=/tbody} {html-tag:tag=/table}

Would result in the following output:

<table width="100%" class="confluenceTable"> <tbody> <tr>
<th class="confluenceTh" colspan="2"> <b>2 col heading</b> </th>
</tr> <tr>
<td class="confluenceTd"> <b>cell 1</b> </td>
<td class="confluenceTd"> <a href="/display/THEMED/Home" title="Home">Home</a> </td>
</tr> </tbody> </table>

NOTE:
We've added in new lines to the example wiki markup and html output shown above to ensure no horizontal scrolling is needed for this page. However, when using the macro to create numerous nested tags, remember that new lines will create <br /> tags in your HTML. To get round this problem, delete the new lines between the {html-tag} macros, etc.

You can find an alternate form of this documentation on our website: {html-tag} Macro.

Donate

This plug-in is available without cost for both commercial and non-commercial purposes. However, if you have found it to be useful, particularly within a commercial environment, please consider making a donation to the author. This will encourage continued development of this and other plug-ins, as well as speeding up the response for your latest maintenance request.

If you wish to donate, it can be done easily with a credit or debit card or bank transfer using PayPal. No account sign-up is required for credit or debit card payments (just click the button where indicated).

Click here to Donate.

Download & Installation

This plugin requires installation into the WEB-INF/lib folder for it to work with confluence 2.1.x

Release History

Testing

This plugin has been tested on the following versions of Confluence:

It should work on other versions as well, post a comment to let us know.

Download the Latest

1. Release: adaptavist-plugin-htmlTag-1.0.jar
2. Source: adaptavist-plugin-htmlTag-1.0.zip

Software is released under the BSD license. Copyright (c) 2005 Adaptavist.com Limited. http://adaptavist.com