Administration Application

Last modified by Admin on 2024/10/28 18:05

administration.pngApplication for administrating wiki features like users, groups, rights etc.
TypeXAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

Description

The administration application allows you to administrate an XWiki instance. It offers both a generic framework for allowing other applications to register administration screens and also provides several screens itself (see below).

If you're installing this application on an existing XWiki installation you should be very careful. If you're using the Distribution Wizard you should be safe as it'll check do an automatic merge and warn you in case of conflicts. However if you're doing a manual import then make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care: 

  • XWiki.XWikiPreferences: This page contains the configuration of your wiki (it overrides the configuration defined in xwiki.cfg). If you import a new version of this page you'll lose any customization you may have made such as the skin to use, the rights for your wiki, etc.
  • XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups.
  • XWiki.RegistrationConfig: Contains your registration settings. Overwrite it will go back to using the defaults.
  • Any other page from the Administration application that you have modified, such as XWiki.DefaultSkin.

Provided Features

This is what you see when you go the global Administration page:

global.png

Some of the Admin Categories are provided by the Administration Application itself (described below) and others are contributed by other extensions using the Configurable Class mechanism (described in the contributing extension).

Users & Rights

Users

Manage the users of the wiki: create new users, delete existing users and edit the user profiles.

users.png

XWiki 11.8-rc-1+

Note that deleting an user requires 2 steps:

  • You have to disable the user first. Disabling the user prevents them from logging in and it doesn't break the scripts that they last modified. This is the recommended way to "remove" an user account from your organization.
  • Then, if you really need to completely remove the user account, you can delete it. However, you should choose another user account with similar access rights to replace the deleted one as page author of existing pages, otherwise, any scripts inside those existing pages will lose their rights and stop working.

deleteUser-replaceAuthor.png

Groups

Manage the user groups: create new groups, delete existing groups and edit the group membership.

groups.png

XWiki 15.8-rc-1+ Groups with custom titles can be filtered using the "Group Name" column.

Rights

Manage the group and user rights: control who can view, edit and delete pages.

rights.png

See also the Authentication guide and the Access rights information.

Extension Rights

XWiki 13.5+

A new section has been added to allow settings the Extension Rights: those rights are not part of XWiki core and are provided by extensions. By default, in XWiki Standard the UI displays the Like right, but other rights can be added depending on the installed extensions.

extension-rights-ui.png

User Profile

Manage what information is displayed on the user profile of each user.

profile.png

User Directory

See the User Directory application.

Registration

registration.png

These settings control the Registration process and also the L&F and the behavior of the Registration page you get when you click on the Register button in the XWiki UI (top right part of the screen).

Registration page:

registrationpage.png

The registration page supports image captchas supplied by the captcha module and also validating the input fields both on the server side and in Javascript using LiveValidation.

The Registration page does not require programming rights to operate so you can configure it even if you are administrating a virtual wiki on a wiki farm.

Activating captchas

In order for the registration page to require a captcha to be solved for registration, you will have to activate it. You can do this from the Registration section of the wiki administration interface.

