cogFilter stream extension to read and write wiki pages on the filesystem
TypeJAR
Developed by

XWiki Development Team

Active Installs0
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Installable with the Extension Manager

Description

Filter stream extension to read and write wiki pages on the filesystem.

This extension make use of the Filter module and the XSD Schema of XWiki.

Here is a list of the few useful tools to play with XFF format:

XFF filter (the current page)
Parse the XFF format through the Filter Module.  This is where you'll get details about XFF format.
XFF REST API
Offer a RESTful API to import an XFF file
XFF Maven Plugin
An Maven plugin to build XFF package from sources, similar to what is doing the XARPlugin

What is XFF?

XFF stands for XWiki Filesystem Format.  This is a new possible representation of XWiki on your hard-drive, like you can do with XAR format.

Why XFF?

XAR is an old legacy format.  It has its advantages like being fully compliant with the XWiki structure, containing every bit of information needed.  But in the other hand, the XML is difficult to handle for a human and it doesn't allow to split significant part of information like creating a Javascript file for XWiki.JavaScriptExtension content, or storing the attachments as separate files (and not in unreadable Base64 encoding).

Format

Let's define this format now.  The important thing to know about this format is that a wiki page is split into pieces.  The other important thing about it is that it's based on the XSD Schema of XWiki; you may find interesting information about this XSD Schema in the documentation of the XWiki RESTful API which has been designed around it.  See the following structure and the following explanations.

wikis/
├── xwiki/
│   ├── wiki.xml                                            (1)
│   └── spaces/
│       ├── MySpace/                                        (2)
│       │   └── pages/
│       │       ├── MyPage1/                                (3)
│       │       │   └── page.xml                            (4)
│       │       └── MyPage2/
│       │           └── page.xml
│       └── Space/
│           ├── space.xml                                   (5)
│           ├── pages/
│           │   └── Page/
│           │       ├── page.xml
│           │       ├── attachments/                        (6)
│           │       │   ├── logo1.png                       (7)
│           │       │   └── logo2.png
│           │       ├── class                               (8)
│           │       │   ├── class.xml                       (9)
│           │       │   └── properties/                     (10)
│           │       │       └── answer                      (11)
│           │       │           └── customDisplay.xwiki21   (12)
│           │       ├── properties/                         (13)
│           │       │   └── content.xwiki21                 (14)
│           │       └── objects/                            (15)
│           │           ├── Space.Page/                     (16)
│           │           │   └── 0/                          (17)
│           │           │       └── object.xml              (18)
│           │           └── XWiki.StyleSheetExtension/
│           │               └── 0/
│           │                   ├── properties/             (19)
│           │                   │   └── code.css            (20)
│           │                   └── object.xml
│           └── spaces/
│               └── SubPath/     
│                   └── pages/                              (21)
│                       └── SubPage/
│                           └── page.xml
└── templatewiki/                                           (22)
    └── wiki.xml
  1.  This is an XML representation of a <wiki> according to the XSD Schema of XWiki, see below for an example of this format
  2. This is the name of the space, pretty much the same structure than for XAR format
  3. Here is the first change with XAR format, the page is not an XML file but a folder
  4. This is an XML representation of a <page> according to the XSD Schema of XWiki, see below for an example of this format
  5.  This is an XML representation of a <space> according to the XSD Schema of XWiki, see below for an example of this format
  6. For storing attachments, create an attachments folder into your page folder
  7. Now, you can just put the files you want as an attachment
  8. If you want the page to be also a class, you can create a class folder
  9. This is an XML representation of a <class> according to the XSD Schema of XWiki, see below for an example of this format
  10. The _metadata folder is for specific customization on the class
  11. Create a folder with the name of the property you want to customize
  12. The name of the file is the name of the specific field of the property answer you want to customize (use the extension you want)
  13. This _metadata is for customizing the page
  14. For example, this is where you can put the content of your wiki page (it will replace the <content> from the _page.xml)
  15. To put objects in your wiki page, create a objects folder
  16. For each kind of object you want, create a sub-folder that you could name after the class ID
  17. You have to decide which will be the number of this object
  18. This is an XML representation of a <object> according to the XSD Schema of XWiki, see below for an example of this format
  19. You may want to customize you objects values with the _metadata folder
  20. The name of the file should be the name of the property you want to customize (use the extension you want)
  21. You can also have Nested Spaces if your version of XWiki support it 7.2
  22. You may also have other wikis in the package (the subwiki must already exists in the XWiki instance; may be fixed in future versions)
