Administration Application

Allows to administrate an XWiki Enterprise instance

Description

The administration application allows you to administrate an XWiki Enterprise instance's :

• General preferences
• Presentation preferences
• Users and groups management
• Rights management
• A lot more.

Screenshots

Verified Registration Page (Since Enterprise 2.2 M2 )

The verified registration page is the new default registration method for XWiki Enterprise. It supports image captchas supplied by the captcha module it also supports 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, starting in 2.3M1, you can do this from the Registration section of the wiki administration interface, if you are using 2.2, you will have to turn on captcha requirement in xwiki.properties see the Administration guide on Configuration.

Options you can set from the Registration section of the Administration Interface (Since Enterprise 2.3M1)

• 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 passoerd 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. NOTE: If using 2.2, captcha.enable must be set true in the xwiki.properties configuration file in xwiki/WEB-INF/

Things which you may configure by editing XWiki.Registration (If you are using version 2.2 then the above parameters are in the top section of XWiki.Registration as well.)

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

Making your application easily configurable with ConfigurableClass (Since Enterprise 2.3M1)

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 it's own configuration form in the administration application where it belongs to.

Note that 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 object of XWiki.ConfigurableClass to your configuration document and add to it an object of the configuration class (your custom class) which you just defined, you also define the section in the administration application where your form should be displayed. When administrators go to the administration application, they see your configuration form right where it ought to be. This is because the administration application queries the database for objects of the XWiki.ConfigurableClass 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 "admin.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.
• 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#H 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.
• 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.

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.

Templates Creation and Administration

Starting with XWiki Enterprise 2.4M2 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 and use the "Create Page" sub menu entry from the "Main" menu.

• 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" icon.

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 "Wanted Links" also offers the choice to create the new document from the available template ("My Template" template in the image below):

Prerequisites & Installation Instructions

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