Inhalt

Vorheriges Thema

Leafled-Resourcen

Nächstes Thema

Portal Server REST-API 2.0

Leafled SPF-Dateiformat Spezifikation

Das Simple Publication Format (kurz: SPF) ist ein Dateiformat zur Beschreibung von einfachen digitalen Publikationen, insbesondere zu Veröffentlichung von Inhalten in unterschiedliche Ausgabekanäle. SPF wurde zur vereinfachten Quell-und Zielapplikationsunabhängiger Distribution von medialen Inhalten entwickelt. Es beschreibt insbesondere die Struktur, die Distribution und die Rich-Media Anreicherung, von im Normalfall für den Print erzeugten PDF-Dokumenten.

Warum nicht andere Formate und Technologien verwenden?

Das Publizieren, insbesondere für die neuen mobilen Endgeräte für iPad und iPhone, stellt besondere Anforderungen an Bandbreite, User Interface und Interaktivität, sodass hier andere Schwerpunkte und Reize innerhalb von Publikationen gesetzt werden müssen, wie in reinen Print-Dokumenten.

Die völlig neuartige Bedienung dieser Geräte setzt natürlich auch andere Schwerpunkte beim Konsum der Inhalte.

Das SPF versucht auf Basis von angereichterten PDF Dateien und einer leistungsfähigen Viewer/Reader-App, möglichst viele Vorteile der vorhandenen und bewährten Plattformen, wie z.B. PDF, WebHosting, HTML5 und Javascript zu erhalten. Hierdurch wird eine schnelle und einfache Übertragung von vorhandenen Dokumenten auf die verschiedenen Geräte ermöglicht.

XML, HTML, CSS, IDML, IDX, FOLIO, Flash sind sehr komplex und die Entwickler aller beteiligten Systeme müssen weitreichende Kenntnisse über das Dateiformat und seine Eigenschaften besitzen, um einen problemlosen Informationsaustausch zu erreichen. Dies ist in der Theorie zwar denkbar und erscheint eine “gute Sache” zu sein; in der Realität sieht es in den meisten Fällen leider anders aus:

  • Durch die relativ hohe Komplexität dieser Beschreibungssprachen ist ein sehr großer Aufwand notwendig um die ersten Ergebnisse zu erzielen.
  • Oftmals fehlt das “Know-How” von Beteiligten, alle notwendigen Parameter zu beschreiben, die von anderen Systemen gebraucht werden.
  • Verschiedene Hersteller implementieren verschiedene Versionen der Formate - welche untereinander meist inkompatibel sind.
  • Die Spezifikationen sind für Neueinsteiger schwer verständlich und setzt detaillierte Erfahrung im jeweiligen Teil der Anwendung voraus.
  • Einige der Formate (wie IDML, IDX, FOLIO, Flash) unterliegen der Kontrolle einzelner Hersteller und schaffen ungewünschte Abhängigkeiten und haben das Risiko - anders als bei offenen Standards - plötzlich nicht mehr weiter entwickelt zu werden.

Aus diesen und einigen anderen Gründen ist es für viele Anwendungsgebiete sinnvoller, eine einfachere Alternative zur Datenübergabe zur Verfügung zu stellen. Diese Alternative hat nicht das Ziel andere Formate zu ersetzen oder damit zu konkurrieren, sondern einen alternativen, sofort wirksamen Weg zur Verfügung zu stellen, welchen Hersteller und andere Projektbeteiligte einfacher verstehen und schneller implementieren können. Weniger Komplexität führt zu schnelleren und zuverlässigeren Ergebnissen.

Hier haben sich in den letzten Jahren offene Standards wie z.B. das JSON Format (Java Script Object Notation) entwickelt, die optimal für solche Zwecke eingesetzt werden können.

Der SPF-Container

Um die Übertragung von Publikationen über das Internet so einfach wie möglich zu gestalten, wird eine einfache Ordnerstruktur verwendet. Diese Ordnerstruktur wird vor der Übertragung in ein ZIP-Archiv gepackt, welches die Daten komprimiert und in eine einzige Datei für die Übertragung zusammenfasst.

ZIP-Softwarewerkzeuge gibt es praktisch auf allen Plattformen und als Bibliotheken für fast alle Programmiersprachen.

Als Beispiel der Inhalt des SPF/ZIP Dateipaketes einer der Dokumentations-Beispielpublikation (mit eingebettetem Bildergalerie-, Video-, Audio- , HTML-Objekten und nachgeladender PDF-PopOver Seite):

../_images/spf-folder-content.png

Die publication.json Datei

Diese Datei enthält eine genau definierte Unterstruktur. Diese Struktur beschreibt alle enthaltenen Bestandteile wie PDF Seiten, Medien, Objekte und Struktur der angereicherten Publikation.

Beispiel für die JSON-Struktur der Willkommens-Publikation:

