The Common-Controls Tag Library

<forms:swapselect>

Generates a select element with two list which allows to transfere elements from one list to the other list. The available elements will be specified by the <base:options>-Tag within the tag body. The data bean should provide an array which holds the selected elements.
The tag may only be used within a com.cc.framework.taglib.forms.FormElementContainerTag. Examples of this are <forms:form> and <forms:section>.
../images/images/formswapselect_small.gif

Body content: JSP
Tag class: FormElementSwapSelectTag
 

[ Syntax ]

Standard Syntax
<forms:swapselect
[ accesskey = "String" ]
[ align = "{left | right | center}" ]
[ colspan = "Integer" ]
[ description = "String" ]
[ disabled = "boolean" ]
[ filter = "boolean" ]
[ height = "String" ]
[ help = "String" ]
[ hideButtons = "String list" ]
[ id = "String" ]
[ imageref = "String" ]
[ join = "Boolean" ]
[ label = "String" ]
[ labelLeft = "String" ]
[ labelRight = "String" ]
[ labeltooltip = "String" ]
[ moveButton = "Boolean" ]
[ multiple = "Boolean" ]
[ name = "String" ]
[ onblur = "String" ]
[ onchange = "String" ]
[ onclick = "String" ]
[ oncontextmenu = "String" ]
[ ondblclick = "String" ]
[ onfocus = "String" ]
[ onkeydown = "String" ]
[ onkeypress = "String" ]
[ onkeyup = "String" ]
[ onmousedown = "String" ]
[ onmousemove = "String" ]
[ onmouseout = "String" ]
[ onmouseover = "String" ]
[ onmouseup = "String" ]
[ orientation = "{horizontal | vertical}" ]
[ permission = "ACL" ]
[ property = "String" ]
[ required = "boolean" ]
[ retainOrder = "Boolean" ]
[ runat = "{server | client | auto}" ]
[ scope = "{any | page | request | session | application}" ]
[ size = "Integer" ]
[ sortOrder = "{none | asc | desc}" ]
[ style = "String" ]
[ styleClass = "String" ]
[ styleId = "String" ]
[ summary = "String" ]
[ tabindex = "Integer" ]
[ tooltip = "String" ]
[ transaction = "Boolean" ]
[ valign = "{top | bottom | center}" ]
[ value = "String" ]
[ width = "String" ]
>
...Body Content...

</forms:swapselect>
 

[ Attributes ]

AttributeTypeDescriptionReq.RTExp
accesskeyString The accesskey attribute can be used to specify a shortcut key for the <LABEL> (activated by pressing Alt and the accesskey togther).  
alignAlignmentType Specifies the horizontal alignment of the element.
  • left = left alignment
  • right = right alignment
  • center = center alignment
 
colspanInteger Specifies the column span of a form element within a multi column form  
descriptionString The description text.  
disabledboolean This attribute can be used to disable the control element. It then does not accept any user inputs and does not generate any control element events.  
filterboolean The automatic HTML coding of the element can be activated or disabled with the filter-attribute.  
heightString Sets the height of the form element. The height may be specified in absolute or percent terms.

Annotation: See HTML documentation for the attribute height.

 
helpString Allows to assign a help id for the element. If set, a help symbol will be displayed beside the element, which will generate an onHelp event if the icon is clicked. The id can be used to display a special page of the help system. The help system is not part of the Common-Controls Framework.

To generate the hyperlink some default framework resources where used:
Resource KeyDescriptionDefault
fw.help.onclickAn optional onclick script handler. The handler can include a {0} placeholder for the help id-
fw.help.targetSpecifies the target where to open the hyperlink_blank
fw.help.tooltipA tooltip for the hyperlinkcontext help

Annotation: A jump screen of the Help system must be specified.

 
hideButtonsString list This attribute can be used to hide some of the buttons. The buttons needs to be specified within a semicolon separated list.

