Zum Inhalt

Wiedervorlagen

Wiedervorlage Funktionen

Die früheren prozeduralen Funktionen aus reminder.lib (lmb_addReminder, lmb_dropReminder, …) wurden entfernt. Eine Übersicht zur Umstellung von altem Code findet sich am Ende dieses Dokuments.

Die Wiedervorlage-Funktionalität (Tabelle LMB_REMINDER) wird über die Klasse Limbas\extra\reminder\Reminder abgebildet.

GUI Element (Javascript)

Anzeigen eines Modals zum Erstellen oder Bearbeiten einer Wiedervorlage.

limbasReminder(reminderId = 0)

Parameter

  • reminderId (optional): Die ID der Wiedervorlage, die angezeigt werden soll. Wenn keine ID angegeben wird, wird das Modal zum Erstellen einer Wiedervorlage angezeigt.

PHP

Klasse Reminder

Die Klasse Reminder repräsentiert eine Wiedervorlage und enthält Methoden zum Erstellen, Bearbeiten und Abrufen von Wiedervorlagen.

use Limbas\extra\reminder\Reminder;

Eigenschaften

Eine Reminder-Instanz besitzt folgende Eigenschaften:

Eigenschaft Typ Beschreibung
id (privat) int Wiedervorlagen-ID. Nur lesbar über $reminder->getId()
$tableId int Tabellen-ID (gtabid), zu der die Wiedervorlage gehört.
$dataId ?int Datensatz-ID.
$deadline DateTime Fälligkeitsdatum der Wiedervorlage.
$description ?string Beschreibung.
$fromUser ?int Ersteller. Ist der Wert null, wird automatisch der aktuell angemeldete Benutzer ($session["user_id"]) gesetzt.
$content ?string Inhalt. Ist der Wert leer und für die Tabelle ein Hauptfeld definiert, wird der Inhalt beim Erstellen automatisch aus dem Hauptfeld des Datensatzes ermittelt.
$category ?int Wiedervorlagengruppe (Kategorie). 0 = Standard-Wiedervorlage.
$workflowInstance ?int Workflow-Instanz.
$formId ?int Formular, das beim Anklicken der Wiedervorlage geöffnet wird.
$multitenantId ?int Mandanten-ID.

Hinweis: Der Konstruktor ist private. Neue Wiedervorlagen werden nicht mit new Reminder(...) erzeugt, sondern über die Factory-Methode Reminder::create() erstellt und gespeichert; bestehende werden über Reminder::get() bzw. Reminder::all() geladen. Die öffentlichen Eigenschaften können anschließend gelesen und (vor einem save()) verändert werden, z. B. $reminder->deadline = $newDate;. Die ID ist nur lesbar über getId().

Statische Methoden

Reminder::create(...)
public static function create(
    int      $tableId,
    ?int     $dataId,
    DateTime $deadline,
    ?string  $description,
    ?int     $fromUser = null,
    ?string  $content = '',
    int      $category = 0,
    int      $workflowInstance = 0,
    int      $formId = 0,
    array    $userOrGroupArray = [],
    bool     $sendMail = false,
): ?array

Erstellt eine oder mehrere Wiedervorlagen und speichert sie.

Parameter Typ Beschreibung
$tableId int Tabellen-ID (gtabid).
$dataId ?int Datensatz-ID.
$deadline DateTime Fälligkeitsdatum.
$description ?string Beschreibung.
$fromUser ?int Ersteller. Bei null wird der aktuell angemeldete Benutzer gesetzt.
$content ?string Inhalt. Bei leerem Wert und vorhandenem Hauptfeld wird der Inhalt automatisch aus dem Datensatz ermittelt.
$category int Wiedervorlagengruppe (Kategorie). 0 = Standard-Wiedervorlage.
$workflowInstance int Workflow-Instanz.
$formId int Formular, das beim Anklicken geöffnet wird.
$userOrGroupArray array Liste der Benutzer und/oder Gruppen, denen die Wiedervorlage zugeordnet wird (siehe Benutzer- und Gruppenzuweisung). Ist die Liste leer, wird die Wiedervorlage dem aktuell angemeldeten Benutzer zugeordnet.
$sendMail bool Ob eine Benachrichtigung per E-Mail an die zugeordneten Benutzer gesendet werden soll.

Rückgabe: Bei Erfolg ein Array der erstellten Reminder-Objekte (deren ID bereits gesetzt ist). Bei einem Datenbankfehler null. Der Vorgang läuft in einer Transaktion; bei einem Fehler wird zurückgerollt.

Das Zuordnungsverhalten hängt davon ab, ob die Kategorie gruppenbasiert ist:

  • Gruppenbasiert: Es wird genau eine Wiedervorlage erstellt, auf die alle zugeordneten Benutzer und Gruppen verweisen.
  • Nicht gruppenbasiert: Für jeden Benutzer (auch jedes Mitglied einer zugeordneten Gruppe) wird eine eigene Wiedervorlage erstellt.
