The Common-Controls Tag Library

<ctrl:treelist>

Generates a list control element whose underlying data structure is a tree. The data model thus implements the TreeGroupDataModel.

The layout of the list can be defined in the JSP-Page.

The <treelist>-tag can only be used in conjunction with a bean that implements the TreeGroupDataModel Interface or is derived from TreeListControl.
../images/images/treelist_small.gif

Body content: JSP
Tag class: TreelistTag
Tei class: TreelistTei
 

[ Syntax ]

Standard Syntax
<ctrl:treelist
[ action = "String" ]
[ ajax = "Boolean" ]
[ border = "Integer" ]
[ buttons = "boolean" ]
[ cellPadding = "Integer" ]
[ cellSpacing = "Integer" ]
[ checkboxes = "boolean" ]
[ createButton = "ACL" ]
[ disabled = "boolean" ]
[ emptyText = "String" ]
[ enableProperty = "String" ]
[ expandMode = "{full | single | multiple}" ]
[ exportListButton = "ACL" ]
[ formElement = "boolean" ]
[ groupselect = "boolean" ]
[ height = "String" ]
[ help = "String" ]
[ hideButtons = "String list" ]
[ id = "String" ]
[ labelWrap = "" ]
[ lines = "boolean" ]
[ linesAtRoot = "boolean" ]
[ locale = "String" ]
[ minRows = "Integer" ]
[ name = "String" ]
[ noframe = "Boolean" ]
[ noheader = "Boolean" ]
[ pageButtons = "integer" ]
[ permission = "ACL" ]
[ printListButton = "ACL" ]
[ property = "String" ]
[ refreshButton = "ACL" ]
[ root = "boolean" ]
[ rows = "Integer" ]
[ runat = "{server | client | auto}" ]
[ scope = "{any | page | request | session | application}" ]
[ scrollHeight = "String" ]
[ select = "{none | single | multiple}" ]
[ shadow = "boolean" ]
[ showHeader = "boolean" ]
[ style = "String" ]
[ styleClass = "String" ]
[ styleId = "String" ]
[ summary = "String" ]
[ tabindex = "Integer" ]
[ taborientation = "{horizontal | vertical}" ]
[ title = "String" ]
[ transaction = "Boolean" ]
[ width = "String" ]
>
...Body Content...

</ctrl:treelist>
 

[ Attributes ]

AttributeTypeDescriptionReq.RTExp
actionString Specifies the Struts Action that is to be called in case of control element events.

This attribute need not be specified if the tag is included within a Struts <html:form> tag. In that case, the name of the action is determined using the Struts Form Bean.

Annotation: The action must be declared in one of the struts-config.xml files.

 
ajaxBoolean Activates the AJAX function of the column. With AJAX all control events will be sent asynchronously to the application server where the processing takes place.

The event processing on the server is the same as without AJAX enabled. However the application developer has the possibility to control the response output through some additional methods of the AjaxRequest interface (the base class for ActionContext).

The normal AJAX server processing (-> AjaxRequest.isAjaxCanceled() == false) will send back a XML stream to the Web Browser. This stream contains only the HTML code for the dirty controls, which will be merged in the Browser through a JavaScript handler into the current HTML DOM Tree. So the Server will not transmit the full HTML page!

  • (+) The transfered HTML code is much smaller.
  • (+) The HTML page stays in the Browser window while the server request is being processed. So the screen will not "flicker".
  • (-) The browser will not keep track of AJAX requests in the navigation history!
  • (-) AJAX depends on JavaScript. Without JavaScript the event will result in a normal browser - server round trip.

Most of the Controls will add themselves to the dirty list of the ActionContext. This is done through a call to AjaxRequest.markDirty(). With this method the application developer has the opportunity to add additional controls to the dirty list and send them back to the browser in the XML stream. This is necessary when an event handler changes the state of a second control that was not the originator of the request.

In some cases it is not sufficient to send back only the dirty control because the whole HTML page has to be changed. In this cases the application developer can cancel AJAX server event processing by calling the AjaxRequest.cancelAjaxRequest() method. When the AJAY request is canceled the framework will send a full HTML page back to the Browser - as if this was a normal HTTP request.

