From version < 27.2 >
edited by Clément Aubin
on 2019/09/30 17:10
To version < 28.1 >
edited by Anca Luca
on 2020/01/06 17:59
< >
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -xwiki:XWiki.caubin
1 +xwiki:XWiki.lucaa
Content
... ... @@ -246,7 +246,7 @@
246 246  * Verify that ##version## is set to 1.1
247 247  * Verify that ##comment## is empty
248 248  * Verify that ##minorEdit## is set to false
249 -* Verify that the ##defaultLanguage## is empty for technical documents or the configured language in the mojo (by default ##en##, it's configurable in the ##<configuration>##, for example ##<defaultLanguage>fr</defaultLanguage>##) 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:(((
249 +* Verify that the ##defaultLanguage## is empty for technical documents or the configured language in the mojo (by default ##en##, it's configurable in the ##<configuration>##, for example ##<defaultLanguage>fr</defaultLanguage>##) 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, content pages take precedence since 7.3; before 7.3 technical pages used to take precedence). For example:(((
250 250  {{code language="xml"}}
251 251  <plugin>
252 252   <groupId>org.xwiki.commons</groupId>

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:
    ...

      
        
          org.xwiki.commons
          xwiki-commons-tool-xar-handlers
          ...version here...
        
      
    ...
  • Create a Maven POM file with the xar packaging: xar
  • 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:

Insert a text value

This can work well, for example, to change skin definitions. E.g.:


 org.xwiki.commons
 xwiki-commons-tool-xar-plugin
 
   
     
       Blog/WebHome.xml
       /xwikidoc/object/property/itemsPerPage
       100
     
     
       org.xwiki.platform:xwiki-platform-administration-ui
       XWiki/XWikiPreferences.xml
       /xwikidoc/object/property/colorTheme
       ColorThemes.Mint
     
   
 

Manipulate XML elements

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


 org.xwiki.commons
 xwiki-commons-tool-xar-plugin
 
   
     
     
       org.xwiki.platform:xwiki-platform-distribution-ui-base
       XWiki/XWikiPreferences.xml
       xwikidoc
       INSERT_CHILD
       src/xar/transformations/ckeditor.xml
     
     
     
       org.xwiki.platform:xwiki-platform-distribution-ui-base
       xwikidoc/attachment
       REMOVE
     
   
 

Insert Text Content of a File

Since 11.4RC1 it is possible to insert the text of another project file. This works well to insert complex JavaScript, Velocity or CSS files. These files, if they are not named .xml  stay within the same directory and will be ignored unless they are inserted and can thus be edited with an integrated development environment (which brings syntax coloring, auto-completion, reformatting, or validation). Here is an example:


 org.xwiki.commons
 xwiki-commons-tool-xar-plugin
 
   
     
         
       INSERT_TEXT
       MyApp/Config.xml
       /xwikidoc/object[className[text()='XWiki.JavaScriptExtension']]/property/code
       src/main/resources/MyApp/config.js
    
   
 

Insert an Attachment

Since 11.4RC1 it is possible to insert the content of another project file as an attachment in Base64 encoding just as XWiki would do it in an XML file of a XAR. You can use this to insert files with the same name edited somewhere else. Doing so, it also updates the filesize attribute. Here is an example:


 org.xwiki.commons
 xwiki-commons-tool-xar-plugin
 
   
     
       
      INSERT_ATTACHMENT_CONTENT
      MyApp/TestDocumentList.xml
      src/main/resources/MyApp/testcolors.xls
    
   
 

Documents types

Since 10.3

It's possible to indicate in the pom.xml the type of a each document. That way the package.xml will be generated automatically but will take into account information it cannot really deduce from the documents XML files.

     
       org.xwiki.commons
       xwiki-commons-tool-xar-plugin
       
         
           
             Main.WebHome
             home
           
           
             Some.Demo.Page
             demo
           
           
             MyApplication.MyConfiguration
             configuration
           
         
       
     

You should only provide one <document> per <entry>. For example, the following configuration will not work :
     
     
       MySpace.MyPage1
       MySpace.MyPage1
       demo
     
   

  Instead, you should write :
     
     
       MySpace.MyPage1
       demo
     
     
       MySpace.MyPage2
       demo
     
   

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:

       org.xwiki.commons
       xwiki-commons-tool-xar-plugin
       ${commons.version}
       
         
         true
       
    • New in 7.3M1 Technical pages are marked hidden. To mark a page as technical use the technicalPages configuration element as in:

       org.xwiki.commons
       xwiki-commons-tool-xar-plugin
       ${commons.version}
       
         
           .*Translations\.xml
         
       
    • New in 10.8RC1 Remove any date, creationDate, contentUpdateDate or attachment date fields, regardless if they have empty values or not. This is done because it's causing confusion for users to install pages that are created in 2005/2009/etc. so we should avoid committing dates on git that users might end up installing.
      • Can be disabled for individual pages with either -Dxar.dates.skip.documentList=Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc. (system property) or Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc. (plugin configuration parameter).
      • Can be disabled for all pages in the xar with either -Dxar.dates.skip=true (system property) or true (plugin configuration parameter).

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 the configured language in the mojo (by default en, it's configurable in the , for example fr) 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:

     org.xwiki.commons
     xwiki-commons-tool-xar-plugin
    ...
     
    ...
       
       
         .*Translations\.xml
       
       
       
         EditTranslations\.xml
       
     
  • Verify that the defaultLanguage is empty for technical documents or the configured language in the mojo (by default en, it's configurable in the , for example fr) 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, content pages take precedence since 7.3; before 7.3 technical pages used to take precedence). For example:

     org.xwiki.commons
     xwiki-commons-tool-xar-plugin
    ...
     
    ...
       
       
         .*Translations\.xml
       
       
       
         EditTranslations\.xml
       
     
  • (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:

     org.xwiki.commons
     xwiki-commons-tool-xar-plugin
    ...
     
    ...
       
         
         
           .*WebPreferences
           \$services\.localization\.render\('admin.preferences.title'\)
         
       
     
  • New in 8.1M1 Verify that Translations pages (i.e. documents with a XWiki.TranslationDocumentClass xobject) are using the plain/1.0 syntax.
  • New in 10.1RC1 Verify that Translations pages don't have a GLOBAL or USER visibility (USER makes no sense and GLOBAL would require Programming Rights, which is an issue in farm-based use cases). This check can be ignore by using the translationVisibilitySkip configuration option (or xar.verify.translationVisibility.skip on the command line).
  • New in 10.6RC1 Verify that attachments have a mimetype set. If the mimetype is missing then the attachment won't be filterable in the attachment view in Page Index.
  • New in 10.8RC1 Verify that any date, creationDate, contentUpdateDate or attachment date fields are not specified, thus risking to import pages with stale dates.
    • Can be disabled for individual pages with either -Dxar.dates.skip.documentList=Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc. (system property) or Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc. (plugin configuration parameter).
    • Can be disabled for all pages in the xar with either -Dxar.dates.skip=true (system property) or true (plugin configuration parameter).

Example usage:


 org.xwiki.commons
 xwiki-commons-tool-xar-plugin
 
   
     
       verify
     
   
 

To skip the execution of the verify mojo, you can use the property xar.verify.skip with the value true.

UnXAR Mojo

To configure it:


 org.xwiki.commons
 xwiki-commons-tool-xar-plugin
 
   ...group id of XAR artifact to expand...
   ...artifact id of XAR artifact to expand...
   ${project.build.outputDirectory}
   
     Space/Page.xml
      ...
   
   
     Space/Page.xml
      ...
   
 

To use it:

  • mvn unxar will expand the XAR file

Get Connected