Application for administrating wiki features like users, groups, rights etc.

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).

Provided Features

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

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).

Edit Mode Settings

See also:

• Configuring the default editor

Localization

See also:

• The Internationalization page
• Writing Internationalized Applications
• Language Settings
• Date Format

Presentation

See also:

• Customizing the Skin

Page Elements

Users

Groups

Rights

See also:

• Authentication guide

Registration

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:

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.

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.
• 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.
• 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.)
• 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.

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:

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

User Profile

Import

Export

Templates

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

Creating templates

• To create a template go to the wiki homepage, click on "+" .
  
• Write the template content and save the document.
  
• This is what you will see at this stage:
  

Create the template provider

To do this go to the administration, then click on the "Templates" link.

On the "Templates" administration page you may:

• Create a Template Provider
• View the Available Template Providers

To create a Template Provider you will need to specify the Space & Page name and 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 (e.g. My Template Provider)
• The template name (e.g. My Template)
• The template to use (e.g. Main.MyTemplate)

Restrict the spaces where the template is available

Templates can be bound to one or more spaces. In this case the choice of creating a new document from those templates will be offered only in the selected spaces.

You can edit the previously created "Template Provider" and check for example the "Main" space:

Users will be offered the choice to create new documents from this template only in the Main space. If they try to edit the space they will be notified that the operation is not allowed.

Using the templates

• After you have created the template and the template provider you can go back to the Main space and start creating pages from this template:

  

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

  

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

  

Google Analytics

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:

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.

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.

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) - Which section should your application be configured in General? Registration? Rights? You can even define a section which doesn't already exist and a new icon will be displayed in the administration main page.
• 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 are only using a single ConfigurableClass object for your application, then you should leave this blank. Also note that this field is evaluated, so if you need to translate a heading you can directly use $services.translation.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.
• configureGlobally (boolean) - Set this true if your application should be configured in the global administration page and false if it should be configured in the administration page for the space which the application resides in.
• 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 category should your application be configured in. This allows to add a new section to an existing category or to create a new category altogether.
• displayBeforeCategory (String) - Where to locate your new category (if it doesn't already exist). Your category will be displayed before the specified existing category.
• categoryIcon (String) - The name of the icon to use when displaying the category in the vertical menu. The name should be a valid icon name in the Silk icon set.
• sectionOrder (Number) - Since XWiki 6.4 RC1 Control the order of the sections. Put a small number to be on the first sections displayed, or a big number to be at the end.

Accessing your configuration

• In Groovy:
  Groovy example:

  def customObject = xwiki.getDocument("MyApp.Configuration").getObject("MyApp.ConfigurationClass")
  def myAppUrl= customObject.getProperty("myAppUrl").value
  
  println "$myAppUrl"

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

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 7.2):

• org.xwiki.platform:xwiki-platform-rendering-macro-velocity 7.2
• org.xwiki.platform:xwiki-platform-rendering-macro-include 7.2
• org.xwiki.platform:xwiki-platform-localization-macro 7.2
• org.xwiki.platform:xwiki-platform-attachment-ui 7.2
• org.xwiki.rendering:xwiki-rendering-macro-html 7.2
• org.xwiki.rendering:xwiki-rendering-macro-message 7.2