The Common-Controls AJAX XML Protocol has the following format:


<?xml version="1.0" encoding="UTF-8" ?>
<ajax-response>
	<token/>
	<controls>
		<control styleId="" class="" name="">
			<html>
				<[CDATA[...]] >
			</html>
		</control>
	</controls>
</ajax-response>
 
borderInteger Specifies the thickness of the border that has to be drawn around the control element.  
buttonsboolean Indicates whether, in case of group nodes, buttons for exploding or closing the branch should be displayed.

This option has no effect if the expandMode of the tree structure is set to full. In that case, buttons are never shown.

 
cellPaddingInteger Sets the cell padding for cell elements  
cellSpacingInteger Sets the cell spacing for cell elements  
checkboxesboolean Indicates whether a checkbox should be displayed before the tree entries.

The tree entries must implement the Checkable Interface, so that the control element can draw the checkboxes. Group nodes must not implement this interface, since the Check-State of groups can be automatically calculated with the help of the state of the pages.

 
createButtonACL Indicates whether a button for creating a new data record should be displayed. By specifying an Access Control List, the creation of new records can be restricted to certain users.  
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.  
emptyTextString A text that is output in the body of the list element if there are no lines available.

The character string is HTML-encoded before outputting.

 
enablePropertyString Indicates the name of a property, with the help of which the drilldown function can be disabled in the relevant line.

For this, the TreeNode-Bean must provide a corresponding Property Getter, which returns a Boolean data type.

Annotation: Valid Java identifier/label. The TreeNode-Bean must implement a suitable property-getter method.

 
expandModeExpansionMode This attribute specifies how many nodes of the tree structure may be displayed exploded at the same time.
  • full = All nodes are shown exploded at all times. The user cannot close any node.
  • single = Only one branch can be exploded.
  • multiple = As many branches as desired can be exploded.
 
exportListButtonACL Shows the exportlist button within the list header. An Access Control List (ACL) can be specified to grant access the button to restricted users.  
formElementboolean This attribute is used to control how the control element should behave in case of a user action.
As form element
A submit of the surrounding form is carried out. All the information about the control element event is transported to the server in hidden fields.
As an independent control element
Control element events are directly triggered in the form of hyperlinks. All the data input in the HTML page is then lost.
Internally, this attribute is used to control how the control element should generate Painter links - as HTML-A tags or HTML-Input tags.

Annotation: The value true may only be used when the control element is situated in a form.

 
groupselectboolean Specifies whether, for the group nodes of the tree structure, a Click Eventhandler should be called.  
heightString Sets the height of the control element. The height may be specified in absolute or percent terms.

See the HTML documentation

 
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 The name of a page scope JSP bean that will contain the current element. Using the given Id, the variable can be accessed in scripting expressions in the tag Body. The id mus be a string lteral because the JSP compiler generates a variable withthis name at compile time

Annotation: A valid Java identifier must be given.

 
labelWrap 
linesboolean Specifies whether connecting lines should be drawn between the construction elements.  
linesAtRootboolean Specifies whether lines should be drawn to the construction elements of the uppermost (displayed) level.  
localeString enables localization for the control element. String literals will be interpreted as keys in the Application.properties file.

Annotation: boolean value true oder false oder the name of a locale.

 
minRowsInteger This attribute is used to specify the minimum number of lines that are depicted simultaneously. When the total number of available lines in the data model is lesser than the number of lines displayed, empty lines are automatically generated.  
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.

 
noframeBoolean Hides the controls frame and title  
noheaderBoolean Hides the controls column headers  
pageButtonsinteger The number of buttons for direct page navigation.  
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

 
printListButtonACL Shows the printlist button within the list header. An Access Control List (ACL) can be specified to grant access the button to restricted users.  
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.

 
refreshButtonACL Specifies whether a button should be displayed for updating the elements.  
rootboolean Specifies whether the root node of the tree structure (Level 0) should be displayed or whether the display should first start at the next tree level(Level 1).

Definition: A tree always has exactly one root!

 
rowsInteger This attribute is used to specify the maximum number of lines that are depicted simultaneously. When the total number of available lines in the data model is greater than the number of lines displayed, scrollbars are automatically generated for slowly scrolling through pages.

