fsbutton(...)

Syntax der fsbutton(...)-Funktion

Der Grundaufbau der fsbutton(...)-Funktion ist wie folgt:

<span$CMS_VALUE(
    fsbutton(
        editorName:"SCHLÜSSELBEGRIFF",
        parameter:{
            "SCHLÜSSELBEGRIFF":WERT,
            "SCHLÜSSELBEGRIFF":WERT,
            [...]
        },
        callback:"callbackFunction"
    )
)$></span>

Die Funktion fsbutton(...) wird immer innerhalb eines Aufrufs der Anweisung CMS_VALUE(...) verwendet. Als Wert wird eine Zeichenkette ausgegeben, die HTML-Attribute enthält, durch die der gerenderte FS_BUTTON grafisch und funktional ausgezeichnet wird. Die Verwendung der CMS_VALUE(...)-Anweisung mit einem fsbutton(...)-Aufruf muss daher immer im öffnenden Tag eines HTML-Block- oder Inline-Elements geschehen, z. B.: Aufruf innerhalb eines DIV-Elements (Block-Element): <div$CMS_VALUE(fsbutton(...))$></div> Aufruf innerhalb eines SPAN-Elements (Inline-Element): <span$CMS_VALUE(fsbutton(...))$></span>

Parameter der fsbutton(...)-Funktion

Für die fsbutton(...)-Funktion lassen sich folgende Parameter angeben:

Parameter editorName

Der Parameter editorName referenziert eine FS_BUTTON-Eingabekomponente, die im Formularbereich der Vorlage definiert wurde. Hierbei muss der Wert des Parameters editorName dem Wert des Attributs name einer FS_BUTTON-Formulardefinition gleichen. Aus dieser Verknüpfung ergeben sich die Einstellungen, die für diese FS_BUTTON-Instanz gelten, z. B. welche Skripte oder Klassen bei Klick- oder Drop-Aktionen ausgeführt werden, welche grafische Auszeichnung auf die gerenderte Komponente angewendet wird, usw.

Der Parameter editorName ist ein Pflichtparameter.

<span$CMS_VALUE(
    fsbutton(
        editorName:"st_headline"
    )
)$></span>

Parameter parameter

Der Parameter parameter definiert zusätzliche, frei assoziierbare Angaben, die bei Klick- und Drop-Aktionen an die jeweils ausgeführten Skripte oder Klassen weitergegeben werden. Die Angaben werden als Schlüssel/Wert-Tupel gemacht, wobei Schlüssel und Wert jeweils vom Typ String sind und in jedem Tupel durch einen Doppelpunkt (:) getrennt werden.

<span$CMS_VALUE(
    fsbutton(
        editorName:"st_headline",
        parameter:{
            "componentToModify":"st_headline",
            "componentType":"textbox",
            "showMessageBox":"true",
            "messageToDisplay":"Die Überschrift wurde ersetzt mit: "
        }
    )
)$></span>

Beanshell-Skripte sowie Java-Klassen, die über die Attribute onClick und onDrop des FS_BUTTON-Tags der Formulardefinition als Button-Aktionen verwendet werden, können auf die mittels der Funktion fsbutton() spezifizierten Parameter wie folgt zugreifen:

• Beanshell-Skripte
  Jeder Parameter wird als Variable verfügbar gemacht. Der im parameter-Array angegebene Schlüsselname eines Parameters wird hierbei als Variablenname verwendet.
• Java-Klassen
  Jeder Parameter wird in dem Map<String, Object>-Objekt gespeichert, das als Parameter der execute()-Methoden des Interface Executable verfügbar gemacht wird. Der im parameter-Array angegebene Schlüsselname eines Parameters wird hierbei als Schlüssel verwendet.

Bei Verwendungen von FS_BUTTON in Vorschauansichten (Aufruf der Funktion fsbutton() in einem Ausgabekanal) erhalten Parameterangaben der Formulardefinition höhere Priorität. Wird für eine FS_BUTTON-Instanz sowohl in der Formulardefinition des Buttons (mittels PARAM-Tag) als auch in einem Ausgabekanal (mittels der Funktion fsbutton()) ein Parameter gleichen Namens angegeben, so wird in Skripten und Executables immer der Parameterwert aus der Formulardefinition (d.h. des PARAM-Tags) verfügbar gemacht.

Parameter callback

Dieser Parameter findet nur in Verbindung mit FS_BUTTON-Instanzen, die in den Vorschauansichten des JavaClients und des WebClients angezeigt werden, Anwendung. Die Callback-Funktionalität wird für FS_BUTTON-Instanzen in Formularen nicht unterstützt.

Nach Ausführung eines Skripts oder einer Executable-Klasse bei Klick oder Drop auf eine FS_BUTTON-Instanz können optional JavaScript-Ausdrücke verarbeitet werden, die ggf. die Ergebnisse der Klick- oder Drop-Aktion mit Bezug auf das HTML-Dokument anwenden.

Der Wert des callback-Parameters kann hierzu JavaScript-Ausdrücke oder den Namen einer anderweitig definierten JavaScript-Funktion enthalten.

Wird als Wert eine Funktion übergeben, die mindestens einen Parameter annimmt, so kann der Rückgabewert des zuvor ausgeführten Skripts oder Executable innerhalb dieser Funktion verarbeitet werden; der Rückgabewert wird in diesem Fall als erster Parameter im Funktionsaufruf angegeben, weitere Parameter der Funktion verbleiben undefined.

Der an die Callback-Funktion weitergegebene Rückgabewert wird wie folgt ermittelt:

Beispiel 1: Angabe von JavaScript-Ausdrücken

JavaScript-Ausdrücke können in gewohnter Form - aber ohne Zeilenumbrüche - als Wert des callback-Parameters angegeben werden. Die Ausdrücke werden sequenziell ausgeführt.

Die Verarbeitung des Rückgabewerts eines Skripts oder Executables ist in dieser Form nicht möglich.

Sollen in den JavaScript-Ausdrücken Sonderzeichen (insbesondere doppelte Anführungszeichen ['"'] und Backslashes ['\', z. B. zur Angabe von "escaped characters" wie der New Line-Anweisung "\n"]) verwendet werden, so muss diesen jeweils ein Backslash vorangestellt werden. Ein doppeltes Anführungszeichen sollte also "\"" geschrieben werden, eine New Line-Anweisung "\\n".

<span$CMS_VALUE(
    fsbutton(
        editorName:"st_headline",
        callback:"var userNotice = 'The button script or executable class has completed its run.'; alert(userNotice);"
    )
)$></span>

Beispiel 2: Angabe einer anonymen Funktion

Als Wert des callback-Parameters kann ebenfalls eine Funktionsdefinition ohne Namen angegeben werden. Enthält die Funktionsdefinition mindestens einen Parameter, so wird der Rückgabewert des zuvor ausgeführten Skripts oder Executables als Wert des ersten Parameters an die Funktion weitergegeben.

Sollen in den JavaScript-Ausdrücken Sonderzeichen (insbesondere doppelte Anführungszeichen ['"'] und Backslashes ['\', z. B. zur Angabe von "escaped characters" wie der New Line-Anweisung "\n"]) verwendet werden, so muss diesen jeweils ein Backslash vorangestellt werden. Ein doppeltes Anführungszeichen sollte also "\"" geschrieben werden, eine New Line-Anweisung "\\n".

<span$CMS_VALUE(
    fsbutton(
        editorName:"st_headline",
        callback:"function(result) { var userNotice = 'Return value: \\n\\n'; alert(userNotice + result); }"
    )
)$></span>

Beispiel 3: Angabe eines Funktionsnamens

Als Wert des callback-Parameters kann ebenfalls der Name einer an anderer Stelle im Dokument definierte Funktion (ohne Parameter) angegeben werden. Enthält die Funktionsdefinition mindestens einen Parameter, so wird der Rückgabewert des zuvor ausgeführten Skripts oder Executables als Wert des ersten Parameters an die Funktion weitergegeben.

Ist die Funktion in einem Objekt eingekapselt (z. B. someObject.doSomething(result)), so muss der Funktionsname inklusive des Objektpfades im callback-Parameter mit runden Klammern umschlossen werden (z. B. callback:"(someObject.doSomething)").

<script type="text/javascript">
    <!--
    function notifyUser(result) {
        var userNotice = "The button script or executable has completed its run. Return value: \n\n";
        alert(userNotice + result);
    }
    // -->
</script>

<span$CMS_VALUE(
    fsbutton(
        editorName:"st_headline",
        callback:"notifyUser"
    )
)$></span>

Verfügbarkeit von Variablen in Skripten und Java-Klassen

Im Kontext von Skripten und Java-Klassen, die durch Klick- und Drop-Aktionen auf den Button ausgeführt werden, sind mehrere Variablen verfügbar. Diese Variablen sind in den Beschreibungen der FS_BUTTON-Attribute onClick und onDrop auf der Seite FS_BUTTON aufgeführt.

Bei Einbindung eines FS_BUTTON in Vorschauansichten durch Verwendung der Funktion fsbutton(...) in einem Ausgabekanal ist die Verfügbarkeit dieser Variablen durch die parallele Verwendung der Ausgabekanalfunktion editorId(...) bedingt:

Die Variable parameter ist nur bei Aufrufen von FS_BUTTON-Skripten oder -Java-Klassen aus Formularen verfügbar.

Die parallele Verwendung von editorId(...) wird in HTML-Ausgabekanälen implementiert, indem sowohl editorId(...) als auch fsbutton(...) in getrennten CMS_VALUE(...)-Anweisungen innerhalb des öffnenden Tags eines HTML-Elements angegeben werden:

<span
    $CMS_VALUE(editorId(...))$
    $CMS_VALUE(fsbutton(...))$
></span>

Innerhalb von Skripten und Java-Klassen beziehen sich die Variablen element und language auf das Store-Element, das in der Funktion editorId(...) mittels der Parameter element, entity oder target spezifiziert wird; wird keiner dieser Parameter angegeben, wird der aktuelle Kontext verwendet.

Beispiele zur Funktion fsbutton(...)

Nachfolgend wird ein Beispiel zur Verwendung der Anweisung innerhalb von Vorlagen gezeigt. Das Beispiel soll die konkrete Auswirkung der Anweisung verdeutlichen und eine Hilfe für den Vorlagenentwickler bei der Erstellung eigener Vorlagen sein.

Das Beispiel hat zum Ziel, die aktuell in der WebClient-Vorschau angezeigte Seite (Kombination aus Seitenreferenz und Seite) freizugeben und die Vorschau anschließend zu aktualisieren. Dazu wird im Formular eine FS_BUTTON-Komponente mit einem Skript als Handler für eine Klick-Aktion definiert. Das Skript selbst übernimmt die Freigabe der aktuellen Seite außerhalb eines Arbeitsablaufs. Im HTML-Ausgabekanal wird die Funktion fsbutton(...) verwendet, die als Parameter den Inhalt einer Textbox zur Kommentareingabe sowie den Namen einer JavaScript-Funktion, die nach Ausführung des Skripts die Aktualisierung der Vorschau übernimmt, übergibt.

Für die Verwendung innerhalb eines Projekts muss das hier gezeigte Beispiel gegebenenfalls angepasst werden! Beispielsweise müssen Variablennamen auf die spezifischen Variablennamen des Projekts geändert werden, in dem die Anweisung verwendet werden soll.

Das Beispiel ist durch die Verwendung der WebClient-JavaScript-API auf eine Verwendung im WebClient ausgelegt; die Anzeige des FS_BUTTON in der JavaClient-Vorschau wird deshalb unterdrückt.

Definition eines FS_BUTTON im Formular

<FS_BUTTON
    name="releasePageButton"
    alwaysEnabled="yes"
    hFill="yes"
    icon="fs:ACTION"
    noBreak="yes"
    onClick="script:releasepagescript"
    style="firstspirit"
    useLanguages="no">
    <LANGINFOS>
        <LANGINFO
            lang="*"
            label="Release Page"
            description="Releases the page and refreshes the preview."/>
    </LANGINFOS>
</FS_BUTTON>

Diese FS_BUTTON-Komponente definiert die Verwendung des Skripts releasepagescript bei Klick-Aktionen.

Skript

Das Skript releasePageScript verwendet die FirstSpirit-Access- und Developer-APIs, um programmatisch die aktuelle, in der Vorschau sichtbare Seitenreferenz sowie die damit verbundene Seite freizugeben.

pageRef = context.storeElement;
if (pageRef != null) {
    page = pageRef.getPage();
    if (page != null) {
        page.setLock(true);
        page.save(commentaryText);
        page.release();
        page.setLock(false);
    }
    pageRef.setLock(true);
    pageRef.save(commentaryText);
    pageRef.release();
    pageRef.setLock(false);
    return "";
} else {
    return "Could not acquire page reference.";
}

FS_BUTTON-Konfiguration im Ausgabekanal

Im HTML-Ausgabekanal wird die FS_BUTTON-Komponente durch Aufruf von fsbutton(...) gerendert und für die Verwendung eines benutzerdefinierten Kommentartextes konfiguriert:

$CMS_IF(#global.is("WEBEDIT"))$

    <script type="text/javascript">
        <!--
        function refreshPage(result) {
            if (result != "") {
                alert(
                    "Could not release page. Reason:\n\n"
                    + result
                );
            } else {
                top.WE_API.Preview.reload();
            }
        }
        // -->
    </script>

    <input type="text" id="releaseCommentary" />

    <div
        $CMS_VALUE(
            fsbutton(
                editorName:"releasePageButton",
                parameter:{
                    "commentaryText":"document.getElementById('releaseCommentary').value".plain
                },
                callback:"refreshPage"
            )
        )$></div>

$CMS_END_IF$

Das JavaScript und die FS_BUTTON-Instanz werden nur in einer WebClient-Vorschau ausgegeben.

Im HTML-Code wird die JavaScript-Funktion refreshPage(...) definiert, die nach ein Klick auf den FS_BUTTON und die darauffolgende Ausführung des Vorlagenskriptes releasePageScript aufgerufen wird.