Die Common-Controls Tag Bibliothek

<ctrl:columntree>

Erzeugt eine Baumstruktur Spalte für das TreeNodeDataModel des Kontrollelementes.

RolleJava Klasse
DesignmodelColumnTreeDesignModel
DatamodelTreeNodeDataModel
Das <columntree>-Tag darf nur innerhalb von einem <treelist>-Tag verwendet werden. Demzufolge muß als Datenmodell für das Kontrollelement ein TreeNodeDataModel verwendet werden.

Es kann nur eine <columntree> Spalte je Kontrollelement sinnvoll verwendet werden

../images/images/columntree_small.gif

Body content: JSP
Tag class: ColumnTreeTag
 

[ Syntax ]

Standard Syntax
<ctrl:columntree
[ ajax = "Boolean" ]
[ align = "{left | right | center}" ]
[ converter = "Java Klassenname oder Converter Id" ]
[ filter = "Boolean" ]
[ imagemap = "String" ]
[ imageProperty = "String" ]
[ join = "{none | false | concatenate | true | separator}" ]
[ maxlength = "Integer" ]
[ onblur = "String" ]
[ onchange = "String" ]
[ oncheck = "String" ]
[ onclick = "String" ]
[ oncollapse = "String" ]
[ oncontextmenu = "String" ]
[ ondblclick = "String" ]
[ onexpand = "String" ]
[ onexpandex = "String" ]
[ onfocus = "String" ]
[ onkeydown = "String" ]
[ onkeypress = "String" ]
[ onkeyup = "String" ]
[ onmousedown = "String" ]
[ onmousemove = "String" ]
[ onmouseout = "String" ]
[ onmouseover = "String" ]
[ onmouseup = "String" ]
[ onuncheck = "String" ]
[ permission = "ACL" ]
[ property = "String" ]
[ sortable = "Boolean" ]
[ style = "String" ]
[ styleClass = "String" ]
[ styleId = "String" ]
[ target = "String" ]
[ targetProperty = "String" ]
[ title = "String" ]
[ tooltip = "String" ]
[ tooltipProperty = "String" ]
[ transaction = "Boolean" ]
[ width = "String" ]
>
...Body Content...

</ctrl:columntree>
 

[ Attribute ]

AttributTypBeschreibungPflichtRTExp
ajaxBoolean Aktiviert die AJAX Funktion der Spalte. Alle Ereignisse werden dann mit JavaScript asynchron an den Server gesendet und dort verarbeitet.

Die Verarbeitung auf dem Server unterscheidet sich nicht von einer normalen Request Behandlung. Der Anwendungsentwickler hat jedoch die Möglichkeit über die Methoden des AjaxRequest Interfaces (Basisklasse von ActionContext) die Ergebnis Rückmeldung zu steuern.

Im Normalfall (-> AjaxRequest.isAjaxCanceled() == false) wird ein Delta XML Stream zum Web Browser zurückgeschickt. Dieser Stream enthält nur die schmutzigen Kontrollelemente, welche dann mit Hilfe eines JavaScript Handlers vom Web Browser im HTML DOM Tree selektiv ausgetauscht werden. Es wird also keine vollständige HTML Seite vom Server übertragen!

  • (+) Die übertragene Datenmenge ist kleiner.
  • (+) Die HTML Seite bleibt im Browser stehen und es gibt kein "flackern".
  • (-) Der Request wird nicht in der Browser Historie vermerkt!
  • (-) Es wird JavaScript benötigt, sonst wird ein normaler Server roundtrip ausgelößt

Die meisten Kontrollelemente fügen sich selbst in die Dirty Liste des ActionContext ein. Hierzu wird einfach die Methode AjaxRequest.markDirty() aufgerufen. Der Anwendungsentwickler hat damit die Möglichkeit noch weitere Kontrollelemente - die durch eine Zustandsänderung ebenfalls schmutzig geworden sind - in den Delta Stream aufzunehmen

Wenn der Request eine vollständig neue HTML Seite zurückgeben soll, dann besteht auch die Möglichkeit die AJAX Verarbeitung auf dem Server abzubrechen. Hierzu wird die Methode AjaxRequest.cancelAjaxRequest() aufgerufen. Das Framework sendet danach immer eine vollständige HTML Seite zurück an den Web Browser.

Das Common-Controls AJAX XML Protokoll hat das folgende Format:


<?xml version="1.0" encoding="UTF-8" ?>
<ajax-response>
	<token/>
	<controls>
		<control styleId="" class="" name="">
			<html>
				<[CDATA[...]] >
			</html>
		</control>
	</controls>
</ajax-response>
 
alignAlignmentType Gibt die Ausrichtung der Spalte an.
  • left = linksbündige Ausrichtung
  • right = rechtsbündige Ausrichtung
  • center = zentrierte Ausrichtung
 
converterJava Klassenname oder Converter Id Gibt den Datentyp Konverter an mit welchem die Daten der Spalte konvertiert werden sollen. Wird dieses Attribut nicht angegeben, so verwendet das Framework einen Default Konverter passend zum Datentyp der Spalte (ConverterRegistry.lookup()).