Annotation: A semicolon separated list. The button names must match values of ControlButton.getName()

 
idString Assigns the control element a unique identifier. Using the given Id, the Java variable can be accessed in the tag Body. The id must be a string literal because the JSP compiler generates a variable with this name at compile time

Annotation: A valid Java identifier must be given.

 
imagerefString Pointer to an element of the Imagemap of the form. The image is drawn before the label of the element.  
joinBoolean Indicates that two adjacent form elements should be joined together  
labelString The label of the form element.  
labelLeftString Specifies the label for the left or upper list.  
labelRightString Specifies the label for the right or lower list.  
labeltooltipString Tooltip on for the label of the form element.  
moveButtonBoolean Specifies if the up and down buttons should be displayed. The buttons can be used to change the order of the items within the list.  
multipleBoolean Specifies that the SwapSelect Control should provide multiple select elements on the right side. This option is currently only available for a horizontal alignment.

If the attribute is set to true the following needs to be considered:

  • The datamodel now has to provide an array with arrays. The dimension of the first array level (= n) has to match the number of select elements on the right side. This means hat the dimension will determine how much select elements on the right side will be displayed.
  • The attribute labelRight now should contain a comma separated list with captions for the different select elements on the right side. So the number of captions should match the array level n. The comma separated list can contain resource keys or simple String literals which should be displayed. If localization is used a simple String literal can be displayed if the "#" is prepended.
  • The attribute size now should contain a comma separated list with the size of the select elements on the left and right side.
    Example:
    size="28;8" (Left 28, All other select elements on the right 8).
    size="28;8;8;8" (Left 28, A different size for each select element on the right).

 
nameString Specifies the name of the Java-Bean. The Java-Bean must be stored in the given scope.

When the tag is surrounded by a Struts <html:form> tag, no Bean Name need be specified. In this case, the Java-Bean is drawn via a property of the Struts Form Bean.

Annotation: A valid Java identifier must be given.

 
onblurString Fires when the object loses the input focus.

Annotation: JavaScript Code

 
onchangeString Fires when the contents of the object or selection have changed.

Annotation: JavaScript Code

 
onclickString Fires when the user clicks the left mouse button on the object.

Annotation: JavaScript Code

 
oncontextmenuString Fires when the user clicks the right mouse button in the client area, opening the context menu.

Annotation: JavaScript Code

 
ondblclickString Fires when the user double-clicks the object.

Annotation: JavaScript Code

 
onfocusString Fires when the object receives focus.

Annotation: JavaScript Code

 
onkeydownString Fires when the user presses a key.

Annotation: JavaScript Code

 
onkeypressString Fires when the user presses an alphanumeric key.

Annotation: JavaScript Code

 
onkeyupString Fires when the user releases a key.

Annotation: JavaScript Code

 
onmousedownString Fires when the user clicks the object with either mouse button.

Annotation: JavaScript Code

 
onmousemoveString Fires when the user moves the mouse over the object.

Annotation: JavaScript Code

 
onmouseoutString Fires when the user moves the mouse pointer outside the boundaries of the object.

Annotation: JavaScript Code

 
onmouseoverString Fires when the user moves the mouse pointer into the object.

Annotation: JavaScript Code

 
onmouseupString Fires when the user releases a mouse button while the mouse is over the object.

Annotation: JavaScript Code

 
orientationOrientationType Specifies the alignment of the two lists.
  • horizontal = Horizontal alignment (left to the right)
  • vertical = Vertical alignment (top to the bottom)
 
permissionACL With this attribute, access to the element can be restricted.

Authorizations are checked using the com.cc.framework.security.Principal object in the user session. The principal object is registered in the session with the method com.cc.framework.security.SecurityUtil#registerPrincipal(HttpSession, Principal). It is made available by the application developer by implementing the principal interface. In this manner, any authorization system can be very easily connected within the framework.

Authorizations are always specified in the form of an Access Control List (ACL). What is involved here is a semicolon-delimited list with individual authorizations. The framweork supports the following authorization types, which, however, can be expanded at will by the application developer:

