FS_BUTTON

FS_BUTTON

The input component FS_BUTTON provides the editor with an icon, a button or a link, which is linked to a FirstSpirit script or a class, provided e.g. by a FirstSpirit module on the server. If the editor clicks this control or uses their mouse cursor to drag and drop objects on it, the referenced script or class is run. in this way, FS_BUTTON can be used to create an icon or a button, which runs an individually implementable function.

The input component can work with other input components. In this way, for example, the editor's entries can be used for the script.

This input component has "under development" status in FirstSpirit Version 4.2 and will not be officially released until FirstSpirit Version 5.0. For further information, please refer to the New input components section.

The input component FS_BUTTON is currently not supported in FirstSpirit-WebClient.

Parameter

The parameters of the FS_BUTTON input component are given in the following table.

Overview

name

The attribute "name" is the variable name of an input component with which the the result object of the input component can be used in the templates - with the help of $CMS_VALUE()$ - or the content can be output.

Overview

allowEmpty

The parameter allowEmpty has no effect on the function of this input component and it will be omitted in a later FirstSpirit version.

Independent of how this parameter is defined in a form, this input component can rest empty, no value must be entered by the editor into this component (corresponds to allowEmpty="YES"). If allowEmpty="NO" is defined, this will be changed automatically to allowEmpty="YES" when the form is saved.

Overview

alwaysEnabled

By default, input components can only be used in FirstSpirit Clients, if the section, the page or the data set, which contains the input component is in Edit mode.

On the other hand, FS_BUTTON can be configured so that the control element (see also icon and style parameters) is also active if the section, page or data set concerned is in View mode. I.e., the referenced script or module can be run, regardless of whether the input component is in Edit or View mode.

However, this only applies to "onClick" mode, i.e. if the control element is clicked. If an object is dragged onto the control element ("onDrop"), the input component must be set in Edit mode.

The alwaysEnabled parameter is used for this: If alwaysEnabled="YES" the input component is also active in View mode. If alwaysEnabled="NO" it does not become active until it is set in Edit mode. If the parameter is not given, the input component does not become active until set in Edit mode (alwaysEnabled="NO").

Overview

convertEntities

The "convertEntities" attribute is used to convert special characters entered in the input components for output in HTML characters.

There are three forms:

• convertEntities="NONE" (standard)
• convertEntities="STANDARD"
• convertEntities="QUOTE"

With the NONE form, no conversion rules whatsoever are applied.

If STANDARD is given the conversion rules in the "convert" area of the selected conversion rule of the presentation channel are applied.

The form QUOTE explicitly includes STANDARD too. However, the "quote" area of the conversion rule is also applied.

Overview

hFill

An input component is always displayed with a pre-defined width.

However, if the input component is to use the full available display width the parameter hFill must be given with the value YES .

Overview

hidden

With the "hidden" parameter an input component can be hidden from the editor.

If hidden="YES" the input component is not visible for the editor, if hidden="NO" it is visible.

The default value for hidden is NO.

Overview

icon

This parameter can be used to assign an icon to the input component. If it is clicked by the editor, or if they use the mouse cursor to drag an object onto it, the reference script or referenced class is run.

Either question or info is to be given as the value for display of the specified symbols. In addition, images from the Media Store can also be used. In this case, the value to be given is media: followed by the unique identifier of the required image. The original resolution of the image is used.

Examples:

With

icon="question"

the symbol is used,

with

icon="info"

the symbol.

The following syntax is used to use images from the Media Store:

icon="media:icon_startSearch"

If the icon parameter is not given, depending on the definition of the style parameter, a link (style="LINK"), a button (style="BUTTON") or a FirstSpirit icon (background only, style="FIRSTSPIRIT") is displayed.

Overview

noBreak

The noBreak parameter can be used to suppress automatic line break after an input component.

The noBreak parameter must be given with value "YES" (noBreak="YES") to suppress the automatic line break.

Overview

onClick

This parameter is used to reference a script from the Template Store or a class, which is to be run when the control element is clicked (see also icon and style parameters).

If a class is referenced, it must implement the de.espirit.firstspirit.access.script.Executable interface!

When the mouse cursor is passed over the control element, the mouse cursor changes depending on the value selected for style, and when clicked the pressing in of the control element is visualized.

The value expected by the parameter in the case of

• a script is the keyword script:, followed by the unique reference name of the required script from the Template Store, e.g.
  onClick="script:do_search"
• a class is the keyword class:, followed by the fully qualified class name, including packet names, e.g.
  onClick="class:..."

If this parameter is not set, the onDrop parameter must be set.

