Novell Doc: NDK: iManager 2.7 Developer Kit

6.3 The MVStringEditor Widget

The MVStringEditor (mved) widget provides an editor control that can store multiple values. It provides the following benefits:

Allows single source for a multivalue string edit (mved) control
Customizes the control for the browser used
Automatically detects the browser and sets the appropriate mode
Allows the mode to be overridden

The mved supports the following Web browsers:

Firefox* 1.5.x and later
Internet Explorer 6 and later

6.3.1 How to Use the MVStringEditor Widget

Include the required mved JavaScript file.
Add the mved on the page.
Load values into the control.
Get values from the control.

For example:

 01:<%@ page pageEncoding="utf-8" contentType="text/html;charset=utf-8" %>
 02:<%@ taglib uri="/WEB-INF/iman.tld" prefix="iman" %>
 03:<%@ taglib uri="/WEB-INF/c.tld" prefix="c" %>
 04:

 05:<HTML>
 06:<HEAD>
 07:   <LINK rel="stylesheet" href="<c:out value="${ContextPath}" />/portal/modules/dev/css/hf_style.css">
 08:      <iman:mvedScripts/>
 09:      <iman:eMFrameScripts/>
 10:

 11:   <SCRIPT>
 12:      function onInit()
 13:         {
 14:            mvLoadFromPack("mved1", "<c:out value="${myData}"/>");
 15:         }
 16:
 17:      function onExit()
 18:      {
 19:         document.form.mvedData.value = mvGetValuesAsPack("mved1");
 20:      }
 21:   </SCRIPT>
 22:</HEAD>
 23:
 24:<BODY onLoad="onInit();">
 25:<FORM name="form" method="post" action="webacc" onSubmit="return onExit();">
 26:   <iman:mved name="mved1" width="150"/>
 27:   <input type=”hidden” name=”mvedData”/>
 28:</FORM>
 29:</BODY>
 30:</HTML>

Of particular interest in the above example are the following:

02: Includes iManager Tag Library
08: Includes javascripts methods required by MVStringEditor
14: Loads data into control
19: Retreives data from control
26: Including control on page
27: Hidden input for posting data to server

To pass values to the control with Java:

 String values = ...;

 request.setAttribute("myItems", values);

To get values from the control with Java:

 String pack = request.getParameter("mved1_packValues");

 String[] items = eMFrameUtils.unpack(pack, taskContext);

6.3.2 Modes

When including the mved, you must decide on a mode. If you do not set a mode, it chooses a mode for you based on the current device.

Table 6-6 MVStringEditor modes

Mode	Description
mvie	Fancy mved for holding and editing multiple values; normal mved for Internet Explorer. This is the default mode for the Browser device type.
mvsel	In this mode, the mved is based on the HTML select control. It has two modes: One line. This mode uses a smaller area. It is the default mode for the Simple device type. The user sees only the first value until clicking the drop-down arrow. Combobox. This mode uses a larger area. It is composed of a text entry area and an expanded select box. It can be used with Browser or Simple device types when it is the only control on the page.

Mode

Description

mvie

Fancy mved for holding and editing multiple values; normal mved for Internet Explorer. This is the default mode for the Browser device type.

mvsel

In this mode, the mved is based on the HTML select control. It has two modes:

One line. This mode uses a smaller area. It is the default mode for the Simple device type. The user sees only the first value until clicking the drop-down arrow.
Combobox. This mode uses a larger area. It is composed of a text entry area and an expanded select box. It can be used with Browser or Simple device types when it is the only control on the page.

6.3.3 Parameters

Table 6-7 MVStringEditor parameters

Parameter	Description
name	Specifies a unique name identifier for the mved.
mode	Specifies one of three mved modes (mvsel, mvie, or mvtxt). If you do not specifiy a mode, the mved picks the mode best suited for the current device. This helps when single-sourcing JSP files across multiple devices.
width	Specifies the width of the control in pixels.
useRootedName	Specifies complete object name including the tree name.
bgColor	Specifies the color of the page around the control. The default is white. Use standard hex HTML color codes to specify the background color.
readonly	Boolean value that, when True, disables the control and dims the control text.
objectTypeName	Specifies an Object Selector typeFilter ("User", "*", etc.)
enforceUnique	Boolean value that, when True, forces all values in the list to be unqiue.
ignoreCase	Boolean value that, when True, instructs the control to ignore case when determining if a value is unique. For example, when ignoreCase is true, "ABC" and "abc" cannot both be added to the list. This attribute is used only when enforceUnique is True.
size	Specifies the number of rows to display in the select box. This attribute is used only when mode is mvsel.
numbersOnly	Boolean value that, when True, instructs the control to only support numeric values.
upperBound	Instructs the control to support only numeric values less than the specified value.
lowerBound	Instructs the control to support only numeric values greater than the specified value.
minLength	Instructs the control to support only string longer than the specified number of characters.
maxLength	Instructs the control to support only strings shorter than the specified number of characters.
xml	Specifies XML as a string to display to the user. The root node can be anything, but it must have child nodes of name value.
history	Displays a history button next to the OS value. This attribute is used only when objectTypeName is True.
disableEdit	Boolean value that, when True, disables the editing of control.
biggerBox	Boolean value that, when True, gives bigger text box. Used in conjunction with Size attribute which should be greater than 0.

6.3.4 JavaScript API

The following JavaScript methods allow you to interact with the MVStringEditor:

mvLoadFromPack (String name, String packedString) The name parameter must be the same as the MVStringEditor_name used for MVStringEditor_inc.

mvGetValuesAsPack (String name) : String (packed) The name parameter must be the same name as the MVStringEditor_name used for MVStringEditor_inc. The return value is a packed string, safe to be posted.

mvGetValuesAsXml (String name) : String (xml content) The name parameter must be the same as the MVStringEditor_name used for MVStringEditor_inc. The return value is XML in string format.

mvLoadFromXml (String name, String xml) The name parameter must be the same as the MVStringEditor_name used for MVStringEditor_inc.

mvEnable (String name)

mvDisable (String name)

The JavaScript methods mvLoadFromPack and mvGetValuesAsPack interact with packed Strings. An empty string is not a valid packed string. If you want an empty packed string, call pack(new Array()). There are methods in eMFrameScripts (JavaScript) and eMFrameUtils (Java) to pack and unpack these strings.

6.3.5 Examples

Following are some MVStringEditor examples::

Packed Strings

In JavaScript header:

 oninit : mvLoadFromPack ("myControl", "<c:out value="${data}"/>");
 onexit: document.form.data.value = mvGetValuesAsPack ("myControl")

In HTML body:

 <iman:mved name=”myControl” ignoreCase=”true” enforceUnique=”true”/>

XML

In JavaScript header:

 oninit: mvLoadFromXml("mycontrol", "<root><value>...</value></root>");
 onexit: hiddenField = mvGetValuesAsXml("mycontrol");

In XML:

 <root>
   <value>test1</value>
   <value>test2</value>
   <value>test3</value>
 </root>