Skip to Content

Register
Log-in
Search
- The Free Speech / Pro White Wiki
- Page Index
- User Index
- Global
- What's New
- Wiki Index

0.0
1
2
3
4
5

0 Votes

Changes for page MyWiki

Last modified by Ryan C on 2025/05/14 13:49

From 8.1 to 9.1 From 10.1 to 11.1

From version

edited by Ryan C
on 2025/04/28 06:25

Change comment: Rollback to version 4.1

To version

edited by Ryan C
on 2025/04/28 06:27

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

@@ -1,597 +1,329 @@
--= XWiki Macros Reference Guide {{id name="xwiki-macros-reference-guide" /}}=
++= XWiki Macros Reference Guide =
  Macros in XWiki are reusable pieces of functionality that can be integrated inside pages. They allow you to insert dynamic content or apply special formatting using a simple syntax. Below is a list of available macros (excluding deprecated or internal macros) along with their descriptions and usage examples.
--== Box Macro {{id name="box-macro" /}}==
--The **Box** macro draws a box around the content inside it:contentReference[oaicite:0]{index=0}. This is useful for highlighting important information or grouping related content in a styled panel.
++== TOC Macro ==
--**Example:** A simple box with a custom title
++The **TOC** macro generates a Table of Contents.
--**Note:** This is a sample box message.
--**Source:**
++{{example}}
++{{toc/}}
++{{/example}}
++== Box Macro ==
--{{code}}
--{{box title="Note"}} This is a sample box message. {{/box}}
--{{/code}}
++The **Box** macro draws a box around the content inside it. This is useful for highlighting important information or grouping related content in a styled panel.
--== Info Macro {{id name="info-macro" /}}==
++{{example}}
++{{box title="Note"}}
++This is a sample box message.
++{{/box}}
++{{/example}}
--The **Info** macro displays an informational message in a styled box format:contentReference[oaicite:1]{index=1}. It is typically rendered with a distinctive color (often blue) to denote general information. This macro inherits all parameters from the Box macro:contentReference[oaicite:2]{index=2} (such as the optional {{code}}title{{/code}}).
++== Info Macro ==
--**Example:** An info message box
++The **Info** macro displays an informational message in a styled box. It is typically rendered with a blue color to denote general information.
++{{example}}
++{{info}}
  This is an informational message.
--**Source:**
++{{/info}}
++{{/example}}
++{{example}}
++{{info title="FYI"}}
++This is an informational message with a title.
++{{/info}}
++{{/example}}
--{{code}}
--{{info}}This is an informational message{{/info}}
--{{/code}}
++== Warning Macro ==
--**Example (with title):** An info message with a title
++The **Warning** macro highlights a warning message in a styled box (yellow/orange background).
--**FYI:** This is an informational message.
--**Source:**
--
--
--{{code}}
--{{info title="FYI"}} This is an informational message. {{/info}}
--{{/code}}
--
--== Warning Macro {{id name="warning-macro" /}}==
--
--The **Warning** macro highlights a warning message in a styled box (usually with a yellow/orange background):contentReference[oaicite:3]{index=3}. It inherits the same optional parameters as the Box macro (like {{code}}title{{/code}}).
--
--**Example:** A warning message box
--
++{{example}}
++{{warning}}
  This is a warning message.
--**Source:**
++{{/warning}}
++{{/example}}
++== Success Macro ==
--{{code}}
--{{warning}}This is a warning message{{/warning}}
--{{/code}}
++The **Success** macro displays a success message in a green-styled box.
--== Success Macro {{id name="success-macro" /}}==
--
--The **Success** macro displays a success message in a styled box (often green) to indicate a successful action or outcome:contentReference[oaicite:4]{index=4}. Like other message macros, it supports the same parameters as the Box macro.
--
--**Example:** A success message box
--
++{{example}}
++{{success}}
  This is a success message.
--**Source:**
++{{/success}}
++{{/example}}
++== Error Macro ==
--{{code}}
--{{success}}This is a success message{{/success}}
--{{/code}}
++The **Error** macro displays a critical error or alert message in a red-styled box.
--== Error Macro {{id name="error-macro" /}}==
--
--The **Error** macro displays an error or alert message in a styled box (commonly red):contentReference[oaicite:5]{index=5}. It is used to draw attention to critical issues or errors. Like the info and warning macros, it also inherits Box macro parameters.
--
--**Example:** An error message box
--
++{{example}}
++{{error}}
  This is an error message.
