0 Votes

Changes for page MyWiki

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

From 9.1 to 8.1 From 11.1 to 10.1

From version

10.1

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

Change comment: There is no comment for this version

To version

9.1

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

Change comment: Rollback to version 4.1

Raw
Rendered

Summary

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

Details

Page properties

Content

@@ -1,329 +1,597 @@
--= XWiki Macros Reference Guide =
++= XWiki Macros Reference Guide {{id name="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" /}}==
--== TOC 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.
--The **TOC** macro generates a Table of Contents.
++**Example:** A simple box with a custom title
--{{example}}
--{{toc/}}
--{{/example}}
++**Note:** This is a sample box message.
++**Source:**
--== Box Macro ==
--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.
++{{code}}
++{{box title="Note"}} This is a sample box message. {{/box}}
++{{/code}}
--{{example}}
--{{box title="Note"}}
--This is a sample box message.
--{{/box}}
--{{/example}}
++== Info Macro {{id name="info-macro" /}}==
--== Info Macro ==
++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}}).
--The **Info** macro displays an informational message in a styled box. It is typically rendered with a blue color to denote general information.
++**Example:** An info message box
--{{example}}
--{{info}}
  This is an informational message.
--{{/info}}
--{{/example}}
++**Source:**
--{{example}}
--{{info title="FYI"}}
--This is an informational message with a title.
--{{/info}}
--{{/example}}
--== Warning Macro ==
++{{code}}
++{{info}}This is an informational message{{/info}}
++{{/code}}
--The **Warning** macro highlights a warning message in a styled box (yellow/orange background).
++**Example (with title):** An info message with a title
--{{example}}
--{{warning}}
++**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
++
  This is a warning message.
--{{/warning}}
--{{/example}}
++**Source:**
--== Success Macro ==
--The **Success** macro displays a success message in a green-styled box.
++{{code}}
++{{warning}}This is a warning message{{/warning}}
++{{/code}}
--{{example}}
--{{success}}
++== 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
++
  This is a success message.
--{{/success}}
--{{/example}}
++**Source:**
--== Error Macro ==
--The **Error** macro displays a critical error or alert message in a red-styled box.
++{{code}}
++{{success}}This is a success message{{/success}}
++{{/code}}
--{{example}}
--{{error}}
++== 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
++
  This is an error message.
--{{/error}}
--{{/example}}
++**Source:**
--== Chart Macro ==
--The **Chart** macro generates graphical charts based on input tables.
++{{code}}
++{{error}}This is an error message{{/error}}
++{{/code}}
--{{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}}
++== Chart Macro {{id name="chart-macro" /}}==
--{{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}}
++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).
--== Children Macro ==
++**Example:** An inline pie chart
--The **Children** macro lists the child pages of the current page.
++(This chart would show the distribution of three categories A, B, and C in a pie chart.)
--{{example}}
++**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}}
  {{children/}}
--{{/example}}
++{{/code}}
--== Code Macro ==
++In this example, {{code}}{{children/}}{{/code}} would produce a bulleted list of links to all pages that are children of the current page.
--The **Code** macro highlights and formats source code.
++== Code Macro {{id name="code-macro" /}}==
--{{example}}
--{{code language="java"}}
--public class Hello {
--    public static void main(String[] args) {
--        System.out.println("Hello World");
--    }
--}
++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"); } }
  {{/code}}
--{{/example}}
--== Comment Macro ==
++**Source:**
--The **Comment** macro hides content from page rendering.
--{{example}}
--Visible part 1.
--{{comment}}This text will not be visible.{{/comment}}
--Visible part 2.
--{{/example}}
++{{code}}
++{{code language="java"}} public class Hello { public static void main(String[] args) { System.out.println("Hello World"); } } {{/code}}
++{{/code}}
--== Container Macro ==
++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:
--The **Container** macro creates multi-column layouts.
--{{example}}
--{{container layoutStyle="columns"}}
--(((**Column 1:** This is the first column.)))
--(((**Column 2:** This is the second column.)))
--{{/container}}
--{{/example}}
++{{code}}
++{{code language="java" layout="linenumbers"}} ... code ... {{/code}}
++{{/code}}
--== Dashboard Macro ==
++== Comment Macro {{id name="comment-macro" /}}==
--The **Dashboard** macro creates areas for gadgets.
++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.
--{{example}}
++**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}}
  {{dashboard columns="2"/}}
--{{/example}}
++{{/code}}
--== Display Macro ==
++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.
--The **Display** macro embeds content from another page.
++== Display Macro {{id name="display-macro" /}}==
--{{example}}
++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}}
  {{display page="Help.Macros"/}}
--{{/example}}
++{{/code}}
--== DisplayIcon Macro ==
++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.
--The **DisplayIcon** macro displays an icon.
++== DisplayIcon Macro {{id name="displayicon-macro" /}}==
--{{example}}
++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}}
  {{displayIcon name="home"/}} Home
--{{/example}}
++{{/code}}
--== Documents Macro ==
++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.).
--The **Documents** macro shows a livetable of documents.
++== Documents Macro {{id name="documents-macro" /}}==
--{{example}}
++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}}
  {{documents space="MySpace"/}}
