XFF filter
 | Filter stream extension to read and write wiki pages on the filesystem |
| Type | JAR |
| Category | |
| Developed by | |
| Active Installs | 0 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
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.
├── 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
- This is an XML representation of a <wiki> according to the XSD Schema of XWiki, see below for an example of this format
- This is the name of the space, pretty much the same structure than for XAR format
- Here is the first change with XAR format, the page is not an XML file but a folder
- This is an XML representation of a <page> according to the XSD Schema of XWiki, see below for an example of this format
- This is an XML representation of a <space> according to the XSD Schema of XWiki, see below for an example of this format
- For storing attachments, create an attachments folder into your page folder
- Now, you can just put the files you want as an attachment
- If you want the page to be also a class, you can create a class folder
- This is an XML representation of a <class> according to the XSD Schema of XWiki, see below for an example of this format
- The _metadata folder is for specific customization on the class
- Create a folder with the name of the property you want to customize
- 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)
- This _metadata is for customizing the page
- For example, this is where you can put the content of your wiki page (it will replace the <content> from the _page.xml)
- To put objects in your wiki page, create a objects folder
- For each kind of object you want, create a sub-folder that you could name after the class ID
- You have to decide which will be the number of this object
- This is an XML representation of a <object> according to the XSD Schema of XWiki, see below for an example of this format
- You may want to customize you objects values with the _metadata folder
- The name of the file should be the name of the property you want to customize (use the extension you want)
- You can also have Nested Spaces if your version of XWiki support it
- You may also have other wikis in the 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/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:
- 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.)
- 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)
Wiki XML
<wiki xmlns="http://www.xwiki.org">
<id>xwiki</id>
<name>xwiki</name>
</wiki>
Space XML
<space xmlns="http://www.xwiki.org">
<id>xwiki:Space</id>
<wiki>xwiki</wiki>
<name>Space</name>
</space>
Page XML
<page xmlns="http://www.xwiki.org">
<title>Hello worlds!</title>
<content>This is a new page</content>
</page>
Class XML
<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
<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).
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:
v0.3.1
This version includes the following:
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