Options you can set from the Registration section of the Administration Interface
  • Use Email Verification. If set to "Yes" then an email will be sent to the email address used when filling the Registration page.
  • (removed since XWiki 11.6RC1) Authentication Active Check. If set to "Yes" it will prevent the users from logging in without entering the token which was previously sent in the email.
  • Validation Email Content. The email template that corresponds to the mail that is sent when "Use Email Verification" is active. The template is in MIME format. For example this allows to send HTML emails; here's an example:
    #set ($wikiname = $request.serverName)
    #set ($host = ${request.getRequestURL()})
    #set ($host = ${host.substring(0, ${host.indexOf('/', ${mathtool.add(${host.indexOf('//')}, 2)})})})
    Subject: Validate your account on ${wikiname}
    Content-type: text/html; charset=iso-8859-1

    <p>Hello <b>${xwiki.getUserName("XWiki.$xwikiname", false)}</b>,</p>
    <p>This email address was used to register a new account on ${wikiname}. If you did not make the request, please ignore this message.</p>
    <p>In order to activate your account, please follow this link:
    ${host}${xwiki.getURL('XWiki.AccountValidation', 'view', "validkey=${validkey}&xwikiname=${xwikiname}")}</p>
  • Confirmation Email Content. The email template that corresponds to the mail that is sent when the user validates his account by clicking in the validation link in the first email he received (i.e. the mail corresponding to the "Validation Email Content" template). Similarly to the "Validation Email Content" this field can contain any valid content in MIME format.
  • Registration page heading
    • This is the line at the top of the page which is shown to people who are registering and when they have just registered.
  • Welcome Message
    • This is only shown when people are filling out the form.
  • (Removed in XWiki 15.10RC1)Enable Javascript field validation (Default: Yes)
    • Set this to false and LiveValidation javascript will not be generated (fields will still be validated at the server side.)
  • (Removed in XWiki 15.10RC1)Default field okay message (Default: 'Ok.')
    • LiveValidation shows a message to indicate to users that they have filled in the field satisfactorily. This is the message they will get if it is not overridden for a particular field.
  • Enable login button (Default: Yes)
    • When the user has registered, we provide a button for them to click which will post their username and password to the login action and get them logged in right away. This however causes the username and password to be passed back in the HTML which may be unacceptable depending on your security needs.
  • Enable automatic login (Default: No)
    • If login button is enabled, then you can have a piece of Javascript push the login button for the user.
  • Redirect here after registration (Default: Main.WebHome)
    • This is the page which the user will be redirected to after pushing the login button if the xredirect parameter is not specified.
  • Require captcha to register (Default: No)
    • Set this true to require the user to solve a captcha in order to register.
  • Require a password with the given length (Default: 6) (since XWiki 11.9)
    • Specify the minimal length for the user passwords.
  • Require at least one lower case character in the password (Default: No) (since XWiki 11.9)
    • Set this to true to force users to have at least one lower case case character in their password.
  • Require at least one upper case character in the password (Default: No) (since XWiki 11.9)
    • Set this to true to force users to have at least one upper case case character in their password.
  • Require at least one number in the password (Default: No) (since XWiki 11.9)
    • Set this to true to force users to have at least one number in their password.
  • Require at least one symbol character in the password (Default: No) (since XWiki 11.9)
    • Set this to true to force users to have at least one symbol in their password.
Things which you may configure by editing XWiki.Registration

In XWiki.Registration, the fields are defined separately from the code which generates the HTML. You can add or remove fields simply by modifying the configuration. Fields are defined as maps. The maps are each required to have a 'name' key which must map to a string. This string will be the id and name of the field when it is rendered into HTML.

label (string)
This is what the user is prompted with above the field for their input.
tag (string)
Usually a field is an input field but if you specify a different tag (eg: textarea) then it will not be an input type field. You can even specify non field tags such as <img> or <div> but it may cause invalid HTML to be generated.
params (map)
This map corresponds to the HTML parameters of the tag. If you specify params to be { 'class' : 'someclass', 'style' : 'color:red;' } then the HTML tag will read <input class="someclass" style="color:red;">
noReturn (boolean)
If this is specified, the field will not be filled in if there is an error and the user has to fix their registration information. If you don't want a password to be passed back in html then set this true for the password fields. Used for the captcha because it makes no sense to pass back an incorrect captcha answer.
doAfterRegistration (string)
Some Velocity code which will be executed after a successful registration. This is used in the favorite color example. Remember to put the code in single quotes (' ') because you want the 'code' entry to equal the literal code, not the output from running it.
validate (map)
This map is the most complex and is covered later on in this section.

Here is the definition of a field which is used in the registration page:

## The user name field, mandatory and programmatically checked to make sure the username doesn't exist.
#set($field =
  {'name' : 'xwikiname',
    'label' : $msg.get('core.register.username'),
    'params' : {
      'type' : 'text',
      'onfocus' : 'prepareName(document.forms.register);',
      'size' : '20'
    },
    'validate' : {
      'mandatory' : {
        'failureMessage' : $msg.get('XWiki.Registration.fieldMandatory')
      },
      'programmaticValidation' : {
        'code' : '#nameAvailable($request.get("xwikiname"))',
        'failureMessage' : $msg.get('core.register.userAlreadyExists')
      }
    }
  })
#set($discard = $fields.add($field))

Line by line it is:

  • A comments and the beginning of a set directive.
    • name is set to 'xwikiname'
    • label is set to 'User Id:' or translation there of.
    • params is set to a new map
      • params map gets type set to 'text'
      • params map gets onfocus set to some Javascript
      • params map gets size set to '20'
    • End of params map
    • validate is set to a new map.
      • validate map gets mandatory set to new map.
        • validate.mandatory gets failureMessage set to 'this field is mandatory' or translation there of.
      • validate.mandatory is ended.
      • validate gets programmaticValidation set to new map
        • validate.programmaticValidation gets 'code' set to a macro call which will check if the username is taken.
        • validate.programmaticValidation gets 'failureMessage' set to a message telling the user that the name is taken.
      • validate.programmaticValidation map is closed.
    • validate map is closed.
  • Map for this field is closed and set directive ends.
  • This field is added to the fields array and the output from the add function is set to discard to avoid having it print on the page.
Validation Constraints

The validate field configuration key is itself a map which allows a number of parameters to be defined. Validation is done in the order of mandatory, then regex, then mustMatch, then programmatic validation so if nothing is entered and the mandatory constraint is not in place then the entry will be accepted and if a entry fails the regex test then it will not be evaluated programmatically.

  • mandatory (Optional)
    • Will fail if the field is not filled in.
    • failureMessage (Required)
      • The message to display if the field is not filled in.
    • noscript (Optional)
      • Will not be validated by Javascript, only on the server side.
  • regex (Optional)
    • Will validate the field using a regular expression. because of character escaping, you must provide a different expression for the javascript validation and the server side validation. Both javascript and server side validation are optional, but if you provide neither, then your field will not be validated.
    • failureMessage (Optional)
      • The message to display if the regex evaluation returns false, note that this is sent in HTML so &lt; will display as <
    • jsFailureMessage (Optional)
      • The message for Javascript to display if regex fails. If jsFailureMessage is not defined Javascript uses failureMessage. NOTE: Javascript injects the failure message using createTextNode so &lt; will be displayed as &lt;
    • pattern (Optional)
      • The regular expression to test the input at the server side, it's important to use this if you need to validate the field for security reasons, also it is good because not all browsers use javascript or have it enabled.
    • jsPattern (Optional)
      • The regular expression to use for client side, you can use escaped characters to avoid them being parsed as Javascript code. To get javascript to unescape characters use: "'+unescape('%5E%5B%24')+'"
        • NOTE: If no jsPattern is specified, the jsValidator will try to validate using 'pattern'.
    • noscript (Optional)
      • Will not be validated by Javascript, only on the server side.
  • mustMatch (Optional)
    • Will fail if the entry into the field is not the same as the entry in another field. Used for password confirmation.
    • failureMessage (Required)
      • The message to display if the field doesn't match the named field.
    • name (Required)
      • The name of the field which this field must match.
    • noscript (Optional)
      • Will not be validated by Javascript, only on the server side.
  • programmaticValidation (Optional)
    • This form of validation executes a piece of Velocity code which you give it and if the code returns the word "failed" then it gives the error message. Remember to put the code in single quotes because you want the value of 'code' to equal the literal code, not the output from running it (Velocity parses code in double quotes)
    • code (Required)
      • The code which will be executed to test whether the field is filled in correctly.
    • failureMessage (Required)
      • The message which will be displayed if evaluating the code returns "false".
  • fieldOkayMessage (Optional)
    • The message which is displayed by LiveValidation when a field is validated as okay. If not specified, will be the LiveValidation default field ok message

Invitation

See the Invitation application.

Extensions

