This build tool allows creating XAR files, expanding XAR files, reformatting them and verifying some best practices.

XAR Mojo

To configure it:

  • Register a new Maven Lifecycle in your POM:
    ...
    <build>
      <extensions>
        <extension>
          <groupId>org.xwiki.commons</groupId>
          <artifactId>xwiki-commons-tool-xar-handlers</artifactId>
          <version>...version here...</version>
        </extension>
      </extensions>
    ...
  • Create a Maven POM file with the xar packaging: <packaging>xar</packaging>
  • Put the wiki pages as XML files in src/main/resources by having directories matching space names. For example:

    structure.png

To use it:

  • mvn xar:xar will generate the XAR file

Transformations

It is also possible to perform transformations on the XML files. For example:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <transformations>
     <transformation>
       <file>Blog/WebHome.xml</file>
       <xpath>/xwikidoc/object/property/itemsPerPage</xpath>
       <value>100</value>
     </transformation>
     <transformation>
       <artifact>org.xwiki.platform:xwiki-platform-administration-ui</artifact>
       <file>XWiki/XWikiPreferences.xml</file>
       <xpath>/xwikidoc/object/property/colorTheme</xpath>
       <value>ColorThemes.Mint</value>
     </transformation>
   </transformations>
 </configuration>
</plugin>

Since 9.5RC1 it's possible to remove/replace/insert a complete XML element. Here is an example:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <transformations>
     <!-- Insert the content of file src/xar/transformations/ckeditor.xml as child of xwikidoc element in XWiki/XWikiPreferences.xml -->
     <transformation>
       <artifact>org.xwiki.platform:xwiki-platform-distribution-ui-base</artifact>
       <file>XWiki/XWikiPreferences.xml</file>
       <xpath>xwikidoc</xpath>
       <action>INSERT_CHILD</action>
       <xml>src/xar/transformations/ckeditor.xml</xml>
     </transformation>
     <!-- Remove first attachments from XWiki/XWikiPreferences.xml -->
     <transformation>
       <artifact>org.xwiki.platform:xwiki-platform-distribution-ui-base</artifact>
       <xpath>xwikidoc/attachment</xpath>
       <action>REMOVE</action>
     </transformation>
   </transformations>
 </configuration>
</plugin>

Format Mojo

To use it:

  • mvn xar:format will perform some cleaning of your XML files, namely:
    • Indent lines (using 2 space characters)
    • Set author, contentAuthor, creator and attachment authors to be xwiki:XWiki.Admin
    • Set version to be 1.1
    • Set minorEdit to be false
    • Remove any content of the defaultLanguage element unless the document has translations. Indeed, if a document has translation we assume it means the document is not a technical document and thus we set the default language to be English. This allows the XWiki SOLR Search to return results when the English language is selected in language facet.
    • Remove any content of the comment element
    • New in 5.4RC1 Add any missing license header by using the license defined in xwiki-commons-tool-verification-resources JAR. License headers will be checked if the formatLicense configuration parameter is set to true:
      <plugin>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
       <version>${commons.version}</version>
       <configuration>
         <!-- Add missing license headers by default -->
         <formatLicense>true</formatLicense>
       </configuration>
      </plugin>
    • New in 7.3M1 Technical pages are marked hidden. To mark a page as technical use the technicalPages configuration element as in:
      <plugin>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
       <version>${commons.version}</version>
       <configuration>
         <technicalPages>
           <technicalPage>.*Translations\.xml</technicalPage>
         </technicalPages>
       </configuration>
      </plugin>

Verify Mojo

This is used to fail the build if the XML pages don't conform to the following rules:

  • Verify that the encoding is UTF-8
  • Verify that author, contentAuthor, creator and attachment authors are set to xwiki:XWiki.Admin
  • Verify that the parent field is not empty (except for Main.WebHome)
  • Verify that version is set to 1.1
  • Verify that comment is empty
  • Verify that minorEdit is set to false
  • Verify that the defaultLanguage is empty for technical documents or en for documents having translations (which we assume are not technical documents). If a page has translations then we consider it as a content page, otherwise we consider it a technical document. Note that since version 7.1 it's possible to provide a white list of content and technical pages (when both are specified and matching, technical pages take precedence). For example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
    ...
     <configuration>
    ...
       <!-- Consider all pages named *Translations as content pages by default -->
       <contentPages>
         <contentPage>.*Translations\.xml</contentPage>
       </contentPages>
       <!-- The EditTranslations page is not a Translation page and thus not a content page! -->
       <technicalPages>
         <technicalPage>EditTranslations\.xml</technicalPage>
       </technicalPages>
     </configuration>
    </plugin>
  • (optional) Verify that the XML files contain license headers (if the formatLicense configuration property is set to true).
  • New in 7.3M1 Verify that Technical pages are set as hidden. See the Format mojo above.
  • New in 7.3 Verify that defined pages have a specific matching title. For example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
    ...
     <configuration>
    ...
       <titles>
         <!-- Verify that all WebPreferences pages have the same title for consistency -->
         <property>
           <name>.*WebPreferences</name>
           <value>\$services\.localization\.render\('admin.preferences.title'\)</value>
         </property>
       </titles>
     </configuration>
    </plugin>
  • New in 8.1M1 Verify that Translations pages (i.e. documents with a XWiki.TranslationDocumentClass xobject) are using the plain/1.0 syntax.

Example usage:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <executions>
   <execution>
     <goals>
       <goal>verify</goal>
     </goals>
   </execution>
 </executions>
</plugin>

UnXAR Mojo

To configure it:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <groupId>...group id of XAR artifact to expand...</groupId>
   <artifactId>...artifact id of XAR artifact to expand...</artifactId>
   <outputDirectory>${project.build.outputDirectory}</outputDirectory>
   <includes>
     <include>Space/Page.xml</include>
      ...
   </includes>
   <excludes>
     <exclude>Space/Page.xml</exclude>
      ...
   </excludes>
 </configuration>
</plugin>

To use it:

  • mvn unxar will expand the XAR file
Tags:
Created by Vincent Massol on 2013/10/28 11:18
   

Get Connected