npsField

The npsField element provides functionality for creating input fields in forms. It supports convenient field-specific error handling and obligatory field values. The required HTML code is generated by the GUI. This ensures that the design is homogeneous.

Syntax

<npsField type="Type" name="Name" label="Label text"
    required="Obligatory" error="Error text" width="Field width" ...>
...
</npsField>

This creates a form field.

type is the type of the form field and can be file, text, select, textarea, date or selectObject.
name is the name of the parameter created.
labelis the text with which the field is to be labelled.
required may be true or false (the default). If the value is true, an error is generated if the user does not specify the value concerned. The error message is displayed next to the field. With selection fields, the option none is not displayed if required is true.
error can be set to an appropriate error message by the wizard programmer. It is displayed if the wizard has found an error in the field value. This message is also displayed next to the field, in a matching design.
width specifies the width of the field in ex, which is the standard unit in the styles used. If required, this value is adjusted internally for better display. The Firefox browser interprets this value incorrectly, which might lead to display errors.

Depending on the field type, additional parameters can be specified as attributes in the npsField tag.

Input Field Types and Their Parameters

Uploading files (type `file`)

<npsField type="file" name="name" 
  fileName="File name" ticketId="Streaming ticket ID"
  mimeType="Mime type" ... />

This creates a file selection field.

fileName Name of the uploaded file. If none has been uploaded, the value should be an empty string.
ticketId ID of the streaming ticket by which the content of the file can be accessed. Use an empty string as the value if no such ID exists.
mimeType Restricts the files available for selection. For details, please refer to the HTML specification.

There is an example of usage.

Entering strings (type `text`)

<npsField type="text" name="name" value="some data" 
    maxLength="maximum length" ... />

This creates a text input field.

maxLength specifies the maximum number of characters that can be entered.

Selecting an option (type `select`)

<npsField type="select" name="name" selectionType="single"
     renderMode="display mode" ... >
...
</npsField>

This creates one or more fields for selecting an option.

renderMode specifies how the field is to be rendered:
- vertical Radio buttons will be displayed.
- list (default): A drop-down menu is displayed.
The width attribute is only taken into account if the value of renderMode is list.
Please specify the values available for selection using npsFieldOption elements.

Selecting several options (type `select`)

<npsField type="select" name="name" selectionType="multi"
     renderMode="Display mode" size="Height" ... >
...
</npsField>

This displays one or more fields for selecting an option.

renderMode specifies how the field is to be rendered:
- vertical: Check boxes are rendered.
- list (default): A multi-selection field is rendered.
The width attribute is only taken into account if renderMode has the value list.
size is only taken into account if renderMode has the value list and specifies the height of the field in lines.
Please specify the values available for selection using npsFieldOption elements.

Entering text (type `textarea`)

<npsField type="textarea" name="name" rows="number of rows"
     cols="number of columns" style="styles"... />

This creates a text area input field.

rows specifies the height of the text area
cols specifies the width of the text area.
style specifies (additional) CSS styles.

Selecting a file (type `selectObject`)

<npsField type="selectObject" name="name" value="File ID"
    startId="Start file ID" startPath="Start file path"
    objectTypes="File types" selectMessage="Message".../>

This creates a file selection field containing one input field to which a selection button is attached. If the button is clicked, the selection page is opened. After selecting a file on this page, the path of the file is placed into the input field.

startId and startPath optionally specify the file initially selected in the selection dialog. Only one of these attributes may be used.
value may optionally be set to a file ID. The path of this file is placed into the input field as a default. This path overrides the startId and startPath presets.
The optional objectTypes restrict the files that appear in the selection dialog with respect to their type. The value of this attribute is a comma-separated list. Folders are always visible.
selectMessage can be optionally used to display a message to the user informing him about the purpose of the file selection.

Selecting a date (type `date`)

<npsField type="date" name="name" value="Date"
  format="Date format"... />

This creates a date selection field consisting of an input field and a selection button. If the button is clicked, the selection page is opened. Selecting a date on this page places the date into the input field.

value is the value of the file selection field as a 14-digit CMS date. The field value passed to the wizard is a 14-digit CMS date as well.
format is the optional format to be applied to the field value. Please refer to the validDateTimeOutputFormats system configuration key for a description of the formatting placeholder values. If this value has not been provided, the date format of the respective user is used.

Usage in Wizards

Input elements, i.e. the corresponding npsField elements, can be comfortably generated in wizards by calling procedures available in the share/script/cm/serverCmds/wizards/lib/layout.tcl Tcl library.

Text field

::layout::textField name label value ...

This creates an npsField element of the text type.

name, label, and value specify the value of the corresponding npsField element attributes. HTML specific characters will be converted.
Additional npsField element attributes may be specified as key/value list, e.g. maxLength.

Example:

::layout::textField product "Product escription" [getParam product]\
    width 40 maxLength 40

Multi-Line Text Field

::layout::textArea name label value ...

This creates an npsField element of the textarea type.

name, label, and value specify the value of the corresponding npsField element attributes. HTML specific characters will be converted.
Additional npsField element attributes may be specified as key/value list, e.g. maxLength.

WYSIWYG HTML Editor (TinyMCE)

::layout::mceEditor name label value ...

This creates a multi-line text field which is replaced at runtime by the TinyMCE HTML editor. The parameters correspond to those of the multi-line text field.

In CMS Fiona 6.8.0 and later, the editor can be configured by means of the optional config argument. The value of this argument is expected to be the JSON representation of the TinyMCE configuration:

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