See the Extension Manager application.

Look & Feel

Themes

Customize the color and icon themes.

themes.png

See the Flamingo Theme application and the Icon Theme application. The more advanced users can also customize the skin using the Skin application.

Panels

See the Panels application.

Presentation

Choose the page tabs that are visible and configure the page header and footer.

presentation.png

If you need more fine-grained control, check the controlling page tabs in the Scripting guide.

Application Panel

See the Application Panel documentation.

Content

Page Templates

It's possible for users and applications to provide pages that can be used as template when creating new pages.

Creating Templates
  • A template is a wiki page. If you want to make an existing page a template then skip to the next section. Otherwise, let's create a new template page. Go to the wiki home page and click on the create page button (the "+" button).
    CreatePage.png
  • As you can see the Create Page dialog lists the available templates that can be used to create new pages. We want to add our template there. But first we need to create it so select "Blank page".
  • Write the template content and save.
    SaveTemplate.png
  • This is what you will see at this stage:
    ViewTemplate.png
  • Note that advanced users can edit the template page in object mode and add meta data that will be copied along with the page content when the template is used. Of course, if you add an object that has a dedicated sheet then the template will look different in view mode, depending on the sheet.
Create the Template Provider

To do this go to the administration and click on the "Templates" link from the "Content" category.

From the "Templates" administration section you can:

  • View the list of Available Template Providers
  • Create a Template Provider

contentTemplates.png

A template provider is a wiki page whose main role is to expose the template on the Create Page dialog so that the users can create new pages based on the template. To create a template provider specify the title and location fields then hit the Create button (see image above). Naming the template provider after the template you've just created is a good practice.

Next you will need to fill in the template provider form. Make sure the following fields are filled in:

  • The provider name - the name displayed in the list of available template providers, in the Templates section, in Administration (e.g. My Template Provider)
  • The template name - the name displayed in the list of available templates, in the Create Page form (e.g. My Template)
  • The template to use - the page that will be used as template when this template provider is used to create a new page (e.g. Main.MyTemplate)

TemplateProvider-Edit.png

Until 7.3M2 there was also a Template Type configuration (with Page and Space options) which was removed since it was not really used.

Location Restrictions

Since 8.3M2 there are 2 types of location restrictions that you can enforce:

  • Visibility restrictions
  • Creation restrictions

Visibility restrictions specify the list of locations where the template provider will be visible to an user that is creating a new page. This allows you to control what type of content you are proposing your users to create, depending where they are trying to create it from. E.g.: propose to create expense reports only when creating a page from the "Expense Reports" location.

A provider that specifies no visibility restrictions is visible, in the Create Page dialog, from any page inside the wiki.

In order to add a visibility restriction you need to edit the template provider and click on the "+" icon below "List of locations where the template must be available". This will open a popup with the page tree from which you can select one or multiple locations. For instance, if you select the "Home" page then your template will be available only when you create a page from the "Home" page or one of its child pages.

Creation restrictions, as the name implies, specify the list of locations where the template provider allows the creation of pages. This allows you to control where your users are allowed to create various types of content. E.g.: restrict the creation of "Evaluations" only to the "HR" location (i.e. as direct or indirect children of the "HR" page).

A provider that specifies no creation restrictions can be used to create pages anywhere in the wiki.

Specifying a creation restriction also has the effect of prefilling the destination location on the Create Page form. When switching between template types on the creation form, if the newly selected template has a creation restriction, the parent location field will be prefilled with one of the template's restrictions. However, if such a template provider has additionally checked the Creation restrictions as suggestions option, then the creation restrictions will not be enforced and will only be used for identifying the default parent location which is prefilled in the creation screen, while the user is still being able to change the parent to something else, outside those restrictions.

In order to add a creation restriction you need to edit the template provider and click on the "+" icon below "Creation restrictions". This will open a popup with the page tree from which you can select one or multiple locations. The creation restrictions are used on the Create Page form to validate the location field.

CreatingPageUsingTemplateDenied.png