The following variable names, with which data of FS_BUTTON can be accessed, can be used in the script context:

• context:
  Access to the script context. Methods of the de.espirit.firstspirit.access.BaseContext interface (Developer API) can be executed on the returned value.
• properties:
  Access to the values (Map) set via the input component. The values are set after the script has been run and are saved when the input component is saved. Methods of the java.util.Map<String, String> interface can be executed on the returned values.
• language:
  Access to the project language (language tab), in which the input component was clicked. The de.espirit.firstspirit.access.Language interface can be executed on the returned value.
• element:
  Access to information of the tree node in which the input component is located, e.g. section, page or data set. The system object #field can be used here to access the information of individual input components (see also PARAMS / PARAM tags).
  Methods of the de.espirit.firstspirit.access.store.IDProvider interface can be run on the returned values, if the input component is in a table template, especially the methods of the de.espirit.firstspirit.access.store.contentstore.Dataset interface.
• drop:
  For checking whether the script was invoked on dragging objects with the mouse cursor and dropping them onto the input component (true) or on clicking the input component (false).

Overview

onDrop

This parameter is used to reference a script from the Template Store or a class, which is to be run when an object is dragged and dropped onto the control element with the mouse cursor ("drop", see also icon and style parameters).

If a class is referenced, it must implement the de.espirit.firstspirit.access.script.Executable interface!

The value expected by the parameter in the case of

• a script is the keyword script:, followed by the unique reference name of the required script from the Template Store, e.g.
  onDrop="script:do_search"
• a class is the keyword class:, followed by the fully qualified class name, including packet names, e.g.
  onDrop="class:..."

If this parameter is not set, the onClick parameter must be set.

The following variable names, with which data of FS_BUTTON can be accessed, can be used in the script context:

• context:
  Access to the script context. Methods of the de.espirit.firstspirit.access.BaseContext interface (Developer API) can be executed on the returned value.
• properties:
  Access to the values (Map) set via the input component. The values are set after the script has been run and are saved when the input component is saved. Methods of the java.util.Map<String, String> interface can be executed on the returned values.
• language:
  Access to the project language (language tab), in which objects have been dropped onto the input component by means of the mouse cursor ("Drop"). The de.espirit.firstspirit.access.Language interface can be executed on the returned value.
• element:
  Access to information of the tree node in which the input component is located, e.g. section, page or data set. The system object #field can be used here to access the information of individual input components (see also PARAMS / PARAM tags).
  Methods of the de.espirit.firstspirit.access.store.IDProvider interface can be run on the returned values, if the input component is in a table template, especially the methods of the de.espirit.firstspirit.access.store.contentstore.Dataset interface.
• drop:
  For checking whether the script was invoked on dragging objects with the mouse cursor and dropping them onto the input component (true) or on clicking the input component (false).
• dropdata:
  Access to the data, which was dropped onto the input component by means of the mouse cursor ("Drop"). Methods of the de.espirit.firstspirit.ui.gadgets.aspects.transfer.CommodityContainer interface (Developer API) can be applied on the returned value.

Overview

preset

Using the preset attribute the handling of default values in an input component can defined (see also chapter Default values). If preset="default" is set, the retrieval value defined in the form is used. If this value in the form is changed later on, these changes will be affect all usages of this default value in the input components maintained by the editor, as long as a value will be set manually in the input component. This is the default setting. If preset="copy" is set, the value entered by the editor is copied directly into the input component. Subsequent changes to the default value in the form do not have any effect on the usages of this default value in the input components maintained by the editor.

Overview

style

FS_BUTTON can be displayed in different variants. These are controlled via the style parameter:

• Button
  With style="BUTTON" the input component is displayed as a button. The text defined via LANGINFOS is displayed on the button, e.g.
  
  
• Link
  With style="LINK" the input component is displayed as a link. The text defined via LANGINFOS is used for this, e.g.
  
  
  
  If the mouse cursor is held over this link (mouseover), the text and underlining become a lighter color.
• FirstSpirit
  With style="FIRSTSPIRIT" it is possible to equip the input component with an icon, whose designed is based on the style of the usual FirstSpirit icons. With the "FIRSTSPIRIT" value, the input component is assigned an icon with the usual JavaClient size and background color as well as the typical shading. Depending on the user's own requirements, it can also be assigned a symbol, which must be referenced via the icon parameter. The individual symbol used for the icon should ideally be an image file with light color, in PNG or GIF format with transparent background and dimensions 19px x 18px. The text defined via LANGINFOS is displayed to the right of the icon, e.g.
  
  
  
  If the mouse cursor is held over the icon and/or text (mouseover), a frame is displayed around these elements.

