agorum.pdfView

Dieses Widget stellt eine PDF-Ansicht mit Annotationsfunktionen dar. Es ermöglicht das Anzeigen und Annotieren von PDF-Dateien (.pdf) direkt in agorum core.

Das Widget wird über die Eigenschaft id an ein PDF-Objekt in agorum core gebunden und lädt dessen Inhalt. Hat der Benutzer Annotationen vorgenommen und löst er das Speichern aus, gibt das Widget den geänderten PDF-Inhalt über das Event uploading als InputStream zurück. Der Aufrufer entscheidet dann selbst, wohin er diesen Inhalt speichert (z. B. zurück in dasselbe Objekt oder als neue Datei in einen Ordner).

Im Bearbeitungsmodus wird ein Dirty-Tracking über die Eigenschaft dirty durchgeführt. Nach erfolgreichem Persistieren des Inhalts sollte widget.dirty = false gesetzt werden, damit ungespeicherte Änderungen korrekt zurückgesetzt sind.

Verwendung

Der typische Anwendungsfall für dieses Widget ist das Anzeigen einer PDF-Datei aus agorum core und das Zurückspeichern nach dem Annotieren.

Verwendungsbeispiel

let aguila = require('common/aguila');
let objects = require('common/objects');
let transaction = require('common/transaction');

let object = objects.tryFind('/agorum/roi/Files/Demo/Willkommen.pdf');

let widget = aguila.create({
  type: 'agorum.pdfView',
  id: object.UUID,
  width: 800,
  height: 1000,
});

// Saves the updated PDF back to the same object.
// In aguila.fork() there is no implicitly active transaction context,
// therefore the writing operation must be encapsulated in transaction().
widget.on('uploading', is =>
  aguila
    .fork(() => transaction(() => object.setContent(is)))
    .then(() => (widget.dirty = false))
);

widget;

Hinweise

• Das Widget setzt voraus, dass das über id referenzierte agorum core Objekt eine PDF-Datei ist.
• Beim Speichern benötigt der aktuelle Benutzer Schreibrechte auf das Zielobjekt, sonst schlägt der Aufruf von object.setContent() bzw. objects.create('file', ...) fehl.
• Ignorieren Sie den im uploading-Event übergebenen Stream nie. Verarbeiten Sie ihn entweder vollständig oder schließen Sie ihn explizit per is.close().

Toolbar

Im oberen Bereich des Widgets befindet sich eine Toolbar, über die der Benutzer das PDF navigieren, zoomen, annotieren, drucken und speichern kann.

 

Toolbar-Buttons

Die Buttons (von links nach rechts):

Bereich	Button	Beschreibung
Navigation	Seitenleiste umschalten	Blendet die Seitenleiste mit Miniaturansichten und Gliederung ein bzw. aus.
	Suchen	Öffnet die Volltextsuche im PDF-Dokument.
Seiten	Vorherige Seite / Nächste Seite	Blättert eine Seite zurück bzw. weiter.
	Seitenzahl-Eingabe	Springt direkt zur eingegebenen Seitennummer. Rechts daneben wird die Gesamtseitenzahl angezeigt.
Zoom	Verkleinern (−)	Reduziert die Zoomstufe.
	Vergrößern (+)	Erhöht die Zoomstufe.
	Zoomstufe	Auswahl der Zoomstufe (z. B. Automatischer Zoom, Seitenbreite, prozentuale Werte).
Speichern	Upload to Server	Löst das uploading-Event mit dem aktuellen, ggf. annotierten PDF-Inhalt aus. Über den im Event-Listener registrierten Code wird der Inhalt zurück nach agorum core geschrieben (siehe Beispiele unter Verwendung).
Annotationen	Zeichnen	Aktiviert das Freihand-Zeichenwerkzeug zum Hinzufügen von Annotationen.
	Text hinzufügen	Fügt einen Text als Annotation an einer beliebigen Stelle des PDFs ein.
	Hervorheben	Markiert ausgewählte Textstellen als Hervorhebung.
	Bild einfügen	Fügt ein Bild als Annotation in das PDF ein.
Ausgabe	Drucken	Öffnet den Druckdialog des Browsers.
	Herunterladen	Lädt das Dokument herunter.
Weitere	Weitere Werkzeuge (»)	Blendet zusätzliche Werkzeuge ein, die in der Toolbar aus Platzgründen ausgeblendet wurden.

Wie wird das Speichern (Upload to Server) ausgelöst?

Klickt der Benutzer in der Toolbar auf Upload to Server, löst das Widget das uploading-Event aus und übergibt einen InputStream mit dem aktuellen, vollständigen PDF-Inhalt (inklusive aller im Widget vorgenommenen Annotationen).

