Changes for page Flavor API

Last modified by Admin on 2020/09/04 13:09

From version < 27.67 >
edited by Admin
on 2019/11/25 15:49
To version < 28.1 >
edited by Vincent Massol
on 2019/11/28 16:23
< >
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -xwiki:XWiki.Admin
1 +xwiki:XWiki.VincentMassol
ExtensionCode.ExtensionClass[0]
Description
... ... @@ -29,7 +29,6 @@
29 29   </properties>
30 30  {{/code}}
31 31  
32 -
33 33  === Known invalid flavors
34 34  
35 35  Since 9.5 it's possible for a distribution to indicate known invalid flavors, which means flavors id known to be invalid with this distribution (a good example is XWiki Enterprise which are invalid in 9.5+).
... ... @@ -126,3 +126,20 @@
126 126   </build>
127 127  </project>
128 128  {{/code}}
128 +
129 +=== Testing ===
130 +
131 +To test a flavor you're developing follow these steps:
132 +* Build the flavor: ##mvn clean install##
133 +* Edit the ##META-INF/extension.xed## file inside the XWiki WAR you're testing with and add your flavor id and version to the list
134 + of known flavors. Note that this is a hack since normally the canonical way would be to deploy the flavor in a
135 + searchable XWiki Extensions Repository but that's a lot more complex and time-consuming.
136 + * Modify the `<xwiki.extension.knownFlavors>` tag to add the flavor id and version. For example if you wish to test the ##org.xwiki.contrib:flavor-demo/1.1-SNAPSHOT## flavor:(((
137 +{{code language='xml'}}
138 + <xwiki.extension.knownFlavors>
139 + org.xwiki.platform:xwiki-platform-distribution-flavor-mainwiki/11.10,
140 + org.xwiki.platform:xwiki-platform-distribution-flavor-wiki/11.10,
141 + org.xwiki.contrib:flavor-demo/1.1-SNAPSHOT</xwiki.extension.knownFlavors>
142 +{{/code}}
143 +* Add your local Maven repository as an Extension repository in the XWiki instance.
144 +* Start or restart XWiki.
lorryAPI to get flavors from the repositories.
TypeJAR
Developed by

XWiki Development Team

Active Installs0
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

Description

XWiki offers different Flavors. A Flavor is a collection of applications. When you install a Flavor, you get a wiki fully configured for a use-case.

This system is mostly visible since XWiki 9.5 which strongly rely on it.

Flavor picker

In some places, you will see the Flavor picker, which is designed to make you chose a Flavor between the extensions available in your repositories. Since 8.1 flavors are also searched in local repository.

flavor-picker.png

Valid flavors

Since 8.0 the Flavor picker won't display all flavors found on various repositories right away. Instead it starts a background job which validate each flavor and find the right version for your distribution. You will see a progress bar and the valid flavor will be automatically added once found.

Known flavors

Since 8.1 it's possible for a distribution to indicate known flavors, which means flavors id and version known to be valid with this distribution. Its usually flavors in sync with the distribution itself or well known like XWiki Flavor or XWiki Enterprise Flavors.

In a Maven project it must be indicated the pom.xml of the distribution package (or its parent) the following way:

 
   
   
        org.xwiki.platform:xwiki-platform-distribution-flavor/${project.version},
        org.xwiki.enterprise:xwiki-enterprise-ui-mainwiki/${project.version},
        org.xwiki.enterprise:xwiki-enterprise-ui-wiki/${project.version}
   
 

Known invalid flavors

Since 9.5 it's possible for a distribution to indicate known invalid flavors, which means flavors id known to be invalid with this distribution (a good example is XWiki Enterprise which are invalid in 9.5+).

In a Maven project it must be indicated the pom.xml of the distribution package (or its parent) the following way:

 
   
   
        org.xwiki.enterprise:xwiki-enterprise-ui-mainwiki,
        org.xwiki.enterprise:xwiki-enterprise-ui-wiki
   
 

How to create a Flavor

This part is technical and designed for technical users.

Technically, a Flavor is nothing but a simple Extension with category flavor (as in flavor in Maven), which depends on other Extensions.

Usually it's a XAR (but it does not have to) with a few Flavor specific pages like the home page and dependencies on various applications.

You might be interested by creating a project in the XWiki Contrib space.

Here is an example of a Flavor, built with Maven:


xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 4.0.0
 
   org.xwiki.commons
   xwiki-commons-pom
   7.1-milestone-2
 
 org.xwiki.contrib
 my-flavor
 My Flavor
 xar
 Description of my Flavor
 
   
   flavor
 
 
   
   
     org.xwiki.enterprise
     xwiki-enterprise-ui-wiki
     ${commons.version}
     xar
     runtime
   
   
   
     org.xwiki.contrib
     xwiki-macro-pdfviewer
     1.4
     xar
     runtime
   
   
   
     org.xwiki.contrib
     application-filemanager-ui
     2.0-rc-1
     xar
     runtime
   
 
 
   
   
     
       org.xwiki.commons
       xwiki-commons-tool-xar-handlers
       ${commons.version}
     
   
   
     
     
       org.xwiki.commons
       xwiki-commons-tool-xar-plugin
       ${commons.version}
     
   
 

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 manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-flavor-api 11.10):

Testing

To test a flavor you're developing follow these steps:

  • Build the flavor: mvn clean install
  • Edit the META-INF/extension.xed file inside the XWiki WAR you're testing with and add your flavor id and version to the list
      of known flavors. Note that this is a hack since normally the canonical way would be to deploy the flavor in a
      searchable XWiki Extensions Repository but that's a lot more complex and time-consuming.
  • Modify the `` tag to add the flavor id and version. For example if you wish to test the org.xwiki.contrib:flavor-demo/1.1-SNAPSHOT flavor:
     
        org.xwiki.platform:xwiki-platform-distribution-flavor-mainwiki/11.10,
        org.xwiki.platform:xwiki-platform-distribution-flavor-wiki/11.10,
        org.xwiki.contrib:flavor-demo/1.1-SNAPSHOT
    • Add your local Maven repository as an Extension repository in the XWiki instance.
    • Start or restart XWiki.

    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 manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

    Dependencies

    Dependencies for this extension (org.xwiki.platform:xwiki-platform-flavor-api 11.10):

Get Connected