SOPHIE 2.0 RESOURCE FORMAT

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:
• _resource.xml file - xml description of all properties of the persisted resource

• _data folder - incorporates all embedded files like images, videos, large texts, etc.

• _cache folder- containing all cached remote resources for offline usage

• 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!).

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.

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

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:

• It begins with a standard <xml> tag.
  
  
• The root tag is named ‘resource’.
  
  
  • It has a mandatory attribute ‘kind’ that specifies the kind of the persisted resource (book, page…).
    
    
  • 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. )
    
    
• 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:
  

  <title>
    Cool Book
  </title>
  

There could be a child ‘template’ that contains a reference to another resource. It is saved like this:

<template>
  <ref location="../Resource Jd88Us"/>
</template>

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.
There could be a ‘comment’ child that has a string value.

There could be an ‘import-origin’child that has a string value. It represents the URI of the import origin of this resource.

Those children nodes are common for all resources. Most of them 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.

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

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:

<page-size>
  <height>480.0</height>
  <width>640.0</width>
</page-size>

Book resources could also have 3 additional child nodes - ‘pages’, ‘page-templates’ and ‘frame-templates’. The value of these properties is a list of references to resources just like the template one. These child nodes have attribute ‘size’ that is integer number indicating how many elements this list holds. Each element of the list is persisted separately in a child node called accordingly ‘page’ or ‘template’. Those elements have attribute ‘index’ since the order of those elements is important to the way the book is presented. In xml files order of the children with the same name on the same level of the xml is not regarded. That way the list of pages for example page elements could change their place in the xml representation but we won`t lose the information for the order in which they were arranged in the book.

Pages, groups and page extras (set of annotations on a page for example) could have ‘elements’ child node. Its value is basically a list of references, although there are a few differences. Here the elements nodes are named ‘element’, the ref is persisted in ‘elementRef’ tag and there is an additional ‘entries’ child node that is used by the timelines determine when this element is active and when it is not.

Frames and Pages have styled background and borders so their resource could have ‘bg-style’ and/or ‘border’ child nodes. The ‘border’ node could have two child nodes. First one is ‘color’. Its value representing the red, green, blue and alpha values of a color like this: ImmColor(r=0.364706, g=0.533333, b=1.00000, a=1.00000). The second one is ‘insets’ that contains four children for the thickness value of the right, left, bottom and top part of the border:

<insets>
  <bottom>5.0</bottom>
  <left>10.0</left>
  <right>15.0</right>
  <top>20.0</top>
</insets>

The background style tag is a bit more complicated. It would almost every time have a child node named ‘type’ that could have 5 different values: none, solid, pattern, gradient, image. In case it is solid, there will be also a child ‘color’ that would have a value just like the border color. It would mean that the background is filled with solid color. If it is none there is no background. If it is pattern or image there is a child node ‘image’ whose value is a reference to an image resource. In the image case this image is stretched to the size of the background area. In the pattern case it is repeated in its original size until the background area is filled.

Groups, frames and stickies could have positioning properties – ‘rotation-angle’ and ‘content-location’. The first one is a simple double number. The second one though is a bit complicated. Its value is a list ‘entries’ that is used to specify the location of the element in different times of its activation. The list elements are named ‘entry’ and have two child nodes – ‘key’ and ‘value’. The key is a position in time in milliseconds. This is true for all ‘entries’ lists for the different properties that have a timeline. The specific thing here is the child ’value’. It has a value that describes location – ‘x’ and ‘y’ values:

<entries size="2">
  <entry index="0">
    <value>
      <y>155.0</y>
      <x>80.0</x>
    </value>
    <key>-1000000000</key>
  </entry>
  <entry index="1">
    <value>
      <y>112.0</y>
      <x>229.0</x>
    </value>
    <key>18640</key>
  </entry>
</entries>

Almost all elements could have a ‘visible’ property. It indicates when the element is visible and when it isn`t. Its value is timeline ‘entries’ list and it is basically the same as the location with the difference that the ‘value’ child is a Boolean - true/false indicating whether in the key moment of the activation of the element it is visible.