npsField

Das Element npsField stellt Funktionalität bereit, um Eingabefelder in Formularen zu erzeugen. Es bietet bequeme feldspezifische Fehlerbehandlung und obligatorische Felder (für unbedingt vom Benutzer zu machende Angaben). Der für die Darstellung erforderliche HTML-Code wird durch das GUI generiert, wodurch das Design einheitlich ist.

Syntax

<npsField type="Typ" name="Name"
  label="Beschriftung" required="Pflicht"
  error="Fehler" width="Breite" …>…</npsField>

Dies erzeugt ein Formularfeld.

• type ist der Typ des Formularfeldes und darf file, text, select, textarea, date oder selectObject sein.
• name ist der Name des erzeugten Parameters.
• label ist der Text, mit dem das Feld beschriftet werden soll.
• required darf true oder false (Voreinstellung) sein. Wenn der Wert true ist, führt es zu einem Fehler, wenn der Benutzer den betreffenden Wert nicht angibt. Die Fehlermeldung wird neben dem Feld angezeigt. Bei Auswahlfeldern wird die Option keine nicht eingeblendet, wenn required auf true steht.
• error kann vom Programmierer des Assistenten auf eine passende Fehlermeldung gesetzt werden, die angezeigt wird, wenn der Assistent im Wert des Feldes einen Fehler gefunden hat. Diese Meldung wird dann ebenfalls neben dem Feld im passenden Design angezeigt.
• width gibt die Breite des Feldes in ex an (ex ist die Standard-Einheit der verwendeten Styles). Dieser Wert wird bei Bedarf zur korrekten Darstellung intern angepasst. Der Firefox-Browser interpretiert diese Angabe derzeit nicht richtig, was zu Darstellungsfehlern führen kann.

Abhängig vom Feldtyp können im npsField-Tag weitere Parameter als Tag-Attribute angegeben werden.

Eingabefeldtypen und ihre Parameter

Dateien hochladen (Typ file)

<npsField type="file" name="Name"
  fileName="Pfad zu der Datei"
  ticketId="Streaming-Ticket-ID"
  mimeType="Mime-Typ" … />

Dies erzeugt ein Dateiauswahlfeld.

• fileName Ist der Name der zu importierenden Datei.
• ticketId ID des Streaming-Tickets, das zum Hochladen der Datei auf den CMS-Server angelegt wurde. Über das Streaming-Interface kann dann mit Tcl auf den Inhalt der Datei zugegriffen werden.
• mimeType schränkt die zur Auswahl stehenden Dateien ein. Details zu Mime-Typen sind in der HTML-Spezifikation zu finden.

Hierzu gibt es ein Anwendungsbeispiel.

Zeichenketten eingeben (Typ text)

<npsField type="text" name="Name" value="Einige Angaben"
    maxLength="Maximale Länge" …/>

Dies erzeugt ein Texteingabefeld.

• maxLength gibt die Anzahl der Zeichen an, die maximal eingegeben werden können.

Eine Option auswählen (Typ select)

<npsField type="select" name="Name" selectionType="single"
    renderMode="Darstellung" …>
…
</npsField>

Dies erzeugt ein oder mehrere Felder zur Auswahl einer Option.

• renderMode gibt an, wie das Feld gerendert werden soll:
  • vertical: Es werden Radiobuttons gerendert.
  • list (Voreinstellung): Es wird ein Aufklapp-Menü gerendert.
• Das Attribut width wird nur ausgewertet, wenn renderMode den Wert list hat.
• Die zur Auswahl stehenden Werte werden mit npsFieldOption-Elementen angegeben.

Mehrere Optionen auswählen (Typ select)

<npsField type="select" name="Name" selectionType="multi"
    renderMode="Darstellung" size="Höhe" …>
…
</npsField>

Dies erzeugt ein oder mehrere Felder zur Auswahl einer Option.

• renderMode gibt an, wie das Feld gerendert werden soll:
  • vertical: Es werden Checkboxen untereinander gerendert.
  • list (Voreinstellung): Es wird ein Mehrfach-Auswahlfeld gerendert.