If this attribute is not specified, all lines are always displayed.

 
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.
 
scrollHeightString Specifies the height of the scrollable body for the control.

Note: If the scrollHeight-Attribute is set, the width-Attribute for each column- and columngroup-Tag needs to be specified!

Annotation: See HTML documentation for the attribute width.

 
selectSelectType Specifies the selection mode of the list. This is only used if a Check column is to be displayed here as well.
  • none = no selection.
  • single = single selection.
  • multiple = multiple selection.
 
shadowboolean Specifies whether the control element should be saved with a shadow.

This function is only available in the case of specific Painterfactories.

 
showHeaderboolean Specifies if the header of the control including the column titels should be rendered. If set to false the header will not be shown  
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.  
taborientationOrientationType This attribute sets the tabulator orientation for multi column controls.
  • horizontal = Horizontal alignment (left to the right)
  • vertical = Vertical alignment (top to the bottom)
 
titleString The main title of the list element. The character string is HTML-encoded before outputting.

Example: becomes ä &auml;

 
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).  
widthString Sets the width of the control element. The height may be specified in absolute or percent terms.

See the HTML documentation

 
 

[ Server Events ]

EventDescription
Add 
public void control_onAdd(
	ControlActionContext ctx,
	String key) throws Exception
CellClick 
public void control_onCellClick(
	ControlActionContext ctx,
	String column,
	String key) throws Exception
Check 
public void control_onCheck(
	ControlActionContext ctx,
	String key,
	SelectMode mode,
	boolean checked) throws Exception
CheckAll 
public void control_onCheckAll(
	ControlActionContext ctx,
	SelectMode mode,
	boolean checked) throws Exception
Collapse 
public void control_onCollapse(
	ControlActionContext ctx,
	String key) throws Exception
Create 
public void control_onCreate(
	ControlActionContext ctx) throws Exception
Delete 
public void control_onDelete(
	ControlActionContext ctx,
	String key) throws Exception
Drilldown 
public void control_onDrilldown(
	ControlActionContext ctx,
	String key) throws Exception
Edit 
public void control_onEdit(
	ControlActionContext ctx,
	String key) throws Exception
Expand 
public void control_onExpand(
	ControlActionContext ctx,
	String key) throws Exception
ExpandEx 
public void control_onExpandEx(
	ControlActionContext ctx,
	String key) throws Exception
ExportList 
public void control_onExportList(
	ControlActionContext ctx) throws Exception
Page 
public void control_onPage(
	ControlActionContext ctx,
	int page) throws Exception
PrintList 
public void control_onPrintList(
	ControlActionContext ctx) throws Exception
Refresh 
public void control_onRefresh(
	ControlActionContext ctx) throws Exception
Select 
public void control_onSelect(
	ControlActionContext ctx,
	String key) throws Exception
Sort 
public void control_onSort(
	ControlActionContext ctx,
	String column,
	SortOrder direction) throws Exception

[ Example ]

Generates a simple treelist


<%@ taglib uri="http://www.common-controls.com/cc/tags-ctrl"    prefix="ctrl" %>
<%@ taglib uri="http://www.common-controls.com/cc/tags-util"   prefix="util" %>

<util:imagemap name="im_region">
   <util:imagemapping  rule="country"  src="images/imgItem.gif"  width="16"  height="16"/>
</util:imagemap>

<ctrl:treelist
   id="treelist13"
   name="regions"
   title="Market Hierarchy"
   rows="15"
   expandMode="multiple"
   buttons="true"
   lines="true"
   linesAtRoot="false"
   root="true"
   refreshButton="true">

   <ctrl:columntree    title="Region"  property="region"  width="150"  imageProperty="type"  imagemap="im_region"/>
   <ctrl:columntext    title="Name"    property="name"    width="300"/>
   <ctrl:columnadd     title="Add"     property="add"     permission="#admin"/>
   <ctrl:columnedit    title="Edit"    property="edit"    permission="#admin"/>
   <ctrl:columndelete  title="Delete"  property="delete"  permission="#admin"/>
</ctrl:treelist>

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