{
    "publicationId": "willkommen",
    "comment": "",
    "toolbarVisible": "auto",
    "name": "Willkommen",
    "pageFitMode": "fit",
    "pagePadding": 5.0,
    "cover": "pdf_pages.pdf#0",
    "deviceOrientations": ["portrait", "landscape"],
    "actions": [],
    "pages": [{
        "mappingFactor": 2.8346462942500001,
        "label": "",
        "width": 1024.0,
        "objects": [{
            "source": "pdf_pages.pdf#0",
            "height": 697.995,
            "width": 1024.0,
            "y": 0.0,
            "x": 0.0,
            "type": "image",
            "id": "pdf_backdrop_0"
        },
        {
            "direction": "south",
            "source": "media",
            "images": ["96d9258370b24bcb87be057090f1ab9a.data", "fc5749ab4cd04d80af9d63f5fa94a691.data", "6b903e5637b2477f930d9840bdbccaa2.data", "1541605fdcd24646b701b124b9269e55.data", "b6f1cbc950784f39bf0a7155c51c2100.data"],
            "height": 267.0,
            "delay": 6.0,
            "width": 798.12495666042605,
            "y": 289.71083836072398,
            "x": 69.587407253311099,
            "type": "gallery",
            "id": "c3898fb65d3f98cdef93c91c815a63bc",
            "transparent": false
        },
        {
            "source": "media/cfcefe8e38614cb292292ac9c3b5e192.data",
            "height": 190.0,
            "width": 250.0,
            "_mediaUuid": "cfcefe8e38614cb292292ac9c3b5e192",
            "y": 269.21581465625798,
            "x": 681.80710148577202,
            "type": "picture",
            "id": "a6de3ce13ae5fb4b699b7b9ef5f78d15"
        },
        {
            "embeddedViewer": false,
            "height": 191.85494837572401,
            "width": 251.68068496600401,
            "href": "spf://goTo?publication=testkiosk_aktivieren",
            "y": 267.15285822211001,
            "x": 679.74414505162395,
            "type": "hyperlink",
            "id": "c4cffbab7c0d00a95bf371662c76a669"
        },
        {
            "source": "media/342462058d0c4145b9c57f37ccc71a9a.data",
            "height": 96.0,
            "width": 150.0,
            "_mediaUuid": "342462058d0c4145b9c57f37ccc71a9a",
            "y": 599.28884411986905,
            "x": 838.59179048098702,
            "type": "picture",
            "id": "2e66c044c68bb1dd21afa4548f12bdcc"
        }],
        "height": 697.995,
        "id": "pdf_page_0"
    },

    //... weitere Seiten und Objekte ...

    ],
    "pageSwitcherEnabled": true,
    "searchEnabled": true,
    "version": 2,
    "stories": [{
        "pages": ["pdf_page_0", "pdf_page_1", "pdf_page_2", "pdf_page_3", "pdf_page_4", "pdf_page_5", "pdf_page_6", "pdf_page_7", "pdf_page_8", "pdf_page_9"],
        "description": "",
        "id": "autogenerated_story",
        "name": "Willkommen"
    }],
    "launchUrl": "",
    "pageDisplayMode": "normal",
    "zoomEnabled": true,
    "browserEnabled": true,
    "viewerThemeColor": "",
    "revision": 13
}

Das publication Objekt

Dieses “Root”-Objekt der publication.json enthält generische Informationen zur Publikation. Nachstehend wurden die Felder/Eigenschaften aus obigem Beispiel herausgezogen und alle weiteren möglichen Eigenschaften des publication Objektes am Schluss ergänzt.

Beispiel:

{
    "publicationId": "willkommen",
    "comment": "",
    "toolbarVisible": "auto",
    "name": "Willkommen",
    "pageFitMode": "fit",
    "pagePadding": 5.0,
    "cover": "pdf_pages.pdf#0",
    "deviceOrientations": ["portrait", "landscape"],
    "pages": [
        //... die Seiten Objekte ...
        ],
    "pageSwitcherEnabled": true,
    "searchEnabled": true,
    "version": 2,
    "stories": [
        //... die Story Objekte ...
        ],
    "launchUrl": "",
    "pageDisplayMode": "normal",
    "zoomEnabled": true,
    "browserEnabled": true,
    "viewerThemeColor": "",
    "revision": 13,

    //... weitere mögliche Publikations-Eigenschaften/Objekte ...

    "toc": [
        //... die TOC/Inhaltsverzeichnis Objekte ...
        ],
    "actions": [
        //... die Action Objekte ...
        ],
    "annotationsEnabled": false
}
Eigenschaft Typ Beschreibung
actions ? Array Ein Array von action-Objekten, welche ein zusätzliche (optionale) eigene Toolbar-Aktionen beschreiben. Wenn action-Objekte in dieser Publikation definiert sind, so werden diese Aktionen zusätzliche zu den Standard-Funktionen in der Toolbar angezeigt.
annotationsEnabled ? Boolean Definiert ob Anmerkungen/Notizen/Lesezeichen in dieser Publikation aktiviert sind. Wenn aktiviert, wird rechts in der Toolbar der   Lesezeichen-Button sowie der   Anmerkungen-Button (nur wenn Anmerkungen vorhanden sind) gezeigt. Gleichzeitig wird die Langer Tap-Geste für die Anbringung der Notizen aktiviert (Default: true)
browserEnabled ? Boolean Definiert ob die Kapitelübersicht gezeigt werden soll. Ist dieses Objekt in der Publikation aktiviert und stories vorhanden, so wird rechts in der Toolbar der   Kapitelbrowser-Button gezeigt (Default: true)
comment ? String Beschreibung/zusätzliche Informationen der Publikation
cover String Der Verweis auf der PDF-Seite innerhalb der Publikation (als Seiten-ID), welche als Cover für diese Publikation verwendet werden soll. Üblicherweise ist dieses die erste Seite der Publikation.
deviceOrientations ? Array In diesem Array werden die möglichen Geräteausrichtungen angegeben. Mögliche Werte sind landscape und portrait. Wenn aufgeführt, kann die Publikation in den angegebenen Ausrichtungen angezeigt werden. (Default: ["landscape", "portrait"])
launchUrl ? String Wenn hier ein SPF/URL-Aktion hinterlegt ist, z.B. “5;spf:showBrowser” wird diese beim ersten Öffnen der Publikation ausgeführt. Eine mit einem ”;” vorangestellte Zahl gibt eine zusätzliche Wartezeit in Sekunden vor Ausführung an.
name String Der Titel der Publikation
pageDisplayMode String
Legt die Seitendarstellung von Einzel- und Doppelseiten bei den verschiedenen Geräteausrichtungen fest. Mögliche Werte sind:

single für eine klassische Einzelseitendarstellung (Default)

spreads für eine Einzelseitendarstellung bei Hochformat und Doppelseitendarstellung mit “Montageseiten” bei Querformat des Gerätes, beginnend mit einer Einzelseite

spreadsEven für eine Einzelseitendarstellung bei Hochformat und Doppelseiten bei Querformat des Gerätes, beginnend mit einem Seitenpaar

pageFitMode ? String
Definiert wie Seiten auf dem Gerät eingepasst werden sollen. Mögliche Werte:

fit - Seite in der Breite und Höhe einpassen (Default)

fitWidth - Seite in der Breite einpassen

fitHeight - Seite in der Höhe einpassen

