Required Rights API
 | Analyzes for document required rights |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard (XWiki 15.9RC1+) |
| Compatibility | XWiki 15.9RC1+ |
Table of contents
Description
The required rights API allows checking if a document or a part of it like an XObject or a macro requires that the document's author has some right. This could, e.g., be script or programming right for script macros or wiki admin right for UI extensions.
Required right analysis can be used to warn users when editing a document would either break macros or objects or when additional rights would be granted that a document or object currently doesn't have. Further, they can be used to perform an analysis which rights a document currently requires and check if the last author has them to suggest fixing them.
At the moment, this is a Java API only. The main entry point for analyzing an XWiki document is RequiredRightAnalyzer<XWikiDocument>. Script APIs might be provided in the future as part of the default implementation.
This API module defines the APIs for checking required rights, components for checking rights need to be defined in their respective components. Each macro and each XClass should define their own analyzer if it needs any special right. Default analyzers are provided in the default implementation that analyze the content of the macro if it indicates that it supports wiki content and that analyze non-restricted text area properties of XObjects when no specific analyzer is provided. That way, not every XClass and macro needs to provide its own analyzer if just standard properties with their default behavior are used. A specific analyzer is always required if the macro or the code that uses the XObjects checks for any rights on the author or if any content that is not marked as such (like a macro parameter) is interpreted as wiki syntax.
Implementing custom analyzers
To implement a custom analyzer, it is sufficient to implement a RequiredRightAnalyzer<BaseObject> with a hint that corresponds to the XClass name like XWiki.JavaScriptExtension or a RequiredRightAnalyzer<MacroBlock> with a hint that corresponds to the macro id. The analyzer will automatically be called when an object or macro of that name is present. Ideally, custom analyzers should be embedded into the right checking workflow of the macro/XClass code to avoid duplicating the logic which rights are required to avoid inconsistencies. Custom analyzers replace the default behavior, so custom analyzers need to take care of analyzing the macro content and any object properties that could contain XWiki syntax or Velocity. For internal analyzers in XWiki itself, AbstractMacroBlockRequiredRightAnalyzer and DefaultObjectRequiredRightAnalyzer provide helper methods that can be used in custom analyzers.
XWiki 15.10+ For macros, a MacroRequiredRightsAnalyzer with the id of the macro as name can be implemented. This is a simpler API that has no dependencies apart from xwiki-rendering-api and is thus a good choice for macros that don't need/want to depend on a lot of XWiki APIs. Further, it should lead to simpler analyzers if the provided API is sufficient.
XWiki 16.3.0+
A org.xwiki.platform.security.requiredrights.display.BlockSupplierProvider role is provided with implementations for displaying an XObject, macro block, a translated message, or simply a text as a code block in the result of the analysis. This can, e.g., be used to display a translated message for the summary or the whole XObject for the details. The following implementations are provided:
- BlockSupplierProvider<BaseObject>: displays all properties of an XObject
- BlockSupplierProvider<MacroBlock>: displays a macro including all parameters and content.
- BlockSupplierProvider<String> with name stringCode: displays a string as a code block.
- BlockSupplierProvider<String> with name translation: displays a translation message with the given parameters.
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-security-requiredrights-api 16.9.0):
- org.xwiki.platform:xwiki-platform-model-api 16.9.0
- org.xwiki.platform:xwiki-platform-security-authorization-api 16.9.0
- org.xwiki.rendering:xwiki-rendering-api 16.9.0
