Signatur
Beschreibung
ps_add_bookmark ist Teil der PS-Erweiterung (PECL) und ermöglicht es, in einem PostScript-Dokument Lesezeichen zu definieren, die in der Dokumentstruktur (z. B. als Inhaltsverzeichnis in einem PDF-Viewer nach PS→PDF-Konvertierung) angezeigt werden. Die Funktion muss aufgerufen werden, während die gewünschte Seite geöffnet ist.
Lesezeichen können hierarchisch verschachtelt werden: Über den Parameter parent lässt sich ein übergeordnetes Lesezeichen angeben. So können Kapitel mit Unterkapiteln oder Abschnitte tief verschachtelt werden. Der Rückgabewert (Handle) des Eltern-Lesezeichens dient dabei als Referenz für Kinder-Lesezeichen.
Der Parameter open steuert, ob das Lesezeichen in der Bookmark-Liste des Viewers standardmäßig aufgeklappt dargestellt wird. Ein Wert von 1 bedeutet aufgeklappt, 0 zugeklappt. Dies ist vor allem bei umfangreichen Dokumenten mit vielen Gliederungsebenen relevant.
Die Funktion ist typischerweise sinnvoll beim automatischen Generieren von mehrseitigen Berichten oder Dokumenten aus PHP heraus, wenn eine strukturierte Navigation gewünscht wird.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $psdoc Pflicht | resource | Die Ressource des PostScript-Dokuments, wie sie von ps_new() zurückgegeben wird. |
|
| $text Pflicht | string | Der angezeigte Text des Lesezeichens, wie er im Bookmark-Panel des Viewers erscheint. | |
| $parent | int | 0 | Handle des übergeordneten Lesezeichens. Der Wert 0 bedeutet, dass dieses Lesezeichen kein Elternelement besitzt (Toplevel). |
| $open | int | 0 | Gibt an, ob das Lesezeichen im Viewer standardmäßig aufgeklappt (1) oder zugeklappt (0) angezeigt wird. |
Rückgabewert
parent-Argument für untergeordnete Lesezeichen verwendet werden. Im Fehlerfall wird 0 zurückgegeben.Beispiele
Einfaches Lesezeichen auf der ersten Seite
<?php
$ps = ps_new();
ps_open_file($ps, 'dokument.ps');
ps_begin_page($ps, 595, 842);
// Lesezeichen für Kapitel 1 anlegen
$bookmark1 = ps_add_bookmark($ps, 'Kapitel 1', 0, 1);
ps_set_font($ps, ps_findfont($ps, 'Helvetica', '', 0), 16);
ps_show_xy($ps, 'Kapitel 1', 50, 800);
ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
?>Hierarchische Lesezeichen (Kapitel und Unterabschnitte)
<?php
$ps = ps_new();
ps_open_file($ps, 'bericht.ps');
// Seite 1: Kapitel 1
ps_begin_page($ps, 595, 842);
$kapitel1 = ps_add_bookmark($ps, 'Kapitel 1', 0, 1);
$abschnitt1_1 = ps_add_bookmark($ps, '1.1 Einleitung', $kapitel1, 0);
ps_set_font($ps, ps_findfont($ps, 'Helvetica', '', 0), 16);
ps_show_xy($ps, 'Kapitel 1 - Einleitung', 50, 800);
ps_end_page($ps);
// Seite 2: Kapitel 2
ps_begin_page($ps, 595, 842);
$kapitel2 = ps_add_bookmark($ps, 'Kapitel 2', 0, 1);
$abschnitt2_1 = ps_add_bookmark($ps, '2.1 Methodik', $kapitel2, 0);
ps_show_xy($ps, 'Kapitel 2 - Methodik', 50, 800);
ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
?>// Wichtig · Fallstricke
PECL-Erweiterung: ps_add_bookmark gehört zur ps-PECL-Erweiterung, die separat installiert werden muss (pecl install ps). Sie ist nicht in der Standard-PHP-Distribution enthalten.
Lesezeichen werden nur dann korrekt in der Ausgabe berücksichtigt, wenn sie innerhalb eines geöffneten Seitenbereichs (zwischen ps_begin_page() und ps_end_page()) definiert werden.
Die Bookmark-Funktionalität entfaltet ihre volle Wirkung erst nach der Konvertierung des PostScript-Dokuments in PDF (z. B. via Ghostscript), da PostScript selbst keine native Bookmark-Navigation im Viewer bietet.