Freeplane version 1.0.x (and 1.1.x) was developed using FreeMind'sformat and file extension (.mm) in an effort to allow a smooth transition to users willing to switch to Freeplane. As Freeplane grows mature and wants to make true its Visions, a new file format is required.
A Freeplane file can come in 4 flavors, as single XML document file or as package:
Single XML document:
a plain XML format with extension .freeplane. This format allows further for easy automated generation and XSLT transformation.
the above format in a standard ZIP or JAR file, i.e. if a file named myfile.freeplane.zip or myfile.freeplane.jar contains a file named myfile.freeplane, it will be opened by Freeplane in the same way as the above plain XML format (other files in the same archive will be ignored). The file format is still easy to generate but takes less space than plain XML, is cleaner to email (some mailers choke on text formats) and can be used to transport other files (even though they will be ignored by Freeplane).
Package Document:
a more complex zipped format with extension .freeplanez. This format allows for embedded styles, images and other 3rd party objects.
the same structure but in an uncompressed directory with extension .freeplane.d.
Each XML file must start with an XML declaration <?xml version="1.0" encoding="UTF-8" ?> .
this means that the Freeplane format is based on XML 1.0 and has UTF-8 as encoding.
(X)HTML entities are not used anymore for accentuated characters but just plain UTF-8 encoding.
A single XML document may continue with an XSLT reference like <?xml-stylesheet type="application/xslt+xml" href="url-to-some-XHTML-transformation-sheet"?> as to allow web browsers to render directly Freeplane files.
Freeplane must ignore (but keep) such entries and should add a default one when creating a new map.
The Freeplane team should offer standard XSLT transformation sheets e.g. under http://freeplane.org/formats/2010/to-xhtml10.xsl.
All XML markups are in small caps and must have an explicit namespace
The namespace must be declared either as xmlns:attribute of the root element of the XML file, or, if rendered by a plug-in, as xmlns:attribute of the XML element rendered by this plug-in
; Example : if a node has the xmlns attribute <map:node xmlns:myplug="myplug-namespace" ...>[...], Freeplane could find an OSGi service NodeRenderer with a filter based on the given namespace to render this specific node.
The namespace for Freeplane specific elements is xmlns:map="http://freeplane.org/formats/2010/map".
Until further notice, all formatting elements are based on XHTML 1.0/1.1 and have the namespace xmlns:xhtml="http://www.w3.org/1999/xhtml".
SimplyHTML must be adapted accordingly, and perhaps released as OSGi bundle!?
We stick to the same namespaces wherever applicable, and add the following one:
|+ Table 6 - Freeplane namespaces
|-
|-
| map || For all Freeplane specific elements || http://freeplane.org/formats/2010/map
|-
| x-office || For Freeplane elements that would belong in the 'office' namespace
| http://freeplane.org/formats/2010/office
|}
Notes : Once Freeplane has a registered mime-type, mimetype could become application/freeplane. The version is made of the ODF version 1.2, 'fp' for Freeplane and an internal version number, 1.0 to start with.
Mandatory section, but only child needed is a Freeplane specific <x-office:map>.
Note : x-office is used instead of office to avoid polluting the 'office' namespace. x-office can be used as an alternative prefix for the same Freeplane namespace as 'map'.
A bit unclear, but I understand something like the following is possible:
<?opendocument cursor-position="''XXX''" ?>
where XXX is a mean to give the cursor position at the time where the document was saved. In Freeplane's case, it could just be a map and/or node ID, but I'm not fully convinced.
<office:scripts>
<office:event-listeners>
TBD: do we need event listeners in Freeplane? How to implement them?
</office:event-listeners>
<office:script script:language="groovy">
''Script Specific Text (can also be a link to an external script)''
</office:script>
<office:script script:language="lang2">
[...]
</office:scripts>
The specification doesn't explicitly contain a list of possible files, so here it is, with a reference to the relevant chapters.
The following table shows a summary of all files to be found in an OpenDocument conform package file, as described in the specification:
|+ Files found in a package according to ODF reference
|-
|-
| mimetype
| first file in ZIP file, uncompressed, contains mime type i.e. application/x-freeplane or application/freeplane
| 2.3 MIME Media Type
|-
| META-INF/manifest.xml
| manifest file in XML format listing all files in the package with their MIME type and, if needed, encryption options
| 3 Manifest File
|-
| manifest.rdf
| meta data file (probably optional for Freeplane)
| 5 Metadata Manifest Files
|-
| META-INF/documentsignatures.xml META-INF/macrosignatures.xml
| Signature files respectively for all files and for macros (optional)
| 4 Digital Signatures File (and in Part 1 - 3.16 Document and Macro Signatures)
|-
| Thumbnails/thumbnail.png
| Preview image of size 256x256 and 24 bits (optional)
| 2.8 Preview Image
|-
| content.xml styles.xml meta.xml settings.xml
| Core content, styles, metadata and settings files
| Part 1
|}
The ODF specification states that a package can contain other files, but it doesn't specify any specific structure (it is also not needed because all such files are referenced in META-INF/manifest.xml). Reading between the lines and analyzing OpenOffice files, I come to the conclusion that all additional files should be in sub-directories with names starting with a capital. Here a few examples/suggestions:
|+ Directories found in a package to contain 3rd party objects
|-
|-
| Pictures/
| for all images. Freeplane accepts JPEG, PNG and GIF formats.
|-
| Icons/
| for user specific icons. Freeplane accepts JPEG, PNG and GIF formats.
|-
| Scripts/
| for Groovy scripts.
|-
| Objects/
| for any object that Freeplane would embed without actually being able to do anything with it but just try to display externally.
|}
Note : further directories can be added as needed.
Note : to embed objects, OpenOffice creates a binary (format ?) reference file ObjectReplacements/Object N (N a growing index) and puts the relevant data in a sub-directory Object N, but I don't think we want to do this.
the chapter is a bit unclear, but I understand basically that links to files within the package are just normal relative links. As all files present in the package need to be referenced in META-INF/manifest.xml, Freeplane can safely compare any relative link to the content of this file, and, only if not found, try to resolve the link outside of the package.
Note : when using a packaged directory, the relative link outside of the package means relative to the directory containing the packaged directory. Example: a packaged directory /home/ewl/Documents/mymap.freeplane.d where content.xml refers to Scripts/myscript.groovy; if internal to the package, the absolute path is /home/ewl/Documents/mymap.freeplane.d/Scripts/myscript.groovy, but externally resolved, it means /home/ewl/Documents/Scripts/myscript.groovy.