| 1 | | The R3 format is not just a Book format but a Resource format. It represents a given Resource with its sub-resources, binary data, cached data, external Resource references, etc. [[BR]] |
| 2 | | Since Resources form a hierarchy (for instance Book -> Page -> Frame), the R3 format structure follows the same hierarchy. [[BR]] |
| 3 | | The R3 format is a zipped file incorporating some directories and some files: |
| 4 | | * each Resource described inside (either the root -resource or any of its sub-resources) has a corresponding directory with some helper directories and files. |
| 5 | | The exact structure description of the format is described via an example. Here is a description of the file format for a Book, though any kind of Resource can be saved in similar structure: |
| 6 | | * The name of the zip file is something like "ExampleBook.s2b". This name without the file extension (namely "ExampleBook") is the name of the Book Resource. The extension depends on the kind of the resource that is persisted. |
| 7 | | * The root directory of the file contains: |
| 8 | | * '''_cache''' - a directory for caching remote Resources. It is used to load a resource even if you can’t connect to the server. |
| 9 | | * '''_data''' - a directory for storing binary and text data. Instead of embedding unreadable binary data in the -resource.xml file, it is stored here and just referred from other places (like the .xml files) |
| 10 | | * '''_resource.xml''' - an .xml file describing the structure and properties of the root-resource. |
| 11 | | * '''sub-elements''' directories – All child resources of the current resource are persisted in similar manner in inner directories named with their names in the resource tree. Those resources are kept in the described above manner. |
| 12 | | Resource names cannot start with an underscore so they won't conflict with _cache, _data and _resource.xml. |
| 13 | | Here is a sample _resource.xml for a book: |
| 14 | | === _resource.xml === |
| | 1 | SOPHIE 2.0 RESOURCE FORMAT |
| | 2 | The R3 format is used for persistence of a sophie 2.0 resources. It is simply the archive of the root directory of the resource. It contains: |
| | 3 | • _resource.xml file - xml description of all properties of the persisted resource |
| | 4 | • _data folder - incorporates all embedded files like images, videos, large texts, etc. |
| | 5 | • _cache folder- containing all cached remote resources for offline usage |
| | 6 | • children directories – There is sub-directory for all child resources of the persisted one that have the same structure as the parent one. The names of those directories do not start with underscore and match the names of the child resources (not their titles!). |
| | 7 | At the end of this page you can find a sample book. You can download it and open it with any file compression software (WinZip, WinRar, 7-zip, File Roller, etc) to gain a better understanding of the described structure. |
| | 8 | Basically every resource could be persisted on its own so there are different file extensions for the different resources: ‘.page’, ‘.book’, ‘.frame’, etc. All of those are further extended by the generalized extension ‘.s2’. So if you were saving a page and you decided to name the file “Page A” the complete name of the file would be “Page A.page.s2”. |
| | 9 | The key part of every resource directory is its _resource.xml. It is different for the different kinds of resources but there are some common things: |
| | 10 | * It begins with a standard <xml> tag. |
| | 11 | * The root tag is named ‘resource’. |
| | 12 | * It has a mandatory attribute ‘kind’ that specifies the kind of the persisted resource (book, page…). |
| | 13 | * There is also mandatory attribute ‘format-version’ whose value is the id of the persistence format. For now this it is always "r3" but in future there could be different formats. ) |
| | 14 | * There is a common child ‘title’. This is the name of the resource that is used in all user controls – the resource palette, links\timelines hud, bottom flap, etc. Its value is string: |
| 36 | | |
| 37 | | * It begins with a standard <xml> tag. |
| 38 | | * All other content is wrapped in a <resource> tag which contains the kind of the resource, the file format id (for now it is always "r3") and other attributes that are not threated as regular properties. |
| 39 | | * All properties of the resource are saved in appropriate format depending on the type of the value. |
| | 20 | * There is a child ‘template’ that contains a reference to another resource. It is saved like this: |
| | 21 | {{{ |
| | 22 | <template> |
| | 23 | <ref location="../Resource Jd88Us"/> |
| | 24 | </template> |
| | 25 | }}} |
| | 26 | This means that the referenced resource is located in the parent directory of the current one and is called “Resource Jd88Us”. Notice that this is the actual name of the resource, not its title. |
| | 27 | * There is a ‘comment’ child that has a string value. |
| | 28 | * There is an ‘import-origin’child that has a string value. It represents the URI of the import origin of this resource. |
| | 29 | Those children nodes are common for all resources. They are not mandatory, though. So the ‘resource’ node could have some or all of them. When a property`s value is null there is no point in having empty tags for it. |
| | 30 | There are many other children nodes that could be found in a _resource.xml depending on the kind of the persisted resource. Here we are presented most of them specifying where you could see them. Basically all properties of a resource are saved in this xml file in appropriate form depending on the type of the kept value. |
| | 31 | When the persisted resource is a book its _resource.xml could have ‘page-size’ node that holds the size of the page- width and height: |
| | 32 | {{{ |
| | 33 | <page-size> |
| | 34 | <height>480.0</height> |
| | 35 | <width>640.0</width> |
| | 36 | </page-size> |
| | 37 | }}} |
