The {html-tag} macro provides a safe mechanism for the addition of specific HTML tags and attributes to be inserted in to your content...

There are times when Wiki Markup Editor doesn't quite provide enough flexibility and the need arises to add custom HTML tags to a page.

There are various ways in which you can do this:

• Create a plugin or user macro - requires administrator privileges and often knowledge of programming
• Use the html macro or [USERGUIDE:html-include macro] - these can be dangerous if mis-used

To overcome these problems, the {html-tag} macro has been created which has the following advantages:

• Only whitelisted HTML tags and attributes can be used - this prevents mis-use of the macro
• The whitelist can be altered to your own needs - this allows you to customise the macro
• Errors are clearly reported on the page through the macro framework - this makes it easy to spot and resolve mistakes
• Allows XHTML compliant output

By inhibiting possibly dangerous tags and attributes, you can provide this macro to a wider audience of users.

Several tags that are already well supported by Confluence have been excluded in a bid to promote the use of Wiki Markup Editor where available.

This macro is used as shown below:

{html-tag:tag=tagName|attrib1=value,...}
body content
{html-tag:tag=/tagname}

Parameters

Parameter	Required	Notes
default		The "usage" default parameter will display additional information about the macro (see examples).
tag		The name of the HTML tag. Only whitelisted HTML tags are allowed. There are three states for the tag parameter: State Example tagName Example Usage Example Output Open Tag div {html-tag:tag=div} <div> Close Tag /div {html-tag:tag=/div} </div> Empty Tag div/ {html-tag:tag=div/} <div />
attributes		Any additional parameters will define attributes for the HTML tag. Only whitelisted attributes are allowed. Attributes can only be added to an Open or Empty Tag.

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!

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 card or bank transfer using PayPal. No account sign-up is required for credit or debit card payments.

This software is released under a BSD License

© 2005 Adaptavist.com Limited

This macro is compatible with Confluence 1.4.x and has been tested with Confluence 1.4.1, 1.4.3 and 1.4.4.

This macro is pre-installed with Builder accounts. If you wish to install it on your own Confluence install, please download it from the Confluence Extensions page.

Adaptavist maintain a JIRA Project for tracking bug reports and feature requests for this macro. The currently reported items are shown below:

• Online Documentation and Download
• html macro
• [USERGUIDE:html-include macro]

Usage Guide

The special "Usage" mode displays a list of the whitelisted tags and attributes:

{html-tag:usage}

The tags are automatically linked to online reference sites so you can find out more about them. Here is an example of the whitelist information on this site:

Note: Always check the usage guide on your own Confluence installation to be fully aware of which tags and attributes are whitelisted.

Acronym tag with attributes

The acronym tag is useful for defining terms...

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

Would result in the following HTML:

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

And here's what it looks like on-screen:

Note: For easier management of terms, why not use the [USERGUIDE:glossary macro] which allows you to define all terms centrally.

Styled DIV

Creates a div with a certain CSS class.

{html-tag:tag=div|class=dynarch-horiz-menu} _*Cool background!*_ {html-tag:tag=/div}

Would result in the following HTML:

<div class="dynarch-horiz-menu"> <em><b>Cool background!</b></em> </div>

And it would look like this on-screen:

As you can see, normal Wiki Markup Editor text works as usual - your're simply wrapping it in HTML tags.

Horizontal Rule

Creates a self-closing <hr> tag:

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

Would result in the following HTML:

<hr width="30%" />

Which looks like this on-screen:

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} [Home] {html-tag:tag=/td}
{html-tag:tag=/tr} {html-tag:tag=/tbody} {html-tag:tag=/table}

Would result in the following HTML:

<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 line feeds in 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 each line feed will create a <br /> tag in your HTML. To get round this problem, delete the line feeds between the {html-tag} macros, etc.

With the line feeds removed, the output looks like this on-screen:

Custom Scrollable Regions

You can use the macro to create custom scrollable regions, for example:

{html-tag:tag=div|class=preformatted|style=height:80 !important; overflow:scroll}
{html-tag:tag=div|class=preformattedContent}
your
scrollable
content
goes
here
{html-tag:tag=/div}{html-tag:tag=/div}

Which results in the following HTML:

<div class="preformatted" style="height:80 !important; overflow:scroll"><div
class="preformattedContent"><br />
your<br />
scrollable<br />
content<br />
goes<br />
here<br />
</div></div>

And looks like this on-screen:

your
scrollable
content
goes
here