Pro Macros

Last modified by Administrator on 2021/10/24 00:00

Pro Macros

Supercharge XWiki’s functionality with Pro macros. Compatible with Atlassian Confluence macros imported during migrations. Can be purchased individually or part of the XWiki Pro package. Try them free.

CategoryMacro
Active Installs16
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Minimal XWiki version supportedXWiki 9.11
SourcesIssues

Macros are how you take XWiki's functionality to the next level. They can be used to:

  • Display content in a more visually appealing manner or highlight important information
  • Embed documents, such as PDF or Office files or display diagrams
  • Show the relations between XWiki pages and improve navigation
  • Display media, such as videos and audio

All Pro macros are compatible with Atlassian Confluence macros imported during migrations (generic macros), with some of them specifically developed only to cover this need (macros used only in the context of Confluence migrations):

Generic Macros

  • Panel
  • Status
  • View Files
  • Note
  • Paste Code
  • Details
  • Content Report Table
  • Column
  • Section
  • Layout
  • Multimedia
  • Anchor

Macros used only in the context of Confluence migrations

  • Gliffy
  • Balsamiq
  • Mockup
  • Confluence Gallery
  • Excerpt

Inserting a macro

To insert a macro you should edit the page:

  • Click on the "+" icon from the editor
  • Select the macro from the list
  • Fill in the needed parameters
  • Click "Submit"

InsertMacros.png

Editing a macro

Macros can be edited by double clicking on the macro in the visual editor. Alternatively, you can edit the syntax of the macro by going to the page's source. The supported parameters, as well as the syntax, are detailed in the Documentation tab for each macro.

Generic Macros

Panel

The Panel macro allows you to display XWiki content inside a visually appealing panel. You can customize its size, colours and border.
This macro supports all Atlassian Confluence parameters as of version 7.9.

Parameters

 Parameter  Name  Default value  Description
 title  Title  -  If specific a title section is added with the specific text
 bgColor  Background color  -  If specific sets the background color of the content of the panel
 width  Width  -  If specified sets the width of the panel (300px or 50%)
 height  Height  -  If specified sets the width of the panel (300px or 50%)
 classes  CSS classes   -  If specified adds css classes to the panel
 borderColor  Border color white If specified sets the panel border color
 borderStyle  Border style solid  If specified sets the css border style
 borderWidth Border width 1px If specified sets the border width in pixels
 borderRadius Border radius8px 8px 0px 0px If specified replaces the default border radius
 titleBGColor  Title background color  -  If specified sets the title section background color
 titleColor  Title text color  -  If specified sets the title text color

Examples

Simple panel

Content of the panel

Simple panel with border and size

Content of the panel

Panel with title and colors

Title of the panel

Content of the panel

Panel with title and colors and border

Title of the panel

Content of the panel

Panel with bootstrap classes

Title of the panel

Content of the panel

Title of the panel

Content of the panel

Title of the panel

Content of the panel

Status

The Status macro helps you highlight the status of an item using a colored box. You can customize both the text and the background color. The background can be either lightly colored, or dark, depending on your preference. The macro can be used inside other macros.

Parameters

 Parameter  Name  Default value  Description
 title  Title The color nameThe text of the status. If not specified, the color name will be displayed (e.g.:"Grey").
 colour  Color GreyThe color of the status (text color and background color). The following colors are available: "Blue", "Green", "Grey", "Purple", "Red" and "Yellow".
 subtle  Subtle FalseThe aspect of the status: either white text on dark color background or dark color text on light color background. It should be filled with "true" or "false".

Examples

{{status title="Task"/}}

Results in:

Check the parameters.Task

{{status title="Improvement" colour="Green"/}}

Results in:

Add a new status macro.Improvement

{{status title="Improvement" colour="Green" subtle="true"/}}

Results in:

Add a new status macro.Improvement

View Files

The View Files macro allows you to embed an Office or a PDF document inside an XWiki page. You will need to attach the document to the page. The supported file types are doc, docx, xls, xlsx, ppt, pptx, and pdf.
Any macro added as such in Confluence should be, when migrating, converted into a view-file macro and have a preview.
To display specific file types you can also use the following macros:

  • View Doc
  • View Pdf
  • View Ppt
  • View Xls

Example

