# Wiki source code of XWiki Syntax Guide

Last modified by Richard Johnson on 2020/08/21 14:41
Export
Office Formats
Export as PDF
Other Formats
Export as HTML

Show last authors

author | version | line-number | content
--- | --- | --- | ---
|  | 1 | {{velocity output="false"}}
|  | 2 | #set($SUPPORTED_SYNTAXES = {})
|  | 3 | #set($void = $SUPPORTED_SYNTAXES.put('1.0', 'XWiki Syntax 1.0'))
|  | 4 | #set($void = $SUPPORTED_SYNTAXES.put('2.0', 'XWiki Syntax 2.0'))
|  | 5 | #set($void = $SUPPORTED_SYNTAXES.put('2.1', 'XWiki Syntax 2.1'))
|  | 6 | ##
|  | 7 | ## needed for sections that contain descriptions valid for several syntaxes
|  | 8 | ## basically it is hack to reuse the 2.0 descriptions for 2.1
|  | 9 | #set($SUPPORTED_SYNTAX_ORDER = ['1.0', '2.0', '2.1'])
|  | 10 | ##
|  | 11 | ## filter all syntaxes that are not installed/configured
|  | 12 | #set($configuredSyntaxes = $services.rendering.getConfiguredSyntaxes())
|  | 13 | #set($enabledSyntaxIds = [])
|  | 14 | #foreach($syntax in $configuredSyntaxes)
|  | 15 | #set($discard = $enabledSyntaxIds.add($syntax.toIdString()))
|  | 16 | #end
|  | 17 | #set($unavailableSyntaxes=[])
|  | 18 | #foreach($supportedSyntax in $SUPPORTED_SYNTAX_ORDER)
|  | 19 | #set($fullSyntaxId = "xwiki/$supportedSyntax")
|  | 20 | #if(!$enabledSyntaxIds.contains($fullSyntaxId))
|  | 21 | #set($discard = $unavailableSyntaxes.add($supportedSyntax))
|  | 22 | #end
|  | 23 | #end
|  | 24 | #foreach($unavailableSyntax in $unavailableSyntaxes)
|  | 25 | #set($discard = $SUPPORTED_SYNTAX_ORDER.remove($unavailableSyntax))
|  | 26 | #set($discard = $SUPPORTED_SYNTAXES.removeKey($unavailableSyntax))
|  | 27 | #end
|  | 28 |
|  | 29 | #if ($request.xaction == 'switchContext')
|  | 30 | $response.sendRedirect($request.target)
|  | 31 | #stop
|  | 32 | #end
|  | 33 |
|  | 34 | #set ($crtCategoryId = "$!{request.category}")
|  | 35 | #if ($crtCategoryId != '')
|  | 36 | #set ($crtCategoryId = $numbertool.toNumber($crtCategoryId).intValue())
|  | 37 | #end
|  | 38 | #set ($crtSectionId = "$!{request.section}")
|  | 39 | #set ($crtSyntaxVer = "$!{request.syntax}")
|  | 40 | #if (!$SUPPORTED_SYNTAXES.containsKey($crtSyntaxVer))
|  | 41 | ## Default to the most current one (if we have any)
|  | 42 | #if(!$SUPPORTED_SYNTAX_ORDER.isEmpty())
|  | 43 | #set ($crtSyntaxVer = $SUPPORTED_SYNTAX_ORDER.get($mathtool.sub($SUPPORTED_SYNTAX_ORDER.size(),1)))
|  | 44 | #end
|  | 45 | #end
|  | 46 | #set($crtSyntaxPos = $SUPPORTED_SYNTAX_ORDER.indexOf($crtSyntaxVer))
|  | 47 |
|  | 48 | #set ($extraParamList = [])
|  | 49 | #if ($request.language)
|  | 50 | #set ($discard = $extraParamList.add("language=$escapetool.url($request.language)"))
|  | 51 | #end
|  | 52 | #if ($request.xpage)
|  | 53 | #set ($discard = $extraParamList.add("xpage=$escapetool.url($request.xpage)"))
|  | 54 | #end
|  | 55 | #if ($extraParamList.isEmpty())
|  | 56 | #set ($extraParams = '')
|  | 57 | #else
|  | 58 | #set ($extraParams = '&'+$stringtool.join($extraParamList,'&'))
|  | 59 | #end
|  | 60 |
|  | 61 | ##
|  | 62 | ## Syntax menu map
|  | 63 | ##
|  | 64 | #set($syntaxMenu = [])
|  | 65 | #set($catCount = -1)
|  | 66 | #set($catName = "")
|  | 67 | #set($catChildren = [])
|  | 68 | #set($results = $services.query.xwql('from doc.object(XWiki.XWikiSyntaxClass) as syntax order by syntax.category, syntax.section').addFilter('currentlanguage').addFilter('unique').execute())
|  | 69 |
|  | 70 | #if($results.empty)
|  | 71 | No syntax sections found!
|  | 72 | #else
|  | 73 | #foreach ($item in $results)
|  | 74 | #set($sectionDoc = $xwiki.getDocument($item))
|  | 75 | #set($obj = $sectionDoc.getObject("XWiki.XWikiSyntaxClass"))
|  | 76 |
|  | 77 | ## detect if we entered a new category
|  | 78 | #if($catCount < $obj.getProperty("category").value)
|  | 79 | ## Put previous category into map (if existing), and reset children map
|  | 80 | #if($catId)
|  | 81 | #set($cat = { 'id' : $catId, 'name' : $catName, 'children' : $catChildren })
|  | 82 | $syntaxMenu.add($cat)
|  | 83 | #set($catChildren = [])
|  | 84 | #end
|  | 85 | ## extract new catId and catName values, and sectionTitle as we are already traveling the DOM
|  | 86 | #foreach($headerBlock in $sectionDoc.getDocument().getXDOM().getBlocks('class:HeaderBlock', 'DESCENDANT'))
|  | 87 | #if($headerBlock.getLevel().getAsInt() == 1)
|  | 88 | #set($catId = $headerBlock.getId().substring(1))
|  | 89 | #set($catName = $services.rendering.render($headerBlock, 'plain/1.0'))
|  | 90 | #elseif($headerBlock.getLevel().getAsInt() == 2)
|  | 91 | #set($sectionTitle = $services.rendering.render($headerBlock, 'plain/1.0'))
|  | 92 | #break
|  | 93 | #end
|  | 94 | #end
|  | 95 | #foreach($headerBlock in $sectionDoc.getTranslatedDocument().getDocument().getXDOM().getBlocks('class:HeaderBlock', 'DESCENDANT'))
|  | 96 | #if($headerBlock.getLevel().getAsInt() == 1)
|  | 97 | #set($catName = $services.rendering.render($headerBlock, 'plain/1.0'))
|  | 98 | #elseif($headerBlock.getLevel().getAsInt() == 2)
|  | 99 | #set($sectionTitle = $services.rendering.render($headerBlock, 'plain/1.0'))
|  | 100 | #break ## otherwise finds nested example headlines
|  | 101 | #end
|  | 102 | #end
|  | 103 | #set($catCount = $obj.getProperty("category").value)
|  | 104 | #else
|  | 105 | ## still in same category, only need new section title
|  | 106 | #foreach($headerBlock in $sectionDoc.getTranslatedDocument().getDocument().getXDOM().getBlocks('class:HeaderBlock', 'DESCENDANT'))
|  | 107 | #if($headerBlock.getLevel().getAsInt() == 2)
|  | 108 | #set($sectionTitle = $services.rendering.render($headerBlock, 'plain/1.0'))
|  | 109 | #break
|  | 110 | #end
|  | 111 | #end
|  | 112 | #end
|  | 113 |
|  | 114 | ## Add new sections to category children map
|  | 115 | #set($child = {'id' : $sectionDoc.documentReference.name.substring(11), 'minSyntax' : $obj.getProperty("minSyntaxId").value, 'maxSyntax' : $obj.getProperty("maxSyntaxId").value, 'name' : $sectionTitle})
|  | 116 | $catChildren.add($child)
|  | 117 | #end
|  | 118 | #end
|  | 119 | #set($cat = { 'id' : $catId, 'name' : $catName, 'children' : $catChildren })
|  | 120 | $syntaxMenu.add($cat)
|  | 121 |
|  | 122 |
|  | 123 | ##
|  | 124 | ## Filter only the sections that are valid for a Syntax
|  | 125 | ##
|  | 126 | #set ($categoriesToRemove = [])
|  | 127 | #foreach ($category in $syntaxMenu)
|  | 128 | #set ($sectionsToRemove = [])
|  | 129 | #foreach ($section on $category.children)
|  | 130 | #set($minSyntaxPos = $SUPPORTED_SYNTAX_ORDER.indexOf($section.minSyntax))
|  | 131 | #if ($minSyntaxPos > $crtSyntaxPos)
|  | 132 | #set ($discard = $sectionsToRemove.add($section))
|  | 133 | #if ($section.id == $crtSectionId)
|  | 134 | #set ($crtSectionId = '') ## clear section if it doesn't exist (can happen when switching from 2.x to 1.0 syntax)
|  | 135 | #end
|  | 136 | #end
|  | 137 | #end
|  | 138 | #set ($discard = $category.children.removeAll($sectionsToRemove))
|  | 139 | #if ($category.children.size() == 0)
|  | 140 | #set ($discard = $categoriesToRemove.add($category))
|  | 141 | #end
|  | 142 | #end
|  | 143 | #set ($discard = $syntaxMenu.removeAll($categoriesToRemove))
|  | 144 | #if ("$!crtCategoryId" != '' && $crtCategoryId >= $syntaxMenu.size())
|  | 145 | #set ($crtCategoryId = '')
|  | 146 | #end
|  | 147 |
|  | 148 | #if ($crtSectionId != '')
|  | 149 | #set ($crtItemId = $crtSectionId)
|  | 150 | #elseif ($crtCategoryId != '')
|  | 151 | #set ($crtItemId = $syntaxMenu.get($crtCategoryId).id)
|  | 152 | #end
|  | 153 | #set ($crtSection = $util.null)
|  | 154 | #set ($crtCategory = $util.null)
|  | 155 |
|  | 156 |
|  | 157 | ##
|  | 158 | ## Prepare the Syntax menu map for processing
|  | 159 | ##
|  | 160 | #foreach ($category in $syntaxMenu)
|  | 161 | ## "Standard" URLs and icons for categories
|  | 162 | #set ($category.url = "?syntax=$escapetool.url(${crtSyntaxVer})&category=${mathtool.sub($foreach.count, 1)}${extraParams}")
|  | 163 | #set ($category.cssClass = "${category.id}Icon")
|  | 164 | #if ("$!{crtCategoryId}" != '' && $foreach.count == $mathtool.add($crtCategoryId, 1))
|  | 165 | #set ($crtCategory = $category)
|  | 166 | #end
|  | 167 | ##
|  | 168 | ## Process each syntax section
|  | 169 | #foreach ($section in $category.children)
|  | 170 | #if ($xwiki.exists("XWiki.XWikiSyntax${section.id}"))
|  | 171 | #if ($crtSectionId == $section.id)
|  | 172 | #set ($crtSection = $section)
|  | 173 | #set ($crtCategory = $category)
|  | 174 | #end
|  | 175 | #set ($section.url = "?syntax=$escapetool.url(${crtSyntaxVer})&section=$escapetool.url(${section.id})${extraParams}")
|  | 176 | #end
|  | 177 | #end
|  | 178 | #end
|  | 179 |
|  | 180 | #**
|  | 181 | * Displays the sections from a syntax category
|  | 182 | *
|  | 183 | * Expected format:
|  | 184 | * sections = vector of items
|  | 185 | * item = map with the following fields:
|  | 186 | * 'id' : mandatory
|  | 187 | * 'name' : the text displayed for the corresponding menu item;
|  | 188 | * optional, defaults to
|  | 189 | * $services.localization.render("$!{translationPrefix}${item.id}")
|  | 190 | *
|  | 191 | * @param $sections the sections list, in the format described above
|  | 192 | * @param $translationPrefix the translation prefix added to the id of each
|  | 193 | * item, in order to generate the name and description; ignored when
|  | 194 | * name or description are specified
|  | 195 | * @param $heading the heading syntax
|  | 196 | *#
|  | 197 | #macro(syntax_displayCategory $sections $translationPrefix $heading)
|  | 198 | #foreach ($section in $sections)
|  | 199 | #syntax_displaySection($section $translationPrefix $heading)
|  | 200 | #end
|  | 201 | #end
|  | 202 |
|  | 203 | #macro(syntax_displaySection $section $translationPrefix $heading)
|  | 204 | #set ($displayVersion = $crtSyntaxVer)
|  | 205 | ## here is the hack to display the description for 2.0 if we have no description for 2.x
|  | 206 | ## this likely needs more work if e.g. there is a 3.x which is not compatible with 2.x
|  | 207 | #set($maxSyntaxPos = $SUPPORTED_SYNTAX_ORDER.indexOf($section.maxSyntax))
|  | 208 | #if ($crtSyntaxPos > $maxSyntaxPos)
|  | 209 | #set ($displayVersion = $section.maxSyntax)
|  | 210 | #end
|  | 211 | #if($heading)
|  | 212 | (% class="sectionheader" %)
|  | 213 | $heading $section.name $heading
|  | 214 |
|  | 215 | #end
|  | 216 | {{include reference="XWiki.XWikiSyntax${section.id}" section="H${displayVersion}${section.id}"/}}
|  | 217 | #end
|  | 218 |
|  | 219 |
|  | 220 | #**
|  | 221 | * Displays the syntax categories
|  | 222 | *
|  | 223 | * Expected format:
|  | 224 | * sections = vector of items
|  | 225 | * item = map with the following fields:
|  | 226 | * 'id' : mandatory
|  | 227 | * 'name' : the text displayed for the corresponding menu item;
|  | 228 | * optional, defaults to
|  | 229 | * $services.localization.render("$!{translationPrefix}${item.id}")
|  | 230 | *
|  | 231 | * @param $sections the sections list, in the format described above
|  | 232 | * @param $translationPrefix the translation prefix added to the id of each
|  | 233 | * item, in order to generate the name and description; ignored when
|  | 234 | * name or description are specified
|  | 235 | *#
|  | 236 | #macro(syntax_displayCategories $syntaxMenu $translationPrefix)
|  | 237 | #set ($subHeading = '====')
|  | 238 | #foreach ($category in $syntaxMenu)
|  | 239 | == $category.name ==
|  | 240 |
|  | 241 | #syntax_displayCategory($category.children 'syntax.' '===')
|  | 242 | #end
|  | 243 | #end
|  | 244 |
|  | 245 | #**
|  | 246 | * Displays the drop down allowing to switch the syntax.
|  | 247 | *#
|  | 248 | #macro (syntaxSwitch)
|  | 249 | #set ($crtSelection = "")
|  | 250 | #if ("$!{crtCategoryId}" != '')
|  | 251 | #set ($crtSelection = "category=$escapetool.url($!{crtCategoryId})")
|  | 252 | #elseif ($crtSectionId != '')
|  | 253 | #set ($crtSelection = "section=$escapetool.url($!{crtSectionId})")
|  | 254 | #end
|  | 255 | #if ($crtSelection != "")
|  | 256 | #set ($crtSelection = "${crtSelection}${extraParams}")
|  | 257 | #else
|  | 258 | #set ($crtSelection = "$extraParams")
|  | 259 | #end
|  | 260 | {{html}}
|  | 261 | <form id="change-context" class="xformInline" action="$doc.getURL()">
|  | 262 | <div>
|  | 263 | <input type="hidden" name="xaction" value="switchContext" />
|  | 264 | #if ($request.language)
|  | 265 | <input type="hidden" name="language" value="$escapetool.xml($request.language)" />
|  | 266 | #end
|  | 267 | #if ($request.xpage)
|  | 268 | <input type="hidden" name="xpage" value="$escapetool.xml($request.xpage)" />
|  | 269 | #end
|  | 270 | <select id="goto-select" name="target" title="$escapetool.xml($services.localization.render("help.changesyntax"))">
|  | 271 | <optgroup label="$services.localization.render('help.choose_syntax')">
|  | 272 | #foreach($syntaxId in $SUPPORTED_SYNTAX_ORDER)
|  | 273 | #set ($query = "syntax=${escapetool.url($syntaxId)}&${crtSelection}")
|  | 274 | <option value="$escapetool.xml($doc.getURL('view', $query))"#if($crtSyntaxVer == $syntaxId) selected="selected"#end>$escapetool.html($SUPPORTED_SYNTAXES.get($syntaxId))</option>
|  | 275 | #end
|  | 276 | </optgroup>
|  | 277 | </select>
|  | 278 | <span class="buttonwrapper"><input type="submit" value="$escapetool.xml($services.localization.render('admin.switchContext'))" class="button" /></span>
|  | 279 | </div>
|  | 280 | </form>
|  | 281 | {{/html}}
|  | 282 | #end
|  | 283 | {{/velocity}}
|  | 284 |
|  | 285 | {{velocity}}
|  | 286 | ##**************************************************************************************************
|  | 287 | ## From the Administration Sheet, used to display a common UI for some wiki features
|  | 288 | ## here used to display all categories / sections of the syntax guide
|  | 289 | ##**************************************************************************************************
|  | 290 | $xwiki.get('jsx').use($doc.getFullName())##
|  | 291 | $xwiki.get('ssx').use($doc.getFullName())##
|  | 292 | #if ($crtSectionId != '')
|  | 293 | #set ($sectionName = ${crtSection.name})
|  | 294 | #elseif ($crtCategoryId != '')
|  | 295 | #set ($sectionName = ${crtCategory.name})
|  | 296 | #else
|  | 297 | #set ($sectionName = $services.localization.render("help.syntaxall"))
|  | 298 | #end
|  | 299 | #set ($syntaxTitle = $services.localization.render("help.syntaxtitle", ["${crtSyntaxVer}"]))
|  | 300 | #syntaxSwitch()
|  | 301 | (((
|  | 302 | #set ($query = "syntax=$escapetool.url(${crtSyntaxVer})${extraParams}")
|  | 303 | #if ($crtCategory){{html}}<a href="${doc.getURL('view', ${query})}">$syntaxTitle</a>{{/html}}#{else}(% class="current" %)$syntaxTitle#{end}#if ($crtCategory) » #if ($crtSection){{html}}<a href="${crtCategory.url}">${crtCategory.name}</a>{{/html}}#{else}(% class="current" %)${crtCategory.name}#{end}#if ($crtSection) » (% class="current" %)${crtSection.name}#end#end
|  | 304 | )))
|  | 305 | == $syntaxTitle: $sectionName ==
|  | 306 |
|  | 307 | #verticalNavigation($syntaxMenu {'translationPrefix' : 'syntax.', 'crtItemId' : "$!crtItemId", 'cssClass' : 'syntax-menu'})
|  | 308 | ##-----------------------------------------
|  | 309 | ## syntax-page display
|  | 310 | ##-----------------------------------------
|  | 311 | #set ($subHeading = '===')
|  | 312 | (% id="syntax-page-content" %)(((
|  | 313 | #if(!$crtSection && !$crtCategory)
|  | 314 | #syntax_displayCategories($syntaxMenu 'syntax.')
|  | 315 | #elseif (!$crtSection)
|  | 316 | #syntax_displayCategory($crtCategory.children 'syntax.' '==')
|  | 317 | #else
|  | 318 | #syntax_displaySection($crtSection 'syntax.' false)
|  | 319 | #end
|  | 320 | ))) ## syntax-page-content
|  | 321 | {{/velocity}}

# Applications

# Tips

If you're a new XWiki user, check out the Getting Started Guide.

# Need help?

If you need help with XWiki you can contact:

- Community Support
- Professional Support

XWiki Debian 13.10.2