--**Source:**
++{{/error}}
++{{/example}}
++== Chart Macro ==
--{{code}}
--{{error}}This is an error message{{/error}}
--{{/code}}
++The **Chart** macro generates graphical charts based on input tables.
--== Chart Macro {{id name="chart-macro" /}}==
++{{example}}
++{{chart type="pie" source="inline" params="range:B2-B4;series:columns;" width="400" height="300"}}
++|=Category|=Value|
++|A|10|
++|B|20|
++|C|30|
++{{/chart}}
++{{/example}}
--The **Chart** macro generates a graphical chart (pie, bar, line, etc.) from provided data sources:contentReference[oaicite:6]{index=6}. It can take data from an inline table or from an external source (another page, attachment, etc.), and supports various chart types through the {{code}}type{{/code}} parameter (e.g., pie, bar, line).
++{{example}}
++{{chart type="bar" source="inline" params="range:B2-C4;series:columns;" width="500" height="300"}}
++|=Quarter|=Product X|=Product Y|
++|Q1|20|15|
++|Q2|30|25|
++|Q3|25|30|
++{{/chart}}
++{{/example}}
--**Example:** An inline pie chart
++== Children Macro ==
--(This chart would show the distribution of three categories A, B, and C in a pie chart.)
++The **Children** macro lists the child pages of the current page.
--**Source:**
--
--
--{{code}}
--{{chart type="pie" source="inline" params="range:B2-B4;series:columns;" width="400" height="300"}} |=Category|=Value| |A|10| |B|20| |C|30| {{/chart}}
--{{/code}}
--
--In the above example, a pie chart is created using an inline table as the data source. The table defines one category column and one value column, and the {{code}}series:columns{{/code}} parameter instructs the macro to treat each column of values as a data series:contentReference[oaicite:7]{index=7}:contentReference[oaicite:8]{index=8}.
--
--**Example (multi-series bar chart):** An inline bar chart comparing two data series
--
--(This chart would display a bar chart with categories Q1–Q3 on the X-axis, and two series "Product X" and "Product Y" as different colored bars.)
--
--**Source:**
--
--
--{{code}}
--{{chart type="bar" source="inline" params="range:B2-C4;series:columns;" width="500" height="300"}} |=Quarter|=Product X|=Product Y| |Q1|20|15| |Q2|30|25| |Q3|25|30| {{/chart}}
--{{/code}}
--
--Here we specify a bar chart with two series. The table provides three categories (Q1, Q2, Q3) and two value columns. The macro renders a grouped bar chart with two bars per category.
--
--== Children Macro {{id name="children-macro" /}}==
--
--The **Children** macro displays a list of child pages of the current page in a tree or list format:contentReference[oaicite:9]{index=9}. It's useful for automatically listing sub-pages without manual updates.
--
--**Example:** Listing child pages
--
--*. [[Child Page 1>>#]]
--*. [[Child Page 2>>#]]
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{children/}}
--{{/code}}
++{{/example}}
--In this example, {{code}}{{children/}}{{/code}} would produce a bulleted list of links to all pages that are children of the current page.
++== Code Macro ==
--== Code Macro {{id name="code-macro" /}}==
++The **Code** macro highlights and formats source code.
--The **Code** macro formats and highlights a section of source code text. It supports many programming languages via syntax highlighting:contentReference[oaicite:10]{index=10}, which can be specified with the {{code}}language{{/code}} parameter. By default, it will attempt to detect the language if not provided:contentReference[oaicite:11]{index=11}. You can also choose to show line numbers by setting {{code}}layout="linenumbers"{{/code}}.
--
--**Example:** Highlighting a Java code snippet
--
--
--{{code}}
--// Java example public class Hello { public static void main(String[] args) { System.out.println("Hello World"); } }
++{{example}}
++{{code language="java"}}
++public class Hello {
++    public static void main(String[] args) {
++        System.out.println("Hello World");
++    }
++}
  {{/code}}
++{{/example}}
--**Source:**
++== Comment Macro ==
++The **Comment** macro hides content from page rendering.
--{{code}}
--{{code language="java"}} public class Hello { public static void main(String[] args) { System.out.println("Hello World"); } } {{/code}}
--{{/code}}
++{{example}}
++Visible part 1.
++{{comment}}This text will not be visible.{{/comment}}
++Visible part 2.
++{{/example}}
--In the rendered output, the code would be syntax-colored for Java. If you wanted to add line numbers to the code block, you could use {{code}}layout="linenumbers"{{/code}}, for example:
++== Container Macro ==
++The **Container** macro creates multi-column layouts.
--{{code}}
--{{code language="java" layout="linenumbers"}} ... code ... {{/code}}
--{{/code}}
++{{example}}
++{{container layoutStyle="columns"}}
++(((**Column 1:** This is the first column.)))
++(((**Column 2:** This is the second column.)))
++{{/container}}
++{{/example}}
--== Comment Macro {{id name="comment-macro" /}}==
++== Dashboard Macro ==
--The **Comment** macro allows putting comments in the wiki source that will not be displayed in the page output:contentReference[oaicite:12]{index=12}. It's useful for leaving notes or temporarily hiding content. The content inside the comment macro is completely omitted when rendering the page.
++The **Dashboard** macro creates areas for gadgets.
--**Example:** Using a comment to hide content
--
--Visible part 1. Visible part 2.
--**Source:**
--
--
--{{code}}
--Visible part 1. {{comment}}This text will not be visible{{/comment}} Visible part 2.
--{{/code}}
--
--In the above example, the text inside the {{code}}{{comment}}{{/code}} macro ("This text will not be visible") is omitted from the output, so the two visible parts appear consecutively as if the commented text wasn’t there.
--
--== Container Macro {{id name="container-macro" /}}==
--
--The **Container** macro groups content and applies a layout to it (such as arranging content in columns):contentReference[oaicite:13]{index=13}:contentReference[oaicite:14]{index=14}. By default, it can implement a {{code}}columns{{/code}} layout (responsive, side-by-side columns) via {{code}}layoutStyle="columns"{{/code}}:contentReference[oaicite:15]{index=15}. Content for each column is separated by wiki group markers {{code}}(((...))){{/code}} inside the macro.
--
--**Example:** Two-column layout
--
--|= |=
--|**Column 1:** This is the content of the first column. |**Column 2:** This is the content of the second column.
--
--**Source:**
--
--
--{{code}}
--{{container layoutStyle="columns"}} (((**Column 1:** This is the content of the first column.))) (((**Column 2:** This is the content of the second column.))) {{/container}}
--{{/code}}
--
--The above will render two columns of content. The container is responsive, so on a narrow screen the columns would stack vertically:contentReference[oaicite:16]{index=16}. The triple parentheses {{code}}((...)){{/code}} are used to delineate each column’s content within the container macro.
--
--== Dashboard Macro {{id name="dashboard-macro" /}}==
--
--The **Dashboard** macro defines a dashboard area into which you can add gadgets:contentReference[oaicite:17]{index=17}. It's commonly used on overview pages to lay out multiple gadgets in columns. The macro can take a {{code}}columns{{/code}} parameter to specify the number of gadget columns.
--
--**Example:** A dashboard with 2 columns
--
--//(Gadget area 1)//
--//(Gadget area 2)//
--**Source:**
--
--
--{{code}}
++{{example}}
  {{dashboard columns="2"/}}
--{{/code}}
++{{/example}}
--In practice, you would add gadgets (such as activity streams, charts, etc.) to the dashboard through the UI. The macro itself mainly sets up the layout for those gadgets.
++== Display Macro ==
--== Display Macro {{id name="display-macro" /}}==
++The **Display** macro embeds content from another page.
--The **Display** macro includes the rendered content of another page into the current page:contentReference[oaicite:18]{index=18}. Unlike the Include macro, it inserts the output as if viewing that page, preserving its internal links and references:contentReference[oaicite:19]{index=19}. Use this when you want to embed a page's content exactly as it appears on its own.
--
--**Example:** Display another page’s content
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{display page="Help.Macros"/}}
--{{/code}}
++{{/example}}
--This will insert the rendered content of the //Help.Macros// page at this location. All headings, images, and links from that page will appear as they do on the original page.
++== DisplayIcon Macro ==
--== DisplayIcon Macro {{id name="displayicon-macro" /}}==
++The **DisplayIcon** macro displays an icon.
--The **DisplayIcon** macro inserts an icon from the XWiki icon set into the page:contentReference[oaicite:20]{index=20}. You specify the icon by its name (and optionally the icon set if different from the default).
--
--**Example:** Inserting a “home” icon
--
--🏠 Home
--**Source:**
--
--
--{{code}}
++{{example}}
  {{displayIcon name="home"/}} Home
--{{/code}}
++{{/example}}
--In this example, the macro {{code}}{{displayIcon name="home"/}}{{/code}} outputs a home icon (the little house symbol before the word "Home"). You can change the {{code}}name{{/code}} to any available icon name in your wiki’s icon theme (for example, {{code}}user{{/code}}, {{code}}document{{/code}}, etc.).
++== Documents Macro ==
--== Documents Macro {{id name="documents-macro" /}}==
++The **Documents** macro shows a livetable of documents.
--The **Documents** macro displays a list of pages in a livetable (a dynamic, filterable table of results):contentReference[oaicite:21]{index=21}. By default it can show all pages, but you can filter to a specific space or other criteria using parameters.
--
--**Example:** Listing all pages in a space
--
--|=Page |=Modified
--|[[Page1>>#]] |2025/04/15
--|[[Page2>>#]] |2025/04/10
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{documents space="MySpace"/}}
--{{/code}}
++{{/example}}
--This will create a livetable listing all pages in the //MySpace// space, with columns such as page name and last modified date. The table allows sorting and filtering (as it’s a livetable). If you omit the {{code}}space{{/code}} parameter, the macro might list pages from the whole wiki (use with caution on large wikis).
++== DocumentTree Macro ==
--== DocumentTree Macro {{id name="documenttree-macro" /}}==
++The **DocumentTree** macro shows a collapsible page tree.
--The **DocumentTree** macro displays a collapsible tree of pages:contentReference[oaicite:22]{index=22}. It’s often used for navigation menus or page indexes. By default, it shows the page hierarchy of the current wiki, but you can specify a different root.
--
--**Example:** Page tree starting from a given page
--
--*. **Help (space)**
--**. Getting Started
--**. Macros
--***. Examples
--***. Reference
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{documentTree reference="Help.WebHome"/}}
--{{/code}}
++{{/example}}
--In the above example, the tree would start at the //Help// space’s home page and display its descendants. The user can expand/collapse branches. If no reference is specified, the macro may display the entire wiki’s page structure by default.
++== Footnote Macro ==
--== Footnote Macro {{id name="footnote-macro" /}}==
++The **Footnote** macro adds footnotes to the page.
--The **Footnote** macro inserts a footnote marker and text that will be collected and displayed at the bottom of the page:contentReference[oaicite:23]{index=23} (or at the position of a {{code}}putFootnotes{{/code}} macro). Each footnote will be automatically numbered.
++{{example}}
++This is a statement{{footnote}}Source: Example Reference{{/footnote}}.
++{{putFootnotes/}}
++{{/example}}
--**Example:** Adding a footnote to a sentence
++== PutFootnotes Macro ==
--This is a statement^^[1]^^ with a reference.\\[1] Source: Example Reference
--**Source:**
++The **PutFootnotes** macro outputs collected footnotes.
++{{example}}
++...page content...
++{{putFootnotes/}}
++{{/example}}
--{{code}}
--This is a statement{{footnote}}Source: Example Reference{{/footnote}} with a reference. {{putFootnotes/}}
--{{/code}}
++== Gallery Macro ==
--In the above example, the text inside {{code}}{{footnote}}{{/code}} (“Source: Example Reference”) will appear as a numbered footnote at the bottom of the page. The {{code}}{{putFootnotes/}}{{/code}} macro (used here at the end) outputs the collected footnotes. If {{code}}putFootnotes{{/code}} is not explicitly used, all footnotes are automatically shown at the end of the page by default:contentReference[oaicite:24]{index=24}.
++The **Gallery** macro displays a collection of images.
--== PutFootnotes Macro {{id name="putfootnotes-macro" /}}==
++{{example}}
++{{gallery}}
++image:Space.Page@Image1.png
++image:Space.Page@Image2.png
++{{/gallery}}
++{{/example}}
--The **PutFootnotes** macro outputs all accumulated footnotes in the page at the location where it is placed:contentReference[oaicite:25]{index=25}. If this macro is not used, footnotes will appear automatically at the very end of the page by default.
++== Groovy Macro ==
--**Example:** Placing footnotes at a custom location
++The **Groovy** macro executes Groovy scripts.
--**Source:**
++{{example}}
++{{groovy}}
++println("Hello from Groovy!")
++{{/groovy}}
++{{/example}}
++== HTML Macro ==
--{{code}}
--... page content ... {{putFootnotes/}}
--{{/code}}
++The **HTML** macro embeds raw HTML into pages.
--Typically, you would put {{code}}{{putFootnotes/}}{{/code}} at the bottom of your content (or wherever you want the footnotes to appear). It will generate a list of all footnotes added via the {{code}}{{footnote}}{{/code}} macro in the text.
++{{example}}
++{{html}}
++<p style="color:red;">This is red text via HTML.</p>
++{{/html}}
++{{/example}}
--== Gallery Macro {{id name="gallery-macro" /}}==
++== Id Macro ==
--The **Gallery** macro displays a collection of images as a gallery or slide-show view:contentReference[oaicite:26]{index=26}. You supply the images in the macro content (as image references or attachments), and the macro will present them with navigation controls.
++The **Id** macro defines an internal link anchor.
--**Example:** A simple image gallery
++{{example}}
++Click [[here>>#myanchor]] to jump.
--[[image:https://www.xwiki.org/logo.png||alt="Image1"]] [[image:https://www.xwiki.org/logo.png||alt="Image2"]]
--(Images displayed in a gallery with navigation controls)
++{{id name="myanchor"/}}
++**Target Location:** You have reached the target.
++{{/example}}
--**Source:**
++== Include Macro ==
++The **Include** macro includes another page's content.
--{{code}}
--{{gallery}} image:Space.Page@Image1.png image:Space.Page@Image2.png {{/gallery}}
--{{/code}}
--
--In this example, two images (Image1.png and Image2.png from //Space.Page//) will be displayed in a gallery. In view mode, the gallery macro would show the first image with controls to navigate to the next image, or it might display thumbnails of both depending on configuration. You can include images from attachments (using {{code}}image:Page@file{{/code}} syntax) or external images (using {{code}}image:http://...{{/code}}).
--
--== Groovy Macro {{id name="groovy-macro" /}}==
--
--The **Groovy** macro executes a Groovy script on the server side:contentReference[oaicite:27]{index=27}. This macro requires programming rights on the wiki, as it can perform advanced operations. It’s often used to manipulate or retrieve data and then output results in the page.
--
--**Example:** A simple Groovy script printing a message
--
--{{code}}Hello from Groovy!{{/code}}
--**Source:**
--
--
--{{code}}
--{{groovy}} println("Hello from Groovy!"); {{/groovy}}
--{{/code}}
--
--**Example:** Using Groovy to access XWiki API
--
--{{code}}This page is: {{/code}}//{{code}}Sample.Page{{/code}}//
--**Source:**
--
--
--{{code}}
--{{groovy}} def doc = xcontext.getDoc(); println("This page is: " + doc.getFullName()); {{/groovy}}
--{{/code}}
--
--In the second example, the Groovy script obtains the current document and prints its full name. Groovy scripts can use XWiki's API (via {{code}}xwiki{{/code}}, {{code}}xcontext{{/code}}, etc.) to interact with the wiki.
--
--== HTML Macro {{id name="html-macro" /}}==
--
--The **HTML** macro allows inserting raw HTML or XHTML content directly into a wiki page:contentReference[oaicite:28]{index=28}. This is useful for embedding external widgets or custom HTML that the wiki syntax doesn’t support. (Using this macro may require programming rights to avoid security risks such as XSS.)
--
--**Example:** Inserting a custom HTML snippet
--
--This is red text via HTML.
--**Source:**
--
--
--{{code}}
--{{html}} This is red text via HTML. {{/html}}
--{{/code}}
--
--**Example:** Embedding an iframe (e.g., a YouTube video)
--
--
--**Source:**
--
--
--{{code}}
--{{html}}  {{/html}}
--{{/code}}
--
--In the above, the HTML macro is used to embed a video player by directly writing an {{code}}<iframe>{{/code}} tag. The wiki will include that HTML as-is in the rendered page.
--
--== Id Macro {{id name="id-macro" /}}==
--
--The **Id** macro defines an anchor in the page that you can link to:contentReference[oaicite:29]{index=29}. It is similar to an HTML anchor {{code}}<a id="..."></a>{{/code}}. This is helpful for creating link targets (for example, for internal page navigation).
--
--**Example:** Creating and linking to an anchor
--
--Click [[here>>#myanchor]] to jump. ...\\{{id name="myanchor" /}}**Target Location:** You have reached the target.
--**Source:**
--
--
--{{code}}
--Click [[here>>#myanchor]] to jump. ... {{id name="myanchor"/}}**Target Location:** You have reached the target.
--{{/code}}
--
--In this example, the {{code}}{{id name="myanchor"/}}{{/code}} macro defines an anchor named "myanchor" right before the "Target Location" text. The link {{code}}[[here>>#myanchor]]{{/code}} will scroll to that location when clicked.
--
--== Include Macro {{id name="include-macro" /}}==
--
--The **Include** macro includes the content of another wiki page into the current page, as if it were written here:contentReference[oaicite:30]{index=30}. By default, it acts as if the included content is part of the current page (e.g., relative links in the included content won’t resolve to the original page):contentReference[oaicite:31]{index=31}.
--
--**Example:** Including a page
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{include page="Help.Introduction"/}}
--{{/code}}
++{{/example}}
--This will insert the content of the //Help.Introduction// page in-line. If that page has section anchors or relative image links, they might need special handling because the included content is merged into the current page context. If you want to include the fully rendered page instead, consider using the {{code}}display{{/code}} macro.
++== Mention Macro ==
--**Example:** Including a specific section of a page
++The **Mention** macro notifies a mentioned user.
--**Source:**
--
--
--{{code}}
--{{include page="Help.Macros" section="HExamples"/}}
--{{/code}}
--
--Here only the section of //Help.Macros// with the heading "Examples" (and its subcontent) will be included. The {{code}}section{{/code}} parameter uses the anchor name of the heading (XWiki automatically generates anchor IDs like {{code}}HHeadingName{{/code}} for each heading).
--
--== Mention Macro {{id name="mention-macro" /}}==
--
--The **Mention** macro allows you to mention a user in content, similar to an @-mention on social platforms. It will typically display the user’s name and trigger a notification to that user.
--
--**Example:** Mentioning a user
--
--@John Doe
--**Source:**
--
--
--{{code}}
++{{example}}
  {{mention user="xwiki:JohnDoe"/}}
--{{/code}}
++{{/example}}
--In the example, {{code}}{{mention user="xwiki:JohnDoe"/}}{{/code}} would produce an @-mention for the user with the username //JohnDoe// (on the //xwiki// wiki). The exact syntax for the user reference may include the wiki and space depending on your configuration. When rendered, it shows the user's name (or profile link), and the user would get a notification that they were mentioned.
++== Notifications Macro ==
--== Notifications Macro {{id name="notifications-macro" /}}==
++The **Notifications** macro displays recent activity.
--The **Notifications** macro displays a feed of recent events (like edits, comments, etc.) on the wiki:contentReference[oaicite:32]{index=32}. This is usually what you see in the "Activity" or "Notifications" panel on the dashboard. It respects the current user's notification preferences and permissions.
--
--**Example:** Showing recent wiki notifications
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{notifications/}}
--{{/code}}
++{{/example}}
--Using {{code}}{{notifications/}}{{/code}} will embed a live notifications feed. Users will see a list of recent events with options to filter or mark as read, similar to the main Notifications panel.
++== Office Macro ==
--== Office Macro {{id name="office-macro" /}}==
++The **Office** macro displays Office documents.
--The **Office** macro displays an office document (such as a Word, Excel, or PowerPoint file) directly within a wiki page:contentReference[oaicite:33]{index=33}. The document must be attached to the wiki (or accessible via a reference). The macro will render the content (for example, using an Office viewer or PDF conversion) so users can read it without downloading.
--
--**Example:** Embedding an attached Word document
--
--**Source:**
--
--
--{{code}}
++{{example}}
  {{office attachment="Main.UserGuide@Guide.docx"/}}
--{{/code}}
++{{/example}}
--This will display the //Guide.docx// file attached to the //Main.UserGuide// page. The content of the document will be shown (users can scroll through the pages of the document on the wiki page). Supported file formats include Word documents (.doc/.docx), Excel spreadsheets, PowerPoint presentations, OpenOffice/LibreOffice formats (odt, ods, odp), etc.:contentReference[oaicite:34]{index=34}.
++== Python Macro ==
--== Python Macro {{id name="python-macro" /}}==
++The **Python** macro executes Python scripts.
--The **Python** macro executes a Python script on the server side:contentReference[oaicite:35]{index=35}. This requires a Python scripting engine to be installed (such as Jython). Like the Groovy macro, it needs programming rights and can interact with the XWiki API.
++{{example}}
++{{python}}
++print("Hello from Python!")
++{{/python}}
++{{/example}}
--**Example:** A simple Python script
++== Script Macro ==
--{{code}}Hello from Python!{{/code}}
--**Source:**
++The **Script** macro executes scripts in different languages.
++{{example}}
++{{script language="velocity"}}
++#set($name = "Velocity")
++Hello $name!
++{{/script}}
++{{/example}}
--{{code}}
--{{python}} print("Hello from Python!") {{/python}}
--{{/code}}
++== Tag Cloud Macro ==
--If the Python macro is enabled and a Python engine is available, the above would output “Hello from Python!”. You can use the XWiki Python API (similar to the Groovy example) to work with the wiki's content within the script.
++The **Tag Cloud** macro displays tags visually.
--== Script Macro {{id name="script-macro" /}}==
--
--The **Script** macro executes a script in a specified scripting language:contentReference[oaicite:36]{index=36}. It is a generic container for different script types (Velocity, Groovy, Python, etc.) controlled by the {{code}}language{{/code}} parameter.
--
--**Example:** Using the Script macro for a Velocity script
--
--{{code}}Hello Velocity!{{/code}}
--**Source:**
--
--
--{{code}}
--{{script language="velocity"}} #set($name = "Velocity") Hello $name! {{/script}}
--{{/code}}
--
--This does the same as writing a Velocity macro block. The Script macro is handy when you want to dynamically choose the language or when including code from an external source using its {{code}}source{{/code}} parameter (for instance, {{code}}{{script language="groovy" source="document:Space.Page"/}}{{/code}} to run a Groovy script from another page). In most cases, using the dedicated language macro (like {{code}}{{velocity}}{{/code}} or {{code}}{{groovy}}{{/code}}) is simpler.
--
--== Tag Cloud Macro {{id name="tag-cloud-macro" /}}==
--
--The **Tag Cloud** macro shows a cloud of tags, where the size of each tag indicates its frequency in the wiki (or in a specific space):contentReference[oaicite:37]{index=37}. This provides a visual overview of popular tags.
--
--**Example:** Tag cloud for the whole wiki
--
--tag1 tag2 tag3 ...
--**Source:**
--
--
--{{code}}
++{{example}}
  {{tagcloud/}}
--{{/code}}
++{{/example}}
--This will display a tag cloud of all tags in the wiki. To limit to a specific space, use the {{code}}space{{/code}} parameter. For example, {{code}}{{tagcloud space="Blog"/}}{{/code}} would show tags just from pages in the Blog space.
++== User Avatar Macro ==
--== Table of Contents (TOC) Macro {{id name="table-of-contents-toc-macro" /}}==
++The **User Avatar** macro shows a user's avatar image.
--The **TOC** macro generates a table of contents for the headings in the page:contentReference[oaicite:38]{index=38}. It is often used at the top of a page to list its sections. You can customize it with parameters like {{code}}start{{/code}} level, {{code}}depth{{/code}}, and whether to number the headings.
++{{example}}
++{{useravatar user="xwiki:JohnDoe"/}}
++{{/example}}
--**Example:** Basic TOC
++== Velocity Macro ==
--*. Introduction
--*. Details
--**. Subsection
--*. Conclusion
++The **Velocity** macro executes Velocity scripts.
--**Source:**
++{{example}}
++{{velocity}}
++#set($name = "Alice")
++Hello $name!
++{{/velocity}}
++{{/example}}
++== Menu Macro ==
--{{code}}
--{{toc/}}
--{{/code}}
++The **Menu** macro builds a navigation menu.
--This will insert a table of contents listing all headings in the page.
++{{example}}
++{{menu}}
++* [[Home>>Main.WebHome]]
++* [[Products>>Main.Products]]
++** [[Product A>>Main.Products.ProductA]]
++** [[Product B>>Main.Products.ProductB]]
++* [[Contact>>Main.Contact]]
++{{/menu}}
++{{/example}}
--**Example:** TOC starting from level 2 headings
--**Source:**
--
--
--{{code}}
--{{toc start="2" numbered="true"/}}
--{{/code}}
--
--In this second example, the TOC will skip level 1 headings and start at level 2, and the entries will be numbered. For instance, a level 2 heading will be labeled “1.”, its level 3 subheading “1.1”, and so on.
--
--== User Avatar Macro {{id name="user-avatar-macro" /}}==
--
--The **UserAvatar** macro displays the avatar image of a specified user:contentReference[oaicite:39]{index=39}. You can use this to show user pictures in pages (for example, in comments or user listings).
--
--**Example:** Showing a user's avatar
--
--[[image:https://www.xwiki.org/xwiki/bin/download/Static/Icons/user.png||alt="Avatar"]] John Doe
--**Source:**
--
--
--{{code}}
--{{useravatar user="xwiki:JohnDoe"/}} John Doe
--{{/code}}
--
--In this example, {{code}}{{useravatar user="xwiki:JohnDoe"/}}{{/code}} would display the profile avatar of the user //JohnDoe// (with a default icon if the user hasn’t set one). You can adjust the size via parameters if needed (e.g., {{code}}size="large"{{/code}} for a larger avatar), depending on the macro's implementation.
--
--== Velocity Macro {{id name="velocity-macro" /}}==
--
--The **Velocity** macro executes a Velocity script on the server side:contentReference[oaicite:40]{index=40}. Velocity is the default scripting language for XWiki and can be used without explicitly using this macro (since wiki pages themselves can contain Velocity code enclosed in {{code}}{{velocity}}{{/code}}... by default if allowed). However, using the macro explicitly can control scope and avoid interference with other syntax.
--
--**Example:** A simple Velocity script
--
--{{code}}Hello Alice!{{/code}}
--**Source:**
--
--
--{{code}}
--{{velocity}} #set($name = "Alice") Hello $name! {{/velocity}}
--{{/code}}
--
--This will output “Hello Alice!”. In Velocity, variables are defined with {{code}}#set{{/code}} and referenced with {{code}}${{/code}}. Velocity has access to many predefined variables (like {{code}}$doc{{/code}} for the current document, {{code}}$services{{/code}}, etc.) in XWiki’s context.
--
--== Menu Macro {{id name="menu-macro" /}}==
--
--The **Menu** macro can generate a navigation menu from a nested list of links. You provide the menu structure in wiki syntax (using nested bullet points) inside the macro, and it will render it as a styled menu.
--
--**Example:** Simple menu
--
--*. [[Home>>#]]
--*. [[Products>>#]]
--**. [[Product A>>#]]
--**. [[Product B>>#]]
--*. [[Contact>>#]]
--
--**Source:**
--
--
--{{code}}
--{{menu}} * [[Home>>Main.WebHome]] * [[Products>>Main.Products]] ** [[Product A>>Main.Products.ProductA]] ** [[Product B>>Main.Products.ProductB]] * [[Contact>>Main.Contact]] {{/menu}}
--{{/code}}