Damit dieser Klick tatsächlich zu einer dauerhaften Änderung in agorum core führt, muss in der Anwendung ein Listener für uploading registriert sein, der den Stream verarbeitet – z. B. mit object.setContent(is) (zurückschreiben) oder objects.create('file', { ... content: is }) (als neue Datei ablegen). Ohne Listener bleibt der Klick wirkungslos und der Stream sollte mit is.close() verworfen werden.

Events

uploading

Wird ausgelöst, sobald der Benutzer aus dem Widget heraus den Speicher-Vorgang anstoßt. Das System übergibt als Parameter einen InputStream, der den aktualisierten PDF-Inhalt enthält. Dieser Stream besitzt, analog zur allgemeinen Beschreibung des uploading-Events der Widget-Basisklasse, zusätzlich folgende Werte:

Wert	Beschreibung
id (String)	Eindeutige Kennung dieses Upload-Vorgangs.
name (String)	Vom Widget vorgegebener Dateiname für den hochzuladenden Inhalt.

Da das Persistieren länger dauern kann, sollte die Operation in aguila.fork() ausgeführt werden. Im .then()-Callback (wieder im UI-Thread) wird dann widget.dirty = false gesetzt.

widget.on('uploading', is =>
  aguila
    .fork(() => transaction(() => object.setContent(is)))
    .then(() => (widget.dirty = false))
);

Parameter

Die folgenden Parameter gelten zusätzlich zu den grundlegenden Eigeschaften der Widget-Basisklasse, insbesondere width, height, cls, tooltip, hidden und disabled, die hier nicht erneut beschrieben werden. 

id (String)

Die Objekt-ID (UUID, numerische ID oder Pfad) des PDF-Objekts in agorum core, das angezeigt bzw. bearbeitet werden soll. Kann bei der Erstellung oder nachträglich gesetzt werden.

// Set via creation
let widget = aguila.create({
  type: 'agorum.pdfView',
  id: object.UUID
});

// Set afterwards
widget.id = object.UUID;

dirty (Boolean)

Gibt an, ob ungespeicherte Änderungen vorliegen. Diese Eigenschaft wird vom Widget verwaltet und sollte vom Aufrufer nach erfolgreichem Persistieren des Inhalts (typischerweise im .then()-Callback nach dem aguila.fork()) wieder auf false gesetzt werden.

Wert	Beschreibung
true	Es liegen ungespeicherte Änderungen vor.
false	Keine ungespeicherten Änderungen.

readOnly (Boolean)

Wert	Beschreibung
true	Versetzt das PDF-Widget in einen reinen Lesemodus. Annotationen sind nicht möglich.
false (Standard)	Das PDF-Widget ist editierbar (Annotationen sind möglich).

Beispiele

PDF anzeigen und in dasselbe Objekt zurückspeichern

let aguila = require('common/aguila');
let objects = require('common/objects');
let transaction = require('common/transaction');

let object = objects.tryFind('/agorum/roi/Files/Demo/Willkommen.pdf');

let widget = aguila.create({
  type: 'agorum.pdfView',
  id: object.UUID,
  width: 800,
  height: 1000,
});

widget.on('uploading', is =>
  aguila
    .fork(() => transaction(() => object.setContent(is)))
    .then(() => (widget.dirty = false))
);

widget;

PDF nur anzeigen (Read-Only)

Für die reine Anzeige genügt es, das Widget mit readOnly: true zu erstellen. Ein Listener für das uploading-Event ist dann nicht erforderlich.

let aguila = require('common/aguila');
let objects = require('common/objects');

let object = objects.tryFind('/agorum/roi/Files/Demo/Willkommen.pdf');

let widget = aguila.create({
  type: 'agorum.pdfView',
  id: object.UUID,
  readOnly: true,
  width: 800,
  height: 1000,
});

widget;

Jede Änderung als neue Datei ablegen

Soll bei jedem Speichervorgang eine neue Datei (statt einer neuen Version des Originals) entstehen, lässt sich der im uploading-Event mitgegebene Stream direkt als content einer neu erzeugten Datei verwenden. Verwenden Sie diesen Listener anstelle des Listeners aus dem ersten Beispiel und nicht beide gleichzeitig.

let aguila = require('common/aguila');
let objects = require('common/objects');
let transaction = require('common/transaction');

let object = objects.tryFind('/agorum/roi/Files/Demo/Willkommen.pdf');

let widget = aguila.create({
  type: 'agorum.pdfView',
  id: object.UUID,
  width: 800,
  height: 1000,
});

widget.on('uploading', is =>
  aguila
    .fork(() =>
      transaction(() =>
        objects.create('file', {
          name: object.baseName + '-' + Date.now() + '.pdf',
          target: object.firstParent,
          content: is,
        })
      )
    )
    .then(() => (widget.dirty = false))
);

 

Exceptions

Zu dieser Funktion existieren keine Exceptions.