Wiki
Clone wikiKeysight Plugins For Atlassian Products / Confluence Plugins / HTML Elements Plugin
Introduction
The HTML Elements plugin contains a number of macros to insert HTML elements and formatting.
Features at a Glance
| Feature | Description |
|---|---|
| AUI Button Macros | Various macros to insert buttons as styled by the Atlassian User Interface to link to internal or external content. |
| AUI Tab Macros | Various macros to insert tab structures onto a page using the Atlassian User Interface's Tab widget. |
| Author's Only Block Macro | A macro used by authors to place content on a page that can't be see by regular viewers. |
| Compact Form Macro | A macro to a very simple form. |
| Extra Table Properties Macro | A macro to set the table width, column widths or suppress the grid lines. |
| HTML5 Multimedia Macro | A macro to insert a video or audio file using HTML5. |
| Layout Width Macro | A macro to fix the width of a page section/column. |
| Link to New Window Macro | A macro to create a link that will open in a new window or tab. |
Features in Detail
AUI Button Macros
Description
The AUI Buttons are a series of related and interconnected macros to create buttons that use the Atlassian User Interface (AUI) styling. They are used to link to other pages or download attachments.
Macro List
| Macro Name | Description |
|---|---|
| AUI Button | A simple button that links to an internal page, space or external URL. |
| AUI Button Group | A macro to group a set of buttons into a single graphical element. |
| AUI Split Button | A button with a link to an internal page, space or external URL coupled with a dropdown menu of additional links. |
| AUI Download Attachments Button | Used to create a link or button to download an attachment without trying to preview the file. |
| Next Page Button | A button that automatically links to the previous page |
| Parent Page Button | A button that automatically links to the parent page |
| Previous Page Button | A button that automatically links to the previous page |
| Previous-Parent-Next Page Navigation | The Previous-Parent-Next Page Navigation macro provides a three section element with the Previous Page Button on the left, the Parent Page Button in the center and the Next Page Button on the Right. |
Usage
AUI Button
To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| URL | The URL to visit when the button is pressed. Any url may be provided, but the field is configured to automatically search for and insert Confluence Pages or Attachments. |
| Space Key | The author did not discover a easy widget provided by Atlassian for creating a dropdown list of matching pages or spaces; but there is a widget for selecting a page and another for selecting a space. Instead of being clever and creating a widget that did both, the author just provided both selection widgets. To use the URL field and leave the Space Key field blank. To link to a space, put any text in the URL field and space key of the targeted space in the Space Key field. In the later case, the text in the URL field will be ignored. |
| Button Text | The text printed on the button. |
| Button Style | Standard, Primary, Link or Subtle. |
AUI Button Group
Insert the macro using the normal Confluence methods, then insert one of more AUI Button macros.
AUI Split Button
In order to work properly, the AUI Split Button needs to be inside of a button group. For the simple case of a single split button, there is a macro parameter option to create the button group container automatically rather than having to insert the AUI Split Button macro inside of an AUI Button Group macro.
For the AUI Split Button, the left part of the button is specified in the macro properties just like the standard AUI Button macro. The dropdown menu is created from an unordered list of links in the body of the macro as in the example below:
| Parameters | Description |
|---|---|
| Main Button URL | The URL to visit when the button is pressed. Any url may be provided, but the field is configured to automatically search for and insert Confluence Pages or Attachments. |
| Space | The author did not discover a easy widget provided by Atlassian for creating a dropdown list of matching pages or spaces; but there is a widget for selecting a page and another for selecting a space. Instead of being clever and creating a widget that did both, the author just provided both selection widgets. To use the Main Button Url field and leave the Space field blank. To link to a space, put any text in the Main Button Url field and space key of the targeted space in the Space Key field. In the later case, the text in the URL field will be ignored. |
| Button Text | The text printed on the button. |
| Create Button Group | The split button must be in a button group. If checked, the button group will be created automatically. If not checked, the macro should be inserted into the body of an AUI Button Group macro. |
AUI Download Attachments Button
To use the macro, attach the file and then insert the macro using the normal Confluence methods and adjust the parameters as needed. The attachment must already be attached to the page before this macro can be inserted.
| Parameters | Description |
|---|---|
| Attachment | The attachment to link to (must already be attached to the page). |
| Button Text | The text printed on the button. If left blank, the name of the Attachment will be used. |
| Button Style | Standard, Primary, Link or Subtle. |
Previous Page Button
The previous page button links to the previous sibling page. If there is no sibling it will link to the parent page. If there is no parent page, it will not display anything. To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Show Page Title | By default, the macro will place the less than, '<', character in the button. If this option is selected, the title of the previous page will be used instead. |
| Button Text | If any text is supplied here, it will be used for the button text rather than the default. The keyword $title will be replaced by the title of the previous page. An example is < $title |
| Button Style | Standard, Primary, Link or Subtle. |
Parent Page Button
The parent page button links to the parent page. If there is no parent page, it will not display anything. To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Show Page Title | By default, the macro will place the less than, '^', character in the button. If this option is selected, the title of the parent page will be used instead. |
| Button Text | If any text is supplied here, it will be used for the button text rather than the default. The keyword $title will be replaced by the title of the parent page. An example is ^ $title ^ |
| Button Style | Standard, Primary, Link or Subtle. |
Next Page Button
The next page button finds the first child page or next sibling page if there are no children. If there is no following sibling page, it will link to the next sibling of the parent page. Should the parent also not have a next sibling, the macro will continue to walk up the tree looking for an ancestor page with a next sibling to link to. If no next sibling page can be found, it will not display anything. To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Show Page Title | By default, the macro will place the less than, '>', character in the button. If this option is selected, the title of the next page will be used instead. |
| Button Text | If any text is supplied here, it will be used for the button text rather than the default. The keyword $title will be replaced by the title of the previous page. An example is $title > |
| Button Style | Standard, Primary, Link or Subtle. |
Previous-Parent-Next Page Navigation
The Previous-Parent-Next Page Navigation macro provides a three section element with the Previous Page Button on the left, the Parent Page Button in the center and the Next Page Button on the Right. To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Show Page Title | If selected, will use the page titles rather than '<', '^' and '>'. |
| Exclude the Parent Button | If selected, the parent page button will be excluded. |
| Previous Page Button Text | If supplied, this text will be used for the Previous Page Button. The keyword $title will be replaced by the title of the previous page. |
| Parent Page Button Text | If supplied, this text will be used for the Parent Page Button. The keyword $title will be replaced by the title of the parent page. |
| Next Page Button Text | If supplied, this text will be used for the Next Page Button. The keyword $title will be replaced by the title of the next page. |
| Button Style | Standard, Primary, Link or Subtle. |
Purpose
These macros were written to solve three problems. First was a way to create a navigation bar that use the same styling as Confluence. Second was to create a widget that automatically linked to the previous, parent and next page. Finally, this was a workaround to provide a direct download link after Atlassian introduced the preview screen.
AUI Tab Macros
Description
The AUI Tab Macros are a series of related and interconnected macros to create tab structures using the Atlassian User Interface (AUI) Tab interface.
Macro List
| Macro Name | Description |
|---|---|
| AUI Tab | Creates a single tab. Must be placed in an AUI Tab Group. |
| AUI Tab Group | Creates a container for AUI Tab. |
| AUI Child Tabs | Creates tabs from the child pages of a target page. |
| AUI Pages Tabs | Creates tabs from a list of pages. |
| AUI Pages By Label Tabs | Creates tabs from a number of pages identified by a label. |
There are aliases for the AUI Tab, AUI Tab Group and AUI Child Tabs so that they can be used to replace the BitVoodoo Navitabs macro.
Usage
AUI Tab
The AUI Tab macro defines a single tab with an AUI Tab Group. One or more may be placed in an AUI Tab Group, but the AUI Tab should always be placed in an AUI Tab Group.
An alias for this macro, Local Tab, can be activated by enabling the Local Tab module in the HTML Elements plugin information on the Manage add-ons page to provide compatibility with instances of the Bitvoodoo Navitab Macro.
| Parameters | Description |
|---|---|
| Title | The text to put in the tab |
| Active | Only one tab in the tab group should be active. This sets which tab will be displayed when the page loads. |
AUI Tab Group
The AUI Tab Group defines a container to hold instances of the AUI Tab macro.
An alias for this macro, Local Tab Group, can be activated by enabling the Local Tab Group module in the HTML Elements plugin information on the Manage add-ons page to provide compatibility with instances of the Bitvoodoo Navitab Macro.
| Parameters | Description |
|---|---|
| Vertical Orientation | If checked, tabs will be positioned vertically rather than horizontally. |
AUI Child Tabs
The AUI Child Tabs macro constructs a tab graphical element where each one of the tabs is labeled by the title of the child page and the tab itself contains the contents of the child page.
An alias for this macro, Childtabs, can be activated by enabling the Childtabs module in the HTML Elements plugin information on the Manage add-ons page to provide compatibility with instances of the Bitvoodoo Navitab Macro.
| Parameters | Description |
|---|---|
| Vertical Orientation | If checked, tabs will be positioned vertically rather than horizontally. |
| Root Page | Specifies the parent page from which to get the child pages. Defaults to the current page. |
| Vertical Orientation | If checked, the tabs will be listed vertically rather than horizontally. |
| Reverse | If checked, the tabs will be listed in reverse order from the listing in the sidebar. |
| Left Truncation | As the page title is inserted into a tab label, this is the number of characters to truncate from the left. |
| Right Truncation | As the page title is inserted into a tab label, this is the number of characters to truncate from the right. |
AUI Pages Tabs
The AUI Pages Tabs macro constructs a tabbed graphical display of a number of Confluence pages. The pages need to be provided in the body of the macro as a unordered list of links to Confluence pages. Each page in the list will be converted to a new tab.
The primary reason this macro was developed was to create a dashboard of project status pages. The macro provides the ability to provide a date. If defined, the macro will pull the version of the pages that existed on that date. If no version of the page existed prior to the date, the first version of the page will be shown. This makes it easier to keep track of the view that was used during a meeting.
| Parameters | Description |
|---|---|
| Vertical | If checked, the tabs will be shown vertically rather than horizontally. |
| Hide Not Permitted Tabs | Normally, if a page is requested by the viewer does not have permissions to see the content, an error message to that effect is shown in the tab. If this option is checked, any tabs for which the user does not have permissions to view the content will not be shown. |
| On Creation Date | If set, the version of the included pages that existed when the containing page was created will be shown. |
| On Date | If checked, the tabs will be listed vertically rather than horizontally. |
AUI Pages By Label Tabs
The AUI Pages By Label Tabs is very similar to the AUI Pages Tabs macro with the exception that the pages are located by a label rather than by an unordred list of links in the body of the macro.
| Parameters | Description |
|---|---|
| Label | The label on pages that should be pulled into the tabbed structure. |
| Limit | The number of pages to pull in. 100 is the maximum number. |
| Vertical | If checked, the tabs will be shown vertically rather than horizontally. |
| On Creation Date | If set, the version of the included pages that existed when the containing page was created will be shown. |
| On Date | If checked, the tabs will be listed vertically rather than horizontally. |
| Left Truncation | As the page title is inserted into a tab label, this is the number of characters to truncate from the left. |
| Right Truncation | As the page title is inserted into a tab label, this is the number of characters to truncate from the right. |
Purpose
These macros were developed when the BitVoodoo Navitabs was converted from a free plugin to a commercial plugin. Since the hard work was done by Atlassian as part of the Atlassian User Interface (AUI), it was deemed easier to roll our own version than continue with the BitVoodoo solution.
Author's Only Block
Description
The Author's Only Block will show the body of the macro only if the current user has permissions to edit the page. This is intended to be used as a way for authors to leave themselves notes on the page without making those notes public to general readers
Usage
Insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| No Border | By default, the block will have a border identifying it as only visible to authors. If selected, this border will not be shown. |
Purpose
This was written as a way to help some of the content authors who maintain spaces with many viewers and few authors.
Compact Form
Description
The Compact Form macro allows a user to create a form on a Confluence page using a plain text syntax in the body of the macro.
Usage
Form Syntax
Every line in the body of the macro maps to a distinct form element.
A Text Field
KEY KEY->LABEL
A text field can be created by specifying a single string, such as KEY. When the submit button is pressed, KEY will be passed in the with whatever text is in the field as the VALUE. To provide a user friendly label on the web page, use the syntax KEY->LABEL. If no label is specified, none will be printed.
Example: USERNAME->Username
A Hidden Field
*KEY:VALUE
The hidden field will not be shown to the user on the web page, but the KEY:VALUE pair will be passed to the form url when submitted.
Example: *SECRET_VALUE->BLUE
A Dropdown Selection
KEY:SELECTION1,SELECTION2,!DEFAULT_SELECTION KEY->LABEL:SELECTION1->LABEL1,SELECTION2->LABEL2,!DEFAULT_SELECTION->LABEL3
The form element is named by the KEY. As with the Text Field, a user friendly label can be provided with the syntax KEY->LABEL. If the key is followed by a colon, and a comma separated list that indicates a dropdown list should be created. Each of the selections can be provided with a user friendly label as shown in the syntax. If one of the selections is preceded with an exclamation point (!), it will be the default selection. Only one selection should be flagged with the exclamation point.
Example: FAVORITE_COLOR->My Favorite Color:!BLUE->Awesome Blue,PINK->Georgeous Pink
Parameters
Insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameter | Description |
|---|---|
| Style | Sets the display style for the form. AUI looks better and fits the general Confluence look and feel. Plain *HTML is more compact. |
| URL | Sets the url where the form data will be sent when submitted. |
| Form Target | Determines if the results from the submitted form should be opened in the same window or a new one. |
| Submit Button Text | Sets the text placed on the submit button. |
Parameters Exclusive to the AUI Style
| Parameter | Description |
|---|---|
| Form Layout | Determines if the labels should be short on the left (default), long on the left, on the top or unsectioned (for short forms). |
Parameters Exclusive to the Plain HTML Style
| Parameter | Description |
|---|---|
| Form Element Separator | A string, such as a line break ( ) to insert between form elements. |
| Form Alignment | The justification of the form elements: Left, Center or Right |
| Submit Button Element Separator | A string, such as a line break ( ) to insert before the submit button. *(Defaults to the Form Element Separator) |
| Submit Button Alignment | The justification of the submit button: Left, Center or Right (Defaults to the Form *Alignment) |
Purpose
This macro was written to allow end users to insert a form on a web page.
Extra Table Properties
Description
This macro allows the user to set the table and column widths. There is also an option to suppress the horizontal lines separating rows. Note, the plugin uses javascript to adjust the widths when the page is rendered. The settings will not be applied when editing the page.
Usage
Insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Table Width | Sets the width of the table. The value will be inserted into the html table element's width attribute. Example: 90% or 400px. |
| Column Widths | A comma seperated list of the desired column widths. Example 100px,200px or 80%,20% |
| Row | As the top row may have merged cells, this parameter determines which row the column width attributes will be added into. |
| Hide Borders | If checked, a stylesheet rule will be applied to suppress the table and cell borders so that no grid lines are visible. |
Purpose
This plugin is trying to fillout some basic table functionality that Confluence should but doesn't provide. It was developed before Confluence allowed some control over the sizing of the columns; however, this macro was still deemed useful as it provided numerical precision in the column spacing.
HTML5 Multimedia
Description
The html5 multimedia macro is used to display a multimedia file (audio or video) via the video and audio tags introduced with html5. The video can be sourced from either an attachment or via url. There is an alias for the macro that will allow Confluence administrators to disable the default multimedia plugin and replace it with this one.
For larger audio/video files is it highly recommended to host them externally to Confluence on backed up media and provide the URL rather than attaching the file to the page. This is because video files can be large and make the backup or upgrade process for Confluence much slower and cumbersome.
The macro does not support the ability to expose a multimedia attachment from a page other than the one the macro is placed on. If there is a desire to place an attached video file on two pages, the recommended approach is to create a video container page where the file is attached and the multimedia macro is inserted and then use the include-page macro to place the video on each of the destination pages.
This macro has two forms: multimedia and html5-multimedia. The former is a direct replacement for the multimedia macro provided with Atlassian Confluence. When this macro was first developed, the Atlassian provided multimedia macro did not work very well with modern browsers. The recent macro for Confluence also uses HTML5, however, it did not provide the ability to source video from a url. For compatibility reasons, the parameters available to the multimedia expression of this macro are identical to the parameters of the default multimedia macro. The html5-multimedia macro provides a few more parameters to expose some of the functionality provided by the html5 tags.
Usage
Insert the macro like any other Confluence macro. The author will need to open the macro properties and either select a video file that has already been attached to the page or provide the url to the video file.
Macro Parameters
| Parameter | Description |
|---|---|
| Attachment | This is the name of the multimedia attachment. The dropdown list will be automatically constructed from *the page attachments. For the macro to work, either the Attachment or URL must be provided. |
| Url (html5-multimedia only) | This is the url to the multimedia file. For the macro to work, either the Attachment or *URL must be provided. |
| Video dimension presets (html5-multimedia only) | These are some common dimensions for video files. If a preset is set, the Width and Height parameters will be ignored. |
| Width | Sets the width of the video container. If a preset is set, the Width and Height parameters will be ignored. |
| Height | Sets the height of the video container. If a preset is set, the Width and Height parameters will be ignored. |
| Poster (html5-multimedia only) | A url to a static picture presented when the video is not playing. |
| AutoPlay | If checked, the video will start to play when the page is loaded. |
| Loop playback (html5-multimedia only) | If checked, the video will re-start after it finishes. |
| File contains audio only (html5-multimedia only) | If checked, the <audio> tags will be used to only show the audio player. If not checked the use of the <audio> or <video> tags will be determined by the file type defaulting to the <video> if the answer is unclear |
| Add a link to download the attachment (html5-multimedia only) | A direct url to the video file will be provided if *this is checked. |
Supported Video Formats
| Audio | Video |
|---|---|
| mp3 | mp4 |
| ogg | ogg |
| wav | webm |
Purpose
The original purpose of this macro was to provide a macro to place a video file on a page using HTML5. At the time this macro was written, the Confluence plugin tried to use Quicktime. The Atlassian macro has been updated to use HTML5; however, it does not allow video to be inserted from a URL so this version of macro is still being used internally by Keysight.
Layout Width
Description
The content editor in Confluence can create sections with either one, two or three columns. The default layouts are one of the following options:
100% 50% | 50% 29.9% | 70.1% 70.1% | 29.9% 33% | 33% | 33% 19.9% | 60.2% | 19.9%
Confluence provides no way to set a custom width of the layout section. This macro uses javascript to override the default and set the width.
Usage
Insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Layout Width | Sets the width of the table. Example: 90% or 400px. The value will be inserted as the value for the css width property in the the sections element's style attribute. |
Purpose
Keysight has been using Confluence to host department home pages. The department managers photo was placed in the right column. As the page width gets small, some of the image would be concealed and scroll bars would be shown. This macro was developed to prevent this behavior.
Link to New Window
Description
This macro allows the user to set the table and column widths. There is also an option to suppress the horizontal
Usage
Insert the macro using the normal Confluence methods, then adjust the parameters as needed.
| Parameters | Description |
|---|---|
| Link URL | The Confluence page or fully qualified url. |
| Link Text | The text of the link |
Purpose
This macro was developed by request from some of the users who wanted to create links that would explicitly open in a new window or tab so that users were not taken away from the current page.
Updated