• Das Attribut width wird nur ausgewertet, wenn renderMode den Wert list hat.
• size wird nur ausgewertet, wenn renderMode auf den Wert list gesetzt ist, und gibt die Höhe des Feldes in Zeilen an.
• Die zur Auswahl stehenden Werte werden mit npsFieldOption-Elementen angegeben.

Text eingeben (Typ textarea)

<npsField type="textarea" name="Name"
    rows="Höhe" cols="Breite"
    style="Style-Angaben"… />

Dies erzeugt einen Texteingabebereich.

• rows gibt die Anzahl der Zeilen des Texteingabebereichs an.
• cols gibt die Breite (Anzahl von Zeichen) des Texteingabebereichs an.
• style ermöglicht es, zusätzliche CSS-Style-Angaben zu machen.

Datei auswählen (Typ selectObject)

<npsField type="selectObject" name="Name" value="Datei-ID"
    startId="Start-Datei-ID" startPath="Start-Datei-Pfad"
    objectTypes="Dateitypen" selectMessage="Meldung"… />

Dies erzeugt ein Dateiauswahlfeld mit einem Eingabefeld und einem Auswahl-Button. Klickt man auf den Button, öffnet sich die Auswahlseite. Wählt man dort eine Datei aus, wird ihr Pfad in das Eingabefeld übernommen.

• startId und startPath geben optional die im Auswahldialog initial selektierte Datei an. Nur eines dieser beiden Attribute darf angegeben werden.
• value enthält optional die ID einer Datei. Der Pfad dieser Datei wird in das Eingabefeld als Vorgabe eingetragen. Dieser Pfad überlagert die Vorgabe von startId bzw. startPath.
• Die optionalen objectTypes schränken die im Auswahldialog erscheinenden Dateien in Bezug auf ihren Typ ein. Der Wert dieses Attributs ist eine kommaseparierte Liste. Ordner sind immer sichtbar.
• Die optionale selectMessage wird angezeigt, um den Benutzer über den Zweck der Dateiauswahl zu informieren.

Datum auswählen (Typ date)

<npsField type="date" name="Name" value="Datum"
    format="Datumsformat"… />

Dies erzeugt ein Datumsauswahlfeld mit einem Eingabefeld und einem Auswahl-Button. Klickt man auf den Button, öffnet sich die Auswahlseite. Wählt man dort ein Datum aus, wird es in das Eingabefeld übernommen.

• value ist der Wert des Datumsauswahlfeldes als 14-stelliges CMS-Datum. Der Feldwert, der an den Assistenten übergeben wird, ist ebenfalls ein 14-stelliges CMS-Datum.
• format ist das optionale Format, mit dem der Feldwert formatiert werden soll. Die möglichen Platzhalter-Werte sind bei dem Systemkonfigurationselement validDateTimeOutputFormats beschrieben. Ist dieser Wert nicht angegeben, wird das Datumsformat des jeweiligen Benutzers verwendet.

Verwendung in Assistenten

Eingabeelemente, d.h. die entsprechenden npsField-Elemente, können in Assistenten komfortabel erzeugt werden, indem Prozeduren aus der Tcl-Bibliothek share/script/cm/serverCmds/wizards/lib/layout.tcl aufgerufen werden. Zusätzliche Parameter werden durchgängig als HTML-Attribute an die erzeugten npsField-Tags übergeben. Dadurch haben Sie die Möglichkeit, CSS-Klassen zu setzen oder zusätzliche HTML-Attribute und Parameter anzugeben.

Einzeiliges Textfeld

::layout::textField name label value …

Erzeugt ein npsField-Element vom Typ text.

• name, label und value setzen die entsprechenden npsField-Element-Attribute. HTML-spezifische Zeichen werden dabei konvertiert.
• Optional können weitere npsField-Element-Attribute als Liste von Name-Wert-Paaren übergeben werden, etwa maxLength.

Beispiel:

::layout::textField bezeichnung "Produktbezeichnung" [getParam bezeichnung]\
    width 40 maxLength 40

Mehrzeiliges Textfeld

::layout::textArea name label value …

Erzeugt ein npsField-Element vom Typ textarea.

• name, label und value setzen die entsprechenden npsField-Element-Attribute. HTML-spezifische Zeichen werden dabei konvertiert.
• Optional können weitere npsField-Element-Attribute als Liste von Name-Wert-Paaren übergeben werden.

WYSIWYG-HTML-Editor (TinyMCE)

::layout::mceEditor name label value …

Erzeugt ein mehrzeiliges Textfeld, das zur Laufzeit durch den TinyMCE ersetzt wird. Die Parameter entsprechen denen des mehrzeiligen Textfelds.

Ab CMS Fiona 6.8.0 kann der Editor mit dem optionalen Argument config konfiguriert werden. Als Wert des Arguments wird die JSON-Repräsentation der TinyMCE-Konfiguration erwartet:

::layout::mceEditor … config {{theme_advanced_buttons1: "bold", …}}

Der TinyMCE setzt die Web-Applikation tinyMCE voraus. Sie können diese mit der folgenden Anweisung deployen:

Instanzverzeichnis/bin/rc.npsd deploy tinyMCE

Ab CMS Fiona 6.8.0 ist die tinyMCE-Web-Applikation in der Liste der voreingestellt zu deployenden Web-Applikationen (rc.npsd.conf) enthalten, wird also durch rc.npsd deploy deployt.

Um die Pfade von Links im bearbeiteten Feldinhalt richtig anzuzeigen, müssen diese vor dem Aufruf des Editors angepasst werden:

set tinyMceTextArea [changeImgPathsToPreviewPaths $blob $objId]

tinyMceTextArea ist hierbei der Name der Variablen, in der der angepasste Feldwert zwischenzeitlich gespeichert wird. blob ist der Feldinhalt, objId die ID der betreffenden CMS-Datei. Nach der Bearbeitung müssen die Pfade wieder normalisiert werden:

set blob [changePreviewPathsToImgPaths $tinyMceTextArea]

Mehrfachauswahl

::layout::chooseMulti limit name valuesAndLabels selectedValues ?label? …

Erzeugt abhängig von der Größe von valuesAndLabels entweder mehrere Auswahlkästchen oder eine Mehrfachauswahlliste. Auswahlkästchen werden verwendet, wenn die Anzahl der Werte kleiner als limit ist.

Einzelauswahl

::layout::chooseSingle limit name valuesAndLabels selectedValue ?label? …

Erzeugt abhängig von der Größe von valuesAndLabels entweder mehrere Auswahlschalter oder ein Popup-Menü. Auswahlschalter werden verwendet, wenn die Anzahl der Werte kleiner als limit ist.

Auswahlschalter

::layout::radioButtons name valuesAndLabels selectedValue ?label? …

Erzeugt ein npsField-Element mit npsFieldOption-Elementen. Die Auswahl wird mit Auswahlschaltern dargestellt.

• name spezifiziert den HTML-Formular-Parameternamen.
• label (optional) ist die Bezeichnung der Auswahl.
• valuesAndLabels ist eine Liste der Auswahlmöglichkeiten. Eine Auswahlmöglichkeit ist eine Liste aus einem Wert und einer optionalen Bezeichnung.
• selectedValue ist der aktuell ausgewählte Wert.
• Optional können weitere npsField-Element-Attribute als Liste von Name-Wert-Paaren übergeben werden, zum Beispiel required.

Beispiel:

::layout::radioButtons color {{yellow gelb} {red rot} {blue blau}}\
    [getParam "color"] "Lackfarbe" required true

Auswahlkästchen

::layout::checkBoxes name valuesAndLabels selectedValues ?label? …

Erzeugt ein npsField-Element mit npsFieldOption-Elementen. Die Auswahl wird als voneinander unabhängig aktivierbare Auswahlkästchen dargestellt.

• Die Parameter sind analog zu ::layout::radioButtons.
• selectedValues enthält im Unterschied zur Prozedur radioButtons die Liste der ausgewählten Optionen.

::layout::checkBox name valueAndLabel selectedValue label …

Erzeugt ein einzelnes Auswahlkästchen.

• Die Parameter sind analog zu ::layout::radioButtons.
• selectedValue enthält im Unterschied zur Prozedur radioButtons die Liste der ausgewählten Optionen.

Popup-Menü

::layout::dropdown name valuesAndLabels selectedValue ?label? …

Erzeugt ein npsField-Element mit npsFieldOption-Elementen. Die Auswahl wird als Popup-Menü dargestellt.

• Die Parameter sind analog zu ::layout::radioButtons.

Mehrfachauswahlliste

::layout::select name valuesAndLabels selectedValues ?label? …

Erzeugt ein npsField-Element mit npsFieldOption-Elementen. Die Auswahl wird als Mehrfachauswahlliste dargestellt.

• Die Parameter sind analog zu ::layout::checkButtons.

Datei-Upload

::layout::fileField name label fileName ticketId …

Erzeugt ein npsField-Element vom Typ file mit dem Namen name und der Bezeichnung label.

• fileName ist der Name einer bereits hochgeladenen Datei. Wurde keine Datei hochgeladen, sollte dieser Wert ein leerer String sein.
• ticketId ist die Streaming-Ticket-ID, mit der auf den Inhalt der hochgeladenen Datei zugegriffen werden kann. Ist diese ID noch nicht bekannt, sollte als Wert dieses Parameters ein leerer String übergeben werden.
• Optional können weitere npsField-Element-Attribute als Liste von Name-Wert-Paaren übergeben werden, zum Beispiel required.

Beispiel:

::layout::fileField importFile "" \
    [getParam importFile.fileName] [getParam importFile.ticketId]\
    required true error $fieldError]]

Hierzu gibt es ein Anwendungsbeispiel.

Dateiauswahl

::layout::selectObject name label id selectMessage …

Erzeugt ein npsField-Element vom Typ selectObject mit dem Namen name, der Bezeichnung label, der Datei-ID id und der Meldung selectMessage.

Datumsauswahl

::layout::dateField name label value …

Erzeugt ein npsField-Element vom Typ date mit dem Namen name, der Bezeichnung label und dem Wert value.

Anwendungsbeispiel

Gibt man in einem Assistenten den folgenden Code an das GUI zurück, so wird auf der entsprechenden Assistenten-Seite ein HTML-Eingabefeld erzeugt, das zum Upload einer Datei auf den Server dient:

<npsField type="file" name="varName" fielName="" ticketId="" ></npsField>

Für die Datei, die der Benutzer hochlädt, wird im Content Management Server ein Streaming-Ticket erzeugt, unter dem man auf die Datei zugreifen kann. Die ID dieses Tickets sowie den Namen der Datei legt der Content Management Server in den beiden Variablen

$varName.fileName
$varName.ticketId

ab, wobei varName der Wert des Tag-Attributs name im npsField-Element ist. Innerhalb des Wizards könnte man auf die Werte beispielsweise folgendermaßen zugreifen:

proc wizard {params objId} {
  set uploadFileName [getParam meinUpload.fileName]
  set uploadTicket [getParam meinUpload.ticketId]
  …
}

Um die hochgeladene Datei dann als CMS-Datei abzulegen, kann man sich in dem entsprechenden Tcl-Befehl auf das Ticket beziehen, damit der Content Management Server den Hauptinhalt der neuen CMS-Datei mit dem Inhalt der hochgeladenen Datei belegt. Vorher werden jedoch aus dem Namen der hochgeladenen Datei der Name der anzulegenden CMS-Datei und deren Dateiendung (sofern nicht aus anderer Quelle gewonnen oder vorgegeben) gebildet:

# Name und Dateiendung ermitteln
set name [file rootname $uploadFileName]
set contentType [string trimleft [file extension $uploadFileName] "."]

# Neue Datei mit dem Inhalt der hochgeladenen Datei anlegen
obj withId $parent createAndLoad name $name objClass generic \
        contentType $contentType blob.stream $uploadTicket

Im obigen Beispiel wird eine neue Datei von der Vorlage Ressource unterhalb des Ordners mit der ID $parent angelegt, zu deren Hauptinhalt der hochgeladene, über das Streaming-Ticket $uploadTicket erreichbare Dateiinhalt wird.

Um die hochgeladene Datei nicht im CMS, sondern im Dateisystem des Servers abzuspeichern, kann man sie über das Ticket mit Hilfe des Tcl- Befehls stream downloadFile auch herunterladen:

set tmpFile "/tmp/uploads/$uploadFileName"
stream downloadFile $uploadTicket $tmpFile

Anschließend liegt die Datei im Verzeichnis /tmp/uploads/.