Wiki Application

Last modified by Admin on 2024/07/29 19:42
houseManage subwikis: create and delete subwikis, invite members
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

  Download v16.6.0SourcesIssues

Table of contents

Description

This application provides an integrated user interface to create new wikis in system, manage them and how user can interact with them.

Create a new wiki

To create a wiki, you need to go to the Wiki Index (using the drawer menu) and then click on the "Create Wiki" button:

CreateWiki.png

A wizard helps you to create the wiki:

wizard-wiki.png

If the Flavor Module is installed, you will get the following wizard:

createwiki-flavors.png

This wizard will allow you to select a flavor to install in the wiki, or to use a template as before. You can even create an empty wiki if you wish!

In the second step, you will select how users can participate to the wiki. Is it open to everyone or does it an invitation? You will also select what kind of users are allowed (local users, specific to that wiki? Global users, that can go to other wikis of the system? Both?).

wizard-user-scope.png

Then you will have a screen with a progress bar and a logging area that explains what is going on:

WikiCreationStep.png

You just have to wait for the end of the process, and you will see a success message and a button that invites you to go to the new created wiki.

WikiCreationStepEnd.png

For versions < 7.0M2:

After the second step, if you have not selected a template during the first step, you will see the Distribution Wizard, that will propose you to install the default application for wiki, called "XWiki Enterprise UI - Wiki". All you have to do is to click on "install" and to follow the instructions.

dw.png

Otherwise, if you have selected a template, you will see a progress bar which indicates that the newly created wiki is provisionning by the system. You just have to wait until it completes, and then you can click on "finalize", to make the wiki perfectlly created.

wizard-provisioning.png

By default, the new wiki is configured to be viewable (but not editable) to any global user who is not a member of that wiki. You can change this setting in the administration of the wiki.

Guest users will have the right to see the subwiki only if they can see the main one. Again, you can change this setting in the administration of the wiki.

Menus and Wiki Index

Before 8.4.3;

A new "Drawer" menu is displayed (and replace the "Wiki" menu on the main wiki), that permits to browse existing wikis and manage the main wiki (users, documents, administration...).

mainwiki-homemenu.png

On the new wikis, the owner of the wiki and the global administrators can delete this wiki:

delete-wiki.png

On the "Drawer" menu, you can browse the wikis with the "Wiki Index":

wiki-index.png

Only the wikis that the user can access are displayed. It means:

  • wikis where the user has the VIEW right.
  • wikis that the user can join or ask to join.
    The other wikis will not be visible.

Note that currently the Home menu is not displayed on a subwiki where local users are enabled. The idea is to make this type of wikis "isolated" from the others. In the future, we plan to add an option to enable or disable the home menu display independently of whether there are local users or not.

descriptor.png

Templates

A template is a wiki that will be considered as a model to create new wikis. When a user select a template to create a new wiki, all the content of the template is copied in the new wiki.

To create a new template, just click on "this wiki will be a template" in the wizard when you create a wiki.

wizard-new-template.png

To see the list of existing templates, you can go to the "Wikis > Templates" section of the global administration (in the "Drawer" menu):

admin-wiki-template.png

Rights

By default, only admins are able to create new wikis. You can decide to give this rights to other users in the "Wikis > Creation Rights" section of the global administration (in the "Drawer" menu):

wiki-creation-rights.png

How to join a wiki

When a user wants to join a wiki, she just have to go on the "Wiki Index". Then, if the wiki is open to new users, there is link in the last column of the table to join the wiki. Depending of the configuration, she may have to perform a "join request", where she is invited to write a little text to explain why she wants to join the wiki.

join-request.png
join-request-2.png

Then, her candidacy could be seen by the administrator of the wiki in the "users" section of the administration. The admin have the ability to accept or refuse the candidacy, and to write a message to the user to explain her decision. A private message is also proposed to store a comment about this candidacy, that the candidate will not see.

candidacies.png

Invite someone on a subwiki

The administrator have the ability to add or simply to invite a user to join a wiki. It can be done in the "users" section of the administration of that wiki.

invite.png

Wiki Alias

Since XWiki 5.4.4, when you create the wiki without the "Path based" system to generate the URL of your wiki, the "Alias" of the wiki will be prompted in the creation wizard:

wikialias.png

You can choose the domain suffix to use (instead of letting XWiki compute a default alias) by setting the following property in your xwiki.properties:

wiki.alias.suffix=mydomain.com

Then, if you create a wiki called "test", the suggested alias will be "test.mydomain.com".

You can change your wiki alias (and add some others) by clicking on the "edit" link associated to the wiki in the Wiki Index.

Configure Wiki

A "Wikis > Descriptor" section can be found in the Administration UI where you can configure the current wiki, whether it is the main wiki or a subwiki.

