Wiki Flavor Application

Last modified by Thomas Mortagne on 2017/03/28 15:10

worldManage a list of flavors for the creation of new wikis.
TypeXAR
Developed by

Guillaume Delhumeau

Active Installs23
Rating
Rate!
6 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

Description

In 7.1M2, this application has been replaced by the Flavor Module which is supported by the XWiki Dev Team. The current application was written as a temporary solution by its author.
However, the current status of the Flavor Module is not enough complete for some needs. That is why it has been maintained for the versions 7.4.x.

This application let the user chose a "flavor" when she creates a new wiki. A "flavor", is a wiki configured with a collection of applications corresponding to a theme. For example, you can have a flavor about a Knowledge Base, with all applications installed to manage such a wiki.

Create a new flavored wiki

Go to "Create Wiki".

CreateFlavoredWiki.png

Here you can select a flavor for the wiki you are going to create. Fill the form like you would have done with the Wiki Manager Application, select the flavor, and click "next".
In the second form, select all parameters concerning the users, and then click "create".

By default, this application comes with no bundled flavors. You have to create them.

You will have a screen about the creation of the wiki:
FlavoredWikiCreation.png

Just wait for the creation of the wiki. At the end of the process, there is no "finalize" button anymore, but a "access the wiki" instead.

Add new flavors

This section is a bit technical and mostly designed to be used by developers who are used to the maven infrastructure.

To add new flavors, in the wiki, go to the "Wiki Flavors" application, using the icon in the applications panel:

WikiFlavorsIcon.png

To access this application, you need to have the administration right. Otherwise, anybody would be able to add new flavors to the wiki, including undesired ones. You can change this configuration by changing rights on the "WikiFlavors" space.

You will have the following screen:

WikiFlavorsApp.png

Again, by default, this application is empty.

Click to "add a new entry", and enter a name.

You will reach the following screen:

WikiFlavorsEntry.png

Fill the form. Extension ID is the maven id of the extension that you want to use as Flavor. This extension must have all the applications that it should contain as dependencies.

Then save it.

You now need to create a translation page, to add the new translation keys you just have created. Create a new page and call it "Translations":

WikiFlavorsCreateTranslations.png

Write your new translations keys, like this:
WikiFlavorsTranslations.png
and save the document.

Now go to the "object" editor to add a TranslationDocumentClass object with the scope "Wiki":
WikiFlavorsTranslationObject.png
and save it.

Now you can go back to the wiki creation page, and enjoy your new flavor:
CreateFlavoredWiki2.png

Note that if you create templates, they will be listed there as flavors too.

To avoid problem with the Programming Rights, the flavor is installed with the "superadmin" user, and all the pages will inherit its rights. So be very careful when you decide to add an extension as flavor because it can be a serious security problem.

We suggest you to create a default flavor for the classic XWiki Enterprise UI for subwikis.
The extension ID is: org.xwiki.enterprise:xwiki-enterprise-ui-wiki

How to create a new flavor

See: How to create a new flavor.

For developers: Add an extra step during the wiki creation

This part is valid for version 1.x. Since 2.x, you should look at the Flavor Module instead because the application is based on it.

Implement the step

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 step.
     * @param request wiki creation request with all information about the wiki to create
     * @throws WikiFlavorException if problem occurs
     */

   void execute(WikiCreationRequest request) throws WikiFlavorException;

   /**
     * The creation steps are sorted by order before being executed so this method returns the one of the current step.
     * @return the order of the step
     */

   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

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 WikiFlavorsCode.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.wikiflavor.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.wikiflavor.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

Be careful to install this extensions after the Wiki Application because it overwrites some of its pages.

Release Notes

v2.2

  • Bug Closed FLAVOR-17 The template description is not displayed anymore in the create wiki form

v2.1

  • Bug Closed FLAVOR-15 The Wiki Flavor Application does not record the installed flavor anymore

v2.0

This version is a big jump on the API side, that is why we have changed the version number.

This version is no longer compatible with XWiki 6.4.x. Please use the last 1.x version if you are interested in running this application in an older XWiki.

  • Improvement Closed FLAVOR-14 Make the application compatible with XWiki 7.4.x

v1.6

  • Bug Closed FLAVOR-13 Unable to create a wiki if a deleted wiki had the same name
  • Bug Closed FLAVOR-12 Sometimes the progress bar is not displayed
  • Bug Closed FLAVOR-11 Wiki owner is not properly assigned on wiki creation

v1.5

  • Bug Closed FLAVOR-9 The WikiProvisionedEvent is not sent
  • Bug Closed FLAVOR-8 The link to the created wiki is wrong in the final step of the wizard
  • Improvement Closed FLAVOR-3 Add unit tests to the Wiki Flavor Application

v1.4

  • Bug Closed FLAVOR-7 Impossible to create subwikis if the browser's cache is not cleaned after creating subwikis with the standard application

v1.3

  • Improvement Closed FLAVOR-4 Add functional tests to the Wiki Flavor Application

v1.2

  • Bug Closed FLAVOR-6 DW does not select the good extensions for flavored wikis during an upgrade (in step 2: wikis)

v1.1

  • Bug Closed FLAVOR-5 A user can create a wiki via the script service without the CREATE_WIKI right.
  • Improvement Closed FLAVOR-2 Handle exceptions in the flavor script service

v1.0

  • Task Closed FLAVOR-1 Commit the first version of Wiki Flavor Application

Dependencies

Dependencies for this extension (org.xwiki.contrib:application-wikiflavor-ui 2.2):

Tags:
Created by Guillaume Delhumeau on 2015/01/29 17:42
    

Get Connected