Before 8.3M2 there was a single spaces property specifying both the places where the template was visible and also where the template could be used to create pages, but it was split into the 2 above described restrictions to allow more flexibility and visibility of the templates feature. We are still supporting old (pre 8.3M2) template providers by reading from their spaces property, but if both the new restrictions and the spaces property are used, the new restriction properties will have priority.

Recommended Templates

Since 9.5RC1, trying to create a page (using the standard Create page UI) from a location matching (exactly, or as a child of) a creation restriction of a visible template provider will have the effect of recommending/promoting the provider's template to the top of the page type list and pre-selecting it.

If more than 1 such providers are detected for the current location (from which the user is trying to create), they will all be pushed to the top of the list, but they will be sorted based on the specificity of the matching creation restriction, so that the restriction that matches the current location best (i.e. most specific one) will be the first and pre-selected one.

This helps in guiding the user to create more structured content and allows applications to benefit from the template provider(s) they define.

Advanced: Creating terminal pages with template providers

Since 7.3RC1, when you create or edit a template provider, as an advanced user, you can also specify if the pages that will be created with it should be terminal or not.

TemplateProvider-Edit-Terminal.png

If the Terminal Page option is set to Yes, then when you select the template provider in the create page step:

  • If you are an advanced user, the Terminal Page checkbox will be checked by default. You can still override the template provider's option and uncheck it manually so that the page is created as non-terminal instead.
  • For regular users, the Terminal Page checkbox is not displayed in the create page step, so the page that will be created will respect the preference specified in the template provider's terminal xproperty.
Action on Create

The template provider can also specify the action to execute when the Create button is clicked on the Create Page dialog (if a template has been selected). The following actions are supported:

  • Edit: clicking the Create button will open the new page in edit mode. You need to save the page from the edit mode in order to actually create the page.
  • Save & Edit: clicking the Create button will save the new page first (with the data copied from the selected template) and then will open the created page in edit mode.
  • Save & View: clicking the Create button will save the new page (with the data copied from the selected template) and then open it in view mode
Using the templates
  • After you have created the template and the template provider you can go back to the home page and start creating pages from this template:

    CreatePageUsingTemplate.png

  • We can see that the content of the new page has been copied from the selected template.

    ViewCreatedPageUsingTemplate.png

  • This example shows that you are offered the choice to create a new page from the available template ("My Template" template in the image below) for broken links:

    CreatePageUsingTemplate1.png

Using a hierarchy of Nested Pages as template

Since 7.4M2, when the template document specified by the template provider is a Non-Terminal document which, in turn, has several descendant documents under its path, a template document hierarchy is established. Whenever creating a new document using this template, the entire template hierarchy will be copied over to the location of the new document.

To create a template hierarchy, simply create a hierarchy of documents and select the root of the hierarchy as template document, when creating your template provider.

Example:

  • The available "MyTemplate" document hierarchy to use:

    MyTemplate
    MyTemplate.A
    MyTemplate.A.X
    MyTemplate.A.X.1
    MyTemplate.B
    MyTemplate.etc...

  • We create a template provider with the display name "My Template" and set "MyTemplate.WebHome" as the template document to use.
  • Creating a new document called "MyNewDocument" by using the template "My Template" will result in the following new document hierarchy being created:

    MyNewDocument
    MyNewDocument.A
    MyNewDocument.A.X
    MyNewDocument.A.X.1
    MyNewDocument.B
    MyNewDocument.etc...

Note: when saving the newly created document for the first time, a notification will be displayed at the bottom of the edit form, displaying progress information (and the form will be disabled when pressing Save & View):
savingNewDocumentWithTemplateHierarchy.png

Localization

Enable or disable the multilingual mode, set the default language and the list of supported languages, configure the date format and the time zone.

localization.png

See also:

Import

Import pages or applications into the wiki. The packaging format is called a XAR. See Import/Export to understand more about the XAR format.

Prerequisites:

  • If your wiki is empty and this is your first import, you will need to log in as superadmin to do the first import since there are no users defined in the wiki at this time.
  • Attach the XAR file you wish to import and then select it from the list under "Available packages". After a few seconds you should see the list of all the pages in your XAR listed and selected by default (unselect the pages/folders you don't wish to import):

    import.png

  • Select the second radio button if you want to replace the document history with the history from the imported package. If you don't select it the newly imported pages will have the revision "1.1"
  • In case you want to preserve the author for the imported pages, check the "Import as backup package" option.
  • Click "Import". This will import all the selected pages
  • At this stage your rights might have been changed as the import may have imported different rights. You may need to log out and log in again.

If you own the sub-wiki (virtual wiki, wiki-farm), you need to be sure that you either:

  • install with a global user having Programming Rights (PR) and UNCHECK the backup pack option
  • install with a global user having PR and keep the backup pack option but in this case MAKE SURE that the user defined in the XAR exists and has PR.
    Otherwise all imported pages would be saved without PR and scripts won't work until you resave them under the user with Programming Rights .

Note, that pages requiring PR are supposed to also contain a XWiki.RequiredRightClass xobject so it should be easy to query them. If you find some that don't have this XObject please let us know. This XObject is just indicative and doesn't change permissions.

If you get a 'Java heap space Out Of Memory exception' you'll need to increase the memory allocated to the JVM running XWiki.

Importing an Extension

When you import a XAR, if the XAR's package.xml contains an extensionId value (representing an Extension Id) then the Importer will check if the Extension exists in its configured XWiki Extension Repositories (the configuration for this is located in xwiki.properties under the extension.repositories keys). If the Extension is found, the Importer will then register it in the list of installed Extensions that you can see when going to the Extension Manager Application's UI.

Export

Export wiki pages into a XAR archive. See Import/Export to understand more about the XAR format.

XWiki 11.10+

You can do a partial export of your wiki by selecting the pages you wish to export. The page tree has 3 filters available:

  • Created pages: the pages created by the user or by XWiki extensions on behalf of the user.
  • Created and modified pages: includes modified extension pages (usually configuration pages). This filter is applied by default because most of the time what you need to export is the pages you created and the extension pages you modified.
  • All pages: includes unmodified extension pages. Exporting unmodified extension pages is usually not recommended because:
    • Importing extension pages is not enough to have the extensions working because extensions need their dependencies. Best is to install extensions through the Extension Manager.
    • Importing extension pages over a different version of the same extension can easily break the extension due to API incompatibilities.

The color of the page node icon indicates whether the page is safe to export or not. Created pages and modified extension configuration pages are marked with green. Modified extension code pages are marked with yellow. Unmodified extension pages are marked with red.

The export tree may show disabled pages because the current export filter excludes them. They are still displayed because they have child pages that are included. You can use the context menu to select / unselect all child pages of a disabled node, provided the disabled node is opened.

The export tree shows hidden pages even if the user profile is configured to hide hidden pages. Hovering over an extension page shows the extension name and id.

XWiki 12.0+ The way the attachment history is exported has changed in order to make the export more performant. As a consequence, if you try to export pages from an XWiki 12.0+ with history and import them in an XWiki older than 12.0, the imported attachments won't have their history. If you care about this then you need to redo the export with the "Target XWiki version" option set to "Below 12.0". This way you get an export that is compatible with older versions of XWiki.

Annotations

See the Annotations application.

Office Server

See the Office Importer application.

Editing

Edit Mode

Choose the default edit mode and configure its title and versioning parameters.

edit.png

See also how to configure the default editor.

WYSIWYG Editors

Checkout the WYSIWYG Editor module.

Syntaxes

See the Rendering administration application.

Name Strategies

Since XWiki 12.0RC1, see the Name Strategy Module for more information.

Mail

See the Mail application.

Search

See the Search application. Solr is currently the default search engine.

Social

XWiki <12.8  the elements of that category were on Other.

Likes

See the Like application.

Mentions

See the Mentions application.

Message Stream

See the Message Stream application.

Notifications

See the Notifications application.

Wikis

See the Wiki application.

Other

Logging

See the Logging application.

Google Analytics

XWiki 14.10+ The Google Analytics feature has been moved to an Extension.

XWiki <14.10

XWiki provides a built-in integration for Google Analytics. To use it simply choose the Analytics mode (Universal or Classic - Check the Google documentation to decide which one is best for you) and fill in your tracking id:

googleanalytics.png

If you have multiple subwikis in your wiki, you'll need to configure each subwiki that you wish to track with a tracking id (it can be the same one across wikis). There's currently no way to specify the tracking id once for all subwikis.

Making your application configurable with ConfigurableClass

So you have created the best application since sliced bread and like a good application designer you made it extensible, and configurable. At the last moment you realize most people don't want to edit configuration files in order to configure an application, what are you to do? You could create a class with properties for each of the configuration options. You could even create a page with an easy to use form but that's a bunch of HTML to write for an application which now has a configuration page that nobody will ever find. There must be an easier way.

What you have to do is:

  • create a custom configuration class for your application (say MyAppCode.CustomConfigurationClass)
  • create a page that will hold the configuration of your application (Say MyApp.Configuration)
  • add an object of your custom configuration class (MyAppCode.CustomConfigurationClass) to the previous document (MyApp.Configuration)
  • add an object of the XWiki.ConfigurableClass to the same document (MyApp.Configuration)
  • set up the XWiki.ConfigurableClass object (see below) and voila!

Your application has now its own configuration form in the administration application where it belongs to.

The current user does not have edit access to any of the applications in the section at the bottom left so it displays "No Access".

How it works

You add an XWiki.ConfigurableClass object to your configuration document and add to it an object of the configuration class (your custom class) which you just defined. You also have to define the section in the administration application where your form should be displayed. When administrators go to the administration application, they will see your configuration form right where it ought to be. This is because the administration application queries the database for XWiki.ConfigurableClass objects and puts them at the right place. Administration application also takes care of generating the HTML form for you so all you have to do is define the custom configuration class.

What happens if I add more than one XWiki.ConfigurableClass object?

By using multiple ConfigurableClass objects which list different custom configuration classes but are set to display in the same section, you can make a single form with settings from multiple custom configuration objects. If instead you add multiple ConfigurableClass objects which are set to be configured in different sections, you can allow your application to be configured in different sections. You can even use the propertiesToShow field to determine which properties should be shown and which should be hidden in the form displayed by a given ConfigurableClass object.

ApplicationSubsections.png

Here you see the result of a single application with two ConfigurableClass objects. Each object is set to display in the same section (the section you see) and they both are set to use the same custom configuration class. Each object only displays two of the custom configuration class's four properties because they have propertiesToShow set. The values of the heading property for the two objects are set to "Section 1" and "Section 2". Also where it says "Test section" is customizable by adding a language pack.

Fields you can define

  • displayInSection (String) - Specifies the administration section that is used to configure your application. Administration sections are listed in the administration menu, grouped in categories (e.g. Rights, Localization, Themes). You can use this field to define a new administration section or you can specify an existing one (defined by some other ConfigurableClass object), in which case your configuration properties will be "appended" to the existing administration section under the specified heading (see below). If you need the section title translated, the value you add in this field will be used as a translation key, prefixed by admin..
  • heading (String) - You can add multiple ConfigurableClass objects to your document with different headings and the properties of each will be displayed under the heading. If you're only using a single ConfigurableClass object for your application then you should leave this blank, unless you want to reuse an existing administration section (see above). Also note that this field is evaluated, so if you need to translate a heading you can directly use $services.localization.render('someKey') as value.
  • configurationClass (String) - This is the name of the custom configuration class which you defined to hold the configuration parameters. If you leave this blank then no form will be created.
  • scope (Static list) -XWiki 13.7+ 

     Define where the configuration should be displayed. Possibles values are:

      • WIKI (displayed Wiki): the configuration will be displayed in the wiki administration (equivalent to true value in configureGlobally for older versions)
      • SPACE (displayed "Current space"): the configuration will be displayed in administration of pages that belongs to the current space (equivalent to false value in configureGlobally for older versions)
      • ALL_SPACES (displayed "All spaces"): the configuration will be displayed on administration of pages for any space, but not on the wiki administration. 
      • WIKI+ALL_SPACES (displayed "Wiki and all spaces"): the configuration will be displayed in all administration pages, be it the wiki administration or any page administration. 
  • linkPrefix (String) - The pretty names of the properties in your custom configuration object will be displayed on the administration page but most of the time those names are not enough of a description, if this is filled in, then each name will be a link to a page, the link will be the value of this field with the name appended (the name not the pretty name). If you set linkPrefix to www.xwiki.org/bin/view/Main/WebHome and the name of one of the configuration options is 'some_config_option' then the pretty name for that option will be a link to www.xwiki.org/bin/view/Main/WebHome#Hsome_config_option This field is evaluated so you may use velocity code eg: $xwiki.getURL('Space', 'Page') .
  • propertiesToShow (List) - If your custom configuration class contains properties which you don't want to display on the form, or if you need more than one ConfigurableClass object which point to the same custom configuration object, then you can fill this in with the names of the properties which should be displayed in the form. The properties will be displayed using their (translatd) pretty names. Since 7.1M1 you can also specify hints / descriptions to better document your displayed fields by adding a translation key of the following format: Space.ConfigurationClass_propertyName.hint. See the Localization Module for more details on translations.
  • codeToExecute (TextArea) - Suppose a simple form just isn't enough for your needs, you can enter Velocity script here and it will be executed. If you leave configurationClass blank, then this is the only code that will be executed and you are free to design your own form. It is important to know that if you do use the default form, codeToExecute is executed before the form is begun, however if you have multiple ConfigurableClass objects in the same application which are also shown in the same section of the administration application (perhaps with different headers) then codeToExecute of any ConfigurableClass object after the first will be executed inside of the form. This is because the administration application tries to do all configuration for one document in a single form to reduce the number of save buttons.
  • iconAttachment (String) - If your application is going to be configured in it's own section of the administration application and you want your own custom icon for that section, you simply attach the icon to the document which has the ConfigurableClass object and set this to the filename of the attachment.
  • displayInCategory (String) - Which administration category should your application be configured in. Administration categories group administration sections (e.g. Users & Rights, Editing, Search). You can specify an existing category to add your administration section to, or you can define a new administration category.
  • displayBeforeCategory (String) - Where to locate your new category in the administration menu (if it doesn't exist already). Your category will be displayed before the specified existing category. This is taken into account only for the ConfigurableClass object that defines the category (the one encountered first).
  • categoryIcon (String) - Specifies the icon to display before the category name in the administration menu. See the XWiki Icon Set for a list of supported values. This is taken into account only for the ConfigurableClass object that defines the category (the one encountered first).
  • sectionOrder (Number) - XWiki 6.4+ Controls the order of the administration sections within an administration category (as can be seen in the administration menu). A small number places the administration section at the top of its category, while a big number places it towards the end.

Accessing your configuration

  • In Groovy:
    Groovy example:
    def configObject = xwiki.getDocument("Mail.MailConfig").getObject("Mail.SendMailConfigClass")
    println configObject.getValue("port")

The value of port would be the value set in the configuration page, for example:

mailSend.png

Things to watch out for

  • If you save the configurable application page but you don't have access to the administration page, then your configurable application will not be displayed, instead an error message will tell the administrator that it couldn't be displayed because you couldn't be trusted to run code in the administrator's security context.
  • If somebody has administration access but does not have access to save the configurable application, they will get an error message telling them so.
  • If somebody has administration access but does not have access to view the configurable application then they will receive an error message on the front page of the administration application. This is because it is possible that not all of the icons could be displayed.
  • Documents are locked using Javascript, if the administrator has Javascript turned off then they will receive a warning that the configurable application could not be locked for editing.

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). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-administration-ui 16.9.0):

Get Connected