--{{/example}}
++{{/code}}
--== DocumentTree Macro ==
++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).
--The **DocumentTree** macro shows a collapsible page tree.
++== DocumentTree Macro {{id name="documenttree-macro" /}}==
--{{example}}
++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}}
  {{documentTree reference="Help.WebHome"/}}
--{{/example}}
++{{/code}}
--== Footnote Macro ==
++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.
--The **Footnote** macro adds footnotes to the page.
++== Footnote Macro {{id name="footnote-macro" /}}==
--{{example}}
--This is a statement{{footnote}}Source: Example Reference{{/footnote}}.
--{{putFootnotes/}}
--{{/example}}
++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.
--== PutFootnotes Macro ==
++**Example:** Adding a footnote to a sentence
--The **PutFootnotes** macro outputs collected footnotes.
++This is a statement^^[1]^^ with a reference.\\[1] Source: Example Reference
++**Source:**
--{{example}}
--...page content...
--{{putFootnotes/}}
--{{/example}}
--== Gallery Macro ==
++{{code}}
++This is a statement{{footnote}}Source: Example Reference{{/footnote}} with a reference. {{putFootnotes/}}
++{{/code}}
--The **Gallery** macro displays a collection of images.
++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}.
--{{example}}
--{{gallery}}
--image:Space.Page@Image1.png
--image:Space.Page@Image2.png
--{{/gallery}}
--{{/example}}
++== PutFootnotes Macro {{id name="putfootnotes-macro" /}}==
--== Groovy Macro ==
++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.
--The **Groovy** macro executes Groovy scripts.
++**Example:** Placing footnotes at a custom location
--{{example}}
--{{groovy}}
--println("Hello from Groovy!")
--{{/groovy}}
--{{/example}}
++**Source:**
--== HTML Macro ==
--The **HTML** macro embeds raw HTML into pages.
++{{code}}
++... page content ... {{putFootnotes/}}
++{{/code}}
--{{example}}
--{{html}}
--<p style="color:red;">This is red text via HTML.</p>
--{{/html}}
--{{/example}}
++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.
--== Id Macro ==
++== Gallery Macro {{id name="gallery-macro" /}}==
--The **Id** macro defines an internal link anchor.
++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.
--{{example}}
--Click [[here>>#myanchor]] to jump.
++**Example:** A simple image gallery
--{{id name="myanchor"/}}
--**Target Location:** You have reached the target.
--{{/example}}
++[[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)
--== Include Macro ==
++**Source:**
--The **Include** macro includes another page's content.
--{{example}}
++{{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}}
  {{include page="Help.Introduction"/}}
--{{/example}}
++{{/code}}
--== Mention Macro ==
++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.
--The **Mention** macro notifies a mentioned user.
++**Example:** Including a specific section of a page
--{{example}}
++**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}}
  {{mention user="xwiki:JohnDoe"/}}
--{{/example}}
++{{/code}}
--== Notifications Macro ==
++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.
--The **Notifications** macro displays recent activity.
++== Notifications Macro {{id name="notifications-macro" /}}==
--{{example}}
++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}}
  {{notifications/}}
--{{/example}}
++{{/code}}
--== Office Macro ==
++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.
--The **Office** macro displays Office documents.
++== Office Macro {{id name="office-macro" /}}==
--{{example}}
++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}}
  {{office attachment="Main.UserGuide@Guide.docx"/}}
--{{/example}}
++{{/code}}
--== Python Macro ==
++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}.
--The **Python** macro executes Python scripts.
++== Python Macro {{id name="python-macro" /}}==
--{{example}}
--{{python}}
--print("Hello from Python!")
--{{/python}}
--{{/example}}
++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.
--== Script Macro ==
++**Example:** A simple Python script
--The **Script** macro executes scripts in different languages.
++{{code}}Hello from Python!{{/code}}
++**Source:**
--{{example}}
--{{script language="velocity"}}
--#set($name = "Velocity")
--Hello $name!
--{{/script}}
--{{/example}}
--== Tag Cloud Macro ==
++{{code}}
++{{python}} print("Hello from Python!") {{/python}}
++{{/code}}
--The **Tag Cloud** macro displays tags visually.
++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.
--{{example}}
++== 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}}
  {{tagcloud/}}
--{{/example}}
++{{/code}}
--== User Avatar Macro ==
++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.
--The **User Avatar** macro shows a user's avatar image.
++== Table of Contents (TOC) Macro {{id name="table-of-contents-toc-macro" /}}==
--{{example}}
--{{useravatar user="xwiki:JohnDoe"/}}
--{{/example}}
++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.
--== Velocity Macro ==
++**Example:** Basic TOC
--The **Velocity** macro executes Velocity scripts.
++*. Introduction
++*. Details
++**. Subsection
++*. Conclusion
--{{example}}
--{{velocity}}
--#set($name = "Alice")
--Hello $name!
--{{/velocity}}
--{{/example}}
++**Source:**
--== Menu Macro ==
--The **Menu** macro builds a navigation menu.
++{{code}}
++{{toc/}}
++{{/code}}
--{{example}}
--{{menu}}
--* [[Home>>Main.WebHome]]
--* [[Products>>Main.Products]]
--** [[Product A>>Main.Products.ProductA]]
--** [[Product B>>Main.Products.ProductB]]
--* [[Contact>>Main.Contact]]
--{{/menu}}
--{{/example}}
++This will insert a table of contents listing all headings in the page.
++**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}}