The things you can change in this section are mostly the ones you've specified when you have created the wiki:

  • Pretty Name
  • Description
  • Owner (can be changed only by the current owner or user with edit rights on the wiki's descriptor, usually global admin)
  • Homepage

Changing the home page has the following effect:

  • When clicking on the logo, you'll be redirected to the new home page
  • When clicking the home icon in the breadcrumb, you'll be redirected to the new home page

wikiDescriptorEditingAdministration-cropped.png

Delete a Wiki

You can delete existing wikis by clicking on the corresponding "Delete" link in the Actions column of the wiki index.
Since 7.0 you will be asked on the confirmation screen to type in the wiki identifier for the wiki you want to delete: 

delete-wiki-confirm-screen.png

This is to prevent wiki deletion by accident, as unlike most delete actions there is no undo for deleting wikis. (If this still happens you need to recover from a backup.)

"Wikis" Macro

This applications comes with a macro that lists available wikis:

WikisMacro.png

Since 6.4.1, it only lists the wikis that the user can access (ie having the "view" right on it).

To use it, edit a page, and with the WYSYWIG editor, go to "Macro > Insert Macro". In the modal window, select the "Navigation" category. There you will see the "Wikis" macro. Select it and click "Insert Macro". There is no parameter.

WikisMacroInsert.png

Or to use this macro in the wiki editor, just write:

{{wikis/}}

Delegate database creation

XWiki 14.9+

By default XWiki will create the database/schema/user (the created object depends on the DB used) when creating a new wiki. However there are cases where you could wish to control that creation yourself (or more precisely that it be done by a DBA or infra admin).

For this case, you can configure the following property from xwiki.properties and XWiki will not try to create the database/schema/user when using the Wiki creation wizard.

wiki.createDatabase = false

Specifically, this is how it's supposed to be used when you want to create a new wiki (in the following order):

  • A DBA creates the new database, or new schema, or new user (that depends on the database.
    • For Derby/DB2/H2 or PostGreSQL (in schema mode) this means creating a new schema, e.g. CREATE SCHEMA <schema name>
    • For HSQLDB this means creating a new schema, e.g. CREATE SCHEMA <schema name> AUTHORIZATION DBA
    • For MYSQL, this means creating a new database, e.g. CREATE DATABASE <db name> CHARACTER SET <character set> COLLATE <collation name>
    • For Oracle this means creating a new user, e.g. CREATE USER <user name> IDENTIFIED BY <user password> QUOTA UNLIMITED ON USERS
  • Then an XWiki user with Admin rights goes to the Create Wiki UI and creates the new wiki using the created database name, schema name or user name specified in the previous step.

Upgrade from XWiki Enterprise Manager

If you currently runs an old XWiki Enterprise Manager (XEM), you should know that the XWiki Development Team has stopped the development of that product. We have decided that because since the version 5.2, XWiki Enterprise comes with the ability to create new wikis, which was the precisely the purpose of XEM. So, we don't need XEM anymore.

To upgrade from a XEM, you just have to replace the webapp by an XWiki Enterprise WAR, that bundle the Wiki Application by default. Then, when you go the wiki with an administrator account, you will see the Distribution Wizard. Just follow the typical steps to upgrade your main wiki.

Then, the wizard will propose you to upgrade the subwikis also. You can upgrade all the wikis at once, or one by one, when you first go to them.

Here the screenshot of what you see if you select to upgrade all the wikis at once:

dw-wikisStep.png

For developers

Script Services

If you want to make your own applications using the wiki management APIs, the following scripting services are available for handling wikis:

Add an extra step during the wiki creation (since 7.0M2)

If you are a Java or a Groovy developer, you can easily add actions to perform during the creation of a new wiki.

Currently, the process is split in 4 different steps, that are executed successively:

  • Create Wiki that only create a new empty wiki. (Order: 1000)
  • Save Metadata that saves the information about the wiki owner, the user scope, the id of the flavor used, etc... (Order: 2000)
  • Provision Wiki that fills the wiki with a flavor or a template. (Order: 3000)
  • Add Users that adds the global users that are members of the wiki. (Order: 4000)

It is possible to add new steps everywhere in the process. To do that, you have to create a new component of the WikiCreationStep role (see how to write a new component).

/**
 * Step to be executed during the wiki creation job.
 */
@Role
public interface WikiCreationStep
{
 /**
  * Execute the steps.
  * @param request wiki creation request with all information about the wiki to create
  * @throws WikiCreationException if problem occurs
  */
 void execute(WikiCreationRequest request) throws WikiCreationException;

 /**
  * The creation steps are sorted by order before being executed so this method returns the one of the current steps.
  * @return the order of the steps
  */
 int getOrder();
}

The getOrder() method returns an number that determines when the step should be executed. For example, if you want your step to be executed between CreateWiki (order 1000) and Save Metadata (order 2000), your method should return a number between 1000 and 2000.

The execute() method contains the code to execute when the step is processed. It takes a WikiCreationRequest parameter that holds the information about the creation of the wiki (eg: the id of the wiki, the pretty name, etc...). It can actually hold all the information you want, since it has generic setProperty() and getProperty() methods.

Customize the Wiki Creation Wizard  (since 7.0M2)

Currently, there is no way to properly customize the wizard. The only thing you can do is editing it (it's only velocity code) to add your features. The page to edit is WikiManager.CreateWiki.

The interesting thing is that you can store some settings in the WikiCreationRequest object that your step can re-use.

This is how the wiki creation request is created and how you can add your properties:

## We create a new WikiCreationRequest object
#set($wikiCreationRequest = $services.wiki.creationjob.newWikiCreationRequest())

## Set some properties
#set($discard = $wikiCreationRequest.setWikiId($request.wikiname))
#set($discard = $wikiCreationRequest.setOwnerId($request.ownerId))
#set($discard = $wikiCreationRequest.setUserScope($request.userScope))

## Add your own parameters
#set($discard = $wikiCreationRequest.setProperty("myProperty", "some value"))
#set($discard = $wikiCreationRequest.setProperty("myOtherProperty", $request.myOtherProperty))
## etc, etc...

## Finally, start the wiki creation process (it is done asynchronously, in a job)
#set($job = $services.wiki.creationjob.createWiki($wikiCreationRequest))

In the code of your step, you can re-use these parameters:

@Override
public void execute(WikiCreationRequest request) throws WikiFlavorException
{
  String myProperty = (String) request.getParameter("myProperty");
  String myOtherProperty = (String) request.getParameter("myOtherProperty");

 // It could actually be any kind of object
  Integer myIntegerProperty = (Integer) request.getParameter("myIntegerProperty");
 // etc, etc...
}

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-wiki-ui-mainwiki 16.6.0):

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected