Die Common-Controls Tag Bibliothek

<forms:swapselect>

Das Tag erzeugt ein HTML Select Element mit zwei Fenstern zwichen denen der Anwender die Einträge hin und her schieben kann. Die Menge der verfügbaren Elemente wird mit Hilfe des <base:options>-Tag im Tag Body angegeben. Die DataBean des Kontrollelementes (das Datenmodell) liefert die Schlüssel der selektierten Elemente in einem Array.
Das Tag darf nur innerhalb eines com.cc.framework.taglib.forms.FormElementContainerTag verwendet werden. Beispiele hierfür sind <forms:form> und <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 = "Stringliste" ]
[ 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>
 

[ Attribute ]

AttributTypBeschreibungPflichtRTExp
accesskeyString Der Tastatur-Shortcut (darf nur ein Zeichen sein), mit dem der Browser den Fokus auf ein Eingabeelement übertragen kann.  
alignAlignmentType Gibt die horizontale Ausrichtung in der Formularelement Zelle an
  • left = linksbündige Ausrichtung
  • right = rechtsbündige Ausrichtung
  • center = zentrierte Ausrichtung
 
colspanInteger Gibt bei einem mehrspaltigen Formular die Anzahl der Spalten an, welche von dem Formularelement belegt werden sollen.  
descriptionString Der Beschreibungstext  
disabledBoolean Über dieses Attribut kann das Kontrollelement deaktiviert werden. Es nimmt dann keine Benutzereingaben entgegen und erzeugt keine Kontrollelement Ereignisse.  
filterBoolean Mit dem filter-Attribut kann die automatische HTML-Codierung des Formularelementes 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.
 
heightString Setzt die Höhe des Kontrollelmentes. Die Höhe kann absolut oder prozentual angegeben werden.

Es hängt vom jeweiligen Kontrollelement Painter ab, ob diese Information ausgewertet wird

Siehe HTML-Dokumentation

 
helpString Weist dem Kontrollelement einen Hilfe Bezeichner zu. Es wird ein Hilfe Symbol neben dem Kontrollelement angezeigt, welches bei einem Klick einen onHelp Event erzeugt. Der Bezeichner wird dabei als Parameter übergeben und kann somit zur Anzeige von kontextabhängigen Hilfetexten benutzt werden.

Das eigentliche Hilfesystem ist nicht Teil des Common-Controls Frameworkes, der onHelp Event kann jedoch zur Verankerung verwendet werden.

Für die Erzeugung des Hyperlinks zum Aufruf der Hilfe sind einige vordefinierte Framework Ressourcen zuständig. Diese kann der Anwendungsentwickler global oder auf Kontrollelement Ebene verändern:

Resource KeybeschreibungVorgabewert
fw.help.onclickEin optionaler onclick JavaScript Handler. Der Handler kann einen {0} Markup für den Hilfe Bezeichner enthalten-
fw.help.targetGibt an wo der Hilfe Hyperlink geöffnet werden soll_blank
fw.help.tooltiptooltip Text für den Hilfe Hyperlinkcontext help

Anmerkung: Der Hilfe Bezeichner wird von dem Common-Controls Framework an das Hilfesystem weitergegeben. Die Syntax und Semantik hängt daher von dem verwendeten Hilfesystem ab.

 
hideButtonsStringliste Mit diesem Attribut kann eine Liste von Schaltflächen ausgeblendet werden. Die auszublendenden Schaltflächen werden in einer Semikolon getrennten Liste angegeben.

Anmerkung: Mit Semikolon getrennte Liste von Schaltflächen Namen. Die Namen müssen dabei einer der ControlButton.getName() Konstanten entsprechen!

 
idString Weist dem Kontrollelement einen eindeutigen Bezeichner zu. Im Tag Body wird daraufhin eine Java Variable angelegt, auf welche in Java Scriptlets zugegriffen werden kann. Diese Variable verweist auf die Kontrollelement Instanz.

Dieses Attribut wird meist in Verbindung mit dem type Attribut verwendet

Anmerkung: Da zur JSP Compile Zeit eine Java Variable mit diesem Bezeichner angelegt wird, muss hier ein String Literal (und keine Expression!) angegeben werden! Der Bezeichner muss den Regeln für gültiger Java Bezeichner folgen.

 
imagerefString Verweis auf ein Element der ImageMap des Formulars. Das Image wird vor dem Label des Formularelementes gezeichnet.

Die ImageMap wird im umschliessenden Formular Tag mit Hilfe des imagemap Attributes gesetzt

 
joinBoolean Mit diesem Flag wird angegeben ob das Vormularelement mit dem vorhergehenden Element verbunden werden soll. Zwischen verbundenen Formularelementen werden keine Trennungslinien gezeichnet.  
labelString Das Label des Formularelementes.  
labelLeftString Gibt das label über dem linken (bzw. oberen) Teilfenster an.  
labelRightString Gibt das label über dem rechten (bzw. unteren) Teilfenster an.  
labeltooltipString Tooltip auf dem Label des Formularelementes.  
moveButtonBoolean Legt fest ob die Schaltflächen zum Verschieben von Zeilen angeboten werden sollen.  
multipleBoolean Mit diesem Attribut wird das SwapSelect Control angewiesen mehrere verschiebungsziele (= rechte Seite bei horizontaler Ausrichtung) zu verwenden.

Wird dieses Attribut auf true gesetzt, dann muss folgendes berücksichtigt werden:

  • Als Datenmodell muss nun eine Array von Arrays zurückgeliefert werden. Dabei gibt die Anzahl der Dimensionen in der ersten Array Ebene (= n) die Anzahl der darzustellenden Verschiebungsziele an
  • Im Attribut labelRight muss eine Semikolon getrennte String Liste mit den Überschriften für die n Verschiebungsziele angegeben werden. Je nach aktiver Lokalisierung können das Ressourcen Schlüssel oder einfache String Literale sein
  • Im Attribut size muss eine Semikolon getrennte String Liste mit den Größen der Optionslisten angegeben werden. Die Liste legt dabei die Größe der linken und rechten Optionslisten fest!
    Beispiel:
    size="28;8" (Links 28, Alle anderen Optionslisten auf der rechten Seite 8).
    size="28;8;8;8" (Links 28, Unterschiedliche Höhe für jede Optionslisten auf der rechten Seite).

 
nameString Gibt den Namen der Java-Bean an. Die Java-Bean muss im angegebenen Scope (siehe scope-Attribut) abgelegt sein.

Wenn das Tag von einem Struts <html:form> Tag umschlossen ist, dann muss kein Bean Name angegeben werden. In diesem Fall wird die Java-Bean über ein Property der Struts Formular Bean gezogen.

Anmerkung: Es muss ein gültiger Java Bezeichner angegeben werden.

 
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

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

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

 
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

 
orientationOrientationType Gibt die Ausrichtung der beiden Teilfenster an.
  • horizontal = Horizontale Ausrichtung (von links nach rechts)
  • vertical = Vertikale Ausrichtung (von oben nach unten)
 
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 Gibt den Namen des Properties an, welches die Daten für das Formularelement liefert.

Dies ist in der Regel nur dann notwendig, wenn die Java-Bean mit einer Struts Formular Bean assoziiert ist.

Anmerkung: Es muss ein gültiger Java Bezeichner angegeben werden.

 
requiredBoolean Gibt an, ob es sich bei dem Formularelement um eine Pflichtangabe handelt. Pflichtfelder werden für den Anwender visuell hervorgehoben dargestellt.  
retainOrderBoolean Mit diesem Attribut wird festgelegt ob die Reihenfolge der Items in den Auswahl Listen bei Links/Rechts Verschiebungen beibehalten werden soll.

Bei langen Optionslisten kann das Beibehalten der Reihenfolge zu Performance Problemen führen

 
runatRunAt Dieses Attribut gibt an, ob für das Kontrollelement JavaScript verwendet werden soll, oder ob das Kontrollelement ausschließlich mit Server Roundtrips arbeiten soll.
  • server = Alle Kontrollelement Aktionen führen zu einem Server Roundtrip und werden auf dem Server bearbeitet.
  • client = Kontrollelement Aktionen werden direkt im Browser des Benutzers durchgeführt. Es hängt von der verwendeten Painter Factory und dem konkreten Kontrollelement Painter ab, wie weit die Unterstützung für Clientside Scripting geht.
  • auto = Das Framework wählt basierend auf der JavaScript Aktivierung des Anwender Browsers den Modus "client" bei aktiviertem JavaScript und "server" bei deaktiviertem JavaScript (siehe BrowserInfo).
 
scopeHttpScope Dieses Attribut gibt den Scope an, in welchem die Java-Bean mit den eigentlichen Anzeigedaten zu finden ist.
  • any = Nach der Bean wird in jedem Scope gesucht.
  • page = Die Bean liegt im PageContext der JSP Seite.
  • request = Die Bean liegt im HTTP Servlet Request
  • session = Die Bean liegt in der HTTP Session
  • application = Die Bean liegt applikationsweit im Servlet Kontext
 
sizeInteger Gibt die Anzahl der sichtbaren Optionen an.  
sortOrderSortOrder Gibt die Sortierreihenfolge des Elementes an
  • none = Es soll keine Sortierung verwendet werden.
  • asc = Aufsteigende Sortierung
  • desc = Absteigende Sortierung
 
styleString Über dieses Attribut kann direkt ein HTML-style Attribut angegeben werden.

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

 
styleClassString Über dieses Attribut kann direkt ein HTML-class Attribut angegeben werden.

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

 
styleIdString Über dieses Attribut kann direkt ein HTML-id Attribut angegeben werden.

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

 
summaryString Gibt einen nicht sichtbaren Summary zu dem Kontrollelement auf der HTML Seite aus. Diese Information kann von speziellen Anzeigegeräten dargestellt werden - zum Beispiel als Sprachausgabe oder Braille Schrift.  
tabindexInteger Tabulator Index für dieses Element.  
tooltipString Ein Kurzer Hinweistext, welcher angezeigt wird, wenn der Anwender den Mauszeiger über das Element bewegt.  
transactionBoolean Mit diesem Flag wird angegeben ob ein Transaction Token (siehe Struts Token Dokumentation) an alle Hyperlinks des Kontrollelementes 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.

 
valignAlignmentType Gibt die vertikale Ausrichtung in der Formularelement Zelle an
  • top = Ausrichtung oben
  • bottom = Ausrichtung unten
  • center = Ausrichtung zentriert
 
valueString Der Wert des Kontrollelementes kann mit diesem Attribut auch direkt als Litteral angegeben werden.  
widthString Setzt die Breite des Kontrollelmentes. Die Breite kann absolut oder prozentual angegeben werden.

Siehe HTML-Dokumentation

 

[ Beispiel ]

Formularelement mit 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 (erstellt mit Common Controls TLDFactory)