TinyMCE requires the tinyMCE web application that can be deployed using the following command:

InstanceDirectory/bin/rc.npsd deploy tinyMCE

In CMS Fiona 6.8.0 and later, the tinyMCE web application is included in the list of the web applications to be deployed (rc.npsd.conf) by default. Thus, it is deployed if rc.npsd deploy is executed.

For properly displaying link paths contained in the field value to be edited, they need to be adapted prior to calling the editor:

set tinyMceTextArea [changeImgPathsToPreviewPaths $blob $objId]

Here, tinyMceTextArea is the name of the variable used for temporarily storing the adapted field value. blob is the field content to be processed and edited, and objId is the ID of the CMS file concerned. After editing, the paths need to be normalized again:

set blob [changePreviewPathsToImgPaths $tinyMceTextArea]

Multi selections

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

Creates a list of checkboxes or one multi-selection element, depending on the size of valuesAndLabels. Checkboxes are used if the size is less than the given limit.

Single selections

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

Creates a list of radio buttons or one popup menu, depending on the size of valuesAndLabels. Radio buttons are used, if the size is less than the given limit.

Radio buttons

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

This creates an npsField element with npsFieldOption elements. The selection is displayed as radio buttons.

name specifies the parameter name of the HTML form.
label (optional) specifies the description of the selection.
valuesAndLabels specifies the list of options. An option is a list consisting of a value and an optional label.
selectedValue specifies the currently selected value.
Additional npsField element attributes may be specified as a list of key/value pairs, for example required.

Example:

::layout::radioButtons color {{ffff00 yellow} {ff0000 red} {0000ff blue}}\
    [getParam "color"] "Color" required true

Checkboxes

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

This creates an npsField element consisting of npsFieldOption elements. The selection is displayed as checkboxes that can be selected independently of each other.

The parameters are analogous to ::layout::radioButtons.
selectedValues contains the list of selected options.

::layout::checkBox name valueAndLabel selectedValue label ...

Creates a single checkbox.

The parameters are analogous to ::layout::radioButtons.
selectedValue contains the list of selected options.

Popup Menu

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

This creates an npsField element consisting of npsFieldOption elements. The selection is displayed as a popup menu.

The parameters are analogous to ::layout::radioButtons

Multi-selection list

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

This creates an npsField element consisting of npsFieldOption elements. The selection is displayed as a multi-selection field.

The parameters are analogous to ::layout::checkButtons

File upload

::layout::fileField name label fileName ticketId ...

This creates an npsField element of the file type, the name name and the description label.

fileName name of the uploaded file once a file has beeen uploaded. In all other cases leave the value empty.
ticketId ID of the streaming ticket by which the content of the file is accessible, once a file has been uploaded. In all other cases leave the value empty.
mimeType restricts the files available for selection. For details regarding mime types, please refer to the HTML specification.

Example:

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

There is an example of usage.

File selection

::layout::selectObject name label id selectMessage ...

This creates an npsField element of the selectObject type with the name name, the description label, the file ID id, and the message selectMessage.

Date selection

::layout::dateField name label value ...

Creates an npsField element of the date type, with the name name, the description label, and the value value.

Example of Usage

If, in a wizard, the following code is returned to the GUI, an HTML input field is created on the corresponding wizard page. It serves to upload a file to the server:

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

For the file the user has uploaded, a streaming ticket is created in the Content Management Server. Through this ticket, the uploaded file can be accessed. The Content Management Server stores the ID of the ticket as well as the name of the file in two variables, namely:

$varName.fileName
$varName.ticketId

varName is the value of the name tag attribute in the npsField element. Inside the wizard, the values can be accessed in the following way, for example:

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

For the purpose of storing the uploaded file as a CMS file you can refer to the ticket in the corresponding Tcl command to have the uploaded file placed into the main content of the CMS file. However, before this is done, the name of the new CMS file as well as its file name extension is taken from the name of the uploaded file (if the name and the extension of the CMS file is not predefined or defined elsewhere):

# Determine name and name extension
set name [file rootname $uploadFileName]
set contentType [string trimleft [file extension $uploadFileName] "."]

# Create new file containing the contents of the uploaded file
obj withId $parent createAndLoad name $name objClass generic \
        contentType $contentType blob.stream $uploadTicket

In the example above, a new file is created from the generic file format. The file is placed into the folder whose ID is $parent, and the main content is filled with the uploaded file which is accessible through the ticket ID.

To store the uploaded file in the file system of the server instead of in the CMS, you can download it using the stream downloadFile command, again specifying the ticket ID of the file:

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

Afterwards, the file can be found in the /tmp/uploads/ directory.

npsField

Syntax

Input Field Types and Their Parameters

Uploading files (type file)

Entering strings (type text)

Selecting an option (type select)

Selecting several options (type select)

Entering text (type textarea)

Selecting a file (type selectObject)

Selecting a date (type date)

Usage in Wizards

Text field

Multi-Line Text Field

WYSIWYG HTML Editor (TinyMCE)

Multi selections

Single selections

Radio buttons

Checkboxes

Popup Menu

Multi-selection list

File upload

File selection

Date selection

Example of Usage

Uploading files (type `file`)

Entering strings (type `text`)

Selecting an option (type `select`)

Selecting several options (type `select`)

Entering text (type `textarea`)

Selecting a file (type `selectObject`)

Selecting a date (type `date`)