Reminder::get(int $id): Reminder|null

Liefert eine einzelne Wiedervorlage anhand ihrer ID oder null, falls keine gefunden wurde.

Reminder::all(array $where = [], ?int $category = null, ?int $tableId = null, ?int $dataId = null, bool $valid = false, ?int $userId = null): array

Liefert ein Array von Reminder-Objekten anhand der übergebenen Filter. Berücksichtigt automatisch Berechtigungen (Tabellenrechte), Mandantenfähigkeit sowie gruppen- bzw. benutzerbasierte Sichtbarkeit.

Parameter Typ Beschreibung
$where array Zusätzliche Where-Bedingungen als ['FELD' => Wert].
$category ?int Wiedervorlagengruppe (Kategorie).
$tableId ?int Tabellen-ID.
$dataId ?int Datensatz-ID.
$valid bool Bei true werden nur fällige Wiedervorlagen (FRIST < aktueller Zeitpunkt) zurückgegeben.
$userId ?int Optionaler Benutzer. Standardmäßig wird der angemeldete Benutzer aus der Session verwendet.
Reminder::allLegacy(?int $category = null, ?int $tableId = null, ?int $dataId = null, ?int $wfl_inst = null, ?bool $valid = false): array

Wie all(), liefert das Ergebnis jedoch im alten, spaltenorientierten Array-Format (['id' => [...], 'validdate' => [...], 'desc' => [...], …]). Nicht empfohlen für neue Entwicklungen, stattdessen all() nutzen.

Reminder::deleteByFilter($reminderId, $tableId = null, $category = null, $dataId = null, $workflowInstance = null, $valid = null): bool

Löscht eine oder mehrere Wiedervorlagen anhand der übergebenen Filter.

Rückgabe: true bei Erfolg, andernfalls false.

Reminder::countPerCategory(int $category): int

Liefert die Anzahl der aktiven (fälligen) Wiedervorlagen einer Kategorie für den aktuellen Benutzer.

Reminder::sendAllCronMails(): void

Versendet für jeden Benutzer eine Sammel-E-Mail mit dessen offenen (fälligen) Wiedervorlagen.

Reminder::convertLegacyUsergroupArray(mixed $userOrGroupArray): array

Hilfsfunktion zur Migration: Wandelt die alte Zuordnungsnotation (String wie '33_u;22_g') in das neue userOrGroupArray-Format um. Nicht empfohlen für neue Entwicklungen, stattdessen neues Format nutzen.

Methoden

save(): bool

Speichert Änderungen an einer bestehenden Wiedervorlage (UPDATE). Voraussetzung ist eine gültige ID; bei einer Wiedervorlage ohne ID (0) gibt die Methode false zurück, ohne etwas zu speichern. Zum Anlegen neuer Wiedervorlagen dient Reminder::create().

Rückgabe: true bei Erfolg, andernfalls false.

update(): bool

Schreibt die aktualisierbaren Felder (tab_id, dat_id, frist, description, content, category, wfl_inst, form_id) in die Datenbank. save() ist im Wesentlichen ein Wrapper um diese Methode mit vorheriger ID-Prüfung.

Rückgabe: true bei Erfolg, andernfalls false.

delete(): bool

Löscht die Wiedervorlage.

Rückgabe: true bei Erfolg, andernfalls false.

getId(): int

Gibt die ID der Wiedervorlage zurück. Über Reminder::get(), Reminder::all() oder Reminder::create() erhaltene Wiedervorlagen tragen ihre tatsächliche ID.

getDeadlineTimezoned(): string

Gibt das Fälligkeitsdatum (deadline) als formatierte, zeitzonenbereinigte Zeichenkette zurück.

toArray(): array

Gibt alle Eigenschaften der Wiedervorlage als assoziatives Array zurück (Schlüssel entsprechen den Property-Namen der Klasse).

toArrayLegacy(): array

Gibt die Wiedervorlage im alten Array-Format (Schlüssel wie tab_id, dat_id, validdate, desc, fromuser, …) zurück. Nützlich für die Kompatibilität mit altem Code. Nicht empfohlen für neue Entwicklungen, stattdessen toArray() nutzen.

Benutzer- und Gruppenzuweisung

Reminder::create() erwartet im Parameter $userOrGroupArray ein Array von Zuordnungen. Jeder Eintrag besteht aus type ('user' oder 'group') und id:

$userOrGroupArray = [
    ['type' => 'user',  'id' => 33],
    ['type' => 'group', 'id' => 22],
    ['type' => 'user',  'id' => 55],
];

Bei einer leeren Liste wird die Wiedervorlage automatisch dem aktuell angemeldeten Benutzer zugeordnet.

Nachrichtentext anpassen

