fsbutton(...)

fsbutton(...) function syntax

The following is the basic structure of the fsbutton(...) function:

<span$CMS_VALUE(
    fsbutton(
        editorName:"KEYWORD",
        parameter:{
            "KEYWORD":VALUE,
            "KEYWORD":VALUE,
            [...]
        },
        callback:"callbackFunction"
    )
)$></span>

fsbutton(...) function parameters

The following parameters can be specified for the fsbutton(...) function:

editorName parameter

The editorName parameter references an FS_BUTTON input component that has been defined in the template form area. Here, the value of the parameter editorName must be equal to the value of the attribute name of a FS_BUTTON form definition. The settings that apply to this FS_BUTTON instance, e.g. the scripts or classes that are executed during the click or drop actions, the graphic display applied to rendered components, etc., are the result of this link.

The editorName parameter is a mandatory parameter.

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

parameter parameter

The parameter parameter defines additional, freely associatable information that is passed to the particular scripts or classes being executed during the click and drop actions. The information becomes a "key/value" tuple, where "key" and "value" are of the string type and are separated in each tuple by a colon (:).

$CMS_VALUE(
    fsbutton(
        editorName:"st_headline",
        parameter:{
            "componentToModify":"st_headline",
            "componentType":"textbox",
            "showMessageBox":"true",
            "messageToDisplay":"This headline was replaced by: "
        }
    )
)$

The parameters are provided to scripts and executable classes, which are executed during click and drop actions. This data can be accessed within scripts and executables as follows:

callback parameter

This parameter is used only in conjunction with FS_BUTTON instances that are displayed in the JavaClient and WebClient preview modes. The callback functionality is not supported for FS_BUTTON instances in forms.

After running a script or an executable class when clicking or dropping onto an FS_BUTTON instance, you have the option of processing JavaScript expressions that may use the results of the click or drop action with reference to the HTML document.

The value of the callback parameter in this case may contain JavaScript expressions or the name of a JavaScript function defined in a different way.

If a function is passed as a value and it takes at least one parameter, the return value of the previously executed script or executable can be processed within this function; the return value in this case is specified as the first parameter in the function call; additional parameters of the function remain undefined.

The return value passed to the callback function is determined as follows:

Example 1: specifying JavaScript expressions

JavaScript expressions can be specified in their usual format, but without line breaks, as the value of the callback parameter. The expressions are executed in sequence.

Processing the return value of a script or executable is not possible in this format.

If special characters (especially double quotation marks ['"'] and backslashes ['\', e.g. for information on "escaped characters" such as the new line instruction "\n"]) are used in JavaScript expressions, a backslash must be placed before each one. For instance, a double quotation mark should be written as "\"", and a new line instruction should be written as "\\n".

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

Example 2: specifying an anonymous function

A function definition can also be specified without a name as a value of the callback parameter. If a function definition contains at least one parameter, the return value of the previously executed script or executable is passed to the function as a value of the first parameter.

If special characters (especially double quotation marks ['"'] and backslashes ['\', e.g. for information on "escaped characters" such as the new line instruction "\n"]) are used in JavaScript expressions, a backslash must be placed before each one. For instance, a double quotation mark should be written as "\"", and a new line instruction should be written as "\\n".

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

Example 3: information on a function name

The name of a function defined at a different location in the document (without parameters) can also be specified as a value of the callback parameter. If the function definition contains at least one parameter, the return value of the previously executed script or executable is passed to the function as a value of the first parameter.

If the function is encapsulated in an object (e.g. someObject.doSomething(result)), the function name, including the object path, must be placed within parentheses within the callback parameter (e.g. 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>

$CMS_VALUE(
    fsbutton(
        editorName:"st_headline",
        callback:"notifyUser"
    )
)$

fsbutton(...) function examples

The following is an example of using the instruction within templates. The purpose of the example is to point out the precise effect of the instruction and to assist template developers in creating their own templates.

For instance, the aim of this example is to enable the page currently displayed in the WebClient preview (combination of page reference and page) and then to update the preview. To do this, an FS_BUTTON component in the form is defined using a script as a handler for a click action. The script itself handles enabling of the current page outside of the workflow. The fsbutton(...) function, which passes the content of a text box for comment input and the name of a JavaScript function as a parameter, handles updating of the preview after the script is executed.

It may be necessary to adapt the example shown here for use within a project. For example, variable names need to be changed to the specific variable names of the project in which the instruction is to be used.

The example is designed for use in WebClient by using the WebClient JavaScript API; display of the FS_BUTTON is therefore suppressed in the JavaClient preview.

Defining an FS_BUTTON in a form

<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>

This FS_BUTTON component defines the use of the releasepagescript script with click actions.

Script

The releasePageScript script uses the FirstSpirit Access and Developer APIs to make the page reference as well as the associated page visible in the preview through programming.

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 configuration in the presentation channel

In the HTML presentation channel, the FS_BUTTON component is rendered when fsbutton(...) is called and configured for the use of a user-defined text comment:

$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$

The JavaScript and FS_BUTTON instance are output only in a WebClient preview.

The HTML code contains the definition for the refreshPage(...) JavaScript function that is called after clicking on the FS_BUTTON and the subsequent execution of the template script releasePageScript.