Literal
true|false -> com.cc.framework.security.StaticPermission
Role
#rolename -> com.cc.framework.security.RoleBasedPermission
Function
$functionname -> com.cc.framework.security.FunctionBasedPermission

 
propertyString Specifies the name of the property using which the Java-Bean is to be accessed. This is generally only necessary when the Java-Bean is associated with a Struts Form Bean.

Annotation: A valid Java identifier must be given.

 
requiredboolean Indicates whether the form element involved is a mandatory input. Mandatory fields are displayed highlighted for the user's convenience.  
retainOrderBoolean Specifies if a given order of the items should be retained if an item is moved from on side to the other side.

Attention: This option should only be used in conjunction with short list and can cause performance problems using large option list.

 
runatRunAt This attribute specifies whether, for the control element, Clientside JavaScript should be used, or whether the control element should work purely with Server Roundtrips.
  • server = All control element actions result in a Server Roundtrip and are processed on the server.
  • client = control element actions are carried out directly in the browser of the user. It depends on the Painter Factory used and the specific control element, how far the support for Clientside Scripting goes!
  • auto = The framework selects based on the users browser settings "client" when JavaScript is enabled and "server" when JavaScript is disabled.
 
scopeHTTPScope This attribute shows the Scope in which the Java-Bean with the actual display data can be found.
  • any = The Bean is searched for in ever Scope.
  • page = The Bean exists as a local variable in the JSP Page.
  • request = The Bean is in the HTTP-request.
  • session = The Bean is in the HTTP-Session.
  • application = The Bean is in the Servletkontext.
 
sizeInteger Specifies the number of visibel options.  
sortOrderSortOrder Specifies the sort order of the elements
  • none = no sorting
  • asc = ascending sorting sequence
  • desc = descending sorting sequence
 
styleString An HTML-style can be directly specified with this attribute.

Annotation: See HTML documentation for the attribute style.

 
styleClassString The HTML-class attribute of the element can be specified with this attribute.

Annotation: See HTML documentation for the Attribute class.

 
styleIdString The HTML-id attribute of the element can be specified with this attribute.

Annotation: See HTML documentation for the Attribute id.

 
summaryString This property can be used for rendering to non-visual media such as speech or Braille.  
tabindexInteger Tabulator Index for this element.  
tooltipString A short descriptive text that is displayed when the user moves the mouse over the element.  
transactionBoolean This flag directs the framework to append a transaction token to all generated hyperlinks. The transactio token allows the detection of form re-submissions (multiple submission of the same HTTP form).  
valignAlignmentType Specifies the vertical alignment of the element.
  • top = top alignment
  • bottom = bottom alignment
  • center = center alignment
 
valueString The value of the field can also be specified directly with this attribute.  
widthString Sets the width of the form element. The width may be specified in absolute or percent terms.

Annotation: See HTML documentation for the attribute width.

 

[ Example ]

Form element with a swapselect element.


<%@ taglib uri="http://struts.apache.org/tags-html"             prefix="html" %>
<%@ taglib uri="http://www.common-controls.com/cc/tags-base"   prefix="base" %>
<%@ taglib uri="http://www.common-controls.com/cc/tags-forms"   prefix="forms" %>

<html:form action="/swapselectdemo">

    <forms:form type="edit" caption="form.swapselect.headline" formid="frmLogin" width="550">

        <forms:swapselect
            property="bookKey"
            label="form.swapselect"
            orientation="horizontal"
            labelLeft="form.label.books.left"
            labelRight="form.label.books.right"
            valign="top"
            size="10"
            width="100%"
            filter="false"
            required="true"
            runat="client"
            disabled="false">

            <base:options property="bookOptions"  keyProperty="isbn" labelProperty="title"/>

        </forms:swapselect>
    </forms:form>

</html:form>

                  
© 2000 - 2007 by www.common-controls.com (build with Common Controls TLDFactory)