{{view-file att--filename="Test.pdf"/}}

Results in:

TestPDF.png

Note

Similar to the warning macro, the note macro is used to highlight important notes in a coloured panel.

Parameters

ParameterDescription
titleThe title of the note.

Example

{{note title="Note: "}}
This is my note with title.
{{/note}}

Results in:

Note: 

This is my note with title.

Paste Code

Similar to the Code macro, the aim of this macro is to allow users to paste code snippets inside XWiki pages.

Parameters

ParameterDescription
languageThe code language to be used for the representation.
titleThe title of the box containing the code.

Example

{{paste-code-macro language="java" title="Hello World Example"}}
class Simple{
    public static void main(String args[]){
        System.out.println("Hello World !");
    }
}
{{/paste-code-macro}}

Results in:

Hello World Example

class Simple{
   public static void main(String args[]){
        System.out.println("Hello Java");
   }
}

Details

The Details macro provides a list of related pages based on tags (labels). Related pages will be in relation to the tags added to the current page, where the macro is used.

Parameters

ParameterDescriptionDefault
idThe id of the details section. 
hiddenWhether to display the details or notfalse
maxResultsMaximum number of pages to displayfalse

Example

{{details id="test" /}}

Results in:

Details.png

Content Report Table

This macro provides a content report in a table format based on tags (labels).

Parameters

ParameterDescriptionRequiredDefault
labelsThe labels (tags) to report on, separated by comma.Yes 
spacesThe space keys to report on, separated by a comma and a blank space (e.g: "Confluence, XWiki")No 
maxResultsMaximum Number of results (pages).No20

Examples

{{content-report-table labels="test"/}}

Results in:

ContentReport.png

Column

The column macro lets you organise content in columns. This macro is used in conjunction with the Section macro, and provides more flexibility to the page layout.

Parameters

ParameterNameDescription 
widthWidthThe width of the column. Can be specified either in pixels (for example, 400px) or as a percentage of the available page width (for example, 50%).

Examples

Simple column

{{column width="350px"}}
Add the Section macro to a page to organise your content in sections and columns.  This macro is used in conjunction with the Column macro.
{{/column}}

Results in:

Add the Section macro to a page to organise your content in sections and columns.  This macro is used in conjunction with the Column macro.

Columns usage in Section

{{section border="true"}}

{{column width="250px"}}
Add the Section macro to a page to organise your content in sections and columns.  This macro is used in conjunction with the Column macro.
{{/column}}

{{column width="300px"}}
Content in the column 2
{{/column}}

{{column width="300px"}}
Content in the column 3
{{/column}}

{{column width="250px"}}
Content in the column 4
{{/column}}

{{/section}}

Results in:

Add the Section macro to a page to organise your content in sections and columns.  This macro is used in conjunction with the Column macro.

Content in the column 2

Content in the column 3

Content in the column 4

Section

Add the Section macro to a page to organise your content in sections and columns. This macro is used in conjunction with the Column macro to personalise the XWiki page layout.

Parameters

ParameterNameDescriptionDefault value
borderShow BorderSelect this option to draw a border around the columns, when they exist.false

Examples

Simple section without border

{{section}}
Content of a simple section, without border.
{{/section}}

Results in:

Content of a simple section, without border.

Simple section with border, no column

No border is added, because the borders are applied on columns, when they exist.

{{section border="true"}}
Content of a simple section, with border.
{{/section}}

Results in:

Content of a simple section, with border.

Simple section with border and column

{{section border="true"}}
{{column}}
Content of a simple section, with border.
{{/column}}
{{/section}}

Results in:

Content of a simple section, with border.

Section with 4 columns

{{section border="true"}}

{{column width="250px"}}
Content in the column 1
{{/column}}

{{column width="300px"}}
Content in the column 2
{{/column}}

{{column width="300px"}}
Content in the column 3
{{/column}}

{{column width="250px"}}
Content in the column 4
{{/column}}

{{/section}}

Results in:

Content in the column 1

Content in the column 2

Content in the column 3

Content in the column 4

Multimedia

The Multimedia macro is a bridge between Confluence and XWiki. It uses the JW Player open-source embeddable media player for web sites, supporting many commonly-used audio and video formats.

Parameters

