...
...
...
| Table of Contents | ||||||||
|---|---|---|---|---|---|---|---|---|
|
| Section |
|---|
| Column |
| Warning |
Removal notice: Please note that the URL user and URL user password parameters were removed (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data. |
|
|---|
Features
Supports capabilities for including data similar to other scripting macros.
Supports find and replace for adjusting resulting output.
Allows
...
administrators to restrict the usage of Javascript in the HTML macro (based
...
on Allow JavaScript in Configuration settings). The Confluence page throws a rendering error if this parameter is not enabled, and
...
Javascript is inserted while using the macro.
Other HTML macros
- {html} and {html-include} macros shipped with Confluence. See the Confluence User Guide: http://confluence.atlassian.com/display/DOC:HTML Macro and http://confluence.atlassian.com/display/DOC:HTML Include Macro. These macros are disabled by default in Confluence, since it is a security exposure unless you only have trusted users on your site. The Confluence HTML macro must be disabled for the new HTML macro to be used.
- HTML Tag - a safer alternative to the standard {html} macro but does not allow for arbitrary HTML to be included.
| Tip |
|---|
By default, header content is excluded as it could interfere with Confluence page HTML. Use head=true to include anyway provided it does not disturb the content. |
Parameters
...
Determines how the output is treated.
- html - standard HTML
- xhtml - data is treated as XHTML and rendered with the Confluence XHTML renderer prior to display
- wiki - data is surrounded by a noformat macro. This is a very special case.
...
If the location of data is specified, the included data follows the body data (if any).
...
Parameters
 |  |
Macro editor label | Default | Description |
|---|---|---|
Data source | ||
Data source | Specify the source of the HTML content to be rendered. The options available are:
| |
...
|
...
|
...
| ||||||||
Layout | ||||||||
Height of iframe (in px) | Enter the minimum height (in px or em) to be used for the rendered content. If you do not specify, the height is auto-rendered according to the HTML content. Example: 500px or 1.5em
| |||||||
Settings | ||||||||
Format | html | Specify how the output is treated. The options are as follows:
| ||||||
Find regex patterns | ||||||||
...
Enter a comma separated list of regex patterns to use to post-process the output HTML with find and replace logic. Example: (href=)(/display) |
...
Replacement strings |
...
Enter a comma separated list corresponding to find patterns via index position in list. |
...
If a comma |
...
is a part of an entry, use single quotes around it. Example: $1$base_url$2 | ||
Timeout in milliseconds | Enter time in milliseconds such that URL connections do not timeout before getting data. Use this to increase time needed for slow connections. Note that if a zero is given the connection may wait infinitely. | |
File encoding | system default |
...
Specify the encoding |
...
Usage
Example - HTML from a file in the script folder in the Confluence home directory
| No Format |
|---|
{html:script=#example.html}
{html}
|
Example - HTML from an attachment
| No Format |
|---|
{html:script=^example.html}
{html}
|
Example - HTML put within {noformat} panel
| No Format |
|---|
{html:output=wiki|noPanel=true}
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam fermentum vestibulum est. Cras rhoncus.
{html}
|
Example - HTML from an URL
...
for an external file, if different from the system default handling. Example: UTF-8. |
...
User id for URL connection (Removed) | Enter the user name for URL access via basic authentication.
| |||
Password for URL connection (Removed) | Enter the password for URL access via basic authentication.
| |||
Allow same origin | Off | Enable the page viewing user to execute scripts to access cookies and Confluence APIs based on the app's Macro security configuration.
| ||
Allow script execution | Off | Enable to allow scripts to be executed based on the app's Macro security configuration.
|
Macro security and macro parameter settings
This section explores how the script global setting along with the parameter settings (Allow same origin and Allow script execution) affects the content in the macro. To learn more about the macro security configurations, see the Configuration page.
The following table explains this co-relation:
Global configuration - Allow JavaScript parameter is enabled? | Global configuration - Macro security is provided? | Page restrictions given? | Macro parameters setting | How is the HTML content affected? | ||
|---|---|---|---|---|---|---|
Allow same origin | Allow script execution | |||||
Yes | NA | NA | NA | NA | Works as expected. If this global configuration parameter is enabled, it overrides any other settings. This is the default behaviour. | |
No | Not defined or none are applied | NA | Off | Off | Works as expected. | |
Off | On | Displays a warning message to apply macro security parameter/space/user/group restrictions and have similar page level restrictions to proceed. | ||||
On | Off | |||||
On | On | Displays a warning message to apply macro security parameter/space/user/group restrictions and have similar page level restrictions to proceed. | ||||
Defined (either Parameter name is given or trusted space/user/group is given) | Same as macro security restrictions | Off | Off | Works as expected. Scripts are not executed and no warnings are displayed. | ||
NA | Off | On | Displays a warning message to apply macro security parameter/space/user/group restrictions and have similar page level restrictions to proceed. | |||
On | Off | |||||
Same as macro security restrictions | On | On | Works as expected. Macro security parameter/space/user/group restrictions must be applied and similar page level restrictions set to render content. | |||
Points to remember
If the global app configuration Allow JavaScript parameter is enabled, it overrides any settings made to the Allow script execution or Allow same origin parameters. This is the default behaviour. This ensures that scripts are executed and content is rendered.
If macro security restrictions are set, the pages which have the HTML macro must have the same space/user/group restrictions to render the content. If not done, a warning message is displayed to apply these restrictions to proceed.
Warning messages are displayed if restricted user/group tries to access a trusted space and the content is not rendered.
Examples
The following examples show how you can use the macro to render HTML content:
HTML from an attachment
| Code Block |
|---|
{html:script=^example.html}
{html}
|
HTML from an URL
| Code Block |
|---|
{html:script=#http://localhost/example.html}
{html}
|
...
Use of CSS inline style sheet
| No Formatcode |
|---|
{html}
<P style="font-size: x-large; color: #8000">
Using inline style sheets - or is that inline styles?
</p>
{html}
|
Example - use of CSS external style sheet
| No Format |
|---|
{html}
<LINK href="http://www.cssgarden.com/css/T22/keylime_0001.css" rel="stylesheet" title="default" type="text/css"></LINK>
<H1>Absolute </H1>
{html} |
| Info |
|---|
| Make sure that style sheet is available on a server and provide an absolute URL reference to this external style sheet resource. |