Beim Senden einer E-Mail kann der Nachrichtentext über eine eigene Funktion angepasst werden. Der Funktionsname wird über die Wiedervorlageeinstellungen definiert. Für die Standard-Wiedervorlage kann die Funktion über das Array $greminder[$gtabid]["message"][0] = 'myExt_functname' gesetzt werden.

Die Funktion wird mit folgenden Argumenten aufgerufen:

$message = myExt_functname(
    $userId,            // Empfänger
    $tableId,           // Tabellen-ID
    $dataId,            // Datensatz-ID
    $category,          // Kategorie
    $deadline,          // aufbereiteter Fälligkeitszeitstempel
    $description,       // Beschreibung
    $content,           // Inhalt
    $workflowInstance   // Workflow-Instanz
);

Beispiel

function myExt_sendReminderMessage($userId, $gtabid, $ID, $category, $date, $description, $header, $wfl_inst)
{
    global $userdat, $session, $umgvar;

    $message = "
        hallo " . $userdat["bezeichnung"][$userId] . "<br><br>
        " . $session['vorname'] . " " . $session['name'] . " send you a $header - reminder for:<br>
        <i><b><a href=\"" . $umgvar['url'] . "/main.php?action=\"> $header </a></b></i><br><br><br>
        $description<br><br>
    ";

    $message .= "
        -------------------------------------------------------------------------------------<br>
        This is an automatically generated email, please do not reply!<br>
        -------------------------------------------------------------------------------------<br>
    ";

    return $message;
}

Beispiele

Wiedervorlage erstellen

use Limbas\extra\reminder\Reminder;

$deadline = new DateTime('2026-03-16 22:44');

$reminders = Reminder::create(
    tableId:          1,
    dataId:           23,
    deadline:         $deadline,
    description:      'Angebot nachfassen',
    category:         2,
    formId:           5,
    userOrGroupArray: [
        ['type' => 'user',  'id' => 1],
        ['type' => 'group', 'id' => 4],
    ],
    sendMail:         true,
);

if ($reminders === null) {
    // Fehler beim Speichern (Transaktion zurückgerollt)
}

Wiedervorlage bearbeiten

$reminder = Reminder::get(42);

if ($reminder) {
    $reminder->deadline    = new DateTime('2026-04-01 09:00');
    $reminder->description = 'Termin verschoben';
    $reminder->save();
}

Wiedervorlagen abrufen

// Alle fälligen Wiedervorlagen zu einem Datensatz
$reminders = Reminder::all(
    category: 0,
    tableId:  1,
    dataId:   23,
    valid:    true
);

foreach ($reminders as $reminder) {
    echo $reminder->getId() . ': ' . $reminder->description . ' – ' . $reminder->getDeadlineTimezoned() . "\n";
}

Wiedervorlage löschen

// Einzelne Instanz löschen
$reminder = Reminder::get(42);
$reminder?->delete();

// Per Filter löschen
Reminder::deleteByFilter(tableId: 5, dataId: 23);

Anzahl ermitteln

$count = Reminder::countPerCategory(2);

Migration von alten Funktionen

Die Datei reminder.lib und die darin enthaltenen prozeduralen Funktionen wurden entfernt. Bestehender Code, der diese Funktionen noch verwendet, muss auf die Reminder-Klasse umgestellt werden. Die folgende Tabelle zeigt die jeweilige Entsprechung.

Entfernte Funktion Neue Entsprechung
lmb_addReminder($gfrist, $gfrist_desc, $gtabid, $ID, $to, $category, $wfl_inst, $fielddesc, $sendmail, $form_id) Reminder::create($gtabid, $ID, $deadline, $gfrist_desc, null, $fielddesc, $category, $wfl_inst, $form_id, $userOrGroupArray, $sendmail)
lmb_dropReminder($rem_id, $gtabid, $category, $ID, $wfl_inst, $valid) Reminder::deleteByFilter($rem_id, $gtabid, $category, $ID, $wfl_inst, $valid)
lmb_changeReminder($rem_id, $gfrist, $gfrist_desc) Reminder::get($rem_id) → Eigenschaften setzen → save()
lmb_getReminder($gtabid, $ID, $category, $wfl_inst, $valid) Reminder::allLegacy($category, $gtabid, $ID, $wfl_inst, $valid)
lmb_getReminderCount($category) Reminder::countPerCategory($category)

Hinweise zur Migration

  • Die alte Zuordnungsnotation ('33_u;22_g') kann mit Reminder::convertLegacyUsergroupArray() in das neue userOrGroupArray-Format überführt werden, jedoch ist es empfehlenswert, den Code direkt auf das neue Format umzustellen.
  • Der frühere $gfrist-Timestamp wird nun über ein DateTime-Objekt ($deadline) abgebildet.
  • Das alte spaltenorientierte Rückgabeformat von lmb_getReminder() entspricht Reminder::allLegacy(); objektorientierter Code sollte stattdessen Reminder::all() verwenden und mit den Reminder-Objekten arbeiten.