ParameterDescriptionRequiredDefault
pageThe page to which the multimedia file is attachedNo 
nameFile name of the attached multimedia file.Yes 
widthThe player width, in pixels. If not defined, the player tries to determine automatically the width from the played media file.No 
heightThe player height, in pixels. If not defined, the player tries to determine automatically the height from the played media file.No 
autostartIf the parameter is set to true then the video or audio file will start playing as soon as the page is loaded.Nofalse

Examples

Video

{{multimedia name="file_example.mp4" width="500" height="200" /}}

Results in:

Loading the video player...

Audio

{{multimedia name="file_example.mp3" height="30"/}}

Results in:

Loading the video player...

Anchor

By including the Anchor macro in a page, you can link to a specific part of a page. Once you have added a link to the anchor, clicking on the link will bring you back to the location of the anchor.

Example

For anchor "test":

{{anchor name="test" /}}

Link syntax:

[[test link>>||anchor="test"]]

Macros used only in the context of Confluence migration

Gliffy

The Gliffy macro is a Confluence specific macro. It is a bridge between the Gliffy macro used in Confluence and the Diagram macro used in the XWiki Diagram Application. The aim of this macro is to allow users to view and modify the diagrams migrated from Confluence. By default, the macro displays the preview of the Gliffy diagram. The user can create the editable version of the diagram, by using its representation into an XWiki diagram, having always the option to go back to the preview of the original diagram.

Parameters

ParameterDescription
nameThe diagram identifier. It should be the name of the attachment storing the Gliffy diagram data. It should not have a filename extension. The Gliffy diagram exports consist in attachments added to the parent page. For example, for a diagram called MyGliffyDiagram, there will be two attachments on the parent page : MyGliffyDiagram.png (the filename with a ".png" extension) representing the preview of the diagram and MyGliffyDiagram (with no filename extention) representing the diagram data.

Besides the name parameter, the {{gliffy}} macro used in Confluence has other parameters that don't have to be cleaned, because these parameters are being ignored by this bridge macro.

Example

  {{gliffy name="MyGliffyDiagram" /}}

Results in:

MyGliffyDiagram.png

Balsamiq

This macro is a bridge for the Confluence Balsamiq Wireframe macro. It displays the image preview of the mockup, as it was migrated from Confluence.

The wireframe preview is an attachment added to the parent page. For example, for a wireframe identified with MyWireframeID, there will be an attachment on the parent page of this form: <balsamiq_MyWireframeID[_branchID].png. This means that there will be a prefix called balsamiq followed by an underscore (_), then the resource identifier (MyWireframeID in this case), then an arbitrary suffix (if it is set, by default it will be called Master). So, here are some filenames matching our example :

  • balsamiq_MyWireframeID_Master.png
  • balsamiq_MyWireframeID.png

Even if the macro is called in Confluence "Balsamiq wireframes", the id of the macro is "mockup". This is why, when importing these types of macros into XWiki, they are converted into "mockup" macros. 

Parameters

ParameterDescriptionAccepted valuesDefault valueMandatory
initialResourceIDThe ressource ID that is part of the mockup filename attached to the current page (in the example above, it would be MyWireframeID).  Yes
initialBranchIDThe branch on which the file was stored. If it exists, by default, Confluence sets it to Master.   
AlignmentThe alignment of the wireframe preview.Left, Center and RightLeft  

Example

  {{wireframe initialResourceID="2278E287-509B-183B-1098-2EC38DDDB7D8" initialBranchID="Master" Alignment="Center"/}}

Results in:

Balsamiq.png

Mockup

This macro id a bridge for the Confluence Balsamiq Mockup macro. It displays the image preview of the mockup, as it was migrated from Confluence.
The mockup preview is an attachment added to the parent page. For example, for a mockup identified with MyMockupID, there will be an attachment on the parent page of this form: <balsamiq/mockup>_MyMockupID[_branchID].png. This means that there should be a prefix called either mockup or balsamiq, followed by an underscore (_), then the resource identifier (MyMockupID in this case), then an arbitrary suffix (if it is set, by default it will be called Master). So, here are some filenames matching our example:

  • balsamiq_MyMockupID_Master.png
  • balsamiq_MyMockupID.png
  • mockup_MyMockupID.png

Parameters

