Administration Application

Administration Application

The administration application allow to administrate an XWiki Enterprise instance.

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.

• 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.
• Any other page you have modified, such as XWiki.XWikiUserSheet, XWiki.DefaultSkin, etc.

Screenshots

Verified Registration Page (Since 2.2M2)

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 turn on captcha requirement in xwiki.properties see the Administration guide on Configuration.

You can configure the registration page by editing the upper section of the document XWiki.Registration.

Configuration options you can set

• 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.
• Use LiveValidation (Default: Yes)
  Set this to false and LivaValidation javascript will not be generated (fields will still be validated at the server side.)
• LiveValidation default field ok 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.
• 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.
• Automatic Login (Default: No)
  If login button is enabled, then you can have a piece of Javascript push the login button for the user.
• Default Redirect (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.
• Failure message parameters (Default: Same parameters as LiveValidation failure message)
  This is where you can set the style, class, etc. of the failure messages which the server supplies. If you are using LiveValidation, you should edit the LiveValidation CSS file instead.

Configuration keys which you may use to configure a field.

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.

## 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

Making your application easily configurable with ConfigurableClass (Since 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.

You create a configuration class for your application, add an object of that class, then instead of creating your own form you add an object of the ConfigurableClass to the same document as your custom configuration object. You set up the Configurable object and voila, your application has it's own configuration form in the administration application where it belongs.

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 ConfigurableClass to your document and direct it to load an object of the configuration 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 ConfigurableClass and puts them in the proper place. The 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 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/bin/Page/Applications/Space#
• 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.