You may use the XFF Maven Plugin to build your package.

Index File

The index file list all the files in the XFF package.  Below is an example of this index.txt file.

wikis/xwiki/wiki.xml
wikis/xwiki/spaces/MySpace/pages/MyPage1/page.xml
wikis/xwiki/spaces/MySpace/pages/MyPage2/page.xml
wikis/xwiki/spaces/Space/space.xml
wikis/xwiki/spaces/Space/pages/Page/page.xml
wikis/xwiki/spaces/Space/pages/Page/metadata/content.xwiki21
wikis/xwiki/spaces/Space/pages/Page/attachments/logo1.png
wikis/xwiki/spaces/Space/pages/Page/attachments/logo2.png
wikis/xwiki/spaces/Space/pages/Page/class/class.xml
wikis/xwiki/spaces/Space/pages/Page/class/metadata/answer/customDisplay.xwiki21
wikis/xwiki/spaces/Space/pages/Page/objects/Space.Page/0/object.xml
wikis/xwiki/spaces/Space/pages/Page/objects/XWiki.StyleSheetExtension/0/object.xml
wikis/xwiki/spaces/Space/pages/Page/objects/XWiki.StyleSheetExtension/0/metadata/code.css
wikis/xwiki/spaces/Space/spaces/SubSpace/pages/SubPage/page.xml
wikis/templatewiki/wiki.xml

Here are a few rules to write this file:

  1. XML file corresponding to an XSD Schema element should be the first of the files describing this element (e.g. all objects will be listed after the corresponding page.xml, all pages will be listed after the corresponding space.xml which will be after wiki.xml, etc.)
  2. If there is a metadata to customize an XSD Schema element, it should be listed right after the XML file describing this element (e.g. metadata is right after page.xml, class.xml or object.xml)
The order of the files in this index file is important; a wrong order may cause incorrect parsing of the XFF package resulting mainly in loss of information.

Wiki XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<wiki xmlns="http://www.xwiki.org">
 <id>xwiki</id>
 <name>xwiki</name>
</wiki>

Space XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<space xmlns="http://www.xwiki.org">
 <id>xwiki:Space</id>
 <wiki>xwiki</wiki>
 <name>Space</name>
</space>

Page XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<page xmlns="http://www.xwiki.org">
 <title>Hello worlds!</title>
 <content>This is a new page</content>
</page>

Class XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<class xmlns="http://www.xwiki.org">
 <id>Space.Page</id>
 <name>Space.Page</name>
 <property name="answer" type="Number">
   <attribute name="name" value="answer"/>
   <attribute name="prettyName" value="Answer"/>
   <attribute name="unmodifiable" value="0"/>
   <attribute name="disabled" value="0"/>
   <attribute name="size" value="30"/>
   <attribute name="numberType" value="long"/>
   <attribute name="customDisplay" value=""/>
   <attribute name="number" value="1"/>
   <attribute name="validationMessage" value=""/>
   <attribute name="validationRegExp" value=""/>
 </property>
</class>

Object XML

<?xml version="1.0" encoding="UTF-8"?>
<object xmlns="http://www.xwiki.org">
 <className>Space.Page</className>
 <property name="answer">
   <value>42</value>
 </property>
</object>

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.

Release Notes

v0.4.0

This version includes the following:

TypeKeyStatusSummary
New FeatureXFF-7ClosedCreate a Maven plugin supporting XFF format
ImprovementXFF-10ClosedRemove the index file
ImprovementXFF-6ClosedAdd support for Nested Spaces
BugXFF-4ClosedDo not depend on the zip tool from Java (any kind of zip file should work)

v0.3.1

This version includes the following:

TypeKeyStatusSummary
BugXFF-3ClosedTitle and parent are not taken into consideration
BugXFF-2ClosedFail to load ZIP files through REST API when ZIP list directories

Dependencies

Dependencies for this extension (org.xwiki.contrib:xff-filter-stream 0.4.0):

  • org.xwiki.contrib:xff-core 0.4.0
  • commons-codec:commons-codec 1.10
  • org.xwiki.platform:xwiki-platform-filter-event-xwiki 7.1.1
  • org.xwiki.commons:xwiki-commons-filter-event-extension 7.1.1
  • org.xwiki.commons:xwiki-commons-filter-xml 7.1.1
  • org.xwiki.platform:xwiki-platform-xar 7.1.1
  • org.xwiki.platform:xwiki-platform-rest-model 7.1.1
Tags:
Created by Jean SIMARD on 2015/09/16 08:47
    

Get Connected