pagePadding ? Number Der Abstand zwischen Seiten in der Einzelseitenanzeige. (Default: 5.0)
pages Array Ein Array von page-Objekten, welche die einzelnen Seiten der Publikation und die auf dieser Seite enhaltenen Objekte beschreiben
pageSwitcherEnabled ? Boolean Definiert ob am unteren Bildschirmrand die Seitenleiste gezeigt werden wird (Default: true)
publicationId String Ein eindeutige ID-String der Publikation im Kiosk. Hierüber wird das Update/Austauschverhalten im Kiosk und App gesteuert
revision Integer Der interne Revisionszähler für die Publikation. Nach einer Änderung an der Publikation wird dieser Zähler um 1 erhöht, um der App damit ein Update zu signalisieren. (Default: 1)
searchEnabled ? Boolean Definiert ob die Suchfunktion der Publikation verfügbar ist. Ist dieses Objekt in der Publikation aktiviert, so wird ganz rechts in der Toolbar der   Such-Button gezeigt (Default: true)
stories ? Array Ein Array von story-Objekten, welche die Strukur einer Publikation und deren Aufteilung in einzelne Kapitel festlegt. Ist dieses Objekt in der Publikation vorhanden und browserEnabled aktiviert, so wird rechts in der Toolbar der   Kapitelbrowser-Button gezeigt.
toc ? Array Ein Array von toc-Objekten, welche ein zusätzliches (optionales) Inhaltsverzeichnis beschreiben. Ist dieses Objekt in der Publikation vorhanden, so wird links in der Toolbar der   TOC-Button gezeigt.
version Integer Die interne Version-Kennzeichnung für das verwendete SPF-Dateiformat. Es wird von Portal und App verwendet um die Kompatibiliät der Publikation zu neueren Programmversionen sicherzustellen und bei Bedarf Aktualisierungen der internen Dateistrukturen vorzunehmen (Default: 2)
viewerThemeColor ? String Legt eine optionale Farbe für die Toolbar fest. Der Farbwert wird als Web-Farbe angegeben z.B. “#808080” steht für ein mittleres Grau
zoomEnabled ? Boolean Definiert ob ein Zoomen innerhalb der Publikation erlaubt ist (Default: true)
annotationsEnabled ? Boolean Gibt mit true an die Funktionen für Leseszeichen und Notizen in der Publikation verfügbar sind. Das   Toolbar-Icon und die Notiz-Geste sind ansonsten deaktiviert. (Default: true)
toolbarVisible ? String Legt das Verhalten der Publikations-Toobar innerhalb dieser Publikation fest. Mögliche Werte sind: “auto” - Nach dem Öffnen unsichtbar, “autostart” - Nach dem Öffnen sichtbar, “always” - Immer sichtbar, “never” - Niemals sichtbar .

Das page Objekt

Über ein page-Objekt wird der Inhalt und die Darstellung einer Publikations-Seite festgelegt. Hier wird die zugrundeliegende PDF-Seite festgelegt und auch alle auf dieser Seite platzierten multimedialen und interaktiven Objekte genau beschrieben.

Beispiel:

{
  "mappingFactor": 2.8346462942500001,
  "label": "Mein Willkommen",
  "width": 1024.0,
  "height": 697.995,
  "id": "pdf_page_0",
  "objects": [
    {
      "source": "pdf_pages.pdf#0",
      "height": 697.995,
      "width": 1024.0,
      "y": 0.0,
      "x": 0.0,
      "type": "image",
      "id": "pdf_backdrop_0"
    }

    // ... weitere Seitenobjekte ...

    {
      "embeddedViewer": false,
      "height": 191.85494837572401,
      "width": 251.68068496600401,
      "href": "spf://goTo?publication=testkiosk_aktivieren",
      "y": 267.15285822211001,
      "x": 679.74414505162395,
      "type": "hyperlink",
      "id": "c4cffbab7c0d00a95bf371662c76a669"
    },
    {
      "source": "media/342462058d0c4145b9c57f37ccc71a9a.data",
      "height": 96.0,
      "width": 150.0,
      "_mediaUuid": "342462058d0c4145b9c57f37ccc71a9a",
      "y": 599.28884411986905,
      "x": 838.59179048098702,
      "type": "picture",
      "id": "2e66c044c68bb1dd21afa4548f12bdcc"
    }
  ], // Abschluss der Seitenobjekte
} // Abschluss dieses Page-Objektes
Eigenschaft Typ Beschreibung
mappingFactor Number Der Skalierungsfaktor mit dem dieser PDF-Seiteninhalt in die vorhandene Referenz-Bildschirmgröße von 1024x768 Point hereinskaliert wird. Siehe hierzu Generelle Hinweise zu Koordinatensystem und Maßeinheiten
id string Ein interner, eindeutiger ID-String zur Identifikation dieser Seite.
label string Ein freier interner String zur Beschreibung des Seiteninhaltes. Dieses label kann im Portal durch den Benutzer geändert werden. Standardmässig wird setzt das Portal hier die laufende Seitennumer der PDF-Datei.
width number Die Breite dieser Publikationsseite (Referenz zur ursprünglichen PDF Seitengröße) unter Berücksichtigung der Referenz-Bildschirmgröße von 1024x768 Point und des ermittelten mappingFactor
height number Die Höhe dieser Publikationsseite (Referenz zur ursprünglichen PDF Seitengröße) unter Berücksichtigung der Referenz-Bildschirmgröße von 1024x768 Point und des ermittelten mappingFactor
objects Array Ein Array von Seitenobjekten die auf dieser Seite platziert sind.
preview ? Boolean Gibt mit true an, ob diese Seite als Voransicht/Lesemuster, vor dem Kauf einer kostenpflichtigen Publikation angesehen werden kann. (Default = false)

Das story Objekt

Über ein story-Objekt können mehrere Seiten zu einem Kapitel zusammengestellt werden. Hierüber kann der Publikation eine eigene Lesestruktur und Reihenfolge gegeben werden. Unabhängig von der ursprünglichen Reihenfolge der Seiten des PDF-Dokumentes, können hier die Seiten in beliebiger Reihenfolge zu eigenen Kaptiteln (Stories) zusammengeführt werden.

Es können mehrere dieser Stories in der Publikation existieren, als stories im publication-Objekt. Das stories-Objekt/Array bestimmt effektive Lesereihenfolge der überhaupt für den Leser sichtbaren Seiten für Kapitelbrowser und Seitenleiste. PDF-Seiten die keinen Stories zugeordnet sind stehen nur für Sonderzwecke, z.B. PopOver Funktionen zur Verfügung.

Beispiel:

"stories": [{
     "pages": ["pdf_page_0", "pdf_page_1", "pdf_page_2", "pdf_page_3", "pdf_page_4", "pdf_page_5", "pdf_page_6", "pdf_page_7", "pdf_page_8", "pdf_page_9"],
     "description": "",
     "id": "autogenerated_story",
     "name": "Willkommen"
 }],
]
Eigenschaft Typ Beschreibung
description array Zusätzlicher Beschreibungstext für dieses Kapitel. Dieser Text wird unterhalb des Kapitelnamens im Kapitelbrowser angezeigt.
id string Ein interner, eindeutiger ID-String zur Kennzeichnung dieser Story.
name string Der Name/Titel dieses Kapitels. Wird als Kapitelüberschrift im Kapitelbrowswer angezeigt.
pages Array Ein Array von page-ID Strings die auf die benutzten page-Objekte verweisen.

Das toc Objekt

Die Publikation kann ein Inhaltsverzeichnis (TOC = Table of Contents) enthalten. Dieses TOC kann auf dem Portal angelegt und bearbeitet oder aus der angelieferten PDF-Datei (wenn vorhanden) automatisch übernommen werden. Dieses TOC kann einen hierarchischen Aufbau haben.

Beispiel:

toc: [
    {
        'label': 'Einleitung 1',
        'href': 'spf://goTo?page=xx1'
    },
    {
        'label': 'Einleitung 2',
        'href': 'spf://goTo?page=xx2'
    },
    {
        'label': 'Einleitung 3',
        'href': 'spf://goTo?page=xx3',
        'children': [
            {
                'label': 'Untereinleitung 1',
                'href': 'spf://goTo?page=ab'
            },
            {
                'label': 'Untereinleitung 2',
                'href': 'spf://goTo?page=xy'
            },
        ]
    },
]

Wenn ein TOC in der Publikation vorhanden ist, wird automatisch das entsprechende Toolbar-Icon zum Aufruf innerhalb der App angezeigt.

Eigenschaft Typ Beschreibung
label string Der Name/Text des Inhaltsverzeichnis-Eintrages
href string Die SPF/URL-Aktion die bei Anwahl des TOC-Eintrages ausgeführt werden soll
children ? array Optionales Array von weiteren TOC-Einträgen die unterhalb dieses TOC-Eintrages angewählt werden können

Das actions Objekt

Die Publikation kann zusätzliche actions Objekte enthalten. Diese Objekte beschreiben zusätzliche Aktionen die in der Publikations-Toolbar eingeblendet werden. Hiermit kann die Publikation um eigene Funktionen erweitert werden.

Beispiel:

"actions": [{
    "position": "left",
    "image": "mail",
    "href": "mailto:support@leafled.de"
  },
  {
    "position": "left",
    "image": "app_globe",
    "href": "spf://popOver?page=8157cfca357f4295b99288f1edd3fc1f&position=center,center"
  },
  {
    "position": "left",
    "image": "alarm",
    "href": "spf://popOver?page=pdf_page_4&position=center,center"
  },
  {
    "position": "right",
    "image": "video_next",
    "href": "spf://goTo?page=last"
  },
  {
    "position": "right",
    "image": "arrow_right",
    "href": "spf://goTo?page=next"
  },
  {
    "position": "right",
    "image": "arrow_left",
    "href": "spf://goTo?page=previous"
  },
  {
    "position": "right",
    "image": "video_previous",
    "href": "spf://goTo?page=first"
  }

Jeder neue hierüber angelegte Toolbar-Button hat ein eigenes Icon sowie eine beliebige SPF-URL Aktion. Wenn actions in der Publikation vorhanden sind, wird automatisch das entsprechende Toolbar-Icon zum Aufruf innerhalb der App angezeigt.

Eigenschaft Typ Beschreibung
image string Der Name/Text des Inhaltsverzeichnis-Eintrages
href string Die URL welche den Ort der Zielresource beschreibt. Hier werden auch mit dem Protokollheader spf:// spezielle nachstehende Aktions-URLs angegeben, die das Einpassen, Zoomen etc. mit speziellen Aktionen bzw. Parametern individuell ansteuerbar macht. Diese Aktions-Buttons werden von der App automatisch mit einem Toolbar-Button-Overlay versehen. Wenn dieser String ein Leerstring ist, dann wird die Bilddatei ohne hinterlegte Aktion - z.B. für Logo-Zwecke - in der Toolbar hinterlegt. Abstandshalter (spacer) können hierdurch auch eingefügt werden.
position ? string left legt fest das dieses Aktions-Element in der Toolbar vom linken Rand aus angefügt wird (züsätzlich neben die fest eingebauten bzw. schon vorhanden Elemente). right fügt dieses Element von rechts in die Toolbar ein.

Die Bilddateien für Toolbar-Buttons sollten PNG Dateien mit weißem Bildinhalt für das Icon und transparentem Hintergrund sein, da dieses Bild mit dem Farbschema zusammen in die Toolbar hereingerechnet wird. Diese Dateien haben im Normalfall 22x22 Pixel für die Anzeige auf dem normalen iPhone und iPad. Für Geräte mit Retina Display sind 44x44 Pixel für die Anzeige vorhanden.

Die Seiten objects

Jede Seite enthält eine Liste von content-Objekten. Diese können unterschiedliche Typen von Inhalten darstellen. PDF Seite, Video, Audio, HTML5/Javascript, Animation, Anker, Hyperlinks, 360er, VR u.v.a.m.

Dieses abstrakte Seiten-Objekt wird normalerweise nicht direkt genutzt, sondern es wird eine der Untertypen verwendet. Alle Typen von Seitenobjekten erben folgende Eigenschaften:

Beispiel (z.B. PDF-Seiteninhalt):

{
  "source": "pdf_pages.pdf#0",
  "height": 697.995,
  "width": 1024.0,
  "y": 0.0,
  "x": 0.0,
  "type": "image",
  "id": "pdf_backdrop_0"
}
Eigenschaft Typ Beschreibung
type String Typ des Seitenobjektes. Es stehen folgende Objekttypen zur Verfügung: image, hyperlink, anchor, audio, video, gallery, html, picture
id String Der eindeutige Identifikationsstring dieses Seitenobjektes
x Number Die horizontale Position auf der Seite in Points (von links aus)
y Number Die vertikale Position auf der Seite in Points (von oben aus)
width Number Die Breite des Objektes in Points
height Number Die Höhe des Objektes in Points
name ? String Ein optionaler Label/Namens-String der zusätzliche Meta-Informationen zu dem Objekt aufnehmen kann. Dieser wird im Portal als Zusatzinfo zu dem Objekt angezeigt

In den nachstehenden verschiedenen Seitenobjekt-Typen sind nur die zusätzlichen individuellen Eigenschaften beschrieben.

Das image Objekt (PDF Seitenhintergrund)

Über das image-Objekt kann der Inhalt einer PDF-Seite auf einer Seite der Publikation angezeigt werden.

Eigenschaft Typ Beschreibung
source String Der Dateiname der zu verwendenden Datei inklusive Seitenindex. Der Dateiname kann von einem Rautezeichen (#) gefolgt werden, womit einer einzelne Seite innerhalb eines PDF-Dokuments gewählt werden kann. (z.B. ‘meine.pdf#4’ für die 5te Seite der PDF).

Beispiel (PDF Hintergrundseite):

{
  "source": "pdf_pages.pdf#0",
  "height": 697.995,
  "width": 1024.0,
  "y": 0.0,
  "x": 0.0,
  "type": "image",
  "id": "pdf_backdrop_0"
}

Vorschau-Thumbnails

Der Rechenaufwand um PDFs zu rastern kann enorm sein - vor allem für Mobilgeräte mit langsameren Prozessoren.

Leafled nutzt hierzu einen einfachen Mechanismus: Vorschau-Thumbnails, welche zusätzlich zu den auflösungsunabhänigen PDF-Daten im SPF-Archiv angelegt werden.

In aktuellen Versionen gibt es zwei größen von Thumbnails: ein Mini-Thumbnail, welches zur Darstellung von Seitenübersichten verwendet wird und ein HiRes-Thumbnail, welches beim Anzeigen einer Seite dem Benutzer präsentiert wird während im Hintergrund die PDF-Daten gerastert werden. Hierzu werden einfach JPEG- oder PNG-Dateien erzeugt, welche sich an folgende Namenskonventionen halten:

Eigenschaft Typ
Mini-Thumbnails Image-Source + ‘____mthumb_’ + Seitenindex (0-basiert) - Beispiel: ‘pdf_name.pdf____mthumb_0’
HiRes-Thumbnails Image-Source + ‘____thumb_’ + Seitenindex (0-basiert) - Beispiel: ‘pdf_name.pdf____thumb_0’

Das anchor Objekt

Ein anchor-Objekt beschreibt einen ‘Ort von Interesse’ innerhalb der Publikation. Dieser Ort wird als ein Rechteck mit einer bestimmten Größe und Position auf einer Seite beschrieben, und kann anschließend über einen Namen / ID referenziert werden. Jedes Anker Objekt ist ein Unterobjekt der Seite auf der es platziert ist. Alle Eigenschaften sind schon in dem Content Objekt denfiniert, deshalb gibt es für dieses Objekt keine zusätzlichen Parameter.

Hierüber können z.B. die einzelnen Textrahmen eines Artikels oder Textrahmen eines Lesezeichens beschrieben.

Eine Standard-Funktionalität ist das automatisches Heranzoomen an diesen anchor bei einem Doppel-Tap darauf. Siehe hierzu auch   Anker.

Das audio Objekt

Das audio-Objekt erlaubt es, Audio-Medien in die Publikation einzubinden. Der Zielrahmen sollte je nach Implementation mit einem   Play-Icon versehen werden und dem Benutzer mit einem Tap erlauben, das Abspielen zu starten, bzw. zu   anzuhalten.

Eigenschaft Typ Beschreibung
source String URL der Mediendatei. Ist die URL ein Stream so wird dieser - falls der Player online ist - aus dem Netz abgespielt. Bevorzugt werden zwischengespeicherte Audiofiles verwendet.
autoPlay ? Boolean Vorgabe ob das Audio direkt bei Wechsel auf die Seite abgespielt wird. Dieses sollte nur für ein einziges Audio/Videoelement auf der Publikationsseite aktiviert sein. (Default: false)
loop ? Boolean Wenn true, wird das Audiofile endlos abgespielt. (Default: false)
_mediaUuid String Ist ein eindeutiger ID-String dieser Mediendatei für die interne Verwaltung

Beispiel (Audio Objekt):

{
    "source": "media/a8c8261b2f614eabbe5bd7bfd6a8c225.data",
    "height": 100.0,
    "width": 100.0,
    "_mediaUuid": "a8c8261b2f614eabbe5bd7bfd6a8c225",
    "y": 589.473684210526,
    "x": 582.342954159593,
    "type": "audio",
    "id": "audio_58075",
    "loop": false,
    "autoPlay": true
}

Mehr Informationen unter   Audio.

Das video Objekt

Über das video-Objekt können Video-Medien in die Publikation eingebunden werden. Je nach Implementation und Hardware des Zielgerätes können die verwendeten Codecs und Containerformate variieren (z.B. iOS verwendet MP4/H.264).

Eigenschaft Typ Beschreibung
source String URL der Videodatei. Ist die URL ein Stream so wird dieser - falls der Player online ist - aus dem Netz abgespielt. Bevorzugt werden zwischengespeicherte Audiofiles verwendet.
autoPlay ? Boolean Vorgabe ob das Video direkt bei Wechsel auf die Seite abgespielt wird. Dieses sollte nur für ein einziges Audio/Videoelement auf der Publikationsseite aktiviert sein. (Default: false)
loop ? Boolean Wenn true, wird das Video endlos abgespielt. (Default: false)
fullScreen ? Boolean Wenn true, wird das Video direkt im Vollbildmodus abgespielt. (Default: false)
dimBackground ? Boolean Legt fest ober der Hintergrund des Objektrahmes abgedunkelt wird. Ansonsten wird nur das   Icon auf der Seite angezeigt. (Default: false)
controlStyle ? String Legt fest, welche Steuerelemente für den Benutzer verfügbar sind, um das Abspielen des Videos zu steuern. Mögliche Werte sind default oder ein Leerstring “” (Zeigt die Standard-Steuerung an) und none (es werden keine Steuerelemente gezeigt). (Default: default)
_mediaUuid String Ist ein eindeutiger ID-String dieser Mediendatei für die interne Verwaltung

Beispiel (Video Objekt):

{
    "fullScreen": true,
    "dimBackground": false,
    "controlStyle": "",
    "height": 40.0,
    "width": 40.0,
    "_mediaUuid": "f648e56233614f0fbf676ab3958cebbd",
    "source": "media/f648e56233614f0fbf676ab3958cebbd.data",
    "y": 645.331069609508,
    "x": 11.8845500848896,
    "type": "video",
    "id": "video_58074",
    "loop": false,
    "autoPlay": false
}

Mehr Informationen unter   Video.

Das html Objekt

Mit diesem Objekt können Offline- oder Online-Inhalte dargestellt werden. Unterstützte Inhalte variieren je nach Plattform. Diese Inhalte können lokal (innerhalb der Publikation) oder im Internet/Netzwerk gespeichert sein. Je nach Implementation sollte dieses Objekt von WebKit-basierten Engines dargestellt werden. Mehr unter Generelle Hinweise zum Anzeigen und Einbetten von Webinhalten und WebKit Technologie

Der HTML-Inhalt wird immer “embedded” - also innerhalb des vorgegebenen Objektrechteckes auf der Publikationsseite angezeigt.

Eigenschaft Typ Beschreibung
source String URL des Zielinhaltes (z.B. HTML-Datei). Diese URL kann auch auf eine lokale, mitgelieferte Datei verweisen. Daher können hiermit auch individuelle, interaktive Inhalte mit HTML5 + JavaScript in die Publikation eingebettet werden (HTML-Objekte)
indexFileName String Bei eingebetteten HTML-Paketen ist hier der Dateiname der HTML Datei angegeben die innerhalb diese Paketes geöffnet werden soll. Dieses
transparent ? Boolean Legt fest, ob der Hintergrund des Galerie-Objektes transparent ist oder nicht (inbesondere interessant bei Verwendung von transparenten PNG Dateien). Bitte beachten Sie, dass dieses einen Einfluss auf die Performance der Anzeige auf dem Gerät haben kann. (Default: false)
scalesPageToFit ? Boolean Legt fest, ob die Inhalte des HTML-Objektes in den Rahmen des Objektes eingepasst werden. (Default: true)
zoomContents ? Boolean Legt fest, ob der Inhalt des HTML-Objektes beim Zoomen mit dem Seiteninhalt vergrößert werden soll. Dies kann zu unscharfen Text und Bildern führen. (Default: true)

Beispiel (Browser/HTML Objekt):

{
    "indexFileName": "",
    "source": "http://www.leafled.de/testen",
    "height": 112.4184694866,
    "width": 202.35324507588,
    "zoomContents": true,
    "y": 890.004828585225,
    "x": 482.910027361983,
    "scalesPageToFit": true,
    "type": "html",
    "id": "html_55362",
    "transparent": false
},

Mehr Informationen unter   Browser.

Das picture Objekt

Über das picture-Objekt kann der Inhalt einer JPG oder PNG Bilddatei auf der Seite platziert werden. Dieses kann für zusätzliche Bildelemente und Icons eingesetzt werden die oberhalb des anderen Inhaltes gezeigt werden.

Transparente PNG Dateien erlauben zusätzliche grafische Effekte da der Hintergrund der picture Objekte selber auch transparent ist.

Eigenschaft Typ Beschreibung
source String Der Dateiname der zu verwendenden Bilddatei. Dieses ist i.d.R. eine PNG bzw. JPG Datei. Das Bild wird proportional in den vorgegebenen Rahmen eingepasst, so das das Bild ohne schwarze Ränder innerhalb des Objektrahmens dargestellt wird. Es wird erst geprüft ob es eine entsprechende interne Bilddatei (Icons, Bildern) mit diesem Basisnamen/ID gibt und danach wird in der Publikation gesucht. Zusätzlich kann man folgende Dateien verwenden: Icon (App Icon iPhone), Icon-iPad (App Icon iPad), iTunesArtwork, Default (Splashscreen), ipad-landscape (Bildhinweis für das Drehen des Gerätes), shelf-background (Standard Textilhintergrund für Shelves), thumbnail-pending (Zahnrad für ladende Publikationen). Die Liste der internen Bilddateien steht unter Tabelle der eingebauten App-Icons.
_mediaUuid String Ist ein eindeutiger ID-String dieser Bildatei für die interne Verwaltung

Beispiel (Picture/Bild Objekt):

{
    "source": "media/4ce7b02570c84e92850662bfb702d929.data",
    "height": 70.0,
    "width": 70.0,
    "_mediaUuid": "4ce7b02570c84e92850662bfb702d929",
    "y": 2.39234449760766,
    "x": 3.58851674641149,
    "type": "picture",
    "id": "picture_57385"
},

Mehr Informationen unter   Bildobjekt.

Die word_index.db Datei

Diese SQL-Datenbank enthält alle Suchworte incl. der Referenzen auf die zugehörige Seite sowie der Seitenkoordinate/Position. Diese Datenbank wird automatisch beim Hochladen der PDF-Inhalte durch das Portal erzeugt und danach passend zum Inhalt der verwendeten PDF-Seiten in das SPF Paket für den Download eingebettet.

Diese Suchdatenbank wird - auch bei mehrhundertseitigen Dokumenten - innerhalb von Sekundenbruchteilen durchsucht und zeigt sofort alle gewünschten Textstellen an.

Sobald die Volltextsuche für eine Publikation im Portal aktiviert ist, wird diese Datenbank eingebettet und die Volltextsuche steht innerhalb der Publikation (über ein Toolbar-Icon) zur Verfügung.

Als Basis hierzu dient eine SQlite3-Datenbank mit folgender SQLite-Datenbankstruktur die mit folgenden Befehlen erzeugt werden kann:

CREATE TABLE words (word TEXT, page TEXT, pos_x REAL, pos_y REAL, pos_w REAL, pos_h REAL);
CREATE INDEX words_index ON words (word);

Wir empfehlen den Index erst nach dem Einfügen aller Datensätze zu erzeugen, um die Performance zu erhöhen.

Daten in der Suchdatenbank

Alle Wörter der Publikation werden in der words-Tabelle angelegt. Beschrieben wird ein Rechteck um das Wort herum, welches auch verwendet wird um die Suchergebnisse farblich hervorzuheben.

Die auszufüllenden Spalten sind:

Eigenschaft Typ Beschreibung
word String Das Wort nach dem gesucht werden kann. Dies ist ein UTF-8-String. Alle Buchstaben müssen klein geschrieben sein (lowercase).
page String Der id-Wert der Seite auf welcher sich das Wort befindet
pos_x Float Die Position des Wort-Rechtecks vom linken Rand der Seite in Leafled-Points
pos_y Float Die Position des Wort-Rechtecks vom oberen Rand der Seite in Leafled-Points
pos_w Float Die Breite des Wort-Rechtecks in Leafled-Points
pos_h Float Die Höhe des Wort-Rechtecks in Leafled-Points

Die pdf_pages.pdf Dateien

Die Leafled App benutzt die PDF-Datei um die Inhalte auf dem Endgerät in voller Qualität anzuzeigen. Sind Dateien mit der Endung ”.pdf” eingebettet so handelt es sich um die Inhalte der hochgeladenen Original PDF-Dateien. Auf die Inhalte der jeweiligen PDF-Seiten wird über das source-Feld jedes page-Objektes heraus verwiesen.

...
"pages": [{
    "mappingFactor": 2.8346462942500001,
    "label": "",
    "width": 1024.0,
    "objects": [{
         "source": "pdf_pages.pdf#0",
...

Das source Element enthält neben dem Verweis auf die PDF-Datei einen zusätzlichen Seitenindex hinter dem “#” Zeichen. Dieser Seitenindex ist “nullbasierend”, d.h. das die Seite 1 mit einem Index von 0, die Seite 2 mit ‘1’, usw. angegeben ist.

Durch das Nachladen oder Ersetzen von PDF Seiten im Portal, kann das SPF mehrere auch etwas anders benannte PDF Dateien enthalten. Auch können unterschiedliche Seiten in anderer Reihenfolge als im Original (aufgrund einer eigenen Kapitelstruktur) in ein Gesamt-PDF-Paket zusammengepackt werden.

Dieses ermöglicht die spätere komfortable Verwendung der PDF-Inhalte (als eine Gesamtdatei und in der korrekten Kapitel-Seitenreihenfolge) für das Bereitstellen zum Druck, Versand per Mail o.ä. .

Die pdf_pages.pdf____thumb_XX Dateien

Für jede PDF Seite wird eine Bitmap-Ansicht auf dem Portal vorberechnet, um die Anzeige der Seiteninhalte auf dem Endgerät zu beschleunigen. Dieses Bitmap-Voransichtsdateien haben im Normalfall eine Auflösung von 1024x768 Pixel und sind im JPG oder PNG Format abgelegt (je nachdem welcher Dateityp eine kompaktere Voransichtsdatei berechnen konnte).

Optional kann das Einbetten dieser Bitmap-Dateien im SPF-Modul des Portales abgeschaltet werden (siehe SPF Dateiformat 1.1). Die Leafled App würde dann zu Ende jedes Downloads die Berechnung der nicht mitgelieferten Seitenvoransichten erst auf dem Gerät ausführen (schnellerer Download vs. Berechnungzeit der Bitmap-Dateien).

Die pdf_pages.pdf____mthumb_XX Dateien

Für jede PDF Seite wird zusätzlich eine kleine Bitmap-Ansicht (ca. 300x204 Pixel) auf dem Portal vorberechnet. Dieses “Thumbnail” wird als Anzeige von kleinen Seitenvoransichten innerhalb der Shelves (Titelseite/Coverpage in Regalansichten), Seitenleiste, Kapitelübersicht und verschiedenen kleinen Listendarstellungen (TOC, Suchdialoge, Anmerkungsliste) verwendet.

Medien in SPF-Containern

SPF-Container können neben den PDF-Inhaltsseiten der Publikation auch zusätzliche Medien enthalten. Diese werden im media-Unterverzeichnis des Containers abgelegt. Zwingend notwendig ist dann die Datei media_index.json, welche zusätzliche Informationen zu den eingebetteten Medien enthält.

Die media_index.json-Datei

Diese Datei hat eine einfache JSON-Struktur, welche aus einer Array von Objekten besteht. Jedes Objekt hat folgende Eigenschaften:

Eigenschaft Typ Beschreibung
mimeType String Der MIME-Type der Mediendatei. Dieser kann z.B. über den file-Kommandozeilenbefehl herausgefunden werden, und ist im Internet auch weitläufig dokumentiert.
description String Ein kurzer Beschreibungstext. Kann ein leerer String sein.
created String Ein ISO-Formatiertes Datum, welches das Erstellungsdatum der Mediendatei beschreibt. Format ist: YYYY-MM-DD hh:mm:ss.ms.
uuid String Eine eindeutige UUID dieser Mediendatei. Das Leafled-System erwartet eine entsprechende Datei nach dem Schema <uuid>.data im Medienverzeichnis, bzw. ein Verzeichnis ohne den .data-Suffix falls es sich um ein HTML-Objekt oder entsprechenden Datentyp handelt. (siehe Besondere Medientypen)
fileName String Der Dateiname der Mediendatei. Dieser Name wird zum optional Export bzw. zur Anzeige in der Benutzeroberfläche genutzt.
groupName String Der Name der Gruppe, in welcher diese Mediendatei eingeordnet werden soll. Kann ein leerer String sein.
size Number Die Größe der Mediendatei (bzw. des Mediencontainers) in Bytes.

Alle Eigenschaften sind nicht optional und müssen enthalten sein.

Besondere Medientypen

Zusätzlich zu einfachen Dateien können auch “komplexe” Medien eingebettet werden. In der Regel wird diese Funktionalität für HTML-Objekte verwendet, welche aus einer beliebigen Hierarchie von verschiedenen Dateien bestehen.

In diesem Fall muss der MIME-Type des Objektes auf den Wert application/x-neo-htmlcontainer gesetzt werden. Wichtig ist, dass im media-Verzeichnis ein entsprechendes Verzeichnis existiert, welches nach der vergebenen UUID benannt ist (ohne Pre- oder Suffix).

Der media-Ordner im SPF-Container:

My-SPF-Container.spf
  |
  |
  +-- publication.json
  |
  +-- pdf_pages.pdf
  |
  +-- media/
      |
      +-- media_index.json
      |
      +-- 62b0ee5de4ed4492b78c5dcde1722113.data
      |
      +-- 949b571b26c54e38883be86c78738bca.data
      |
      +-- f62d484a291b4498973045356a814c94.data

Typischer Inhalt einer media-index.json

[
  {
      "mimeType": "image/jpeg",
      "description": "",
      "created": "2013-07-27 09:03:45.905584",
      "uuid": "53678766b02a470c86ef946af1bd38bf",
      "fileName": "biene.jpg",
      "groupName": "erste Galerie",
      "size": 59229
  },
  {
      "mimeType": "image/jpeg",
      "description": "",
      "created": "2013-07-27 09:03:46.136517",
      "uuid": "593adc15caa64fc6a756981c6593f2e8",
      "fileName": "blase.jpg",
      "groupName": "erste Galerie",
      "size": 85075
  },
  {
      "mimeType": "image/jpeg",
      "description": "",
      "created": "2013-07-27 09:03:46.499080",
      "uuid": "5011b7410e69419c8e1c9f4c54f16546",
      "fileName": "blume.jpg",
      "groupName": "erste Galerie",
      "size": 142990
  },
  {
      "mimeType": "image/jpeg",
      "description": "",
      "created": "2013-07-27 09:03:46.931235",
      "uuid": "0f1868ca946847d3ae26323a6688b5e0",
      "fileName": "cham.jpg",
      "groupName": "erste Galerie",
      "size": 205999
  },
  {
      "mimeType": "image/jpeg",
      "description": "",
      "created": "2013-07-27 09:03:47.288950",
      "uuid": "ed000dc65a9b40ecaf9a456635d8bbb9",
      "fileName": "stoff.jpg",
      "groupName": "erste Galerie",
      "size": 168275
  },
  {
      "mimeType": "audio/mp4",
      "description": "",
      "created": "2013-07-26 14:39:05.886687",
      "uuid": "a8c8261b2f614eabbe5bd7bfd6a8c225",
      "fileName": "SaxSpot.m4a",
      "groupName": "Medien",
      "size": 1247083
  },
  {
      "mimeType": "image/png",
      "description": "",
      "created": "2013-07-29 18:19:25.196903",
      "uuid": "dac6d7fc97db4718a82b5758aba0c198",
      "fileName": "alarm_on_24.png",
      "groupName": "Icons",
      "size": 321
  },
  {
      "mimeType": "application/x-neo-htmlcontainer",
      "description": "",
      "created": "2013-07-28 14:15:17.747977",
      "uuid": "4d0cf3128f2a48bca478bb193f037b47",
      "fileName": "webkit_tetris.zip",
      "groupName": "Zusatzmedien",
      "size": 353868
  },
  {
      "mimeType": "video/quicktime",
      "description": "",
      "created": "2013-07-26 14:39:03.693537",
      "uuid": "f648e56233614f0fbf676ab3958cebbd",
      "fileName": "big_buck_bunny_small_trailer.mov",
      "groupName": "Medien",
      "size": 749574
  },
  {
      "mimeType": "image/png",
      "description": "",
      "created": "2013-08-05 15:40:33.675292",
      "uuid": "4ce7b02570c84e92850662bfb702d929",
      "fileName": "delete@2x.png",
      "groupName": "Icons",
      "size": 645
  }
]

Hinweise zum Erstellen eigener SPF Pakete

Achten Sie darauf das beim Erstellen eines ZIP Paketes nur die Inhaltsdateien ausgewählt sind. Der SPF-Importer des Portals erwartet alle Dateien sowie den Media Ordner in der obersten Ordner-Ebene. Wenn Sie den übergeordneten Ordner “zippen” können die Inhalte nicht importiert werden.

Die Mediendateien können von Ihnen alternativ auch im obersten Ordner abgelegt und verlinkt werden. Mit dem Import werden alle Bestandteile der SPF Datei in die Portal-Datenbank überführt und so von der Struktur her vereinheitlicht. Bei einem späteren Export als SPF liegt die Publikation in der oben beschriebenen Struktur (Media Ordner) vor.

Sie Suchdatenbank word_index.db muß nicht mitgeliefert werden. Diese Datenbank wird beim Hochladen des SPF-Paketes in das Portal automatisch generiert.

Die Bitmap Voransichtsdateien werden nach dem Hochladen auch automatisch erzeugt. Der Portalserver braucht diese Dateien selber für Cover- und Kapitelübersichten sowie den Seiteneditor und berechnet diese bei Bedarf neu. Daher müssen diese Dateien nicht unbedingt mitgeliefert werden. Sind jedoch Bitmap Voransichten eingebettet so werden diese für die weiteren Prozessschritte auf dem Portal verwendet. Mehr unter Thumbnailberechnung 1.0 und SPF Dateiformat 1.1 (Thumbnails im SPF-Archiv einbetten).