Sheet Module

The Sheet Module provides an API for managing class and document sheets.

Sheets

A sheet is an XWiki page determining how to display the attached objects, title and content of other XWiki documents. The title and the content are rendered in the context of the displayed document. A very important detail is that sheets are not responsible for the page layout. For this purpose, you should use Velocity templates.

Programming rights set on a sheet are preserved when the sheet is rendered in the context of the displayed document. This means that you can write a sheet with programming rights and use it for documents that don't have programming rights. 

On the other hand, a sheet saved by an user without programming rights won't gain programming rights when used to display a document that has programming rights. This is achieved by rendering the sheet as if its content author was also the content author of the displayed document.

Class Sheets

A class sheet displays data stored in an object attached to an XWiki page. To control the display, you need

  • to bind the XWiki class defining the object type to a sheet; this can be done by adding an "XWiki.ClassSheetBinding" object to the class document 
  • to set the sheet reference as the value of the "Sheet" property.

    ClassSheetBindingObject.png

Below you have an example of a class sheet that displays all the property values of the first object of a specific type attached to the current document:

{{velocity}}
#set($class = $doc.getObject('Example.YourClass').xWikiClass)
#foreach($property in $class.properties)
 ; $property.prettyName
 : $doc.display($property.getName())
#end
{{/velocity}}

Document Sheets

A document sheet is useful when you wish to display a document differently than the rest of its type. You can bind your document to a custom sheet by adding an "XWiki.DocumentSheetBinding" object and by setting the custom sheet reference as value of the "Sheet" property. You may also leave the "Sheet" property blank, which means that the document will be bind to itself, thus will control its own display. A second possible use case is to display document metadata, like for instance the current document statistics.

DocumentSheetBindingObject.png

Most of XWiki class documents have:

  • an object of type "XWiki.ClassSheetBinding" for specifying the class sheet used to display class instances 
  • an object of type "XWiki.DocumentSheetBinding" pointing to "XWiki.ClassSheet" used to display the class document itself

Request Sheets

To apply a sheet on a document upon request, you can use the URL sheet query string parameter as follows: /xwiki/bin/view/Main/UserPage?sheet=XWiki.XWikiUserSheet. The sheet specified in the request is applied only to the requested document and it doesn't work recursively.

Action Sheets

A document can have different behaviors for each XWiki action like view or edit. The usual approach is to write a sheet that uses the Document#display() method whose output depends on the current action. In case there are important differences between how the document behaves in View and Inline form or Edit mode, it is recommendable to write two different sheets instead of checking the current action inside a single sheet. To do this, you can bind your class or document to two or more different sheets and then add an object of type "XWiki.SheetDescriptorClass". For each object, you then need to fill the Action property with the corresponding action name.

SheetDescriptorClassObject.png

The edit mode is usually specified by the editor URL query string parameter. When the editor is not specified in the edit URL, the Display Module looks for a sheet that matches the edit action. If it finds one, then it uses that sheet to display the document in edit mode. This is called the 'Inline form' edit mode. You can force it by setting the editor URL query string parameter to inline.

User and Group Sheets

You can have different sheets per user or group by binding your class or document to multiple sheets for which you then have to configure the corresponding access rights. A sheet matches the current action if one of the following conditions is satisfied:

  • the sheet document doesn't have an object of type XWiki.SheetDescriptorClass
  • the sheet document has an object of type XWiki.SheetDescriptorClass for which the Action property is blank
  • the sheet document has an object of type XWiki.SheetDescriptorClass for which the Action property matches the current action.

Sheet Script Service

In XWiki applications it is recommended to use the Sheet Script Service instead of the hard-coded "XWiki.ClassSheetBinding", "XWiki.DocumentSheetBinding" or "XWiki.SheetDescriptorClass". 

{{velocity}}
#set($className = 'Blog.BlogPostClass')
The list of class sheets bound to $className:
#set($classDocument = $xwiki.getDocument($className))
#foreach($sheetReference in $services.sheet.getClassSheets($classDocument))
 * $services.model.serialize($sheetReference)
#end
{{/velocity}}

  

Search this space