ParameterDescription
NameThe resource ID that is part of the mockup filename attached to the current page (in the example above, it would be MyMockupID).
initialResourceIDIn case the Name parameter is not set, this is parameter will be taken into account for identifying the attachment representing the mockup preview.
initialBranchIDThe branch on which the file was stored. If it exists, by default, Confluence sets it to Master.

Example

  {{mockup initialResourceID="2278E287-509B-183B-1098-2EC38DDDB7D8" initialBranchID="Master"/}}

This means that the accepted preview filenames attached to the current page are: 

  1. balsamiq_2278E287-509B-183B-1098-2EC38DDDB7D8_Master.png
  2. mockup_2278E287-509B-183B-1098-2EC38DDDB7D8_Master.png

Filename number 1. has priority, so in case both files are attached to the current page, the first one is displayed.

It results in:

Balsamiq.png

Confluence Gallery

The Confluence Gallery macro is a bridge between Confluence and XWiki. This bridge uses the XWiki implementation of the Gallery macro under the hood and therefore assumes that the Confluence gallery macro is prefixed during import. There are a few things to note:

Only a subset of the parameters supported by the Confluence macro are supported by this bridge macro: title, exclude, include and page. The remaining parameters are ignored:

  • columns does not make sense for the XWiki macro as the images are displayed differently
  • excludeLabel and includeLabel are not supported since XWiki does not support attachment tags
  • sort and reverse have not been implemented in this bridge macro

Parameters

ParameterDescriptionRequiredDefault
titleTitle of the gallery.No 
excludeExcluded images (comma separated).No 
includeIncluded images (comma separated).No 
pagePages containing the images to display. Current page if empty.No 

Example

All images in the current page:

{{confluence_gallery/}}

Results in:

Gallery.png

Excerpt

The Excerpt macro is a bridge macro between Confluence and XWiki. It allows the user to mark part of the page's content for use by other macros. Note the Excerpt include macro is not yet available.

The macro can also be used to hide part of the content of a page.

Parameters

ParameterDescriptionDefault
atlassian-macro-output-typeThe ouput type. It can be either BLOCK or INLINE.INLINE
hiddenIf true, the content of the macro will be hidden.false

Example

Example of excerpt with HTML:
{{excerpt}}
|=Title1|=Title2|=Title3
|Text1|Text2|Text3
{{/excerpt}}

Results in:

Title1Title2Title3
Text1Text2Text3

Example of hidden excerpt:
{{excerpt hidden="true"}}
My hidden content.
{{/excerpt}}

Result in:
My hidden content.

Installation Steps

This paid extensions requires XWiki 9.11 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).

Navigate to the Extension Manager

In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.

step1.png

Install the Extension

Search for the extension you wish to install and use the Install button to install it.

step2.png

Get a License

Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.

step3.png

Install the License

If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.

However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.

Use the Extension

Start using the Extension! Refer to the extension's documentation to know how to use it.

Options

The price is per year and varies depending on the support level and the number of users.

Support / Users 10 25 50 100 250 500 1000 2500 5000 10000 20000
Silver

Benefits

What do you get when you purchase an XWiki extension?

1 year license

By purchasing an XWiki extension license, you'll benefit from it during one year.

Free updates

You benefit from all the extension updates during one year. You are always up to date.

Support included

If you are facing an issue, you can reach the XWiki support. Our team is always available to help.

How to Buy

To buy, install this extension from inside your XWiki instance and follow the instructions.

Release notes

v1.2

Update parent version to 11.10.

Extension details

This information is only displayed to Administrators. Your users can't see this tab.

License

  • GNU Lesser General Public License 2.1

Sources

Issues

Type

  • xar

Developed by

Compatibility

  • Requires XWiki 9.11 or above.

Installable with the Extension Manager

Dependencies

  • com.xwiki.licensing:application-licensing-licensor-api 1.19
  • org.xwiki.platform:xwiki-platform-office-ui 11.10
  • com.xwiki.pdfviewer:macro-pdfviewer-ui 2.2.1
  • org.xwiki.contrib:macro-jwplayer 2.1.6
  • org.xwiki.platform:xwiki-platform-rendering-wikimacro-store 11.10
Tags: XWiki Pro
XWiki SAS Copyright © 2021