If the parameter is not given, by default the input component is displayed as the "button" variant.

Overview

useLanguages

The useLanguages parameter can be used to specify whether or not an input component is to store different or deviating values for different languages (multi-lingual maintenance).

If the parameter is not given, deviating values are stored for the different languages as a default.

If NO (...useLanguages="NO") is specified, one value is stored for all languages.

Overview

DROPTYPES

If the "onDrop" variant of the input component is used (see onDrop parameter), the DROPTYPES tag must be used to define the object types which may be dropped onto the input component with the mouse cursor ("Drop"). A TYPE or MIME tag must be given for each allowed type.

MIME

The MIME tag can be used by the user to define their own MIME types, which may be dragged and dropped onto the input component using the mouse cursor. A tag must be given for each type.

Overview

classname

This parameter must be used to give a class, via which the MIME type can be transferred, e.g.

classname="java.io.InputStream"

Overview

type

This parameter must be used to define a MIME type, which is to be transferable, e.g.

type="application/video" 

Overview

TYPE

The TYPE tag can be used to define specified object types, which may be dragged and dropped onto the input component using the mouse cursor. A tag must be given for each type.

Overview

value

This parameter can be used to give predefined object types, which may be dragged and dropped onto the input component using the mouse cursor.

The following values and types can be used for this:

• TEXT_HTML (HTML text)
• TEXT_PLAIN (Plain Text)
• EXTERNAL (external files)

FirstSpirit objects

• NODE (FirstSpirit node)
• PAGEFOLDER (Page Store: folder)
• PAGE (Page Store: pages)
• BODY (Page Store: content areas)
• SECTION (Page Store: sections)
• SITESTOREFOLDER (Site Store: menu levels)
• PAGEREF (Site Store: page references)
• DOCGROUP (Site Store: document groups)
• MEDIAFOLDER (Media Store: folder)
• PICTURE (Media Store: images)
• FILE (Media Store: files)
• DATASET (Content Store: data sets)

• MEDIA (Media Store: Media;
  is replaced with <TYPE value="picture"/> and <TYPE value="file"/> when the template is saved)

Example:

<DROPTYPES>
 <MIME type="application/video" classname="java.io.InputStream"/>
 <TYPE value="text_html"/>
 <TYPE value="text_plain"/>
 <TYPE value="external"/>
 <TYPE value="picture"/>
 <TYPE value="file"/>
</DROPTYPES>

Overview

LANGINFOS

Using the tag LANGINFOS language-dependent information can be defined for each input component, e.g. which title is to be used for the input component in the different project languages (parameter label), which tooltip is to be displayed (parameter description) etc. For reasons of clarity, definitions which are identical in multiple languages will be merged. For example,

<LANGINFOS> 
 <LANGINFO lang="*" label="Datum"/> 
 <LANGINFO lang="DE" label="Datum"/> 
 <LANGINFO lang="EN" label="Datum"/>
</LANGINFOS>

will be merged to

 <LANGINFOS> 
 <LANGINFO lang="*" label="Datum"/> 
</LANGINFOS>

after saving.

Up to and including FirstSpirit version 4.2R2 language definitions will be deleted only in the case if the values are identical in all languages (as in example above). Furthermore, only the parameters lang, description and label are taken into account when merging.

Since FirstSpirit version 4.2R4 all parameters are taken into account (e.g. format and length). Furthermore, language definitions are also merged within LANGINFOS tags, if they are identical in at least two languages. For example,

<LANGINFOS> 
 <LANGINFO lang="*" label="Date" format="dd.MM.yy"/>
 <LANGINFO lang="DE" label="Date" format="dd.MM.yy"/>
 <LANGINFO lang="EN" label="Date" format="MM/dd/yy"/>
</LANGINFOS>

will become

 <LANGINFOS> 
 <LANGINFO lang="*" label="Date" format="dd.MM.yy"/>
 <LANGINFO lang="EN" label="Date" format="MM/dd/yy"/>
</LANGINFOS>

after saving.

The definition for the fallback value (*) will not be deleted in any case. If there are two or more language definitions with identical values the first one will be maintained, the other will be deleted.

IMPORTANT: Up to and including FirstSpirit version 4.2R2 at least one definition for the fallback labelling ("*") must be given:

<LANGINFOS>
 <LANGINFO lang="*" label="TEXT"/>
</LANGINFOS>

From FirstSpirit version 4.2R4 the fallback definition can be omitted. In this case, the language which is defined first will be used automatically as fallback value. For example,

<LANGINFOS>
 <LANGINFO lang="EN" label="Date"/>
 <LANGINFO lang="DE" label="Datum"/> 
</LANGINFOS>

will become

 <LANGINFOS> 
 <LANGINFO lang="*" label="Date"/>
 <LANGINFO lang="DE" label="Datum"/> 
</LANGINFOS>

after saving.

LANGINFO

The LANGINFO tag is used to give values or attributes for a language as well for use as fallback values.

In order to state values or attributes for a language it is necessary to give the abbreviation of the project language in the lang parameter:

...
<LANGINFO lang="DE".../>
...

Fallback values are given with the special language abbreviation * ("for all languages"):

...
<LANGINFO lang="*".../>
...

The lang parameter is a mandatory parameter.

Overview

lang

The lang parameter is used to give the language abbreviation which is entered in the server properties see FirstSpirit Manual for Administrators, Chapter "Language templates") to specify for which project languages the definitions are to apply, e.g. DE for German, EN for English, FR for French etc. The following characters can be used as often as required: -, _, 0-9 and A-Z. Lower case letters are transformed automatically into upper case letters after having saved the template. In addition * can be used for fallback values.

Overview

description

The description parameter can be used to give a description which is used to display a tool tip (mouse-over).

Overview

label

The label parameter is used to give the surface labelling for input and visualisation components.

Overview

PARAMS

The PARAMS / PARAM tags can be used to transfer script/module values referenced via onClick and / or onDrop.

The #field system object can be used to access values in other input components of the current form. In this context the de.espirit.firstspirit.forms.FormField instance is available.

PARAM

Within PARAMS, a PARAM tag with a name parameter is required for each value to be transfered to the referenced script/module.

Overview

name

The name parameter is used to define the name of the parameter to be transferred to the referenced script / module.

Overview

TEXT

The value, which is to be transferred to the referenced script / module is defined here.

The system object #field can be used to access input components of the same form. This is done by attaching the variable name of the input component concerned, separated by a dot, e.g.

<PARAM name="targeturl">#field.st_text</PARAM>

where targeturl is the parameter name which can be used in the script / module, and st_text is the variable name of the input component whose value is to be used.

Example:

<PARAMS>
 <PARAM name="targeturl">#field.st_url</PARAM>
 <PARAM name="wikisearch">#field.st_wikisearch</PARAM>
</PARAMS>

LanguageAbbreviation	Language abbreviation, e.g. DE, EN, FR or * for return values
ButtonStyle	Display type of the control element BUTTON Display as button (default) LINK Display as link FIRSTSPIRIT Display in FirstSpirit style (transparent PNG or GIF, 19px x 18 px required)
DropType	Predetermined object types which can be dragged and dropped onto the control element TEXT_HTML Drop type html text TEXT_PLAIN Drop type plain text EXTERNAL Drop type external file-based data NODE Drop type arbitrary firstspirit node PAGEFOLDER Drop type pagestore folder node PAGE Drop type page node BODY Drop type body node SECTION Drop type section node SITESTOREFOLDER Drop type sitestore folder node PAGEREF Drop type page reference node DOCGROUP Drop type document group node MEDIAFOLDER Drop type mediastore folder node PICTURE Drop type media node of type picture FILE Drop type media node of type file DATASET Drop type dataset node
YesNo	Switch to apply an attribute or not NO Do not apply attribute YES Apply attribute
String	A random character string
Preset	Define the general preset modes. Default Retrieve default from definition, if no value is set. Copy Copy default from definition and save automatically.
ConvertEntity	Switch with which to define the conversion rule NONE Do not use any conversion rules STANDARD Use the conversion rules of the "convert" area QUOTE Use the conversion rules of the "convert" and "quote" area
Designator	Unique identifier of variable length; must start with a letter or underscore and may only contain the characters "A-Z", "a-z", "0-9" and "_", e.g. "fr_st_varName"

Example

An example of the input component "FS_BUTTON":

<FS_BUTTON 
       name="BEZEICHNER" 
       icon="media:BEZEICHNER"
       onClick="script:BEZEICHNER" 
       noBreak="NO" 
       useLanguages="NO" 
       hFill="YES">
  <LANGINFOS>
    <LANGINFO lang="*" label="TEXT" description="TEXT"/>
    <LANGINFO lang="DE" label="TEXT" description="TEXT"/>
    <LANGINFO lang="EN" label="TEXT" description="TEXT"/>
  </LANGINFOS>
  <PARAMS>
    <PARAM name="BEZEICHNER">#field.BEZEICHNER</PARAM>
  </PARAMS>
</FS_BUTTON>