Dokumentation
Anleitung

Overlay-JSON: Seiten, Bilder und Seitensprünge

Seitenversatz, Zentimeterpositionen, Bilder, Seitensprünge und reine Seitenleisten-Inhalte für Seitenbereiche erklären.

Auf dieser Seite

Die Datei hallo-viertel.json beschreibt die zusätzlichen Inhalte des Beispielhefts. Sie liegt direkt neben hallo-viertel.pdf. Öffnen Sie die JSON in einem Texteditor. Speichern Sie gültiges JSON als UTF-8: Feldnamen und Texte stehen in doppelten Anführungszeichen, Dezimalzahlen verwenden einen Punkt, Kommentare und abschließende Kommas sind nicht erlaubt.

Seiten richtig zuordnen

Das Beispiel hat acht physische PDF-Seiten, aber nur sechs gedruckte Inhaltsseiten:

Physische PDF-Seite Inhalt Gedruckte Seitennummer
1 Deckblatt keine
2 Übersicht keine
3 Neu hier? 1
4 Ein Kaffee, bitte. 2
8 Mein Tag in Lindenau 6

Schnellstart: Zählen Sie die Seiten vor der gedruckten Seite 1

Öffnen Sie Ihre PDF und suchen Sie die Seite, auf der unten oder oben die Seitenzahl 1 gedruckt ist. Wie viele PDF-Seiten liegen davor? Zählen Sie Deckblatt, Übersicht und auch leere Seiten mit.

Für ein neues Produkt empfehlen wir: Verwenden Sie in der JSON die gedruckten Seitenzahlen und tragen Sie die Anzahl dieser Vorseiten bei beiden Feldern, pageOffset und startPage, ein.

Vor der gedruckten Seite 1 liegen … pageOffset startPage
keine Seiten 0 0
ein Deckblatt 1 1
ein Deckblatt und eine Übersicht 2 2
vier Vorseiten, einschließlich leerer Seiten 4 4

Das gilt für Hefte, deren Inhaltsseiten fortlaufend ab 1 nummeriert sind. Den Sonderfall einer PDF mit eigenen internen Seitenlabels erklären wir weiter unten.

Unser Beispiel hat zwei Vorseiten. Die passenden Grundeinstellungen lauten deshalb:

{
  "version": 2,
  "startPage": 2,
  "pageOffset": 2,
  "twoPageOffset": 1,
  "overlays": []
}
  • version: 2 legt das verwendete JSON-Format fest.
  • twoPageOffset: 1 lässt in der Doppelseitenansicht das Deckblatt einzeln stehen; danach werden die physischen Seiten 2 und 3, 4 und 5 usw. zusammengefasst. Es verändert keine Seitennummern.

Warum gibt es dafür zwei Felder?

Die Felder sind keine Alternativen. Das eine platziert die Zusatzinhalte, das andere beschriftet die Seitenanzeige.

pageOffset beantwortet: Auf welche PDF-Seite gehört mein Bild, Audio oder anderer Zusatzinhalt?

Sie möchten ein Bild auf der gedruckten Seite 1 anbieten. In der JSON schreiben Sie dafür pageNum: 1. Mit pageOffset: 2 überspringt der Reader bei dieser Zuordnung die beiden Vorseiten und setzt das Bild auf die dritte PDF-Seite. Dort steht im Heft die gedruckte Seitenzahl 1. Ohne diesen Versatz würde das Bild auf dem Deckblatt landen.

startPage beantwortet: Welche Seitenzahl soll der Reader für diese Seite anzeigen?

Auf der dritten PDF-Seite soll in der Seitenanzeige „1“ stehen, passend zur gedruckten Seitenzahl. Dafür steht startPage auf 2: Die beiden Vorseiten werden bei der sichtbaren Nummerierung abgezogen. Ohne diese Einstellung würde dort „3“ stehen, sofern die PDF keine eigenen Seitenlabels hat. Das Bild wäre mit dem richtigen pageOffset trotzdem auf der richtigen Seite.

Achtung: startPage: 2 bedeutet nicht „Öffne das Heft auf Seite 2“. Es stellt nur die Nummerierung ein. Kein Feld entfernt Deckblatt oder Übersicht aus der PDF.

So prüfen Sie Ihre Einstellung

  1. Legen Sie einen Zusatzinhalt mit pageNum: 1 an, beispielsweise das Bild aus dem nächsten Abschnitt.
  2. Öffnen Sie das Medium im Reader und blättern Sie zur Seite mit der gedruckten Seitenzahl 1.
  3. Prüfen Sie getrennt: Ist der Zusatzinhalt auf dieser Seite? Dann passt die Zuordnung mit pageOffset. Zeigt auch die Seitenanzeige „1“? Dann passt die sichtbare Nummerierung.
Was stimmt nicht? Was sollten Sie kontrollieren?
Das Bild liegt auf dem Deckblatt oder einer anderen Seite. pageNum und pageOffset. Eine Änderung an startPage verschiebt das Bild nicht.
Das Bild liegt richtig, aber die Seitenanzeige zeigt „3“ statt „1“. startPage beziehungsweise die internen PDF-Seitenlabels. Lassen Sie den bereits passenden pageOffset unverändert.

Wann müssen die Werte unterschiedlich sein?

Für ein neues Heft nach diesem Vorgehen normalerweise nicht. Ein Unterschied ist beispielsweise nötig, wenn Sie vorhandene JSON-Daten übernehmen, die bereits die tatsächlichen PDF-Seiten zählen.

Angenommen, das Bild für die gedruckte Seite 1 hat dort bereits pageNum: 3, weil es auf die dritte PDF-Seite gehört. Dann verwenden Sie pageOffset: 0, damit nicht noch einmal zwei Seiten addiert werden. startPage: 2 bleibt für die Anzeige „1“ bestehen. Mit pageOffset: 2 würde derselbe Eintrag fälschlich auf der fünften PDF-Seite landen.

Bleiben Sie innerhalb einer JSON-Datei bei einer Zählweise. Der Seitenversatz gilt auch für Lektionsbereiche und die Seitenangaben von Sprungzielen, nicht nur für Bilder.

Sonderfall: Die PDF bringt eigene Seitenlabels mit

Eine PDF kann interne Seitenbezeichnungen speichern, etwa „i“, „ii“, „1“, „2“. Diese heißen Seitenlabels. Eine auf die Seite gedruckte Zahl allein ist noch kein solches Label.

Interne PDF-Seitenlabels können bei der Anzeige Vorrang vor der Berechnung mit startPage haben. Bleibt die angezeigte Seitenzahl trotz richtig eingestelltem startPage falsch, prüfen Sie die Seitenlabels beim PDF-Export. pageOffset brauchen Sie weiterhin passend zur Zählweise Ihrer JSON: PDF-Seitenlabels verschieben keine Zusatzinhalte.

Ein Bildoverlay hinzufügen

Das erste Bild steht unter media/viertel.jpg. Der Eintrag in overlays lautet:

{
  "pageNum": 1,
  "destX": 18.4,
  "destY": 15.4,
  "type": "image",
  "path": "viertel.jpg",
  "description": "Das Viertel – Bild vergrößern",
  "category": "Bilder",
  "taskID": "L1-A1",
  "skills": ["Sprechen"],
  "keywords": ["Begrüßung", "Nachbarschaft"]
}

pageNum benennt hier die gedruckte Inhaltsseite. type legt die Aktion fest: image öffnet ein Bild. Für diesen Bildpfad ergänzt der Reader den Ordner media, sodass viertel.jpg auf media/viertel.jpg verweist. Groß-/Kleinschreibung und Dateiendung müssen stimmen.

Positionen in Zentimetern

destX und destY sind Zahlen in Zentimetern, gemessen von der linken oberen Ecke der PDF-Seite. X wächst nach rechts, Y nach unten. Der Bezugspunkt des normalen Overlaybuttons ist seine untere Mitte.

Bei destX: 18.4 und destY: 15.4 liegt dieser Bezugspunkt also 18,4 cm rechts und 15,4 cm unterhalb der linken oberen Seitenecke. Das Beispiel verwendet A4-Seiten mit 21 × 29,7 cm. Die Werte sind keine Bildschirm-Pixel und werden beim Zoomen mit der Seite skaliert.

Messen Sie die Position an der endgültigen PDF-Seite. Lassen Sie ausreichend Abstand zu Text, Rand und anderen Buttons. Prüfen Sie das Ergebnis im Reader auch nach einem Zoomwechsel.

Beschreibung und Ordnung

description benennt den Inhalt in der Seitenleiste. category ergänzt eine Kategorie für Suche und Filter. Die sichtbaren Gruppen im Hauptbereich richten sich je nach Ansicht auch nach dem Medientyp; beispielsweise muss category: "Hören" nicht zu einer Überschrift „Hören“ führen. taskID verknüpft den Inhalt mit einer Aufgabe; verwenden Sie dafür stabile, eindeutige Bezeichnungen. skills und keywords ergänzen Begriffe für die Suche und Filter.

Für das zweite Bild kopieren Sie den Eintrag und ändern mindestens Seite, Position, Pfad und Beschreibung. Das vollständige Beispiel verwendet auf Seite 2 cafe.jpg mit destX: 18.4 und destY: 12.8.

Das geöffnete Bildoverlay der ersten Lektion

Lektionen gliedern

tableOfContents beschreibt Lektionsbereiche. Die Felder fromPage und toPage sind einschließlich ihrer Grenzen zu verstehen und verwenden dasselbe Seitensystem wie pageNum:

"tableOfContents": [
  { "title": "Neu hier?", "shortTitle": "01", "fromPage": 1, "toPage": 1 },
  { "title": "Ein Kaffee, bitte.", "shortTitle": "02", "fromPage": 2, "toPage": 2 }
]

Dieser Ausschnitt gehört als Eigenschaft in das äußere JSON-Objekt, neben overlays. Im vollständigen Beispiel stehen dort alle sechs Lektionen.

Was die Leser davon sehen

Die Lektionsbereiche geben den Seiten und Zusatzinhalten einen gemeinsamen Kontext:

  • Orientierung beim Blättern: Auf Inhaltsseite 2 zeigt die Seitenleiste im Beispiel „02, Seite 2“. shortTitle liefert die kurze Lektionsbezeichnung. Ohne passenden Lektionsbereich steht dort nur die Seitenangabe. Bei einer aktiven Suche oder Filterung treten Ergebnisangaben an die Stelle dieser Anzeige.
  • Gezielt in einer Lektion suchen: Im Filter erscheint „Lektionen“. Leser können eine oder mehrere Lektionen wählen und die angezeigten Materialien beziehungsweise die PDF-Textsuche auf deren Seiten begrenzen. „Alle Seiten“ hebt diese Einschränkung auf. Die Auswahl springt nicht automatisch zum Lektionsanfang.
  • Suchergebnisse zuordnen: Treffer können ihre Lektion zusammen mit der Seite anzeigen. In der aufgabenorientierten Ergebnisansicht dienen die Lektionen außerdem als Zwischenüberschriften über den Aufgabengruppen.
  • Lesezeichen wiederfinden: Lesezeichen erhalten einen Lektionsbezug und lassen sich nach Lektionen filtern. Ein Seitenlesezeichen kann weiterhin „Seite 2“ heißen; die Lektionsbezeichnung ergänzt seine Einordnung und kann beim Umbenennen vorgeschlagen werden.

So lässt sich etwa das Café-Bild über den Lektionsfilter „02“ finden, ohne alle Materialien des Hefts durchsuchen zu müssen. Bei einer längeren Lektion, beispielsweise von Seite 2 bis 4, gehören alle drei Seiten zum selben Filterbereich.

Titel und Bereiche festlegen

Geben Sie für jede Lektion sowohl title als auch shortTitle an. title ist der vollständige Name, shortTitle eine kurze, verständliche Bezeichnung wie „02“ oder „Lektion 2“. Einige kompakte Anzeigen verwenden ausdrücklich shortTitle; lassen Sie dieses Feld deshalb nicht einfach weg.

Verwenden Sie eindeutige Lektionstitel und möglichst lückenlose, nicht überlappende Bereiche für die Inhaltsseiten. Bei Überschneidungen wird für die aktuelle Lektionszuordnung der erste passende Eintrag verwendet. Seiten außerhalb aller Bereiche bleiben lesbar, haben aber keinen Lektionsbezug. Ohne tableOfContents funktionieren PDF und Overlays weiterhin; der Lektionsfilter und die zusätzliche Lektionsanzeige fehlen.

Der Name tableOfContents bedeutet hier nicht, dass ein klickbares Inhaltsverzeichnis erzeugt wird. Der Inhaltsverzeichnis-Bereich des Readers verwendet die in der PDF eingebettete Gliederung. Die JSON-Lektionen verändern weder diese PDF-Gliederung noch das gedruckte Inhaltsverzeichnis. Für einen gezielten Sprung aus der Seitenleiste verwenden Sie beispielsweise den folgenden jump-Eintrag.

Einen Seitensprung ergänzen

Dieser zusätzliche Eintrag im Array overlays verweist von Inhaltsseite 6 auf Inhaltsseite 2:

{
  "type": "jump",
  "pageNum": 6,
  "description": "Noch einmal: Im Café bestellen",
  "target": { "type": "page", "pageNum": 2 }
}

pageNum: 6 ist die Seite, auf der der Verweis angeboten wird. target.pageNum: 2 ist sein Ziel. Für beide gilt der eingestellte Seitenversatz. Der Verweis erscheint in der Seitenleiste unter Verweise, nicht als Button auf der PDF. Deshalb benötigt dieser Eintrag keine Position.

Nur Seitenleiste oder zusätzlich ein Button auf der Seite?

Die Seitenzuordnung und die Darstellung sind zwei getrennte Entscheidungen:

Variante Button auf der PDF Eintrag in der Seitenleiste
Normales Medium, etwa type: "pdf", mit pageNum: 2 Auf Seite 2 an destX/destY Auf Seite 2
Dasselbe Medium mit pageFrom: 2, pageTo: 4 Weiterhin nur auf Seite 2 Auf den Seiten 2, 3 und 4
type: "extraMaterial" mit Bereich 2–4 Kein Button Auf den Seiten 2, 3 und 4
type: "jump" Kein Button Verweis auf der Quellseite beziehungsweise im angegebenen Bereich

Die Tabelle beschreibt den normalen Hauptbereich der Seitenleiste. Ein nicht auf main gesetztes addon ist ein anderer Weg: Es ordnet den Inhalt einem eigenen Add-on-Tab zu und unterdrückt den PDF-Button. Verwenden Sie das nicht als Ersatz für gewöhnliches Zusatzmaterial im Hauptbereich.

PDF-Button auf einer Seite, Seitenleisteneintrag für einen Bereich

{
  "type": "pdf",
  "pageNum": 2,
  "pageFrom": 2,
  "pageTo": 4,
  "destX": 18.4,
  "destY": 18,
  "path": "material/loesungen.pdf",
  "description": "Lösungen und Gesprächsimpulse",
  "category": "Zusatzmaterial"
}

Der Button bleibt auf Inhaltsseite 2. Der Eintrag in der Seitenleiste ist zusätzlich auf den Inhaltsseiten 3 und 4 verfügbar. Auf Seite 1 und ab Seite 5 erscheint er nicht. pageFrom und pageTo schließen beide Grenzen ein; der eingestellte pageOffset gilt auch für diese Werte.

Bei normalen Medien muss pageNum innerhalb des Bereichs liegen. Verwenden Sie ganze Seitenzahlen und bleiben Sie innerhalb der PDF. Fehlt ein gültiger Bereich, fällt der Reader bei normalen Medien auf die einzelne Quellseite zurück.

Dasselbe Dokument ausschließlich in der Seitenleiste

{
  "type": "extraMaterial",
  "pageNum": 2,
  "pageFrom": 2,
  "pageTo": 4,
  "path": "material/loesungen.pdf",
  "description": "Begleitblatt – nur Seitenleiste (Seiten 2–4)",
  "category": "Zusatzmaterial"
}

Dieser Eintrag bietet das Dokument auf den Inhaltsseiten 2 bis 4 an, ohne irgendwo einen Button auf der PDF zu zeichnen. Für dieses Zusatzmaterial geben Sie beide Bereichsgrenzen an. Koordinaten sind nicht erforderlich.

Nur destX und destY wegzulassen reicht bei einem normalen Medium nicht. Fehlende Koordinaten können zu einem Button am Seitenursprung führen. Auch category: "Zusatzmaterial" ändert nur die Einordnung; erst der Typ extraMaterial legt hier die reine Seitenleisten-Darstellung fest.

Vergleich im laufenden Beispiel

Das erweiterte Paket aus Audio, Video und Zusatz-PDFs einbinden enthält absichtlich beide Einträge mit derselben PDF-Datei, aber unterschiedlichen Beschreibungen. So können Sie sie direkt vergleichen. Für Ihr eigenes Produkt wählen Sie normalerweise eine der beiden Varianten.

Inhaltsseite 2: beide Einträge in der Seitenleiste, PDF-Button nur für das normale Medium

Inhaltsseite 3: beide Einträge weiterhin verfügbar, auf dieser PDF-Seite keine Overlaybuttons

Prüfen Sie beim eigenen Bereich immer die erste und letzte eingeschlossene Seite sowie jeweils eine Seite davor und danach. Blättern Sie außerdem von der Ankerseite weg: Ein Bereich soll keinen zusätzlichen PDF-Button auf jeder Seite erzeugen.

Änderungen hochladen

Speichern Sie die JSON unter demselben Namen und laden Sie sie an denselben Ort im Medium hoch. Sie ersetzt die bisherige Datei. Die PDF bleibt als Index eingestellt. Starten Sie das Medium anschließend erneut und prüfen Sie jede geänderte Stelle.

Das Grundpaket deckt Bilder und Seitensprünge ab. Audio, Video, zusätzliche Dokumente und die Bereichsbeispiele enthält das erweiterte Paket in Audio, Video und Zusatz-PDFs einbinden. Eine eigene HTML-Übung erklärt Eigene HTML-Übungen aus der PDF öffnen.

Weiter mit der Abschlussprüfung: PDF-Overlay-Produkte prüfen und aktualisieren. Das vollständige Beispielpaket finden Sie im Einstieg: PDF mit Overlays: Einstieg und Beispielpaket. Upload-Schritte: PDF mit Overlays im Marketplace einrichten.