Versions Compared

Old Version 35

changes.mady.by.user Smita Nair

Saved on

compared with

New Version Current

changes.mady.by.user Smita Nair

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Warning

Removal notice:

Please note that the URL user and URL user password parameters were removed in 5.8.5 (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data.

Table of Contents
minLevel2
maxLevel6
outlinefalse
styledefault
typelist
printabletrue
Info

To comply with Atlassian requirements, the HTML macro name has changed from HTML to Html-bobswift from version 5.7.0. Any existing occurrences of the HTML macro name are not affected by this change; however, only the Html-bobswift macro name is now available in the macro browser for any new macro additions to the pages.

Features

  • Render HTML content from within the macro body, attachments, or remote locations using URLs.

  • Allows malformed HTML to be cleaned so content displays properly with JTidy.

  • Supports find and replace for adjusting resulting output.

  • Allows the user to restrict the usage of Javascript in the Html-bobswift macro (based on the configuration of Allow Javascript in theConfigurationpage). The Confluence page throws a rendering error if this parameter is not enabled, and Javascript is inserted while using the macro.

  • Supports capabilities for including data similar to other scripting macros.

  • Supports security restrictions as described in

    CMSP

    Macro Security for Confluence.

Info

  • The macro works with valid, downloadable HTML files only. 

    Tip
    titleHow to identify HTML files that are valid for the macro?

    Paste the file link into your browser's address bar. If the actual HTML code is displayed in the browser, it is considered to be invalid or in an incorrect format. If the file downloads to your system, the macro can process the file and its contents.

  • If you want to specify a URL in the Location of HTML data parameter, make sure that only a raw URL is provided.

     A

     A raw URL is defined as the part of the URL following the domain information and includes the query string, if present.

     For

     For example, in the URL string http://www.contoso.com/articles/recent.aspx, the raw URL is /articles/recent.aspx.

Note
title

Important information for Macro Security users!

Existing pages that use the HTML macro name with the Macro Security macro are unaffected, and for any new macro additions with the Html-bobswift macro name, specify the same HTML configurations as given for the HTML macro. In such cases, parameters for both, HTML and Html-bobswift, macro names must be added in Macro Security for Confluence Configuration to render the HTML content on the pages correctly. Any entries made for the XSLT macro remain unaffected and hence, the entries made for this macro can be retained as-is in the Macro Security configuration. Refer  Refer to the the Configuration page for  for more information.

Other HTML macros

  • Confluence comes with two native macros: {html} and {html-include}. These macros are disabled by default in Confluence, since it is a security exposure unless you only have trusted users on your site. The native Confluence HTML macros must be disabled to use the Html-bobswift macro of HTML for Confluence.

  • 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 a Confluence page's HTML code. Enable Include head section HTML to include the header tag, provided it does not mess up the HTML content.

Parameters

Macro browser label

Default

Description

Macro parameter

Format

html

Specify how the output is treated. The options are as follows:

  • html - transformed output is standard HTML.

  • xhtml - transformed output is treated as XHTML and rendered with the Confluence XHTML renderer.

  • wiki - transformed output is treated as wiki markup and rendered with the Confluence wiki renderer.

output

Profile


Enter the profile name to access the files to be rendered. Profiles contain a basic set of parameters used to access a remote location such as the type of URL, user credentials, and so on.

 Refer to this link to

 Refer to profiles configuration to know more about

profile configuration and this link for

profiles and see tutorials. 

Note

  • Contact your Confluence

administrator for

  • administrator for further information about the profiles available in your instance.

  • If a profile is specified, it is recommended to provide the relative path to the location of the HTML file to be rendered.

profile

Location of HTML data

macro body

Enter the location that contains the HTML file to be rendered. If a location of data is specified, the included data follows the body data (if any).

  • #filename - Data is read from the file located in Confluence home/script/filename directory. Subdirectories can be specified.

  • global page template name - Data is read from a global page template. Special note: How to deal with templates on Confluence 4.3 and later.

  • space:page template name - Data is read from a space template.

#http

  • #http://... - Data is read from the URL specified. May require user name and password as well. 

Info

If a Profile is specified, the pound sign (#) is optional, that is, the URL is processed regardless of the pound sign (#) before the URL.

  • ^attachment - Data is read from an attachment to the current page.

  • page^attachment - Data is read from an attachment to the page name provided.

  • space:page^attachment - Data is read from an attachment to the page name provided in the space indicated.

Note
title

Precedence in URL handling

URLs are processed using a fixed precedence explained as follows:

  1. If the given URL is linked to a specific application like Bitbucket, GitLab, or GitLab, the macro does not require any user credentials, and processes and renders the given file. Refer to

this article

  1. application links for information

about application links

  1. .

  2. If Profile is specified, the macro appends the URL given here with the URL specified in the profile configuration, and accesses the location to render the required file.

  3. Lastly, if no application links or profiles were given, the URLs are processed as-is and the required file is rendered.

script

Find regex patterns


Enter a comma-separated list of regex patterns to dynamically update the output content.

 Refer to this article for

 Read more

information

about regular expressions.

Example: (href=)(/display)

find

Replacement strings


Enter a comma-separated list of positions to search

for patterns

for patterns in the output content. Note that the positions are indexed beginning at "1".

If

If a comma is a part of the search, use single quotes (') around it.

Example: http://www.google.com/$1

replace

File encoding

system default

Specify the

encoding

encoding for an external file, if different from the system default handling.

Example: UTF-8

.

encoding

Select to use JTidy

false

Enable this option to use JTidy to ensure the HTML is well formed to prevent page display problems.

tidy

Remove conflicting tags

true

Disable this option to

surround the

surround the HTML with an iframe. By default, this parameter allows the display of HTML content in a Confluence page without an iframe. The html, body, and (optionally) the head tags including their corresponding ending tags are removed so that it displays properly on a Confluence page.

clean

Include head section HTML

false

Enable this option to retain all the other tags from the header section and treat them as regular body content. This is useful for retaining style information in particular.

 By

 By default, the head tag is always removed.

 Valid

 Valid only if Remove conflicting tags is enabled.

head

Omit panel when output is wiki 

false

Enable this option to hide the panel around the rendered content. This parameter provides a way of setting the nopanel parameter of the noformat macro. Valid only if Format is set to wiki.

noPanel

Width of iframe

500

Enter the width for the iframe that displays the HTML content. Valid only if Remove conflicting tags is disabled.

width

Height of iframe

500

Enter the height for the iframe that displays the HTML content. Valid only if Remove conflicting tags is disabled.

height

URL user 


Enter the user name to be used for URL access to HTML files.

Warning

Removal notice:

Please note that the URL user and URL user password parameters were removed in 5.8.5 (see Deprecation notice: URL user and URL user password parameters). We recommend using  profiles to access external data.

user

URL user

password 

password 


Enter the user password to be used for URL access to HTML files. 

Warning

Removal notice:

Please note that the URL user and URL user password parameters were removed in 5.8.5 (see Deprecation notice: URL user and URL user password parameters). We recommend using  profiles to access external data.

password

Timeout in milliseconds


Enter time in milliseconds to wait until the URL connection times out before getting data. Use this to increase time needed for slow connections. Note that if a zero is given, the connection may wait indefinitely.

timeout

title
Info

About profiles:

  • Administrators create profiles to connect to remote locations. A profile contains the basic information required to access a remote location and usually contains the base URLs of the location. In the macro editor, you must specify the relative URL in the Location of HTML data parameter. The macro combines these paths to create an absolute URL. If any part of this URL is incorrect or the URL itself is invalid, the macro generates an error. To get more information about profiles, select the relevant article specified in the Helpful resources section.

  • Since release 5.7.0,

    the 

    the HTML

     macro

     macro name has changed

    from HTML to 

    from HTML to Html-bobswift. Existing pages that use

    the 

    the HTML

     macro

     macro name with

    the 

    the Macro Security

     macro

     macro are unaffected. Any new pages that are created automatically use

    the 

    the Html-bobswift

     macro

     macro name. So, entries for both, HTML

     and 

     and Html-bobswift, macro names must be kept in Macro Security for Confluence Configuration. 
    If any of these entries are not available

    in Macro

    in Macro Security for Confluence Configuration, an error, "Security restricted macro

    with parameter

    with parameter 'profile' is not allowed. An edit restriction is required that matches the macro authorization list.", is displayed. Ensure that the following entries are available for the HTML macro name:

    • Key: html.profile.*
      Value: *ANY

    • Key: html
      Value: *ANY

    • Key: html.allowJavascript
      Value: *ANY

    Ask your administrator to manually add the following

    entries for

    entries for the Html-bobswift

     macro

     macro name in Macro Security for Confluence Configuration > Secured macros:

    • Key: html-bobswift.profile.*
      Value: *ANY

    • Key: html-bobswift
      Value: *ANY

    • Key: html-bobswift.allowJavascript
      Value: *ANY

Usage examples

HTML from a file in the Confluence home/script directory

No Formatcode
{html:script=#example.html}
{html}

HTML from an attachment

No Formatcode
{html:script=^example.html}
{html}

HTML put within {noformat} panel

No Formatcode
{html:output=wiki|noPanel=true}
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam fermentum vestibulum est. Cras rhoncus.
{html}

HTML from a URL

No Formatcode
{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}

Use of CSS external style sheet

No Formatcode
{html}
<LINK href="http://www.cssgarden.com/css/T22/keylime_0001.css"  rel="stylesheet" title="default" type="text/css"></LINK>
<H1>Absolute </H1>
{html}

Make sure that style sheet is available on a server and provide the absolute URL reference to this external style sheet resource.

Anchor
html_57_html_helpfulResources
html_57_html_helpfulResources
Helpful resources