Der Konverter kann auf die folgenden Arten angegeben werden:

  • Es wird die öffentliche Converter Id angegeben.
  • Es wird der voll qualifizierter Java Klassenname des Konverters angegeben. Dieser muss das Converter Interface implementieren

Anmerkung: Die angegebene Java Klasse muss das Converter Interface implementieren!

 
filterBoolean Mit dem filter-Attribut kann die automatische HTML-Codierung des Spalteninhaltes aktiviert bzw. deaktiviert werden.
  • true = Die HTML Konvertierung ist aktiv. So wird beispielsweise das "<" Zeichen als "&lt;" codiert. HTML Code wird damit nicht ausgeführt.
  • false = Die HTML Konvertierung ist abgeschaltet. HTML Code wird demzufolge direkt in die Seite eingesetzt und somit ausgeführt.
 
imagemapString Gibt den Namen einer ImageMap an, die im Request Scope abgelegt sein muss. Die Werte die das imageProperty liefert werden auf die Einträge dieser ImageMap abgebildet. Die Abbildung erfolgt anhand des regulären Ausdrucks der jedem Eintrag der ImageMap zugeordnet ist.

Das Framework hängt bei Gruppenknoten an den Wert des imageProperty implizit die Zeichenketten .open bzw. .closed an, um zwischen dem geöffneten und geschlossenen Zustand unterscheiden zu können.

Das Framework verwendet für Gruppenknoten per Voreinstellung ein Ordnersymbol als Image.

Anmerkung: Unter dem Namen muss eine ImageMap im Request Scope abgelegt sein.

 
imagePropertyString Gibt das Property an, über welches jeder Row-Bean ein Image zugeordnet werden kann.

Die Image Namen bezeichnen keine direkten HTML-Ressourcen, sie werden vielmehr anhand der ImageMap in den tatsächlichen Ressourcen Namen übersetzt.

Anmerkung: Gültiger Java Bezeichner für ein Property welches von jeder Row-Bean implementiert werden muss.

 
joinJoinMode Verbindet die Zellen der Spalte mit den Zellen der vorangehenden Spalte.

Zellen können nur innerhalb derselben Spaltengruppe verbunden werden!

  • none = Die Spalten werden nicht verbunden
  • false = Entspricht "none"
  • concatenate = Die Spalten werden ohne Zwischenraum zusammengefügt
  • true = Entspricht "concatenate"
  • separator = Die Spalten werden mit einem Zwischenraum zusammengefügt
 
maxlengthInteger Gibt die maximale Zeichenzahl für die Anzeige in Spaltenüberschriften und Zellen an. Weitere Zeichen werden durch "..." angedeutet.
Diese Funktionalität ist unwirksam, wenn das Attribut filter="false" gesetzt ist, da in diesem Fall die tatsächlich sichtbare Zeichenzahl nicht ermittelt werden kann. 		 
onblurString Fires when the object loses the input focus.

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

 
oncheckString Fires when a checkbox is checked

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

 
oncollapseString Fires when a tree node is collapsed

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

 
ondblclickString Fires when the user double-clicks the object.

Anmerkung: JavaScript Code

 
onexpandString Fires when a tree node is expanded

Anmerkung: JavaScript Code

 
onexpandexString Fires when a tree node with unknown child count is expanded

Anmerkung: JavaScript Code

 
onfocusString Fires when the object receives focus.

Anmerkung: JavaScript Code

 
onkeydownString Fires when the user presses a key.

Anmerkung: JavaScript Code

 
onkeypressString Fires when the user presses an alphanumeric key.

Anmerkung: JavaScript Code

 
onkeyupString Fires when the user releases a key.

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

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

Anmerkung: JavaScript Code

 
onuncheckString Fires when a checkbox is unchecked

Anmerkung: JavaScript Code

 
permissionACL Mit diesem Attribut kann der Zugriff auf das Element beschränkt werden.

Berechtigungen werden über das Principal Objekt in der Benutzer Session geprüft. Das Principal Objekt wird mit der Methode SecurityUtil.registerPrincipal() in der Session registriert. Es wird vom Anwendungsentwickler durch Implementierung des Principal Interfaces zur Verfügung gestellt. Somit lassen sich sehr einfach beliebige Berechtigungssysteme mit dem Framework verbinden.

Berechtigungen werden immer in Form einer Access Control List (ACL) angegeben. Dabei handelt es sich um einen Ausdruck dessen Elemente Einzelberechtigungen sind. Das Framweork unterstützt die folgenden Berechtigungstypen, welche jedoch vom Anwendungsentwickler beliebig erweitert werden können:

Literal
true|false -> StaticPermission
Rolle
#rollenname -> RoleBasedPermission
Funktion
$funktionsname -> FunctionBasedPermission

Zur Formulierung der Ausdrücke kann die folgende Syntax verwendet werden:

PERMISSION_PREFIX
	: '#' | '$'

AND_OP
	: 'and' | '&' | '*'

XOR_OP
	: 'xor' | '^'

OR_OP
	: 'or' | '|' | '+'

UNARY_OP
	: '~' | '!'

permission
	: PERMISSION_PREFIX IDENTIFIER

primary_expr
	: permission
	| '(' expr_list ')'

unary_expr
	: primary_expr
	| UNARY_OP primary_expr

logical_and_expr
	: unary_expr
	| logical_and_expr AND_OP unary_expr

logical_xor_expr
	: logical_and_expr
	| logical_or_expr XOR_OP logical_and_expr

logical_or_expr
	: logical_xor_expr
	| logical_or_expr OR_OP logical_xor_expr

expr_list
	: logical_or_expr
	| expr_list ';' logical_or_expr
	| expr_list ',' logical_or_expr

Access Control Listen werden mit der statischen Methode AccessControlList.parse() eingelesen. Der Parser verwendet wiederum die statische Methode PermissionFactory.parse() um die einzelnen Permissions zu lesen. Der Anwendungsentwickler kann über die PermissionFactory eigene von Permission abgeleitete Klassen registrieren und so den Sprachumfang der ACL erweitern.

 
propertyString Der Name des Properties welches die Daten der Spalte liefert.

Anmerkung: Gültiger Java Bezeichner. Die Zeilenobjekte müssen eine passende Property-Getter Methode implementieren.

 
sortableBoolean Das Attribut gibt an, ob nach dieser Spalte sortiert werden kann. Wird hier der Wert true angegeben, dann kann der Benutzer mit einem Mausklick auf den Spaltenkopf die Sortierung umschalten. Es wird in diesem Fall ein onSort Event ausgelösst.

In den folgenden Fällen kann das Framework das ListDataModel selbstständig sortieren:

  • Das ListDataModel ist von einer Java Collection Klasse abgeleitet
  • Das ListDataModel implementiert das Sortable Interface

In allen übrigen Fällen muss der Anwendungsentwickler eine eigene onSort() Methode zur Verfügung stellen.

 
styleString Über dieses Attribut kann direkt ein HTML-style Attribut für die Zellen der Spalte angegeben werden.

Anmerkung: Siehe HTML Dokumentation für das Attribut style.

 
styleClassString Über dieses Attribut kann direkt ein HTML-class Attribut für die Zellen der Spalte angegeben werden.

Anmerkung: Siehe HTML Dokumentation für das Attribut class.

 
styleIdString Über dieses Attribut kann direkt ein HTML-id Attribut für die Zellen der Spalte angegeben werden.

Anmerkung: Siehe HTML Dokumentation für das Attribut id.

 
targetString Über dieses Attribut kann direkt ein HTML-target Attribut für die Zellen der Spalte angegeben werden.

Anmerkung: Siehe HTML Dokumentation für das Attribut target.

 
targetPropertyString Gibt den Namen eines Properties an, welches als HTML-Target Attribut für die jeweilige Zelle verwendet wird.

Anmerkung: Gültiger Java Bezeichner. Die Zeilenobjekte müssen eine passende Property-Getter Methode implementieren.

 
titleString Gibt die Spaltenüberschrift an.

Die Zeichenkette wird vor der Ausgabe HTML-codiert.

 
tooltipString Gibt den Tooltip Text an

Anmerkung: lokalisierbare Zeichenkettenkonstante

 
tooltipPropertyString Gibt den Namen eines Properties an, mit dessen Hilfe die jeweilige Zelle mit einem HTML-Text Attribut versehen werden kann.

Anmerkung: Gültiger Java Bezeichner. Die Zeilenobjekte müssen eine passende Property-Getter Methode implementieren.

 
transactionBoolean Mit diesem Flag wird angegeben ob ein Transaction Token (siehe Struts Token Dokumentation) an alle Hyperlinks der Spalte angehängt werden soll.

Mit dem Transaction Token können Form Re-submissions (mehrfaches Absenden eines HTML Formulars) erkannt werden.

Funktionsweise: Das Transaction Token is ein "Stempel" mit welchem die Applikation jede generierte HTML Seite stempelt (es wird ein hidden Field bzw. zusätzliche URL Parameter für alle Hyperlinks erzeugt). Bei einem Server Request kann der vom Browser zurückgeliefert Stempel mit dem in der Session gespeicherten Wert verglichen werden. Wenn der Wert übereinstimmt, dann passt die Seite zum aktuellen Applikations Zustand.
Stimmt der Stempel nicht überein, dann sind Applikationszustand und Browser Inhalt asynchron und die Applikation kann auf diesen Fehler - wie auch immer - reagieren. Eine Abweichung entsteht immer dann, wenn der Anwender eine ältere Seite aus der Browser Historie absendet.

 
widthString Setzt die Breite der Spalte. Die Breite kann dabei absolut oder prozentual angegeben werden.

Siehe HTML-Dokumentation.

 

[ Beispiel ]

Erzeugt ein TreeList Control mit einer ImageMap und einer Tree Spalte.


<%@ 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="Region 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:treelist>

                  
© 2000 - 2007 by www.common-controls.com (erstellt mit Common Controls TLDFactory)