OS.bee documentation - User contributions [en]

Statemachine DSL

2018-05-03T16:30:09Z

Wu: /* Statemachine DSL */

== Introduction ==

=== State Machine ===

'''State Machine''' or '''extended finite-state machine (EFSM)''' is a mathematical model of computation and represents an abstract machine that can be in exactly one of a finite number of states at any given time. The State Machine can change from one ''state'' to another in response to external ''events''. The change from one state to another is called a ''transition''. A EFSM is defined by a list of its states, its ''initial state'', and the conditions for each transition. The condition for a transition is called ''guard''. There can be many guards protecting a transition to be triggered. Every guard is joined with a logical AND operation, so every guard must evaluate to true, to trigger a protected transition. Data operations can occur before a transition. They are called ''actions''. Actions prepare the indicated state of the transition, calculate things or display information.
The StatemachineDSL described in the following implements an EFSM where the FSM-block is represented by ''states'', the A-block is called ''actions'' and the E-block is called ''guards''.

=== Further reading ===

https://en.wikipedia.org/wiki/Finite-state_machine

https://en.wikipedia.org/wiki/Extended_finite-state_machine

https://en.wikipedia.org/wiki/UML_state_machine

== Statemachine DSL ==
Statemachine DSL implements the state pattern (https://en.wikipedia.org/wiki/State_pattern) and interconnects UI model, FunctionLibrary, DTO and peripheral services like JavaPOS, ZVT protocol and others.

The main semantic elements of the StatemachineDSL are:
*'''package''' - The root element that contains all the other elements. A model can contain multiple packages.
*'''import''' declarations - Used to import external models or other Java classes.
*'''statemachine''' - The container for the implementation of the EFSM following the state pattern.
*'''events''' - Contains all user defined events.
*'''event''' - Defines a single event by id. Events build the interconnection elements between controls and transitions.
*'''controls''' - The container for all type of beans (https://en.wikipedia.org/wiki/JavaBeans) to be controlled by the state machine.
*'''scheduler''' - A type of bean that can be triggered to emit a defined event after a defined delay.
*'''keypad''' - A type of bean that builds a keypad containing one or more buttons to emit a defined event when pressed.
*'''fields''' - A type of bean that holds data of input fields or labels from UI.
*'''dataProvider''' - A type of bean that retrieves and stores data based on DTO.
*'''peripheral''' - A type of bean that controls input/output operations with peripheral units. Peripheral units can be printers, displays or other external devices following the JavaPOS standard (http://www.javapos.com/). Peripheral units can also emit events representing its current state or error.
*'''attribute''' - Defines different types for usage with control.
*'''states''' - The container for all state definitions of this state machine.
*'''state''' - A single state the machine can be at a point in time.
*'''triggers''' - The container for all possible event processing blocks inside a state.
*'''trigger''' - The action block following this trigger will be executed when one of its events occur.
*'''actions''' - The container for all process instructions to be done in sequence inside this block. Optionally an action block can follow a transition.
*'''transition''' - The transition will be executed when all actions of this block were processed successfully.
*'''guards''' - The container for guards protecting the following transistion.
*'''guard''' - A condition that must evaluate to true that the following transistion will be processed.

==== Syntax ====

===== package definition =====

► '''Syntax''':
<syntaxhighlight lang="java">
package <package name> [{
statemachine <statemachine name> [describedBy <description string>]
[functiongroup <function:FunctionLibraryStatemachineGroup>]
initialState <StatemachineState>
initialEvent <StatemachineEvent>
events {
event <event name>
. . .
}
controls {
StatemachineControl
. . .
}
states {
StatemachineState
. . .
}
. . .
}]
</syntaxhighlight>

► '''example''':
<syntaxhighlight lang="java">
package net.osbee.sample.foodmart.statemachines {
statemachine CashTerminal describedBy "Cash Register"
functiongroup CashRegister
initialState IDLE
initialEvent onStartUp
events {
event onStartUp
. . .
}
controls {
scheduler Schedulers {. . .}
. . .
}
states {
state IDLE { . . .}
. . .
}
}

</syntaxhighlight>

===== important definition =====

====== StatemachineActionFieldConcatenation ======
► '''Syntax''':
<syntaxhighlight lang="java">
<STRING> [+ <STRING> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
<SignedNumber> [+ <SignedNumber> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
<INTEGER> [+ <INTEGER> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
<BOOLEAN> [+ <BOOLEAN> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
StatemachineEvaluationType [+ StatemachineEvaluationType . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
translate <STRING> [+ translate <STRING> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
get <StatemachineControlFieldAttribute> [+ get <StatemachineControlFieldAttribute> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation[,StatemachineActionFieldConcatenation. . . ]) [+ operation <function:FunctionLibraryOperation>. . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
retrieve from <key ID>.<attribute ID> [+ retrieve from <key ID>.<attribute ID> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute> [+ dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute> . . .]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
function <function:FunctionLibraryFunction> (StatemachineActionFieldConcatenation[,StatemachineActionFieldConcatenation . . . ])
</syntaxhighlight>
or
<syntaxhighlight lang="java">
event
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentResponse from <StatemachinePeripheralDevicePT>
</syntaxhighlight>

*StatemachineEvaluationType is including: getIPAddress |getHostName | getNow | getUserAgentInfo | isTouchDevice | isHttps | getBrowserLocale | getUserName| getUserPassword | getUserEmail | getUserPosition | getUserPrintService | getSceenWidth | getScreenHeight | getTrigger .

► '''example''':
<syntaxhighlight lang="java">
operation dopayment(retrieve from paymentMethod.last)
</syntaxhighlight>

====== StatemachineActionFieldSource ======
► '''Syntax''':
<syntaxhighlight lang="java">
<STRING>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
<SignedNumber>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
<INTEGER>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
<BOOLEAN>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
StatemachineEvaluationType
</syntaxhighlight>
or
<syntaxhighlight lang="java">
translate <STRING>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
get <StatemachineControlFieldAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
function <function:FunctionLibraryFunction> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation. . . ])
</syntaxhighlight>
or
<syntaxhighlight lang="java">
retrieve from <key ID>.<attribute ID>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
event
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentResponse from <StatemachinePeripheralDevicePT>
</syntaxhighlight>

* StatemachineEvaluationType is including: getIPAddress | getHostName | getNow | getUserAgentInfo | isTouchDevice | isHttps | getBrowserLocale | getUserName| getUserPassword | getUserEmail | getUserPosition | getUserPrintService | getSceenWidth | getScreenHeight | getTrigger.

► '''example''':
<syntaxhighlight lang="java">
function getPaymentTotal()
</syntaxhighlight>

====== StatemachineFilter ======
► '''Syntax''':
<syntaxhighlight lang="java">
and ( [StatemachineFilter] , StatemachineFilter. . . )
</syntaxhighlight>
or
<syntaxhighlight lang="java">
or ( [StatemachineFilter] , StatemachineFilter. . . )
</syntaxhighlight>
or
<syntaxhighlight lang="java">
StatemachineCompareOperationEnum (dto <StatemachineControlDTOAttribute>.< dto:LDtoInheritedAttribute>, StatemachineActionFieldSource)
</syntaxhighlight>
or
<syntaxhighlight lang="java">
isBetween(dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>, start StatemachineActionFieldSource, end StatemachineActionFieldSource)
</syntaxhighlight>
or
<syntaxhighlight lang="java">
isNull (dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>)
</syntaxhighlight>
or
<syntaxhighlight lang="java">
isLike (dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>, StatemachineActionFieldSource [ignoreCase])
</syntaxhighlight>
or
<syntaxhighlight lang="java">
not ( StatemachineFilter )
</syntaxhighlight>
or
<syntaxhighlight lang="java">
matches (dto <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>, <filterString> [ignoreCase] [onlyMatchPrefix])
</syntaxhighlight>

* StatemachineCompareOperationEnum is including: equal | greater | less | greaterOrEqual | lessOrEqual.

► '''example''':
<syntaxhighlight lang="java">
keystroke @paymentGiven and operation givenChanged()
</syntaxhighlight>

====== StatemachineAction ======
► '''Syntax''':
<syntaxhighlight lang="java">
blinkRate <rate INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
clearDevice <StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
createWindow row <viewportRow INT> column <viewportColumn INT> height <viewportHeight INT> width <viewportWidth INT> windowHeight <windowHeight INT> windowWidth <windowWidth INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
cursorType StatemachineLineDisplayCursorType @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
destroyWindow <StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
deviceBrightness <brightness INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
displayBitmap id <bitmapId INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
displayText text StatemachineActionFieldConcatenation [type StatemachineLineDisplayTextType] @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
displayTextAt text StatemachineActionFieldConcatenation row <row INT> column <column INT> [type StatemachineLineDisplayTextType] @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
interCharacterWait <wait INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
marqueeFormat StatemachineLineDisplayMarqueeFormat @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
marqueeRepeatWait <wait INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
marqueeType StatemachineLineDisplayMarqueeType @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
marqueeUnitWait <wait INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
scroll StatemachineLineDisplayScrollTextType <units INT> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
openDrawe <StatemachinePeripheralDeviceCashDrawer>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
printBarcode data <data STRING> barcodeType StatemachinePOSPrinterBarcodeType @<StatemachinePeripheralDevicePOSPrinter>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
printBitmap id <bitmapId INT> @<StatemachinePeripheralDevicePOSPrinter>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
printCut text StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePOSPrinter>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
printNormal text StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePOSPrinter>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
printerBitmap id <bitmapId INT> name <name STRING> @<StatemachinePeripheralDevicePOSPrinter>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
displayBitmap id <bitmapId INT> name <name STRING> @<StatemachinePeripheralDeviceLineDisplay>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentOpen host StatemachineActionFieldConcatenation port StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePT>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentClose @<StatemachinePeripheralDevicePT>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentAcknowledge @<StatemachinePeripheralDevicePT>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentReversal withPassword StatemachineActionFieldConcatenation ofReceipt StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePT>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentRegistration withPassword StatemachineActionFieldConcatenation configuration <configuration STRING> @<StatemachinePeripheralDevicePT>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
paymentAuthorization ofAmount StatemachineActionFieldConcatenation @<StatemachinePeripheralDevicePT>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
printReport <report:Report> [from <StatemachineStorage>]
</syntaxhighlight>
or
<syntaxhighlight lang="java">
set StatemachineActionFieldConcatenation @<StatemachineControlFieldAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
remove <StatemachineControlFieldAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
visible <StatemachineControlVisibility>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
invisible <StatemachineControlVisibility>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
clear <StatemachineControlFieldAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
caption StatemachineActionFieldConcatenation @<StatemachineControlButtonAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
image <image STRING> @<StatemachineControlButtonAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
search StatemachineActionFieldConcatenation in <StatemachineControlDTOAttribute>.<dto:LDtoInheritedAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
store StatemachineActionFieldConcatenation with <key ID>.<Attribute ID>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
schedule <StatemachineControlSchedulerAttribute>
</syntaxhighlight>
or
<syntaxhighlight lang="java">
operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation . . . ])
</syntaxhighlight>
or
<syntaxhighlight lang="java">
transition <StatemachineState> guard <function:FunctionLibraryGuard> [onFail caption <onFailCaption STRING> description <onFailDescription STRING> type StatemachineUserMessageType]{ StatemachineAction. . .}
</syntaxhighlight>

* StatemachineLineDisplayCursorType is including: none | fixed | block | halfblock | underline | reverse | other | blink.
* StatemachineLineDisplayTextType is including: normal | blink | reverse | blinkreverse.
* StatemachineLineDisplayMarqueeFormat is including: walk | place.
* StatemachineLineDisplayMarqueeType is including: none | up | down | left | right | init.
* StatemachineLineDisplayScrollTextType is including: up | down | left | right.
* StatemachinePOSPrinterBarcodeType is including: upca | upcb | jan8 | ean8 | jan13 | ean13 | tf | itf | codeabar | code39 | code93 | code128 | upca_s | upce_s | upcd1 | upcd2 | upcd3 | upcd4 | upcd5 | ean8_s | ean13_s | ean128 | orca | ocrb | code128_parsed | gs1databar | gs1databar_e | gs1databar_s | gs1databar_e_s | pdf417 | maxicode | datamatrix | qrcode | uqrcode | aztec | updf417.
* StatemachineUserMessageType is including: humanized | warning | error | tray | assistive .

► '''example''':
<syntaxhighlight lang="java">
clearDevice LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
createWindow row 0 column 0 height 1 width 20 windowHeight 1 windowWidth 87 @LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
marqueeFormat walk @LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
marqueeType init @LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
marqueeRepeatWait 800 @LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
marqueeUnitWait 100 @LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
displayText text "OS.bee is the only software that adapts to your business rules, rather than vice versa." @LineDisplay
</syntaxhighlight>

<syntaxhighlight lang="java">
invisible login
</syntaxhighlight>

<syntaxhighlight lang="java">
visible numbers
</syntaxhighlight>

<syntaxhighlight lang="java">
clear passwordEntry
</syntaxhighlight>

<syntaxhighlight lang="java">
set 0.0 @paymentGiven
</syntaxhighlight>

<syntaxhighlight lang="java">
operation loadPLU(1.0,6.0)
</syntaxhighlight>

<syntaxhighlight lang="java">
paymentOpen host dto cashregister.payment_ip port dto cashregister.payment_port @VeriFone
</syntaxhighlight>

===== events =====

► '''Syntax''':
<syntaxhighlight lang="java">
events {
event <event name>
. . .
}
</syntaxhighlight>

*events - Contains all user defined events.
*event - Defines a single event by id. Events build the interconnection elements between controls and transitions.

► '''example''':
<syntaxhighlight lang="java">
events {
event onStartUp
. . .
}
</syntaxhighlight>

===== controls =====

► '''Syntax''':
<syntaxhighlight lang="java">
controls {
StatemachineControl
. . .
}
</syntaxhighlight>

<syntaxhighlight lang="java">
keypad <name ID> event StatemachineControlButtonEventType {
button <name ID> [image <image STRING>] key <keystroke STRING>|id <identity INT>|event <StatemachineEvent>
. . .
}
</syntaxhighlight>
or
<syntaxhighlight lang="java">
fields <name ID> {
field <name ID> type StatemachineFieldType
. . .
&
layout <name ID>
. . .
}
</syntaxhighlight>
or
<syntaxhighlight lang="java">
dataProvider <name ID> {
dto <name ID> type <dto:LDto> [event <StatemachineEvent>]
. . .
&
filter <name ID> StatemachineFilter
. . .
}
</syntaxhighlight>
or
<syntaxhighlight lang="java">
scheduler <name ID> {
scheduler <name ID> delay <delay INT> send <StatemachineEvent>
. . .
}
</syntaxhighlight>
or
<syntaxhighlight lang="java">
peripheral <name ID> {
lineDisplay <name ID>
. . .
posPrinter <name ID>
. . .
cashDrawer <name ID>
. . .
payment <name ID>
. . .
}
</syntaxhighlight>

*'''controls''' - The container for all type of beans (https://en.wikipedia.org/wiki/JavaBeans) to be controlled by the state machine.
*'''scheduler''' - A type of bean that can be triggered to emit a defined event after a defined delay.
*'''keypad''' - A type of bean that builds a keypad containing one or more buttons to emit a defined event when pressed.
*'''fields''' - A type of bean that holds data of input fields or labels from UI.
*'''dataProvider''' - A type of bean that retrieves and stores data based on DTO.
*'''peripheral''' - A type of bean that controls input/output operations with peripheral units. Peripheral units can be printers, displays or other external devices following the JavaPOS standard (http://www.javapos.com/). Peripheral units can also emit events representing its current state or error. The supported peripherals are listed [[OS.bee_peripherals_for_JavaPOS|here]].
* '''StatemachineControlButtonEventType''' is including: keyboard | trigger | identity.
* '''StatemachineFieldType''' is including: Boolean | Integer| Long | Double | String | Date | SuggestText.

► '''example''':

<syntaxhighlight lang="java">
keypad NumericPad event keyboard {
button zero key "0"
button one key "1"
button two key "2"
button three key "3"
button four key "4"
button five key "5"
button six key "6"
button seven key "7"
button eight key "8"
button nine key "9"
button dzero key "00"
button dot key "."
}
</syntaxhighlight>

<syntaxhighlight lang="java">
fields UiControl {
layout numbers
layout login
layout paymentFields
layout entry
layout functions
layout plu
layout money
layout method
layout receipt
field passwordEntry type String
field sku type SuggestText
field paymentTotal type Double
field paymentGiven type String
field paymentChange type Double
field paymentPayed type Double
field qty type Double
field totalAmount type Double
field amount type Double
field price type Double
field productName type String
field paymentTerminal type String
field filterToggleStyle type String
field blurEvent type EmbeddableEvent
field focusEvent type EmbeddableEvent
field contextEvent type EmbeddableEvent
}
</syntaxhighlight>

<syntaxhighlight lang="java">
dataProvider DataControl {
dto product type MproductDto
dto cashregister type CashRegisterDto
dto cashslip type CashSlipDto
dto cashpayment type CashPaymentDto event onPaymentSelection
dto cashposition type CashPositionDto event onPositionSelection
dto cashpaymentmethod type CashPaymentMethodDto
filter positionFilter equal(path cashposition.product.low_fat, true)
}
</syntaxhighlight>

<syntaxhighlight lang="java">
scheduler Schedulers {
scheduler toAutoLogout delay 10000 send onLogout
scheduler toStart delay 100 send onStartUp
scheduler toDisplayTest1 delay 10000 send onDisplayTest1
scheduler toDisplayTest2 delay 6000 send onDisplayTest2
scheduler toDisplayTest3 delay 4000 send onDisplayTest3
scheduler toDisplayTest4 delay 3000 send onDisplayTest4
scheduler toDisplayTest5 delay 4000 send onDisplayTest5
scheduler toDisplayTest6 delay 1000 send onDisplayTest6
scheduler toDisplayTest7 delay 1000 send onDisplayTest7
scheduler toDisplayTestFinish delay 2000 send onDisplayTestFinish
scheduler toDisplayIdle delay 100 send onDisplayIdle
scheduler toPaymentTerminalRecovery delay 1000 send onPaymentTerminalRecovery
}
</syntaxhighlight>

<syntaxhighlight lang="java">
peripheral PeripheralControl {
lineDisplay LineDisplay
posPrinter POSPrinter
cashDrawer CashDrawer
payment VeriFone
}
</syntaxhighlight>

===== states =====

► '''Syntax''':
<syntaxhighlight lang="java">
states {
StatemachineState
. . .
}
</syntaxhighlight>

<syntaxhighlight lang="java">
state <state name>{
[triggers {
trigger (<StatemachineEvent>. . .)
[guards {
guard <function:FunctionLibraryGuard> [onFail caption <onFailCaption STRING> description <onFailDescription STRING> type StatemachineUserMessageType]
. . .
}]
actions [transition <StatemachineState>] {
StatemachineAction
. . .
}
. . .
}]
& [identity operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation . . . ])]
& [keystroke @<StatemachineControlFieldAttribute> [and operation <function:FunctionLibraryOperation> (StatemachineActionFieldConcatenation [,StatemachineActionFieldConcatenation . . . ]]]
}
</syntaxhighlight>

*'''states''' - The container for all state definitions of this state machine.
*'''state''' - A single state the machine can be at a point in time.
*'''triggers''' - The container for all possible event processing blocks inside a state.
*'''trigger''' - The action block following this trigger will be executed when one of its events occur.
*'''actions''' - The container for all process instructions to be done in sequence inside this block. Optionally an action block can follow a transition.
*'''transistion''' - The transition will be executed when all actions of this block were processed successfully.
*'''guards''' - The container for guards protecting the following transistion.
*'''guard''' - A condition that must evaluate to true that the following transistion will be processed.
* StatemachineUserMessageType is including: humanized |warning |error |tray |assistive.

► '''example''':
<syntaxhighlight lang="java">
state IDLE {
triggers {
trigger onStartUp
actions transition LOCKED{
clearDevice LineDisplay
displayText text translate "locked" @LineDisplay
invisible entry
invisible receipt
invisible FunctionPad
invisible PaymentPad
invisible PluPad
invisible sku
invisible plu
invisible method
invisible paymentFields
invisible filterToggle
visible login
visible NumericPad
visible numbers
visible functions
visible erase
visible delete
visible ok
printerBitmap id 1 name "OSbee" @POSPrinter
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="java">
state MODIFY_PAYMENT {
triggers {
trigger onCancel
actions transition PAYMENT{
transition PAYMENTTERMINAL_REVERSAL guard canCancelPaymentTerminal {
visible paymentTerminal
invisible money
invisible method
invisible functions
store event with paymentMethod.last
paymentReversal withPassword
dto cashregister.payment_password
ofReceipt function getSelectedPaymentReceipt() @VeriFone
}
operation cancelPayment()
invisible cancelit
visible numbers
visible erase
visible delete
visible money
visible method
operation computePayed()
operation givenChanged()
clearDevice LineDisplay
displayTextAt text translate "total" row 0 column 0 @LineDisplay
displayTextAt text translate "remain" row 0 column 10 @LineDisplay
displayTextAt text function getPaymentTotal() row 1 column 0 @LineDisplay
displayTextAt text function getPaymentRemain() row 1 column 10 @LineDisplay
}
trigger onBack
actions transition PAYMENT{
visible numbers
invisible cancelit
visible erase
visible delete
visible money
visible method
}
trigger onPaymentSelection
guards {
guard hasNoPaymentSelection
}
actions transition PAYMENT {
visible numbers
invisible cancelit
visible erase
visible delete
visible money
visible method
}
trigger onLogout
actions transition IDLE{
schedule toStart
}
}
}
</syntaxhighlight>

<syntaxhighlight lang="java">
state PAYMENTTERMINAL_FAILURE {
triggers {
trigger onPaymentTerm
actions transition PAYMENT {
invisible paymentTerminal
visible money
visible method
visible functions
operation givenChanged()
}
}
}
</syntaxhighlight>

== Copyright Notice ==
{{Copyright Notice}}

Datainterchange DSL

2018-02-12T12:30:25Z

Wu:

==Purpose==

The Data Interchange DSL (datainterchange for short) is made for defining data exchange models that can be used to import data from various formats (CSV, XML, EDI, etc.), map the data to entities, store them into database, or export them back into other formats.

You only need to define the ''relationship'' between the file and the bean, not the import / export process themselves. Once defined, these models can be used in e.g. action DSL to define actions which, when triggered, execute the actual import / export process, which are generated automatically by the OSBP based on the model.

==Overview==

As shown on the figure below, the [DSL Inferrer] will generate various views and In/Export component according to model described by datainterchange DSL (and action DSL, in the case of ActionButtons). The action buttons, when clicked, will trigger their corresponding In/Export processes by putting [http://download.osbee.org/downloads/javadoc/osbee-master-clean/org.eclipse.osbp.xtext.datainterchange.feature/apidocs/ WorkerThread (Runnable)] jobs into the executor job pool within the TriggerView (prefixed with datainterchang name), buttons (and toolbar / menus containing them) are further included in the perspective.

[[File:Datainterchange.png|600px|center|frame|''Figure 1: - Data Interchange Structure.'']]

==Data Interchange Model File==

Datainterchange DSL model files end with the <code>.data</code> extension. Data Interchange models may be split into several <code>.data</code> files, as long as they have the same package declaration.

In the following we will dive deeper into the description and the usage of Datainterchange related and reserved keywords.

===import===
In the import section are all entities to be found - as full qualified names – that are currently used in the DSL.

► '''Example''':
<syntaxhighlight lang="java">

import ns net.osbee.sample.foodmart.entities.Mstore
import ns net.osbee.sample.foodmart.entities.Mwarehouse
import ns net.osbee.sample.foodmart.entities.Mregion

</syntaxhighlight>

Note that <code>ns</code> is a mandatory keyword (stands for "namespace") that comes after import for distinguishing the OS.bee internal namespaces and Java library namespaces. Wildcards are not supported, all names should be imported separately. Note that the import section will be imported/added automatically if they are used in the package, so you don't have to manually manage this section.

===package===

Datainterchange DSL model files must start with a package declaration. Packages are the root element of the DSL and should be defined as <code><ApplicationName>.datainterchange</code>.

► '''Example''':
<syntaxhighlight lang="java">package net.osbee.sample.foodmart.datainterchanges { }</syntaxhighlight>

Data Interchange models may be split into several .data files, as long as they have the same package declaration, the interchanges will be available under this package name.

===title===
With the keyword title you can give a name to the corresponding TriggerView dialog inside your application. For example, the definition of the same datainterchanges package from above with title "Data Interchange Example":

► '''Example''':
<syntaxhighlight lang="java">package net.osbee.sample.foodmart.datainterchanges title "Data Interchange Example" {}</syntaxhighlight>

This title will be translated based on locale.

You can get more details about the TriggerView in the section below.

===interchange===
The <code>interchange</code> keyword defines interchange units for entities in the package, it should be in the form of:

► '''Example''':
<syntaxhighlight lang="java">
interchange <InterchangeUnitName> [describedBy <description>] <EntityManagerMode> file <FileType> [<FileDetails>] beans {
...
}
</syntaxhighlight>

Where <code>InterchangeUnitName</code> being the name of the interchange unit; <code>describedBy</code> (optional) can be used to provide a short description string. <code>EntityManagerMode</code> being how the file should be handled (see section "persist, merge, remove" below), and after <code>file</code> keyword, you should specify the type of the source / target data file you would like to import from or export to, then the file path, and other details depends on the type.

The following example specifies an interchange that reads a CSV file under the specified path (note the forward slash as the path separator), delimited by semicolon, skip one line (the header), and treat the content as encoded in UTF-8:

► '''Example''':
<syntaxhighlight lang="java">

interchange CurrencyNames persist file
CSV "C:/data/ISOCurrencyCode20170101.csv" delimiter ";" skipLines 1 encoding "UTF-8"
beans {
...
}
</syntaxhighlight>

The <code>beans</code> keyword comes after all the file specification and starts a block of entity definitions, which will be covered in section "entity".

===describedBy===
With this keyword you can the optional description of an interchange unit as shown below.

► '''Example''':
<syntaxhighlight lang="java">
interchange Currencies describedBy "european central bank currency exchange rates based on euro" persist ... { ... }
</syntaxhighlight>

===vectorName===
With the optional keyword <code>vectorName</code> followed by a string value you are able to define the name of the root element of both XML configuration files needed by Smooks. Please note that it also means that the first (root-)element of an XML-File you would have exported (file filled with real data) via the application will have the same name.

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file ... { ... }
</syntaxhighlight>

You can view the result of this sample of code like shown below on figure[[#Figure3|''3'']].

===persist, merge, remove===
These keywords define the purpose of the datainterchange unit and has a similar meaning as in the JPA's EntityManager class. Basically, <code>persist</code> will insert the data records into database, <code>merge</code> will update existing data record, or insert new one if necessary, <code>remove</code> will remove the record if it could be found in database.

► '''Example 1''': (persist)
<syntaxhighlight lang="java">
interchange EDIOrders describedBy "Orders" persist file
XML "C:/data/orders.xml"
beans {
...
}
</syntaxhighlight>

► '''Example 2''': (merge)
<syntaxhighlight lang="java">
interchange Stores merge file
XML "C:/data/stores.xml"
beans {
...
}
</syntaxhighlight>

► '''Example 3''': (remove)
<syntaxhighlight lang="java">
interchange Storesremove remove file
XML "C:/data/stores_remove.xml"
beans {
...
}
</syntaxhighlight>

===file===
With the keyword file you are able to set the file format of the files you intent to process with you interchange unit.

► '''Syntax''':
<syntaxhighlight lang="java">interchange <SampleInterchangeUnitName> <EntityManagerMode> file <FileNameFormat> {}</syntaxhighlight>

The current supported file formats are CSV, EDI and XML followed by the name of the file you want to process, given its full path location in the system.
► '''Example 1''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit1 merge file CSV "C:/temp/testFile.csv" {}</syntaxhighlight>
► '''Example 2''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit2 persist file XML "C:/temp/testFile.xml" {}</syntaxhighlight>
► '''Example 3''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit3 merge file EDI "C:/temp/testFile.edi" {}</syntaxhighlight>

After choosing the file format you can either give the file name as a String value in a double quote "..." as shown here above, or press Ctrl+Space to get via the content assist the option of opening a File Chooser/Picker to specify the file you want to work with.

[[File:FileChooser.jpg|center|frame|''Figure 2: File Chooser'']]

Please note that you can also change the path(?) of the file to process on runtime by selecting a new file.

===mapByAttribute===

The <code>mapByAttribute</code> keyword is an XML-specific keyword that turns on the automatic attribute mapping. When enabled, datainterchange will detect if the value being mapped is from an attribute. For example, the 'USD' value in the following XML file comes from the attribute 'currency' of the element 'Cube':

► '''Example''':
<syntaxhighlight lang="xml">
<Cube currency='USD' rate='1.3759'/>
</syntaxhighlight>

while in the following XML file, the same value is encapsulated in the element 'currency':

► '''Example''':
<syntaxhighlight lang="xml">

<Cube>
<currency>USD</currency>
<rate>1.3759</rate>
</Cube>
</syntaxhighlight>

When <code>mapByAttribute</code> is present, datainterchange will automatically decide that a query in the form like <code>'/Cube/currency'</code> will also catch the value from attribute. Without it, the query will have to put a <code>'@'</code> symbol in front of the attribute name, i.e. <code>'/Cube/@currency'</code>.

===elementSize===
With the keyword <code>elementSize</code> followed by an integer, the user can set the estimated average size of the elements in bytes. Since the underlying API cannot know the size of an element before it is processed, this value can be supplied as a guide value to be used for estimating the import / output progress based on how much bytes have been processed.

► '''Example''':
<syntaxhighlight lang="java">
interchange EDIOrders describedBy "edi orders" persist elementSize 50 file EDI "C:/data/orders.edi" beans {
...
}
</syntaxhighlight>

Defines an average estimated element size of 50 bytes.

===delimiter===

The <code>delimiter</code> is a CSV format-specific keyword, which defines the character to use in the CSV file to set the delimiter/separation character between different values. Default value is "," (comma).

► '''Example''':
<syntaxhighlight lang="java">
interchange CurrencyNames persist file
CSV "C:/data/ISOCurrencyCodes081507.csv" delimiter ";" ... {
...
}
</syntaxhighlight>

will set the delimiter of the CSV file to ";".

===skipLines===
This is a CSV format-specific keyword. Using <code>skipLines</code> followed by an integer, the user can specify the number of lines to be skipped from the beginning in the processing of the selected file, this can be used to skip headers.

► '''Example''':
<syntaxhighlight lang="java">
interchange CurrencyNames persist file CSV "C:/data/ISOCurrencyCodes081507.csv" ... skipLines 1 encoding "UTF-8" {
...
}
</syntaxhighlight>

will skip the first line of the CSV file.

===report===

If a '''datainterchange''' unit is defined with the <code>report</code> keyword, a report will be generated for data conversions. The report file is generated by Smooks, lies under <code>/smooks</code> output directory of the datainterchange bundle, and has a name in the form like <code><DataInterChangeName>-input.xml</code> for input processes, and <code><DataInterChangeName>-output.xml</code> for output processes. '''Note: turn on report will have an impact performance.'''

===indent===

The <code>indent</code> is a CSV-format specified keyword which adds indentation character data to the generated event stream. This simply makes the generated event stream easier to read in its serialized form and generally should only be used in testing.

===quoteCharacter===

The <code>quoteCharacter</code> is a CSV format-specific keyword, which defines the character to use in the CSV file to identify values.

===encoding===
With the keyword '''enconding''' followed by the encoding name as a string value you are able to specify the valid encoding of the file content.

► '''Example 1''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName merge elementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "UTF-8"{}</syntaxhighlight>
► '''Example 2''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName remove elementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "GB18030"{}</syntaxhighlight>
► '''Example 3''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName persistelementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "ISO-2022-JP"{}</syntaxhighlight>

===mappingModel===

The <code>mappingModel</code> keyword is an EDI-specific keyword which can be used to specify an EDI to XML mapping model in XML format for Smooks.

===validate===

The <code>validate</code> keyword is an EDI-specific keyword that...

===beans===

The keyword <code>beans</code> starts the series of entities. The name "bean" comes from the internal entities called JavaBean, which act as data containers.

===entity===

With the <code>entity</code> keyword followed by a fully qualified name, the user can specify the mapping between a source data file and a data-containing entity. The behavior of the mapping can be further fine-tuned with the keywords discussed below. While these keywords can theoretically be combined all together and create very complicated behavior, they are normally used in a simple and straight forward way.

The general form of <code>entity</code> keywords is:

► '''Syntax''':
<syntaxhighlight>
entity <ID>
[nodeName <node-name>]
[createOn <element-map>]
[marker <property-name>]
[expression '{' <expressions> '}']
[lookup '{' <lookup-rules> '}']
[format '{' <formats> '}']
[mapping '{' <mappings> '}']
[keys '{' <lookup-keys> '}']
;
</syntaxhighlight>

The order of the keywords is fixed, i.e. they are all optional, but must appear in the given order.

====nodeName====

With the optional keyword <code>nodeName</code> followed by a string you can specify the name (alias) of corresponding elements inside an (XML) input/output configuration file. This name is used to identify entities within an XML file using the [http://freemarker.org/docs/pgui_datamodel.html NodeModel of Freemarker] instead of using the standard Java Object Model name. For example:

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file XML "C:/.../net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/stores.xml" beans {
entity Mregion nodeName "region"
entity Mstore nodeName "store"
entity Mwarehouse nodeName "warehouse"
}
</syntaxhighlight>

The result from this example code is the generation of Smooks configuration files, in which the structure of the output data file (order of elements) will be the same as declared inside the beans {...} expression block. The alias you have specified after the keyword will be used as element (entity) name inside the XML files.

<div id="Figure3"> [[File:FreeMarkerNodeModelStoreInEx.png|600px|thumb|center|''Figure 3: Store-import.xml and Store-export.xml with NodeModel'']] </div>

The use of this keyword gives you the flexibility of naming entities using aliases in order to match any third part system description. By omitting the definition of both aliases ''region'' and ''warehouse'' like shown below, we obtain slightly divergent but very different contents than the ones from above.

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file XML "C:/.../net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/stores.xml" beans {
entity Mregion
entity Mstore nodeName "store"
entity Mwarehouse
}
</syntaxhighlight>

[[File:FreeMarkerJavaObjectModelStoreInEx.png|600px|thumb|center|''Figure 4: Store-import.xml (normal) and Store-export.xml (normal) with Java Object Model Name'']]

Please note that the declaration order of each node names matters.

====createOn====

The <code>createOn</code> keyword followed by a string specifies on which input element should an entity to be created. For example:

► '''Example''':
<syntaxhighlight lang="java">
entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" ... {
...
}

</syntaxhighlight>

will create an <code>Mcurrency</code> entity when encountering <code>/Envelope/Cube/Cube</code> in the source data file.

====marker====

With <code>marker</code> keyword optionally followed by a property-name, the user can set the data to be imported to have an additional property under the given name whose value set to 1, while updating the existing data to have this property having value 0. This could be useful to identify the most recent import of some periodically updated data. For example:

► '''Example''':
<syntaxhighlight lang="java">

entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
...
}
</syntaxhighlight>

will make the entity <code>McurrencyStream</code> to have a property "<code>latest</code>", which is to be set to 1 for the most recently imported data.

====expression====

With an <code>expression { ... }</code> block, the user can define expressions that assign certain value to an entity property. These expressions are of two types, the first one is:

► '''Syntax''':
<syntaxhighlight lang="java">

assign <id> with <value> as <type>

</syntaxhighlight>

this will assign the property <code>id</code> with the value of <code>value</code>, in type of <code>type</code>. The <code>value</code> may be one of the following:

* <code>NowDate</code>: the date of now (the time point of action)
* <code>StartDate</code>: the date when the process started
* <code>UniversallyUniqueIdentifier</code>: an UUID

and <code>type</code> may be one of the following:

* <code>Date</code>: the value of NowDate or StartDate will be in date format
* <code>Milliseconds</code>: the value of NowDate or StartDate will be in millisecond
* <code>Nanoseconds</code>: the value of NowDate or StartDate will be in nanosconds
* <code>Random</code>: the value of UUID will be random
* <code>ExecuteContext</code>: the value of UUID will be unique for the execute context

Note that the <code>Random</code> and <code>ExecuteContext</code> should be only combined with <code>UniversallyUniqueIdentifier</code>, while the other types should be only combined with <code>NowDate</code> or <code>StartDate</code>.

► '''Example''':
<syntaxhighlight lang="java">
entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
assign importDate with NowDate as Date
}
</syntaxhighlight>

will assign the <code>importDate</code> as the current date in <code>Date</code> format.

The other type of expression has the form:

► '''Syntax''':
<syntaxhighlight lang="java">

copy <target-property> from <entity-name> property <from-property>

</syntaxhighlight>

which will copy the value of <code>from-property</code> from the <code>entity-name</code> to <code>target-property</code>.

► '''Example''':
<syntaxhighlight lang="java">

entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" expression {
copy currencyDate from McurrencyDay property ratingDate
}

</syntaxhighlight>

will copy the value of <code>ratingDate</code> from <code>McurrencyDay</code> entity to <code>currencyDate</code>.

====lookup====
<div id="lookup">
With a <code>lookup</code> { ... } block, the user can define a set of '''lookup-rules''' to identify complex data within our persistence layer (DB or In-Memory...). This makes sense when the data in a source file can't be clearly identified by an attribute (id), but moreover when the set data it contains is persisted over several entities.

► '''Syntax''':
<syntaxhighlight lang="java">
lookup {
[<lookup-rules>]*
}
</syntaxhighlight>

Lookup-rule expression:
<syntaxhighlight>
lookup-rule:
'for' .. 'on' .. 'createOn' .. 'with' .. 'cacheSize' .. 'mapTo' .. ['allowNoResult' | 'allowNoResult' | 'markerPath']
</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
interchange Currencies describedBy "european central bank currency exchange rates based on euro" persist elementSize 50 file
XML "C:/git/development/net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/eurofxref-hist-90d.xml"

mapByAttribute beans {
entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
assign importDate with NowDate as Date
}
entity McurrencyDay createOn "/Envelope/Cube/Cube" format {
for ratingDate coding "yyyy-MM-dd"
}
mapping {
map ratingDate to "time"
}
entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" expression {
copy currencyDate from McurrencyDay property ratingDate
}
lookup {
for currency_name on McurrencyName createOn "/Envelope/Cube/Cube/Cube" with isoCode cacheSize 300 mapTo "currency" allowNoResult
markerPath {
markerEntity McurrencyNameStream markedBy latest
}
}
mapping {
map conversion_ratio to "rate"
}

}

</syntaxhighlight>

</div>

We will provide you in upcoming releases with more information about so called '''locator''' instances, which are generated in the background on the basis of the '''lookups''' you would have defined, in order to query persisted data. This will give you more insights about how the Datainterchange DSL really works at the lower level.

====format====

With a <code>format { ... }</code> block, the user can define the format of the entity property being converted. A <code>format</code> block can have more than one format definitions, in the following format:

► '''Syntax''':
<syntaxhighlight lang="java">

format {
for <property> coding <format-string> [locale <locale-string>]
...
}

</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">

entity McurrencyDay createOn "/Envelope/Cube/Cube" format {
for ratingDate coding "yyyy-MM-dd"
}

</syntaxhighlight>

will convert the <code>"/Envelope/Cube/Cube"</code> data to <code>ratingDate</code> property of <code>McurrencyDay</code> in format <code>"yyyy-MM-dd"</code>, where

► '''Example''':
<syntaxhighlight lang="java">

entity EDIOrderHeader createOn "/Order/header" format {
for hdrDate coding "EEE MMM dd HH:mm:ss zzz yyyy" locale "en_US"
}

</syntaxhighlight>

will format the <code>hdrDate</code> in format <code>"EEE MMM dd HH:mm:ss zzz yyyy"</code> with English locale, i.e. the month and weekday names will be in English.

====mapping====
With a <code>mapping { ... }</code> block, the user can easily '''map''' (or rather '''match''') attributes of the data model to values from external source files.

► '''Syntax''':
<syntaxhighlight lang="java">
mapping {
[map <entity-attribute> to <Data>]*
[mapBlob <entity-attribute> to <Data> [extension <blob-file-extension] [path <blob-path>] mimeType <mine-type> ]*
}
</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
mapping{
map conversion_ratio to "rate"
mapBlob currency_icon to "currency_icon" extension "png" path "C:/data/currency_images" mimeType png
}
</syntaxhighlight>

The first map of the above example will map the attribute conversion_ratio of the entity to field "rate".
The second mapBlob does a bit more work, it will:

* generate full file paths by combining the path, the file names specified by "currency_icon" field, and the extension,
* upload the files into database with the given mimeType, and
* assign the UUID of the blob to property currency_icon of the entity.

Please note that the only valid attributes here are the members of the corresponding entity, which the user has chosen prior defining the <code>mapping</code> block itself.

====keys====
With a <code>keys</code> { ... } block, the user can define a set of '''keys''' to identify data within our persistence layer (DB or In-Memory...).
This makes sence when the data in a source file can't be clearly identified by an attribute (id). Therefore a set of attributes (keys) can be defined and then be used as identification parameter set by a [[#lookup|''lookups'']] instance in order to query our data pool and identify data using several criteria.

► '''Syntax''':
<syntaxhighlight lang="java">
keys {
[key <entity-attribute>]*
}
</syntaxhighlight>

Assuming you try to update the address data of an employee from an entity named Employee, but you happen not to have his/her personal id. By setting a <code>keys</code> { ... } block, like shown here below, you allow the Datainterchange unit to look into the database after employee's data based on the key set inside this block, rather than using a personal id, which might have been here unique and more than enough to find the employee right away.

► '''Example''':
<syntaxhighlight lang="java">
keys {
key last_name
key first_name
key age
}
</syntaxhighlight>

Please note that the only valid attributes here are members of the corresponding entity, that you would have chosen prior defining the <code>keys</code> block itself.

==TriggerView==
A TriggerView will be automatically generated by the DataInterchange DSL as soon as you define an interchange unit inside the model file and save it.

You can see on the right side of the figure shown below, the definition of 10 interchange units within the Datainterchange model file (blue rectangles); and on the right side of the figure you can see, how the TriggerView looks like (green rectangle), when it is embedded inside an application page in its entirety.

[[File:TriggerView.png|600px|center|''Figure 5: Datainterchange TriggerView Definition and Application Views''|thumbnail|600px]]

To achieve this result you need to do two simple steps. You need first to either integrate the TriggerView into an existing perspective or create a new perspective and then integrate the view into it, like shown below.

► '''Example 1''':
<syntaxhighlight lang="java">
import ns net.osbee.sample.foodmart.datainterchanges
...

package net.osbee.sample.foodmart.perspectives {

perspective Currencies iconURI "employee" {
sashContainer c1 orientation horizontal {
part imex view dataInterchange datainterchanges spaceVolume "20"
...
}
}
}
</syntaxhighlight>

The most important thing in this example is to notice the use of the keyword '''view''' followed by the keyword '''dataInterchange''' and the name ''datainterchanges'' referring to the package, in which all datainterchange unit definitions have to be found.

The second step would be to create a menu entry for you to be able to access the newly created or altered perspective in the application via the menu bar, like shown in the following example.

► '''Example 2''':
<syntaxhighlight lang="java">
import ns net.osbee.sample.foodmart.perspectives.Currencies
...

package net.osbee.sample.foodmart.menues {
...
entry Menu describedBy "my menu" {
entry Perspectives {
entry MasterData {
entry Company image "company" perspective Company
entry Employees image "employee" perspective Employee
entry Products image "products" perspective Products
entry CashRegisterData image "editor_area" perspective CashMasterDataRegister

entry Currencies image "products" perspective Currencies

entry People image "task_action_delegate" perspective PeopleMock

}
...
... }
}

}
</syntaxhighlight>

[[File:TriggerViewMenuSelection.png|600px|center|''Figure 6: Datainterchange TriggerView Menu Selection''|thumbnail|600px]]

The figure above shows the same menu structure defined in the example 2 and results in showing the application with the TriggerView, as you can see on the left side of the figure 5. You can get and review more information on how to create menu entries and perspectives in both [[Menu DSL]] and [[Perspective DSL]] documentation pages.

Among all the components that are generated for the use of each interchange unit functions are action buttons, you would find inside toolbars in some dialogs. Usually you have to define them by yourself in the corresponding DSL files. This step is not needed here, since it has already been generated for this particular view.

[[File:TriggerViewActionButtons.png|600px|center|''Figure 7: Action Buttons for datainterchange unit functions''|thumbnail|600px]]

Please note that it is '''not mandatory''' to display all available functionalities through the use of the TriggerView like shown here above. It is customary to only use parts of the generated Datainterchange components (e.g. action buttons) where you see them fit; for instance in order to only use each interchange unit functionalities (import and/or export) in separated and dedicated views (dialogs). Therefore, we also recommend you to have a look at the [[Action DSL]] documentation page in order to understand how to create your own toolbars, and so forth creating the buttons using import or export functions of any datainterchange unit you would have created.

==Smooks Configuration and Settings File==
'''Please note that whenever a model is saved''', the '''Datainterchange DSL''' will do three things '''automatically''':

* generate Java classes,
* generate Smooks configuration files for both import and export functions, and
* generate a config file to modify the import and export paths on runtime.

===Smooks Configuration File===

The OS.bee implementation of Data Interchange interface is based on Smooks. Smooks is a Java framework for processing XML and non XML data (CSV, EDI, Java etc) by mapping data to JavaBeans, which can later be persisted, enriched (merge with existing data from other source), or converted and exported into other formats.

Smooks relies on a proper configuration file for the import / export processes. These configuration files are generated by the Datainterchange DSL automatically. Here is a brief introduction of how the generated Smooks configuration files work.

When a data import / export Smooks instance is initiated, it will be supplied with the generated config file. This file defines the actions to be performed upon certain events during the SAX parsing process. Here is an example:
<syntaxhighlight lang="xml" line='line'>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd" xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.2.xsd">
<jb:bean beanId="McurrencyNameStream" class="net.osbee.sample.foodmart.entities.McurrencyNameStream" createOnElement="/csv-set">
<jb:expression property="importDate">PTIME.nowDate</jb:expression>
<jb:wiring beanIdRef="McurrencyName" setterMethod="addToCurrencyNames"/>
</jb:bean>
<jb:bean beanId="McurrencyName" class="net.osbee.sample.foodmart.entities.McurrencyName" createOnElement="/csv-set/csv-record">
<jb:value data="/csv-set/csv-record/isoCode" decoder="String" property="isoCode"/>
<jb:value data="/csv-set/csv-record/name" decoder="String" property="name"/>
<jb:value data="/csv-set/csv-record/countries" decoder="String" property="countries"/>
</jb:bean>
<csv:reader fields="isoCode,name,countries" indent="false" separator=";" skipLines="1"/>
<params>
<param name="stream.filter.type">SAX</param>
<param name="inputType">input.csv</param>
<param name="smooks.visitors.sort">false</param>
<param name="input.csv" type="input.type.actived">C:/git/net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/ISOCurrencyCodes081507.csv</param>
</params>
</smooks-resource-list>
</syntaxhighlight>

Further informations on the Smoooks framework are available and can be reviewed in its [http://www.smooks.org/guide documentation] you will find on the [http://www.smooks.org/index official website].

===Path Config File===

The file is interpreted using the Properties xml im- and export method and looks like this:

<syntaxhighlight lang="java">

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>dataInterchange file URLs</comment>
<entry key="EmployeesDepartment-import">C:/myimports/employeesdepartment.xml</entry>
<entry key="EmployeesDepartment-export">C:/myexports/employeesdepartment.xml</entry>
</properties>

</syntaxhighlight>

By default this file is named like the title in the Data Interchange package and extended by "Config" and has the extension "xml":

<code>package net.osbee.sample.foodmart.datainterchanges title "DataInterchange" {}</code>

leads to the filename:

<code>DataInterchangeConfig.xml</code>

and is stored platform independently in the current user's home directory under the subdirectory ".osbee".

An administrator must receive this configuration file with the application, modify it and place it somewhere on the application server. The path to this configuration file must be supplied in the product's preferences (<code>org.eclipse.osbp.production.prefs</code>):

<code>datainterchange/datainterchangeConfiguration=c\:\\DataInterchangeConfig.xml</code>

The path value obviously depends on the operating system you are developing.

== Copyright Notice ==
{{Copyright Notice}}

Datainterchange DSL

2017-11-08T09:05:47Z

Wu: /* mapping */

==Purpose==

The Data Interchange DSL (datainterchange for short) is made for defining data exchange models that can be used to import data from various formats (CSV, XML, EDI, etc.), map the data to entities, store them into database, or export them back into other formats.

You only need to define the ''relationship'' between the file and the bean, not the import / export process themselves. Once defined, these models can be used in e.g. action DSL to define actions which, when triggered, execute the actual import / export process, which are generated automatically by the OSBP based on the model.

==Overview==

As shown on the figure below, the [DSL Inferrer] will generate various views and In/Export component according to model described by datainterchange DSL (and action DSL, in the case of ActionButtons). The action buttons, when clicked, will trigger their corresponding In/Export processes by putting [http://download.osbee.org/downloads/javadoc/osbee-master-clean/org.eclipse.osbp.xtext.datainterchange.feature/apidocs/ WorkerThread (Runnable)] jobs into the executor job pool within the TriggerView (prefixed with datainterchang name), buttons (and toolbar / menus containing them) are further included in the perspective.

[[File:Datainterchange.png|600px|center|frame|''Figure 1: - Data Interchange Structure.'']]

==Data Interchange Model File==

Datainterchange DSL model files end with the <code>.data</code> extension. Data Interchange models may be split into several <code>.data</code> files, as long as they have the same package declaration.

In the following we will dive deeper into the description and the usage of Datainterchange related and reserved keywords.

===import===
In the import section are all entities to be found - as full qualified names – that are currently used in the DSL.

► '''Example''':
<syntaxhighlight lang="java">

import ns net.osbee.sample.foodmart.entities.Mstore
import ns net.osbee.sample.foodmart.entities.Mwarehouse
import ns net.osbee.sample.foodmart.entities.Mregion

</syntaxhighlight>

Note that <code>ns</code> is a mandatory keyword (stands for "namespace") that comes after import for distinguishing the OS.bee internal namespaces and Java library namespaces. Wildcards are not supported, all names should be imported separately. Note that the import section will be imported/added automatically if they are used in the package, so you don't have to manually manage this section.

===package===

Datainterchange DSL model files must start with a package declaration. Packages are the root element of the DSL and should be defined as <code><ApplicationName>.datainterchange</code>.

► '''Example''':
<syntaxhighlight lang="java">package net.osbee.sample.foodmart.datainterchanges { }</syntaxhighlight>

Data Interchange models may be split into several .data files, as long as they have the same package declaration, the interchanges will be available under this package name.

===title===
With the keyword title you can give a name to the corresponding TriggerView dialog inside your application. For example, the definition of the same datainterchanges package from above with title "Data Interchange Example":

► '''Example''':
<syntaxhighlight lang="java">package net.osbee.sample.foodmart.datainterchanges title "Data Interchange Example" {}</syntaxhighlight>

This title will be translated based on locale.

You can get more details about the TriggerView in the section below.

===interchange===
The <code>interchange</code> keyword defines interchange units for entities in the package, it should be in the form of:

► '''Example''':
<syntaxhighlight lang="java">
interchange <InterchangeUnitName> [describedBy <description>] <EntityManagerMode> file <FileType> [<FileDetails>] beans {
...
}
</syntaxhighlight>

Where <code>InterchangeUnitName</code> being the name of the interchange unit; <code>describedBy</code> (optional) can be used to provide a short description string. <code>EntityManagerMode</code> being how the file should be handled (see section "persist, merge, remove" below), and after <code>file</code> keyword, you should specify the type of the source / target data file you would like to import from or export to, then the file path, and other details depends on the type.

The following example specifies an interchange that reads a CSV file under the specified path (note the forward slash as the path separator), delimited by semicolon, skip one line (the header), and treat the content as encoded in UTF-8:

► '''Example''':
<syntaxhighlight lang="java">

interchange CurrencyNames persist file
CSV "C:/data/ISOCurrencyCode20170101.csv" delimiter ";" skipLines 1 encoding "UTF-8"
beans {
...
}
</syntaxhighlight>

The <code>beans</code> keyword comes after all the file specification and starts a block of entity definitions, which will be covered in section "entity".

===describedBy===
With this keyword you can the optional description of an interchange unit as shown below.

► '''Example''':
<syntaxhighlight lang="java">
interchange Currencies describedBy "european central bank currency exchange rates based on euro" persist ... { ... }
</syntaxhighlight>

===vectorName===
With the optional keyword <code>vectorName</code> followed by a string value you are able to define the name of the root element of both XML configuration files needed by Smooks. Please note that it also means that the first (root-)element of an XML-File you would have exported (file filled with real data) via the application will have the same name.

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file ... { ... }
</syntaxhighlight>

You can view the result of this sample of code like shown below on figure[[#Figure3|''3'']].

===persist, merge, remove===
These keywords define the purpose of the datainterchange unit and has a similar meaning as in the JPA's EntityManager class. Basically, <code>persist</code> will insert the data records into database, <code>merge</code> will update existing data record, or insert new one if necessary, <code>remove</code> will remove the record if it could be found in database.

► '''Example 1''': (persist)
<syntaxhighlight lang="java">
interchange EDIOrders describedBy "Orders" persist file
XML "C:/data/orders.xml"
beans {
...
}
</syntaxhighlight>

► '''Example 2''': (merge)
<syntaxhighlight lang="java">
interchange Stores merge file
XML "C:/data/stores.xml"
beans {
...
}
</syntaxhighlight>

► '''Example 3''': (remove)
<syntaxhighlight lang="java">
interchange Storesremove remove file
XML "C:/data/stores_remove.xml"
beans {
...
}
</syntaxhighlight>

===file===
With the keyword file you are able to set the file format of the files you intent to process with you interchange unit.

► '''Syntax''':
<syntaxhighlight lang="java">interchange <SampleInterchangeUnitName> <EntityManagerMode> file <FileNameFormat> {}</syntaxhighlight>

The current supported file formats are CSV, EDI and XML followed by the name of the file you want to process, given its full path location in the system.
► '''Example 1''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit1 merge file CSV "C:/temp/testFile.csv" {}</syntaxhighlight>
► '''Example 2''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit2 persist file XML "C:/temp/testFile.xml" {}</syntaxhighlight>
► '''Example 3''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit3 merge file EDI "C:/temp/testFile.edi" {}</syntaxhighlight>

After choosing the file format you can either give the file name as a String value in a double quote "..." as shown here above, or press Ctrl+Space to get via the content assist the option of opening a File Chooser/Picker to specify the file you want to work with.

[[File:FileChooser.jpg|center|frame|''Figure 2: File Chooser'']]

Please note that you can also change the path(?) of the file to process on runtime by selecting a new file.

===mapByAttribute===

The <code>mapByAttribute</code> keyword is an XML-specific keyword that turns on the automatic attribute mapping. When enabled, datainterchange will detect if the value being mapped is from an attribute. For example, the 'USD' value in the following XML file comes from the attribute 'currency' of the element 'Cube':

► '''Example''':
<syntaxhighlight lang="xml">
<Cube currency='USD' rate='1.3759'/>
</syntaxhighlight>

while in the following XML file, the same value is encapsulated in the element 'currency':

► '''Example''':
<syntaxhighlight lang="xml">

<Cube>
<currency>USD</currency>
<rate>1.3759</rate>
</Cube>
</syntaxhighlight>

When <code>mapByAttribute</code> is present, datainterchange will automatically decide that a query in the form like <code>'/Cube/currency'</code> will also catch the value from attribute. Without it, the query will have to put a <code>'@'</code> symbol in front of the attribute name, i.e. <code>'/Cube/@currency'</code>.

===elementSize===
With the keyword <code>elementSize</code> followed by an integer, the user can set the estimated average size of the elements in bytes. Since the underlying API cannot know the size of an element before it is processed, this value can be supplied as a guide value to be used for estimating the import / output progress based on how much bytes have been processed.

► '''Example''':
<syntaxhighlight lang="java">
interchange EDIOrders describedBy "edi orders" persist elementSize 50 file EDI "C:/data/orders.edi" beans {
...
}
</syntaxhighlight>

Defines an average estimated element size of 50 bytes.

===delimiter===

The <code>delimiter</code> is a CSV format-specific keyword, which defines the character to use in the CSV file to set the delimiter/separation character between different values. Default value is "," (comma).

► '''Example''':
<syntaxhighlight lang="java">
interchange CurrencyNames persist file
CSV "C:/data/ISOCurrencyCodes081507.csv" delimiter ";" ... {
...
}
</syntaxhighlight>

will set the delimiter of the CSV file to ";".

===skipLines===
This is a CSV format-specific keyword. Using <code>skipLines</code> followed by an integer, the user can specify the number of lines to be skipped from the beginning in the processing of the selected file, this can be used to skip headers.

► '''Example''':
<syntaxhighlight lang="java">
interchange CurrencyNames persist file CSV "C:/data/ISOCurrencyCodes081507.csv" ... skipLines 1 encoding "UTF-8" {
...
}
</syntaxhighlight>

will skip the first line of the CSV file.

===report===

If a '''datainterchange''' unit is defined with the <code>report</code> keyword, a report will be generated for data conversions. The report file is generated by Smooks, lies under <code>/smooks</code> output directory of the datainterchange bundle, and has a name in the form like <code><DataInterChangeName>-input.xml</code> for input processes, and <code><DataInterChangeName>-output.xml</code> for output processes. '''Note: turn on report will have an impact performance.'''

===indent===

The <code>indent</code> is a CSV-format specified keyword which adds indentation character data to the generated event stream. This simply makes the generated event stream easier to read in its serialized form and generally should only be used in testing.

===quoteCharacter===

The <code>quoteCharacter</code> is a CSV format-specific keyword, which defines the character to use in the CSV file to identify values.

===encoding===
With the keyword '''enconding''' followed by the encoding name as a string value you are able to specify the valid encoding of the file content.

► '''Example 1''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName merge elementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "UTF-8"{}</syntaxhighlight>
► '''Example 2''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName remove elementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "GB18030"{}</syntaxhighlight>
► '''Example 3''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName persistelementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "ISO-2022-JP"{}</syntaxhighlight>

===mappingModel===

The <code>mappingModel</code> keyword is an EDI-specific keyword which can be used to specify an EDI to XML mapping model in XML format for Smooks.

===validate===

The <code>validate</code> keyword is an EDI-specific keyword that...

===beans===

The keyword <code>beans</code> starts the series of entities. The name "bean" comes from the internal entities called JavaBean, which act as data containers.

===entity===

With the <code>entity</code> keyword followed by a fully qualified name, the user can specify the mapping between a source data file and a data-containing entity. The behavior of the mapping can be further fine-tuned with the keywords discussed below. While these keywords can theoretically be combined all together and create very complicated behavior, they are normally used in a simple and straight forward way.

The general form of <code>entity</code> keywords is:

► '''Syntax''':
<syntaxhighlight>
entity <ID>
[nodeName <node-name>]
[createOn <element-map>]
[marker <property-name>]
[expression '{' <expressions> '}']
[lookup '{' <lookup-rules> '}']
[format '{' <formats> '}']
[mapping '{' <mappings> '}']
[keys '{' <lookup-keys> '}']
;
</syntaxhighlight>

The order of the keywords is fixed, i.e. they are all optional, but must appear in the given order.

====nodeName====

With the optional keyword <code>nodeName</code> followed by a string you can specify the name (alias) of corresponding elements inside an (XML) input/output configuration file. This name is used to identify entities within an XML file using the [http://freemarker.org/docs/pgui_datamodel.html NodeModel of Freemarker] instead of using the standard Java Object Model name. For example:

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file XML "C:/.../net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/stores.xml" beans {
entity Mregion nodeName "region"
entity Mstore nodeName "store"
entity Mwarehouse nodeName "warehouse"
}
</syntaxhighlight>

The result from this example code is the generation of Smooks configuration files, in which the structure of the output data file (order of elements) will be the same as declared inside the beans {...} expression block. The alias you have specified after the keyword will be used as element (entity) name inside the XML files.

<div id="Figure3"> [[File:FreeMarkerNodeModelStoreInEx.png|600px|thumb|center|''Figure 3: Store-import.xml and Store-export.xml with NodeModel'']] </div>

The use of this keyword gives you the flexibility of naming entities using aliases in order to match any third part system description. By omitting the definition of both aliases ''region'' and ''warehouse'' like shown below, we obtain slightly divergent but very different contents than the ones from above.

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file XML "C:/.../net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/stores.xml" beans {
entity Mregion
entity Mstore nodeName "store"
entity Mwarehouse
}
</syntaxhighlight>

[[File:FreeMarkerJavaObjectModelStoreInEx.png|600px|thumb|center|''Figure 4: Store-import.xml (normal) and Store-export.xml (normal) with Java Object Model Name'']]

Please note that the declaration order of each node names matters.

====createOn====

The <code>createOn</code> keyword followed by a string specifies on which input element should an entity to be created. For example:

► '''Example''':
<syntaxhighlight lang="java">
entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" ... {
...
}

</syntaxhighlight>

will create an <code>Mcurrency</code> entity when encountering <code>/Envelope/Cube/Cube</code> in the source data file.

====marker====

With <code>marker</code> keyword optionally followed by a property-name, the user can set the data to be imported to have an additional property under the given name whose value set to 1, while updating the existing data to have this property having value 0. This could be useful to identify the most recent import of some periodically updated data. For example:

► '''Example''':
<syntaxhighlight lang="java">

entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
...
}
</syntaxhighlight>

will make the entity <code>McurrencyStream</code> to have a property "<code>latest</code>", which is to be set to 1 for the most recently imported data.

====expression====

With an <code>expression { ... }</code> block, the user can define expressions that assign certain value to an entity property. These expressions are of two types, the first one is:

► '''Syntax''':
<syntaxhighlight lang="java">

assign <id> with <value> as <type>

</syntaxhighlight>

this will assign the property <code>id</code> with the value of <code>value</code>, in type of <code>type</code>. The <code>value</code> may be one of the following:

* <code>NowDate</code>: the date of now (the time point of action)
* <code>StartDate</code>: the date when the process started
* <code>UniversallyUniqueIdentifier</code>: an UUID

and <code>type</code> may be one of the following:

* <code>Date</code>: the value of NowDate or StartDate will be in date format
* <code>Milliseconds</code>: the value of NowDate or StartDate will be in millisecond
* <code>Nanoseconds</code>: the value of NowDate or StartDate will be in nanosconds
* <code>Random</code>: the value of UUID will be random
* <code>ExecuteContext</code>: the value of UUID will be unique for the execute context

Note that the <code>Random</code> and <code>ExecuteContext</code> should be only combined with <code>UniversallyUniqueIdentifier</code>, while the other types should be only combined with <code>NowDate</code> or <code>StartDate</code>.

► '''Example''':
<syntaxhighlight lang="java">
entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
assign importDate with NowDate as Date
}
</syntaxhighlight>

will assign the <code>importDate</code> as the current date in <code>Date</code> format.

The other type of expression has the form:

► '''Syntax''':
<syntaxhighlight lang="java">

copy <target-property> from <entity-name> property <from-property>

</syntaxhighlight>

which will copy the value of <code>from-property</code> from the <code>entity-name</code> to <code>target-property</code>.

► '''Example''':
<syntaxhighlight lang="java">

entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" expression {
copy currencyDate from McurrencyDay property ratingDate
}

</syntaxhighlight>

will copy the value of <code>ratingDate</code> from <code>McurrencyDay</code> entity to <code>currencyDate</code>.

====lookup====
<div id="lookup">
With a <code>lookup</code> { ... } block, the user can define a set of '''lookup-rules''' to identify complex data within our persistence layer (DB or In-Memory...). This makes sense when the data in a source file can't be clearly identified by an attribute (id), but moreover when the set data it contains is persisted over several entities.

► '''Syntax''':
<syntaxhighlight lang="java">
lookup {
[<lookup-rules>]*
}
</syntaxhighlight>

Lookup-rule expression:
<syntaxhighlight>
lookup-rule:
'for' .. 'on' .. 'createOn' .. 'with' .. 'cacheSize' .. 'mapTo' .. ['allowNoResult' | 'allowNoResult' | 'markerPath']
</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
interchange Currencies describedBy "european central bank currency exchange rates based on euro" persist elementSize 50 file
XML "C:/git/development/net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/eurofxref-hist-90d.xml"

mapByAttribute beans {
entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
assign importDate with NowDate as Date
}
entity McurrencyDay createOn "/Envelope/Cube/Cube" format {
for ratingDate coding "yyyy-MM-dd"
}
mapping {
map ratingDate to "time"
}
entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" expression {
copy currencyDate from McurrencyDay property ratingDate
}
lookup {
for currency_name on McurrencyName createOn "/Envelope/Cube/Cube/Cube" with isoCode cacheSize 300 mapTo "currency" allowNoResult
markerPath {
markerEntity McurrencyNameStream markedBy latest
}
}
mapping {
map conversion_ratio to "rate"
}

}

</syntaxhighlight>

</div>

We will provide you in upcoming releases with more information about so called '''locator''' instances, which are generated in the background on the basis of the '''lookups''' you would have defined, in order to query persisted data. This will give you more insights about how the Datainterchange DSL really works at the lower level.

====format====

With a <code>format { ... }</code> block, the user can define the format of the entity property being converted. A <code>format</code> block can have more than one format definitions, in the following format:

► '''Syntax''':
<syntaxhighlight lang="java">

format {
for <property> coding <format-string> [locale <locale-string>]
...
}

</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">

entity McurrencyDay createOn "/Envelope/Cube/Cube" format {
for ratingDate coding "yyyy-MM-dd"
}

</syntaxhighlight>

will convert the <code>"/Envelope/Cube/Cube"</code> data to <code>ratingDate</code> property of <code>McurrencyDay</code> in format <code>"yyyy-MM-dd"</code>, where

► '''Example''':
<syntaxhighlight lang="java">

entity EDIOrderHeader createOn "/Order/header" format {
for hdrDate coding "EEE MMM dd HH:mm:ss zzz yyyy" locale "en_US"
}

</syntaxhighlight>

will format the <code>hdrDate</code> in format <code>"EEE MMM dd HH:mm:ss zzz yyyy"</code> with English locale, i.e. the month and weekday names will be in English.

====mapping====
With a <code>mapping { ... }</code> block, the user can easily '''map''' (or rather '''match''') attributes of the data model to values from external source files.

► '''Syntax''':
<syntaxhighlight lang="java">
mapping {
[map <entity-attribute> to <Data>]*
}
</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
mapping{
map conversion_ratio to "rate"
}
</syntaxhighlight>

Please note that the only valid attributes here are the members of the corresponding entity, which the user has chosen prior defining the <code>mapping</code> block itself.

====keys====
With a <code>keys</code> { ... } block, the user can define a set of '''keys''' to identify data within our persistence layer (DB or In-Memory...).
This makes sence when the data in a source file can't be clearly identified by an attribute (id). Therefore a set of attributes (keys) can be defined and then be used as identification parameter set by a [[#lookup|''lookups'']] instance in order to query our data pool and identify data using several criteria.

► '''Syntax''':
<syntaxhighlight lang="java">
keys {
[key <entity-attribute>]*
}
</syntaxhighlight>

Assuming you try to update the address data of an employee from an entity named Employee, but you happen not to have his/her personal id. By setting a <code>keys</code> { ... } block, like shown here below, you allow the Datainterchange unit to look into the database after employee's data based on the key set inside this block, rather than using a personal id, which might have been here unique and more than enough to find the employee right away.

► '''Example''':
<syntaxhighlight lang="java">
keys {
key last_name
key first_name
key age
}
</syntaxhighlight>

Please note that the only valid attributes here are members of the corresponding entity, that you would have chosen prior defining the <code>keys</code> block itself.

==TriggerView==
A TriggerView will be automatically generated by the DataInterchange DSL as soon as you define an interchange unit inside the model file and save it.

You can see on the right side of the figure shown below, the definition of 10 interchange units within the Datainterchange model file (blue rectangles); and on the right side of the figure you can see, how the TriggerView looks like (green rectangle), when it is embedded inside an application page in its entirety.

[[File:TriggerView.png|600px|center|''Figure 5: Datainterchange TriggerView Definition and Application Views''|thumbnail|600px]]

To achieve this result you need to do two simple steps. You need first to either integrate the TriggerView into an existing perspective or create a new perspective and then integrate the view into it, like shown below.

► '''Example 1''':
<syntaxhighlight lang="java">
import ns net.osbee.sample.foodmart.datainterchanges
...

package net.osbee.sample.foodmart.perspectives {

perspective Currencies iconURI "employee" {
sashContainer c1 orientation horizontal {
part imex view dataInterchange datainterchanges spaceVolume "20"
...
}
}
}
</syntaxhighlight>

The most important thing in this example is to notice the use of the keyword '''view''' followed by the keyword '''dataInterchange''' and the name ''datainterchanges'' referring to the package, in which all datainterchange unit definitions have to be found.

The second step would be to create a menu entry for you to be able to access the newly created or altered perspective in the application via the menu bar, like shown in the following example.

► '''Example 2''':
<syntaxhighlight lang="java">
import ns net.osbee.sample.foodmart.perspectives.Currencies
...

package net.osbee.sample.foodmart.menues {
...
entry Menu describedBy "my menu" {
entry Perspectives {
entry MasterData {
entry Company image "company" perspective Company
entry Employees image "employee" perspective Employee
entry Products image "products" perspective Products
entry CashRegisterData image "editor_area" perspective CashMasterDataRegister

entry Currencies image "products" perspective Currencies

entry People image "task_action_delegate" perspective PeopleMock

}
...
... }
}

}
</syntaxhighlight>

[[File:TriggerViewMenuSelection.png|600px|center|''Figure 6: Datainterchange TriggerView Menu Selection''|thumbnail|600px]]

The figure above shows the same menu structure defined in the example 2 and results in showing the application with the TriggerView, as you can see on the left side of the figure 5. You can get and review more information on how to create menu entries and perspectives in both [[Menu DSL]] and [[Perspective DSL]] documentation pages.

Among all the components that are generated for the use of each interchange unit functions are action buttons, you would find inside toolbars in some dialogs. Usually you have to define them by yourself in the corresponding DSL files. This step is not needed here, since it has already been generated for this particular view.

[[File:TriggerViewActionButtons.png|600px|center|''Figure 7: Action Buttons for datainterchange unit functions''|thumbnail|600px]]

Please note that it is '''not mandatory''' to display all available functionalities through the use of the TriggerView like shown here above. It is customary to only use parts of the generated Datainterchange components (e.g. action buttons) where you see them fit; for instance in order to only use each interchange unit functionalities (import and/or export) in separated and dedicated views (dialogs). Therefore, we also recommend you to have a look at the [[Action DSL]] documentation page in order to understand how to create your own toolbars, and so forth creating the buttons using import or export functions of any datainterchange unit you would have created.

==Smooks Configuration and Settings File==
'''Please note that whenever a model is saved''', the '''Datainterchange DSL''' will do three things '''automatically''':

* generate Java classes,
* generate Smooks configuration files for both import and export functions, and
* generate a config file to modify the import and export paths on runtime.

===Smooks Configuration File===

The OS.bee implementation of Data Interchange interface is based on Smooks. Smooks is a Java framework for processing XML and non XML data (CSV, EDI, Java etc) by mapping data to JavaBeans, which can later be persisted, enriched (merge with existing data from other source), or converted and exported into other formats.

Smooks relies on a proper configuration file for the import / export processes. These configuration files are generated by the Datainterchange DSL automatically. Here is a brief introduction of how the generated Smooks configuration files work.

When a data import / export Smooks instance is initiated, it will be supplied with the generated config file. This file defines the actions to be performed upon certain events during the SAX parsing process. Here is an example:
<syntaxhighlight lang="xml" line='line'>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd" xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.2.xsd">
<jb:bean beanId="McurrencyNameStream" class="net.osbee.sample.foodmart.entities.McurrencyNameStream" createOnElement="/csv-set">
<jb:expression property="importDate">PTIME.nowDate</jb:expression>
<jb:wiring beanIdRef="McurrencyName" setterMethod="addToCurrencyNames"/>
</jb:bean>
<jb:bean beanId="McurrencyName" class="net.osbee.sample.foodmart.entities.McurrencyName" createOnElement="/csv-set/csv-record">
<jb:value data="/csv-set/csv-record/isoCode" decoder="String" property="isoCode"/>
<jb:value data="/csv-set/csv-record/name" decoder="String" property="name"/>
<jb:value data="/csv-set/csv-record/countries" decoder="String" property="countries"/>
</jb:bean>
<csv:reader fields="isoCode,name,countries" indent="false" separator=";" skipLines="1"/>
<params>
<param name="stream.filter.type">SAX</param>
<param name="inputType">input.csv</param>
<param name="smooks.visitors.sort">false</param>
<param name="input.csv" type="input.type.actived">C:/git/net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/ISOCurrencyCodes081507.csv</param>
</params>
</smooks-resource-list>
</syntaxhighlight>

Further informations on the Smoooks framework are available and can be reviewed in its [http://www.smooks.org/guide documentation] you will find on the [http://www.smooks.org/index official website].

===Path Config File===

The file is interpreted using the Properties xml im- and export method and looks like this:

<syntaxhighlight lang="java">

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>dataInterchange file URLs</comment>
<entry key="EmployeesDepartment-import">C:/myimports/employeesdepartment.xml</entry>
<entry key="EmployeesDepartment-export">C:/myexports/employeesdepartment.xml</entry>
</properties>

</syntaxhighlight>

By default this file is named like the title in the Data Interchange package and extended by "Config" and has the extension "xml":

<code>package net.osbee.sample.foodmart.datainterchanges title "DataInterchange" {}</code>

leads to the filename:

<code>DataInterchangeConfig.xml</code>

and is stored platform independently in the current user's home directory under the subdirectory ".osbee".

An administrator must receive this configuration file with the application, modify it and place it somewhere on the application server. The path to this configuration file must be supplied in the product's preferences (<code>org.eclipse.osbp.production.prefs</code>):

<code>datainterchange/datainterchangeConfiguration=c\:\\DataInterchangeConfig.xml</code>

The path value obviously depends on the operating system you are developing.

== Copyright Notice ==
{{Copyright Notice}}

Datainterchange DSL

2017-11-07T14:09:21Z

Wu: /* mappingModel */

==Purpose==

The Data Interchange DSL (datainterchange for short) is made for defining data exchange models that can be used to import data from various formats (CSV, XML, EDI, etc.), map the data to entities, store them into database, or export them back into other formats.

You only need to define the ''relationship'' between the file and the bean, not the import / export process themselves. Once defined, these models can be used in e.g. action DSL to define actions which, when triggered, execute the actual import / export process, which are generated automatically by the OSBP based on the model.

==Overview==

As shown on the figure below, the [DSL Inferrer] will generate various views and In/Export component according to model described by datainterchange DSL (and action DSL, in the case of ActionButtons). The action buttons, when clicked, will trigger their corresponding In/Export processes by putting [http://download.osbee.org/downloads/javadoc/osbee-master-clean/org.eclipse.osbp.xtext.datainterchange.feature/apidocs/ WorkerThread (Runnable)] jobs into the executor job pool within the TriggerView (prefixed with datainterchang name), buttons (and toolbar / menus containing them) are further included in the perspective.

[[File:Datainterchange.png|600px|center|frame|''Figure 1: - Data Interchange Structure.'']]

==Data Interchange Model File==

Datainterchange DSL model files end with the <code>.data</code> extension. Data Interchange models may be split into several <code>.data</code> files, as long as they have the same package declaration.

In the following we will dive deeper into the description and the usage of Datainterchange related and reserved keywords.

===import===
In the import section are all entities to be found - as full qualified names – that are currently used in the DSL.

► '''Example''':
<syntaxhighlight lang="java">

import ns net.osbee.sample.foodmart.entities.Mstore
import ns net.osbee.sample.foodmart.entities.Mwarehouse
import ns net.osbee.sample.foodmart.entities.Mregion

</syntaxhighlight>

Note that <code>ns</code> is a mandatory keyword (stands for "namespace") that comes after import for distinguishing the OS.bee internal namespaces and Java library namespaces. Wildcards are not supported, all names should be imported separately. Note that the import section will be imported/added automatically if they are used in the package, so you don't have to manually manage this section.

===package===

Datainterchange DSL model files must start with a package declaration. Packages are the root element of the DSL and should be defined as <code><ApplicationName>.datainterchange</code>.

► '''Example''':
<syntaxhighlight lang="java">package net.osbee.sample.foodmart.datainterchanges { }</syntaxhighlight>

Data Interchange models may be split into several .data files, as long as they have the same package declaration, the interchanges will be available under this package name.

===title===
With the keyword title you can give a name to the corresponding TriggerView dialog inside your application. For example, the definition of the same datainterchanges package from above with title "Data Interchange Example":

► '''Example''':
<syntaxhighlight lang="java">package net.osbee.sample.foodmart.datainterchanges title "Data Interchange Example" {}</syntaxhighlight>

This title will be translated based on locale.

You can get more details about the TriggerView in the section below.

===interchange===
The <code>interchange</code> keyword defines interchange units for entities in the package, it should be in the form of:

► '''Example''':
<syntaxhighlight lang="java">
interchange <InterchangeUnitName> [describedBy <description>] <EntityManagerMode> file <FileType> [<FileDetails>] beans {
...
}
</syntaxhighlight>

Where <code>InterchangeUnitName</code> being the name of the interchange unit; <code>describedBy</code> (optional) can be used to provide a short description string. <code>EntityManagerMode</code> being how the file should be handled (see section "persist, merge, remove" below), and after <code>file</code> keyword, you should specify the type of the source / target data file you would like to import from or export to, then the file path, and other details depends on the type.

The following example specifies an interchange that reads a CSV file under the specified path (note the forward slash as the path separator), delimited by semicolon, skip one line (the header), and treat the content as encoded in UTF-8:

► '''Example''':
<syntaxhighlight lang="java">

interchange CurrencyNames persist file
CSV "C:/data/ISOCurrencyCode20170101.csv" delimiter ";" skipLines 1 encoding "UTF-8"
beans {
...
}
</syntaxhighlight>

The <code>beans</code> keyword comes after all the file specification and starts a block of entity definitions, which will be covered in section "entity".

===describedBy===
With this keyword you can the optional description of an interchange unit as shown below.

► '''Example''':
<syntaxhighlight lang="java">
interchange Currencies describedBy "european central bank currency exchange rates based on euro" persist ... { ... }
</syntaxhighlight>

===vectorName===
With the optional keyword <code>vectorName</code> followed by a string value you are able to define the name of the root element of both XML configuration files needed by Smooks. Please note that it also means that the first (root-)element of an XML-File you would have exported (file filled with real data) via the application will have the same name.

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file ... { ... }
</syntaxhighlight>

You can view the result of this sample of code like shown below on figure[[#Figure3|''3'']].

===persist, merge, remove===
These keywords define the purpose of the datainterchange unit and has a similar meaning as in the JPA's EntityManager class. Basically, <code>persist</code> will insert the data records into database, <code>merge</code> will update existing data record, or insert new one if necessary, <code>remove</code> will remove the record if it could be found in database.

► '''Example 1''': (persist)
<syntaxhighlight lang="java">
interchange EDIOrders describedBy "Orders" persist file
XML "C:/data/orders.xml"
beans {
...
}
</syntaxhighlight>

► '''Example 2''': (merge)
<syntaxhighlight lang="java">
interchange Stores merge file
XML "C:/data/stores.xml"
beans {
...
}
</syntaxhighlight>

► '''Example 3''': (remove)
<syntaxhighlight lang="java">
interchange Storesremove remove file
XML "C:/data/stores_remove.xml"
beans {
...
}
</syntaxhighlight>

===file===
With the keyword file you are able to set the file format of the files you intent to process with you interchange unit.

► '''Syntax''':
<syntaxhighlight lang="java">interchange <SampleInterchangeUnitName> <EntityManagerMode> file <FileNameFormat> {}</syntaxhighlight>

The current supported file formats are CSV, EDI and XML followed by the name of the file you want to process, given its full path location in the system.
► '''Example 1''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit1 merge file CSV "C:/temp/testFile.csv" {}</syntaxhighlight>
► '''Example 2''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit2 persist file XML "C:/temp/testFile.xml" {}</syntaxhighlight>
► '''Example 3''':<syntaxhighlight lang="java">interchange SampleInterchangeUnit3 merge file EDI "C:/temp/testFile.edi" {}</syntaxhighlight>

After choosing the file format you can either give the file name as a String value in a double quote "..." as shown here above, or press Ctrl+Space to get via the content assist the option of opening a File Chooser/Picker to specify the file you want to work with.

[[File:FileChooser.jpg|center|frame|''Figure 2: File Chooser'']]

Please note that you can also change the path(?) of the file to process on runtime by selecting a new file.

===mapByAttribute===

The <code>mapByAttribute</code> keyword is an XML-specific keyword that turns on the automatic attribute mapping. When enabled, datainterchange will detect if the value being mapped is from an attribute. For example, the 'USD' value in the following XML file comes from the attribute 'currency' of the element 'Cube':

► '''Example''':
<syntaxhighlight lang="xml">
<Cube currency='USD' rate='1.3759'/>
</syntaxhighlight>

while in the following XML file, the same value is encapsulated in the element 'currency':

► '''Example''':
<syntaxhighlight lang="xml">

<Cube>
<currency>USD</currency>
<rate>1.3759</rate>
</Cube>
</syntaxhighlight>

When <code>mapByAttribute</code> is present, datainterchange will automatically decide that a query in the form like <code>'/Cube/currency'</code> will also catch the value from attribute. Without it, the query will have to put a <code>'@'</code> symbol in front of the attribute name, i.e. <code>'/Cube/@currency'</code>.

===elementSize===
With the keyword <code>elementSize</code> followed by an integer, the user can set the estimated average size of the elements in bytes. Since the underlying API cannot know the size of an element before it is processed, this value can be supplied as a guide value to be used for estimating the import / output progress based on how much bytes have been processed.

► '''Example''':
<syntaxhighlight lang="java">
interchange EDIOrders describedBy "edi orders" persist elementSize 50 file EDI "C:/data/orders.edi" beans {
...
}
</syntaxhighlight>

Defines an average estimated element size of 50 bytes.

===delimiter===

The <code>delimiter</code> is a CSV format-specific keyword, which defines the character to use in the CSV file to set the delimiter/separation character between different values. Default value is "," (comma).

► '''Example''':
<syntaxhighlight lang="java">
interchange CurrencyNames persist file
CSV "C:/data/ISOCurrencyCodes081507.csv" delimiter ";" ... {
...
}
</syntaxhighlight>

will set the delimiter of the CSV file to ";".

===skipLines===
This is a CSV format-specific keyword. Using <code>skipLines</code> followed by an integer, the user can specify the number of lines to be skipped from the beginning in the processing of the selected file, this can be used to skip headers.

► '''Example''':
<syntaxhighlight lang="java">
interchange CurrencyNames persist file CSV "C:/data/ISOCurrencyCodes081507.csv" ... skipLines 1 encoding "UTF-8" {
...
}
</syntaxhighlight>

will skip the first line of the CSV file.

===report===

If a '''datainterchange''' unit is defined with the <code>report</code> keyword, a report will be generated for data conversions. The report file is generated by Smooks, lies under <code>/smooks</code> output directory of the datainterchange bundle, and has a name in the form like <code><DataInterChangeName>-input.xml</code> for input processes, and <code><DataInterChangeName>-output.xml</code> for output processes. '''Note: turn on report will have an impact performance.'''

===indent===

The <code>indent</code> is a CSV-format specified keyword which adds indentation character data to the generated event stream. This simply makes the generated event stream easier to read in its serialized form and generally should only be used in testing.

===quoteCharacter===

The <code>quoteCharacter</code> is a CSV format-specific keyword, which defines the character to use in the CSV file to identify values.

===encoding===
With the keyword '''enconding''' followed by the encoding name as a string value you are able to specify the valid encoding of the file content.

► '''Example 1''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName merge elementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "UTF-8"{}</syntaxhighlight>
► '''Example 2''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName remove elementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "GB18030"{}</syntaxhighlight>
► '''Example 3''':<syntaxhighlight lang="java">interchange SampleInterchangeUnitName persistelementSize 50 file CSV "C:/temp/testFile.csv" delimiter ";" skipLines 1 encoding "ISO-2022-JP"{}</syntaxhighlight>

===mappingModel===

The <code>mappingModel</code> keyword is an EDI-specific keyword which can be used to specify an EDI to XML mapping model in XML format for Smooks.

===validate===

The <code>validate</code> keyword is an EDI-specific keyword that...

===beans===

The keyword <code>beans</code> starts the series of entities. The name "bean" comes from the internal entities called JavaBean, which act as data containers.

===entity===

With the <code>entity</code> keyword followed by a fully qualified name, the user can specify the mapping between a source data file and a data-containing entity. The behavior of the mapping can be further fine-tuned with the keywords discussed below. While these keywords can theoretically be combined all together and create very complicated behavior, they are normally used in a simple and straight forward way.

The general form of <code>entity</code> keywords is:

► '''Syntax''':
<syntaxhighlight>
entity <ID>
[nodeName <node-name>]
[createOn <element-map>]
[marker <property-name>]
[expression '{' <expressions> '}']
[lookup '{' <lookup-rules> '}']
[format '{' <formats> '}']
[mapping '{' <mappings> '}']
[keys '{' <lookup-keys> '}']
;
</syntaxhighlight>

The order of the keywords is fixed, i.e. they are all optional, but must appear in the given order.

====nodeName====

With the optional keyword <code>nodeName</code> followed by a string you can specify the name (alias) of corresponding elements inside an (XML) input/output configuration file. This name is used to identify entities within an XML file using the [http://freemarker.org/docs/pgui_datamodel.html NodeModel of Freemarker] instead of using the standard Java Object Model name. For example:

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file XML "C:/.../net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/stores.xml" beans {
entity Mregion nodeName "region"
entity Mstore nodeName "store"
entity Mwarehouse nodeName "warehouse"
}
</syntaxhighlight>

The result from this example code is the generation of Smooks configuration files, in which the structure of the output data file (order of elements) will be the same as declared inside the beans {...} expression block. The alias you have specified after the keyword will be used as element (entity) name inside the XML files.

<div id="Figure3"> [[File:FreeMarkerNodeModelStoreInEx.png|600px|thumb|center|''Figure 3: Store-import.xml and Store-export.xml with NodeModel'']] </div>

The use of this keyword gives you the flexibility of naming entities using aliases in order to match any third part system description. By omitting the definition of both aliases ''region'' and ''warehouse'' like shown below, we obtain slightly divergent but very different contents than the ones from above.

► '''Example''':
<syntaxhighlight lang="java">
interchange Stores remove vectorName "stores" elementSize 83 file XML "C:/.../net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/stores.xml" beans {
entity Mregion
entity Mstore nodeName "store"
entity Mwarehouse
}
</syntaxhighlight>

[[File:FreeMarkerJavaObjectModelStoreInEx.png|600px|thumb|center|''Figure 4: Store-import.xml (normal) and Store-export.xml (normal) with Java Object Model Name'']]

Please note that the declaration order of each node names matters.

====createOn====

The <code>createOn</code> keyword followed by a string specifies on which input element should an entity to be created. For example:

► '''Example''':
<syntaxhighlight lang="java">
entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" ... {
...
}

</syntaxhighlight>

will create an <code>Mcurrency</code> entity when encountering <code>/Envelope/Cube/Cube</code> in the source data file.

====marker====

With <code>marker</code> keyword optionally followed by a property-name, the user can set the data to be imported to have an additional property under the given name whose value set to 1, while updating the existing data to have this property having value 0. This could be useful to identify the most recent import of some periodically updated data. For example:

► '''Example''':
<syntaxhighlight lang="java">

entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
...
}
</syntaxhighlight>

will make the entity <code>McurrencyStream</code> to have a property "<code>latest</code>", which is to be set to 1 for the most recently imported data.

====expression====

With an <code>expression { ... }</code> block, the user can define expressions that assign certain value to an entity property. These expressions are of two types, the first one is:

► '''Syntax''':
<syntaxhighlight lang="java">

assign <id> with <value> as <type>

</syntaxhighlight>

this will assign the property <code>id</code> with the value of <code>value</code>, in type of <code>type</code>. The <code>value</code> may be one of the following:

* <code>NowDate</code>: the date of now (the time point of action)
* <code>StartDate</code>: the date when the process started
* <code>UniversallyUniqueIdentifier</code>: an UUID

and <code>type</code> may be one of the following:

* <code>Date</code>: the value of NowDate or StartDate will be in date format
* <code>Milliseconds</code>: the value of NowDate or StartDate will be in millisecond
* <code>Nanoseconds</code>: the value of NowDate or StartDate will be in nanosconds
* <code>Random</code>: the value of UUID will be random
* <code>ExecuteContext</code>: the value of UUID will be unique for the execute context

Note that the <code>Random</code> and <code>ExecuteContext</code> should be only combined with <code>UniversallyUniqueIdentifier</code>, while the other types should be only combined with <code>NowDate</code> or <code>StartDate</code>.

► '''Example''':
<syntaxhighlight lang="java">
entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
assign importDate with NowDate as Date
}
</syntaxhighlight>

will assign the <code>importDate</code> as the current date in <code>Date</code> format.

The other type of expression has the form:

► '''Syntax''':
<syntaxhighlight lang="java">

copy <target-property> from <entity-name> property <from-property>

</syntaxhighlight>

which will copy the value of <code>from-property</code> from the <code>entity-name</code> to <code>target-property</code>.

► '''Example''':
<syntaxhighlight lang="java">

entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" expression {
copy currencyDate from McurrencyDay property ratingDate
}

</syntaxhighlight>

will copy the value of <code>ratingDate</code> from <code>McurrencyDay</code> entity to <code>currencyDate</code>.

====lookup====
<div id="lookup">
With a <code>lookup</code> { ... } block, the user can define a set of '''lookup-rules''' to identify complex data within our persistence layer (DB or In-Memory...). This makes sense when the data in a source file can't be clearly identified by an attribute (id), but moreover when the set data it contains is persisted over several entities.

► '''Syntax''':
<syntaxhighlight lang="java">
lookup {
[<lookup-rules>]*
}
</syntaxhighlight>

Lookup-rule expression:
<syntaxhighlight>
lookup-rule:
'for' .. 'on' .. 'createOn' .. 'with' .. 'cacheSize' .. 'mapTo' .. ['allowNoResult' | 'allowNoResult' | 'markerPath']
</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
interchange Currencies describedBy "european central bank currency exchange rates based on euro" persist elementSize 50 file
XML "C:/git/development/net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/eurofxref-hist-90d.xml"

mapByAttribute beans {
entity McurrencyStream createOn "/Envelope/Cube" marker latest expression {
assign importDate with NowDate as Date
}
entity McurrencyDay createOn "/Envelope/Cube/Cube" format {
for ratingDate coding "yyyy-MM-dd"
}
mapping {
map ratingDate to "time"
}
entity Mcurrency createOn "/Envelope/Cube/Cube/Cube" expression {
copy currencyDate from McurrencyDay property ratingDate
}
lookup {
for currency_name on McurrencyName createOn "/Envelope/Cube/Cube/Cube" with isoCode cacheSize 300 mapTo "currency" allowNoResult
markerPath {
markerEntity McurrencyNameStream markedBy latest
}
}
mapping {
map conversion_ratio to "rate"
}

}

</syntaxhighlight>

</div>

We will provide you in upcoming releases with more information about so called '''locator''' instances, which are generated in the background on the basis of the '''lookups''' you would have defined, in order to query persisted data. This will give you more insights about how the Datainterchange DSL really works at the lower level.

====format====

With a <code>format { ... }</code> block, the user can define the format of the entity property being converted. A <code>format</code> block can have more than one format definitions, in the following format:

► '''Syntax''':
<syntaxhighlight lang="java">

format {
for <property> coding <format-string> [locale <locale-string>]
...
}

</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">

entity McurrencyDay createOn "/Envelope/Cube/Cube" format {
for ratingDate coding "yyyy-MM-dd"
}

</syntaxhighlight>

will convert the <code>"/Envelope/Cube/Cube"</code> data to <code>ratingDate</code> property of <code>McurrencyDay</code> in format <code>"yyyy-MM-dd"</code>, where

► '''Example''':
<syntaxhighlight lang="java">

entity EDIOrderHeader createOn "/Order/header" format {
for hdrDate coding "EEE MMM dd HH:mm:ss zzz yyyy" locale "en_US"
}

</syntaxhighlight>

will format the <code>hdrDate</code> in format <code>"EEE MMM dd HH:mm:ss zzz yyyy"</code> with English locale, i.e. the month and weekday names will be in English.

====mapping====
With a mapping { ... } block you are able single-handedly to '''map''' or rather to '''match''' each data attributes from an external source file to attributes of your data model.

► '''Syntax''':
<syntaxhighlight lang="java">
mapping {
[map <entity-attribut> to "Data"]*
}
</syntaxhighlight>

► '''Example''':
<syntaxhighlight lang="java">
mapping{
map conversion_ratio to "rate"
}
</syntaxhighlight>

Please note that the only valid attributs here are members of the corresponging entity, that you would have chosen prior defining the <code>mapping</code> block itself.

====keys====
With a <code>keys</code> { ... } block, the user can define a set of '''keys''' to identify data within our persistence layer (DB or In-Memory...).
This makes sence when the data in a source file can't be clearly identified by an attribute (id). Therefore a set of attributes (keys) can be defined and then be used as identification parameter set by a [[#lookup|''lookups'']] instance in order to query our data pool and identify data using several criteria.

► '''Syntax''':
<syntaxhighlight lang="java">
keys {
[key <entity-attribute>]*
}
</syntaxhighlight>

Assuming you try to update the address data of an employee from an entity named Employee, but you happen not to have his/her personal id. By setting a <code>keys</code> { ... } block, like shown here below, you allow the Datainterchange unit to look into the database after employee's data based on the key set inside this block, rather than using a personal id, which might have been here unique and more than enough to find the employee right away.

► '''Example''':
<syntaxhighlight lang="java">
keys {
key last_name
key first_name
key age
}
</syntaxhighlight>

Please note that the only valid attributes here are members of the corresponding entity, that you would have chosen prior defining the <code>keys</code> block itself.

==TriggerView==
A TriggerView will be automatically generated by the DataInterchange DSL as soon as you define an interchange unit inside the model file and save it.

You can see on the right side of the figure shown below, the definition of 10 interchange units within the Datainterchange model file (blue rectangles); and on the right side of the figure you can see, how the TriggerView looks like (green rectangle), when it is embedded inside an application page in its entirety.

[[File:TriggerView.png|600px|center|''Figure 5: Datainterchange TriggerView Definition and Application Views''|thumbnail|600px]]

To achieve this result you need to do two simple steps. You need first to either integrate the TriggerView into an existing perspective or create a new perspective and then integrate the view into it, like shown below.

► '''Example 1''':
<syntaxhighlight lang="java">
import ns net.osbee.sample.foodmart.datainterchanges
...

package net.osbee.sample.foodmart.perspectives {

perspective Currencies iconURI "employee" {
sashContainer c1 orientation horizontal {
part imex view dataInterchange datainterchanges spaceVolume "20"
...
}
}
}
</syntaxhighlight>

The most important thing in this example is to notice the use of the keyword '''view''' followed by the keyword '''dataInterchange''' and the name ''datainterchanges'' referring to the package, in which all datainterchange unit definitions have to be found.

The second step would be to create a menu entry for you to be able to access the newly created or altered perspective in the application via the menu bar, like shown in the following example.

► '''Example 2''':
<syntaxhighlight lang="java">
import ns net.osbee.sample.foodmart.perspectives.Currencies
...

package net.osbee.sample.foodmart.menues {
...
entry Menu describedBy "my menu" {
entry Perspectives {
entry MasterData {
entry Company image "company" perspective Company
entry Employees image "employee" perspective Employee
entry Products image "products" perspective Products
entry CashRegisterData image "editor_area" perspective CashMasterDataRegister

entry Currencies image "products" perspective Currencies

entry People image "task_action_delegate" perspective PeopleMock

}
...
... }
}

}
</syntaxhighlight>

[[File:TriggerViewMenuSelection.png|600px|center|''Figure 6: Datainterchange TriggerView Menu Selection''|thumbnail|600px]]

The figure above shows the same menu structure defined in the example 2 and results in showing the application with the TriggerView, as you can see on the left side of the figure 5. You can get and review more information on how to create menu entries and perspectives in both [[Menu DSL]] and [[Perspective DSL]] documentation pages.

Among all the components that are generated for the use of each interchange unit functions are action buttons, you would find inside toolbars in some dialogs. Usually you have to define them by yourself in the corresponding DSL files. This step is not needed here, since it has already been generated for this particular view.

[[File:TriggerViewActionButtons.png|600px|center|''Figure 7: Action Buttons for datainterchange unit functions''|thumbnail|600px]]

Please note that it is '''not mandatory''' to display all available functionalities through the use of the TriggerView like shown here above. It is customary to only use parts of the generated Datainterchange components (e.g. action buttons) where you see them fit; for instance in order to only use each interchange unit functionalities (import and/or export) in separated and dedicated views (dialogs). Therefore, we also recommend you to have a look at the [[Action DSL]] documentation page in order to understand how to create your own toolbars, and so forth creating the buttons using import or export functions of any datainterchange unit you would have created.

==Smooks Configuration and Settings File==
'''Please note that whenever a model is saved''', the '''Datainterchange DSL''' will do three things '''automatically''':

* generate Java classes,
* generate Smooks configuration files for both import and export functions, and
* generate a config file to modify the import and export paths on runtime.

===Smooks Configuration File===

The OS.bee implementation of Data Interchange interface is based on Smooks. Smooks is a Java framework for processing XML and non XML data (CSV, EDI, Java etc) by mapping data to JavaBeans, which can later be persisted, enriched (merge with existing data from other source), or converted and exported into other formats.

Smooks relies on a proper configuration file for the import / export processes. These configuration files are generated by the Datainterchange DSL automatically. Here is a brief introduction of how the generated Smooks configuration files work.

When a data import / export Smooks instance is initiated, it will be supplied with the generated config file. This file defines the actions to be performed upon certain events during the SAX parsing process. Here is an example:
<syntaxhighlight lang="xml" line='line'>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd" xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.2.xsd">
<jb:bean beanId="McurrencyNameStream" class="net.osbee.sample.foodmart.entities.McurrencyNameStream" createOnElement="/csv-set">
<jb:expression property="importDate">PTIME.nowDate</jb:expression>
<jb:wiring beanIdRef="McurrencyName" setterMethod="addToCurrencyNames"/>
</jb:bean>
<jb:bean beanId="McurrencyName" class="net.osbee.sample.foodmart.entities.McurrencyName" createOnElement="/csv-set/csv-record">
<jb:value data="/csv-set/csv-record/isoCode" decoder="String" property="isoCode"/>
<jb:value data="/csv-set/csv-record/name" decoder="String" property="name"/>
<jb:value data="/csv-set/csv-record/countries" decoder="String" property="countries"/>
</jb:bean>
<csv:reader fields="isoCode,name,countries" indent="false" separator=";" skipLines="1"/>
<params>
<param name="stream.filter.type">SAX</param>
<param name="inputType">input.csv</param>
<param name="smooks.visitors.sort">false</param>
<param name="input.csv" type="input.type.actived">C:/git/net.osbee.sample.foodmart/net.osbee.sample.foodmart.datainterchange/smooks-resources/ISOCurrencyCodes081507.csv</param>
</params>
</smooks-resource-list>
</syntaxhighlight>

Further informations on the Smoooks framework are available and can be reviewed in its [http://www.smooks.org/guide documentation] you will find on the [http://www.smooks.org/index official website].

===Path Config File===

The file is interpreted using the Properties xml im- and export method and looks like this:

<syntaxhighlight lang="java">

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>dataInterchange file URLs</comment>
<entry key="EmployeesDepartment-import">C:/myimports/employeesdepartment.xml</entry>
<entry key="EmployeesDepartment-export">C:/myexports/employeesdepartment.xml</entry>
</properties>

</syntaxhighlight>

By default this file is named like the title in the Data Interchange package and extended by "Config" and has the extension "xml":

<code>package net.osbee.sample.foodmart.datainterchanges title "DataInterchange" {}</code>

leads to the filename:

<code>DataInterchangeConfig.xml</code>

and is stored platform independently in the current user's home directory under the subdirectory ".osbee".

An administrator must receive this configuration file with the application, modify it and place it somewhere on the application server. The path to this configuration file must be supplied in the product's preferences (<code>org.eclipse.osbp.production.prefs</code>):

<code>datainterchange/datainterchangeConfiguration=c\:\\DataInterchangeConfig.xml</code>

The path value obviously depends on the operating system you are developing.

== Copyright Notice ==
{{Copyright Notice}}

UI DSL

2017-10-27T16:02:04Z

Wu: /* mobileTab */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

A text feld is generated with the <code>textfield</code> keyword. Textfields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following "datatype validators" may be defined in the parentheses between the keyword and the name:

* <code>maxLength</code> - creates a maximum-length validator for this field
(integer)
* <code>minLength</code> - creates a minimum-length validator for this field
(integer)
* <code>regex</code> - creates a regular expression validator for this field (String)

Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textfield [( [maxLength=<maxLength>]
[minLength=<minLength>]
[regex=<rexegString>]
[i18n <i18nKey>]
[styles <stylesString>]
[readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield (regex="[A-Z]-[0-9]{4}") TestText
}
}
</syntaxhighlight>

In the above example, a textfield is created along with validators that check the input in the UI field for conformity to certain conditions. If the requirements are not met, an error mark will be displayed.

===Mobile UI===

The UI DSL supports a variety of elements that are optimised for display on mobile devices. Mobile UIs are described in <code>.uimodel</code> files similar to regular UI models. The main difference is that the top level element in a mobile UI is a "mobile view" (instead of an desktop view or "ideview"), created by the keyword <code>mobile</code>.

Most of the UI elements that can be used in a desktop view (ideview) can be used inside a mobile view as well. In particular, these are:

* <code>combo</code>
* <code>datefield</code>
* <code>decimalField</code>
* <code>horizontalLayout</code> - here they are called <code>mobileHorizontalLayout</code>
* <code>label</code>
* <code>numericField</code>
* <code>optionsgroup</code>
* <code>progressbar</code>
* <code>searchfield</code>
* <code>searchPanel</code> - here called <code>mobileSearchPanel</code>
* <code>tab</code>
* <code>table</code>
* <code>tabsheet</code> - here called <code>mobileTab</code>
* <code>textarea</code>
* <code>textfield</code>
* <code>verticalLayout</code> - here called <code>mobileVerticalLayout</code>

If these model elements are used in a mobile environment, they will be rendered by the appropriate UI elements for Vaadin mobile UIs.

====Mobile-only Elements====

In addition to the mobile version of "desktop" UI elements, currently there is one additional UI element that can only be used in mobile UIs:

=====<code>switchIt</code>=====

A toggle switch for use in mobile UIs is generated with the <code>switchIt</code> keyword. Switches serve the same purpose in mobile UIs that checkboxes do for desktop UIs. A switch can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
switchIt [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
mobile Sample {
verticalGroup Options {
switchIt Active
} align fill-fill
}
</syntaxhighlight>

In the above example, a "sliding style" switch is created with the <code>switchIt</code> keyword.

====Mobile Layouts====
As has been stated above, vertical and horizontal layouts, search panels and tabsheets are available also in mobile UIs, albeit with another keyword. In these layouts, the simple UI elements listed above can be used in order to render mobile UIs.

In addition to

* <code>mobileHorizontalLayout</code>
* <code>mobileSearchPanel</code>
* <code>mobileTab</code>
* <code>mobileVerticalLayout</code>

there are a few mobile-only layouts without desktop UI counterparts available:

=====<code>horizontalButtonGroup</code>=====

A horizontal button group combines buttons to a unit in a mobile UI. It is created by the horizontalButtonGroup keyword. A horizontal button group can receive a name, an i18n key, a string with CSS styles and a readonly flag.

The elements contained in it, databinding instructions and visibility processor directives may be de�ned in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
horizontalButtonGroup [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<contained UI elements>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
horizontalButtonGroup Group {
button PushMe
button OrMe
button (readonly) ButNotMe
}
</syntaxhighlight>

In the above example, a horizontal button group will tie three buttons together horizontally.

=====<code>mobileTab</code>=====

A mobile tabsheet is similar to the regular tabsheet with the big difference that the tab selection is at the bottom. It is created by the <code>mobileTab</code> keyword. A mobile tabsheet can receive a name, an <code>i18n</code> key and a string with CSS styles.

The tabs contained in it, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
mobileTab [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<contained UI elements>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

mobile Sample {
mobileTab Main {
tab first verticalGroup Person {
form Demo {
textfield FirstName
textfield LastName
}
}
tab second verticalGroup Details {
form Demo {
textfield Address
textfield City
}
}
}
}
</syntaxhighlight>

In the above example, a mobile tabsheet is created with the keyword <code>mobileTab</code>. Each tab can contain an UI element or a layout (in this case, a vertical group).

=====<code>navRoot</code>=====
=====<code>navbarActions</code>=====
=====<code>navButton</code>=====
=====<code>verticalGroup</code>=====

====Mobile Navigation====

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-27T07:47:58Z

Wu: /* horizontalButtonGroup */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

A text feld is generated with the <code>textfield</code> keyword. Textfields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following "datatype validators" may be defined in the parentheses between the keyword and the name:

* <code>maxLength</code> - creates a maximum-length validator for this field
(integer)
* <code>minLength</code> - creates a minimum-length validator for this field
(integer)
* <code>regex</code> - creates a regular expression validator for this field (String)

Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textfield [( [maxLength=<maxLength>]
[minLength=<minLength>]
[regex=<rexegString>]
[i18n <i18nKey>]
[styles <stylesString>]
[readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield (regex="[A-Z]-[0-9]{4}") TestText
}
}
</syntaxhighlight>

In the above example, a textfield is created along with validators that check the input in the UI field for conformity to certain conditions. If the requirements are not met, an error mark will be displayed.

===Mobile UI===

The UI DSL supports a variety of elements that are optimised for display on mobile devices. Mobile UIs are described in <code>.uimodel</code> files similar to regular UI models. The main difference is that the top level element in a mobile UI is a "mobile view" (instead of an desktop view or "ideview"), created by the keyword <code>mobile</code>.

Most of the UI elements that can be used in a desktop view (ideview) can be used inside a mobile view as well. In particular, these are:

* <code>combo</code>
* <code>datefield</code>
* <code>decimalField</code>
* <code>horizontalLayout</code> - here they are called <code>mobileHorizontalLayout</code>
* <code>label</code>
* <code>numericField</code>
* <code>optionsgroup</code>
* <code>progressbar</code>
* <code>searchfield</code>
* <code>searchPanel</code> - here called <code>mobileSearchPanel</code>
* <code>tab</code>
* <code>table</code>
* <code>tabsheet</code> - here called <code>mobileTab</code>
* <code>textarea</code>
* <code>textfield</code>
* <code>verticalLayout</code> - here called <code>mobileVerticalLayout</code>

If these model elements are used in a mobile environment, they will be rendered by the appropriate UI elements for Vaadin mobile UIs.

====Mobile-only Elements====

In addition to the mobile version of "desktop" UI elements, currently there is one additional UI element that can only be used in mobile UIs:

=====<code>switchIt</code>=====

A toggle switch for use in mobile UIs is generated with the <code>switchIt</code> keyword. Switches serve the same purpose in mobile UIs that checkboxes do for desktop UIs. A switch can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
switchIt [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
mobile Sample {
verticalGroup Options {
switchIt Active
} align fill-fill
}
</syntaxhighlight>

In the above example, a "sliding style" switch is created with the <code>switchIt</code> keyword.

====Mobile Layouts====
As has been stated above, vertical and horizontal layouts, search panels and tabsheets are available also in mobile UIs, albeit with another keyword. In these layouts, the simple UI elements listed above can be used in order to render mobile UIs.

In addition to

* <code>mobileHorizontalLayout</code>
* <code>mobileSearchPanel</code>
* <code>mobileTab</code>
* <code>mobileVerticalLayout</code>

there are a few mobile-only layouts without desktop UI counterparts available:

=====<code>horizontalButtonGroup</code>=====

A horizontal button group combines buttons to a unit in a mobile UI. It is created by the horizontalButtonGroup keyword. A horizontal button group can receive a name, an i18n key, a string with CSS styles and a readonly flag.

The elements contained in it, databinding instructions and visibility processor directives may be de�ned in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
horizontalButtonGroup [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<contained UI elements>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
horizontalButtonGroup Group {
button PushMe
button OrMe
button (readonly) ButNotMe
}
</syntaxhighlight>

In the above example, a horizontal button group will tie three buttons together horizontally.

=====<code>mobileTab</code>=====
=====<code>navRoot</code>=====
=====<code>navbarActions</code>=====
=====<code>navButton</code>=====
=====<code>verticalGroup</code>=====

====Mobile Navigation====

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T16:42:21Z

Wu: /* switchIt */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

A text feld is generated with the <code>textfield</code> keyword. Textfields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following "datatype validators" may be defined in the parentheses between the keyword and the name:

* <code>maxLength</code> - creates a maximum-length validator for this field
(integer)
* <code>minLength</code> - creates a minimum-length validator for this field
(integer)
* <code>regex</code> - creates a regular expression validator for this field (String)

Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textfield [( [maxLength=<maxLength>]
[minLength=<minLength>]
[regex=<rexegString>]
[i18n <i18nKey>]
[styles <stylesString>]
[readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield (regex="[A-Z]-[0-9]{4}") TestText
}
}
</syntaxhighlight>

In the above example, a textfield is created along with validators that check the input in the UI field for conformity to certain conditions. If the requirements are not met, an error mark will be displayed.

===Mobile UI===

The UI DSL supports a variety of elements that are optimised for display on mobile devices. Mobile UIs are described in <code>.uimodel</code> files similar to regular UI models. The main difference is that the top level element in a mobile UI is a "mobile view" (instead of an desktop view or "ideview"), created by the keyword <code>mobile</code>.

Most of the UI elements that can be used in a desktop view (ideview) can be used inside a mobile view as well. In particular, these are:

* <code>combo</code>
* <code>datefield</code>
* <code>decimalField</code>
* <code>horizontalLayout</code> - here they are called <code>mobileHorizontalLayout</code>
* <code>label</code>
* <code>numericField</code>
* <code>optionsgroup</code>
* <code>progressbar</code>
* <code>searchfield</code>
* <code>searchPanel</code> - here called <code>mobileSearchPanel</code>
* <code>tab</code>
* <code>table</code>
* <code>tabsheet</code> - here called <code>mobileTab</code>
* <code>textarea</code>
* <code>textfield</code>
* <code>verticalLayout</code> - here called <code>mobileVerticalLayout</code>

If these model elements are used in a mobile environment, they will be rendered by the appropriate UI elements for Vaadin mobile UIs.

====Mobile-only Elements====

In addition to the mobile version of "desktop" UI elements, currently there is one additional UI element that can only be used in mobile UIs:

=====<code>switchIt</code>=====

A toggle switch for use in mobile UIs is generated with the <code>switchIt</code> keyword. Switches serve the same purpose in mobile UIs that checkboxes do for desktop UIs. A switch can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
switchIt [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
mobile Sample {
verticalGroup Options {
switchIt Active
} align fill-fill
}
</syntaxhighlight>

In the above example, a "sliding style" switch is created with the <code>switchIt</code> keyword.

====Mobile Layouts====
As has been stated above, vertical and horizontal layouts, search panels and tabsheets are available also in mobile UIs, albeit with another keyword. In these layouts, the simple UI elements listed above can be used in order to render mobile UIs.

In addition to

* <code>mobileHorizontalLayout</code>
* <code>mobileSearchPanel</code>
* <code>mobileTab</code>
* <code>mobileVerticalLayout</code>

there are a few mobile-only layouts without desktop UI counterparts available:

=====<code>horizontalButtonGroup</code>=====
=====<code>mobileTab</code>=====
=====<code>navRoot</code>=====
=====<code>navbarActions</code>=====
=====<code>navButton</code>=====
=====<code>verticalGroup</code>=====

====Mobile Navigation====

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T16:36:16Z

Wu: /* Alignment */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

A text feld is generated with the <code>textfield</code> keyword. Textfields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following "datatype validators" may be defined in the parentheses between the keyword and the name:

* <code>maxLength</code> - creates a maximum-length validator for this field
(integer)
* <code>minLength</code> - creates a minimum-length validator for this field
(integer)
* <code>regex</code> - creates a regular expression validator for this field (String)

Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textfield [( [maxLength=<maxLength>]
[minLength=<minLength>]
[regex=<rexegString>]
[i18n <i18nKey>]
[styles <stylesString>]
[readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield (regex="[A-Z]-[0-9]{4}") TestText
}
}
</syntaxhighlight>

In the above example, a textfield is created along with validators that check the input in the UI field for conformity to certain conditions. If the requirements are not met, an error mark will be displayed.

===Mobile UI===

The UI DSL supports a variety of elements that are optimised for display on mobile devices. Mobile UIs are described in <code>.uimodel</code> files similar to regular UI models. The main difference is that the top level element in a mobile UI is a "mobile view" (instead of an desktop view or "ideview"), created by the keyword <code>mobile</code>.

Most of the UI elements that can be used in a desktop view (ideview) can be used inside a mobile view as well. In particular, these are:

* <code>combo</code>
* <code>datefield</code>
* <code>decimalField</code>
* <code>horizontalLayout</code> - here they are called <code>mobileHorizontalLayout</code>
* <code>label</code>
* <code>numericField</code>
* <code>optionsgroup</code>
* <code>progressbar</code>
* <code>searchfield</code>
* <code>searchPanel</code> - here called <code>mobileSearchPanel</code>
* <code>tab</code>
* <code>table</code>
* <code>tabsheet</code> - here called <code>mobileTab</code>
* <code>textarea</code>
* <code>textfield</code>
* <code>verticalLayout</code> - here called <code>mobileVerticalLayout</code>

If these model elements are used in a mobile environment, they will be rendered by the appropriate UI elements for Vaadin mobile UIs.

====Mobile-only Elements====

In addition to the mobile version of "desktop" UI elements, currently there is one additional UI element that can only be used in mobile UIs:

=====<code>switchIt</code>=====

A toggle switch for use in mobile UIs is generated with the <code>switchIt</code> keyword. Switches serve the same purpose in mobile UIs that checkboxes do for desktop UIs. A switch can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
switchIt [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
mobile Sample {
verticalGroup Options {
switchIt Active
} align fill-fill
}
</syntaxhighlight>

In the above example, a "sliding style" switch is created with the <code>switchIt</code> keyword.

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T16:31:26Z

Wu: /* Mobile UI */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

A text feld is generated with the <code>textfield</code> keyword. Textfields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following "datatype validators" may be defined in the parentheses between the keyword and the name:

* <code>maxLength</code> - creates a maximum-length validator for this field
(integer)
* <code>minLength</code> - creates a minimum-length validator for this field
(integer)
* <code>regex</code> - creates a regular expression validator for this field (String)

Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textfield [( [maxLength=<maxLength>]
[minLength=<minLength>]
[regex=<rexegString>]
[i18n <i18nKey>]
[styles <stylesString>]
[readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield (regex="[A-Z]-[0-9]{4}") TestText
}
}
</syntaxhighlight>

In the above example, a textfield is created along with validators that check the input in the UI field for conformity to certain conditions. If the requirements are not met, an error mark will be displayed.

===Mobile UI===

The UI DSL supports a variety of elements that are optimised for display on mobile devices. Mobile UIs are described in <code>.uimodel</code> files similar to regular UI models. The main difference is that the top level element in a mobile UI is a "mobile view" (instead of an desktop view or "ideview"), created by the keyword <code>mobile</code>.

Most of the UI elements that can be used in a desktop view (ideview) can be used inside a mobile view as well. In particular, these are:

* <code>combo</code>
* <code>datefield</code>
* <code>decimalField</code>
* <code>horizontalLayout</code> - here they are called <code>mobileHorizontalLayout</code>
* <code>label</code>
* <code>numericField</code>
* <code>optionsgroup</code>
* <code>progressbar</code>
* <code>searchfield</code>
* <code>searchPanel</code> - here called <code>mobileSearchPanel</code>
* <code>tab</code>
* <code>table</code>
* <code>tabsheet</code> - here called <code>mobileTab</code>
* <code>textarea</code>
* <code>textfield</code>
* <code>verticalLayout</code> - here called <code>mobileVerticalLayout</code>

If these model elements are used in a mobile environment, they will be rendered by the appropriate UI elements for Vaadin mobile UIs.

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T16:27:36Z

Wu: /* textfield */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

A text feld is generated with the <code>textfield</code> keyword. Textfields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following "datatype validators" may be defined in the parentheses between the keyword and the name:

* <code>maxLength</code> - creates a maximum-length validator for this field
(integer)
* <code>minLength</code> - creates a minimum-length validator for this field
(integer)
* <code>regex</code> - creates a regular expression validator for this field (String)

Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textfield [( [maxLength=<maxLength>]
[minLength=<minLength>]
[regex=<rexegString>]
[i18n <i18nKey>]
[styles <stylesString>]
[readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield (regex="[A-Z]-[0-9]{4}") TestText
}
}
</syntaxhighlight>

In the above example, a textfield is created along with validators that check the input in the UI field for conformity to certain conditions. If the requirements are not met, an error mark will be displayed.

===Mobile UI===

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T16:20:05Z

Wu: /* textarea */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====
A text area is generated with the <code>textarea</code> keyword. Text areas can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
textarea [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textarea MyText
}
}
</syntaxhighlight>

In the above example, a text area is created with the <code>textarea</code> keyword.

=====<code>textfield</code>=====

===Mobile UI===

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T16:16:10Z

Wu: /* table */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====
A table is generated with the table keyword. Tables can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a table may be given a datatype (e.g. a DTO) that can be set with the type keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If images are to be displayed in the table, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set.

The values that are to be displayed can be fed into the table by databinding (see section "databinding" below). The columns displayed and their order are determined by the column keywords in the columns section of the table. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified. Columns are enumerated within the columns environment. For each column, the content has to be specified. This can be done by specifying a property of the datatype contained within the table. These properties may be nested.

'''Syntax''':

<syntaxhighlight lang="java">
table [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[imageField <imageField>]
[useBeanService]
[readonly]
[columns {
[column <content>] [icon <iconString>]
}]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

table DataTable {
useBeanService
type net.osbee.sample.foodmart.dtos.general.VegetableDto

columns {
column category
column weight
column color
column origin
}

bind tableRefresh --> [this].refresh
} align fill-fill

</syntaxhighlight>

In the above example, a table is created with the <code>table</code> keyword. A BeanService is used, and a datatype is assigned to the table. Columns and their order are specified in the columns section.
The values are entered into the table by databinding.

=====<code>textarea</code>=====

=====<code>textfield</code>=====

===Mobile UI===

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T15:29:43Z

Wu: /* searchfield and searchPanel */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

A search field is generated with the <code>searchfield</code> keyword. Search fields must be located inside a search panel. They provide wildcard support for search actions. A search field can be given an i18n key and a string with CSS styles. The property of the datatype that is searched must be specified.

The datatype that is searched is defined in the <code>searchPanel</code> around the search field. A search panel can be given a name, an <code>i18n</code> key and a string with CSS styles. In curly braces, the datatype that shall be searched can be specified, and search fields for various properties of this datatype (nested properties are supported), databinding instructions and visibility processor directives may be defined. After the closing braces, an alignment may be specified. More about search is covered in section "search" below.

'''Syntax''':

<syntaxhighlight lang="java">
searchPanel [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[searchfield [( [i18n <i18nKey>]
[styles <stylesString>] )] <property>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

searchPanel SearchPanel {
type net.osbee.sample.dtos.CurrencyDto
searchfield abbrivation
searchfield fullname
} align top-fill

</syntaxhighlight>

In the above example, two search panels are created with the <code>searchPanel</code> keyword. They may be given a datatype to be searched. The single properties in which can be searched are specified in search fields.

=====<code>table</code>=====

=====<code>textarea</code>=====

=====<code>textfield</code>=====

===Mobile UI===

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T14:43:37Z

Wu: /* optionsgroup */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

=====<code>table</code>=====

=====<code>textarea</code>=====

=====<code>textfield</code>=====

===Mobile UI===

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T14:40:10Z

Wu: /* referenceField */

==Purpose==

The UI DSL facilitates the creation of model-based user interfaces (UIs) and their integration into complex applications. It is not intended for styling and design specifications.

Using UI DSL, layouts and fields can easily be defined along with the appropriate validation and binding mechanisms. The underlying ECView model uses Eclipse databinding to create an efficient databinding between UI elements and the Java objects they represent. The UI model is kept independent of rendering implementations so that it can be easily re-used.

By referencing DTO models (as defined by the [[DTO DSL]]) in the UI DSL, UI model and internal application logic can be tightly interwoven. The ECView UI model is extensible and allows for a straightforward implementation of new UI elements.

The UI DSL is used to define UI models along with the '''desired''' validators and databindings. Valid UI DSL files are compiled to ECView model definitions (Java classes) that are interpreted by the UI renderer in real time. Thus, the UI DSL acts as a simplified frontend for the ECView model.

In the reference implementation, Vaadin has been chosen as the UI framework that is used to render the UI model. However, since the model-view-controller distinction has been observed, it is possible to change the rendering service without having to change the underlying UI model. For example, JavaFX might be used to render the exact same UI model as Vaadin.

ECView is a UI model based on the Eclipse Modeling Framework (EMF). It defines various UI elements and their properties and possible relations. UI elements are thus represented as EObjects and can be manipulated accordingly. Furthermore, databinding can be done efficiently by using the Eclipse databinding mechanism. ECView attaches so-called editparts to its model elements. Acting as controllers, these editparts tie the application's model and its visual representation together. Editparts are responsible for making changes to the model. ECView provides support for various validation mechanisms (min-length, max-length, regex ...). The UI DSL can make use of such validations easily and allows the definition of additional custom validators using Xexpressions. Application logic can interface with the UI model using the editparts of the respective model elements (reading values, changing visibility etc.). Furthermore, the rendered UI may be addressed by application logic directly, if necessary.

[[File:uidsl-1.png|center|frame|''Figure 1: Architecture - the UI DSL helps to define an ECView UI model that is propagated to the rendering layer (Vaadin) by editparts.'']]

==UI Model Files==

UIs are defined in text files with the file extension <code>.ui</code>. These UI model files carry the information necessary to render a user interface and are made up of the following sections:

*Package declaration: The UI model file must have a unique fully qualified name that can be specified with the package keyword at the beginning of the file.
*Import section: UI model files can address definitions from other models (e.g. datasource or validator specifications). The model files that contain these definitions can be specified with the import keyword followed by the fully qualified name of the file and the <code>*</code> wildcard.
*Validator definitions: The UI DSL supports the usage of validators that can be attached to UI elements directly in the UI model file. If validators are to be used for several UI elements, they may be defined once in this section and given an alias that can then be used to attach them to other UI elements. A validator can be defined for later use by the <code>validatorAlias</code> keyword.
*The UI model definitions: The UI is described as a tree-like containment structure, starting with the root element. This can either be an <code>ideview</code> (for a desktop view) or a <code>mobile</code> (for a view optimized for smartphones).

There are two Eclipse views that can be used for UI preview: A "Vaadin IDE Preview" view that displays a "desktop" UI and a "Vaadin Mobile Preview" view that renders a mobile UI. Both views are generated from the current <code>.ui</code> model file.

[[File:uidsl-2.png|center|frame|''Figure 2: UI model file - After the package name specification and an import declaration, a view is described. This file is automatically translated to an ECView model that is rendered by the Vaadin UI.'']]

==Syntax==

The UI model DSL uses keywords to define UI elements. The UI elements represent a containment tree starting with either an <code>ideview</code> or a <code>mobile</code> view as topmost element. In order to reflect the containment structure, keywords for UI elements may be followed by braces that surround the keywords for contained elements.

===Package Definition===

With <code>package</code> keyword, the user defines the UI package that contains views.

► '''Example''':
<syntaxhighlight lang="java">
package <UImodel name> {
<views>
}
</syntaxhighlight>

===Views===

A view is the topmost UI element and can contain further UI elements. Currently two type of views are supported: <code>ideview</code> for desktop, and <code>mobile</code> view for mobile devices.

====<code>ideview</code>====

This keyword defines a desktop view. It is used as a root element for rendering the UI. An ideview may be given a name; it can contain the following elements:

* <code>sharedStateGroup</code> definition (optional): Views may belong to one shared state group if an <code>ISharedStateContext</code> is provided by the <code>ViewContext</code>. Shared state groups are used by <code>IBeanSearchService</code> to provide and handle a consistent set of data shared across multiple views. This comes with a shared "dirty" state for changed data that have not yet been written to the database. Shared state groups are identified by a String.
* <code>category</code> definition (optional): Views may be assigned to categories that are handled by external frameworks. This setting has no effect within the UI DSL, but can be used to pass information to an external framework.
* <code>exposedActions</code> (optional): actions that are defined within the view, but can be executed from without (e.g. load, save, delete etc.).
* <code>datasource</code> and data alias definitions (optional).
* UI elements: These elements make up the visible content of the view. They may be hierarchically nested.
* "global" validation assignments (optional).
* <code>databinding</code> assignments (optional).
* visibility processor directives (optional).

====<code>mobile</code>====

This keyword defines a view optimized for mobile devices such as smartphones or tablets. This "mobile" view serves as topmost UI element and can contain further UI elements. In addition to the elements supported by <code>ideview</code>, mobile views also control transitions between pages.

[[File:uidsl_03.png|center|frame|''Figure 3: Example - A <code>.uimodel</code> file defines an <code>ideview</code> inside a package. The <code>ideview</code> contains <code>sharedStateGroup</code>, <code>exposedActions</code>, <code>category</code> and <code>datasource</code> definitions, a <code>verticalLayout</code> with the visible UI elements and <code>bind</code> databinding directives.'']]

===UI Elements===

The following sections describe the keywords that define basic UI elements. Most of them can be used in both <code>ideview</code> and <code>mobile</code> contexts.

====Layouts====

=====<code>horizontalLayout</code>=====

A horizontal layout can be generated with the <code>horizontalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a horizontal layout, elements are arranged next to each other with labels above the element.

Autowiring information, databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

horizontalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
textfield Name
textfield City
textfield State
}
}

</syntaxhighlight>

The above example will arrange three text fields next to each other.

=====<code>verticalLayout</code>=====

A vertical layout can be generated with the <code>verticalLayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a vertical layout, elements are arranged above each other with labels above the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

verticalLayout [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
[autowire source <autowireSource>]
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Address {
verticalLayout person {
textfield Name
textfield Street
decimalField Number
}
}

</syntaxhighlight>

The above example will arrange three text fields stacking above each other.

=====<code>gridlayout</code>=====

A gridlayout can be generated with the <code>gridlayout</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a <code>gridlayout</code>, elements are arranged in columns, the rows being filled from left to right. Element labels are displayed above the element. In parentheses after the keyword, the desired number of columns may be specified (default is 2), and an <code>i18n</code> key, a string with CSS styles and a readonly flag may be given.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

gridlayout [( [columns=<columnNumber>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Target {
gridlayout (columns=2) {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, a gridlayout arranges its elements in rows and columns. The rows are filled from letf to right, then the columns from top to bottom.

=====<code>form</code>=====

A form layout can be generated with the <code>form</code> keyword and can optionally be given a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag. In a form layout, elements are arranged in a column. Element labels are displayed on the left side of the element.

Databinding instructions and visibility processor directives may be defined separately for each layout. After the closing braces, an alignment may be specified.

'''Note''': A form layout disables alignment specifications for the elements contained in it.

'''Syntax''':

<syntaxhighlight lang="java">

form [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<layoutname>] {
<UI elements>
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

ideview Target {
from AdressForm {
textfield Name
textfield Street
decimalField number
}
}

</syntaxhighlight>

In the above example, the form layout will lists the contained elements below each other, and set the labels to the left of the elements.

====Tabs and Tabsheets====

Tabs are similar to layouts insofar as they can contain other layouts. Tabs themselves have to be contained inside a <code>tabsheet</code>, however. The tabsheet in its turn can reside inside a layout or be directly attached to a view. Similarly to layouts, tabsheets can be nested (a tab can contain an "inner" tabsheet). Below shows an illustration of these containment possibilities:

[[File:uidsl-5.png|center|frame|''This graph illustrates how the various elements of the UI DSL can be contained in each other.'']]

=====<code>tabsheet</code>=====

A tabsheet is created by using the <code>tabsheet</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. The tabs contained in the tabsheet are described within the braces following the tabsheet statement: Each tab is introduced with the tab keyword followed by a name and the tab contents: either a single UI element or a layout with several UI elements.

'''Syntax''':

<syntaxhighlight lang="java">
tabsheet [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[tab <name> <tabContent>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

=====<code>tab</code>=====

A tab may carry a single UI element, a layout or a tabsheet. Tabs must reside in tabsheets. After the tab keyword, a tab may be given a name, followed directly by the tab content.

'''Syntax''':

<syntaxhighlight lang="java">
tab <name> <tabContent>
</syntaxhighlight>

'''Sample''':

<syntaxhighlight lang="java">
package net.osbee.sample.pos.uimodels

ideview Location {
tab one form CurrentLocation {
textfield Name
textfield Street
numericField Number
}
tab two textarea Overview
}
</syntaxhighlight>

In the above example, a tabsheet holds tabs that can contain either single UI elements or layouts.

====Dialogs====

Dialogs are a special case of layouts: They open in new "views" that are laid over the ordinary UI; much like pop-up windows. Dialogs are a dynamic feature of the UI and are opened with commands, see section "Commands" below for commands that can be used.

=====<code>dialog</code>=====

A dialog is created by using the <code>dialog</code> keyword (optionally followed by an <code>i18n</code> key and/or a string with CSS styles) and can be given a name. A dialog may be given a type, and it can contain UI elements.

Databinding instructions and visibility processor directives may be defined separately for each layout.

'''Syntax''':

<syntaxhighlight lang="java">

dialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[<UI elements>]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

=====<code>searchdialog</code>=====

A search dialog is similar to a regular dialog. It is created with the <code>searchdialog</code> keyword. The difference is that in a search dialog, search fields may be specified. The search dialog provides wildcard support for the search fields, see section "searching" below for details.

'''Syntax''':

<syntaxhighlight lang="java">

searchdialog [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type]
[search { <searchfields> }]
[content { <UI elements> }]
[bind <binding>]
[visibility <directive>]
}

</syntaxhighlight>

====Simple UI Elements====

The UI DSL supports a wide range of "simple" UI elements. This section documents these elements along with their appropriate options.

=====<code>button</code>=====

A push button is generated with the <code>button</code> keyword. Buttons can receive a name, an <code>i18n</code> key, a string with CSS styles, a <code>readonly</code> flag and an alignment specification.

'''Syntax''':

<syntaxhighlight lang="java">

button [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Location {
horizontalLayout person {
button clickMe align top-right
button (readonly) doNotClickMePlease
}
}

</syntaxhighlight>

The above example will create two buttons with the lower one set to read-only (disabled).

=====<code>checkbox</code>=====

A checkbox is generated with the checkbox keyword. Checkboxes can receive a name, an <code>i18n</code> key, a string with CSS styles and a <code>readonly</code> flag.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

checkbox [( [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
verticalLayout person {
checkbox clickMe
checkbox (readonly) doNotClick
}
}

</syntaxhighlight>

The above example will create two checkboxes, with the second one disabled.

=====<code>combo</code>=====

An combo box is generated with the combo keyword. Combo boxes can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the type keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the options group, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions, and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

combo [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
combo Combo {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Combo].collection
}

</syntaxhighlight>

In the above example, combo boxes are created with the <code>combo</code> keyword, shown as image icons with the given caption. The values displayed are retrieved via databinding.

=====<code>datefield</code>=====

A datefield is generated with the <code>datefield</code> keyword. Datefields can receive a name, an <code>i18n</code> key, a string with CSS styles, and a readonly flag.

Furthermore, the following may be defined in parentheses between the keyword and the name:

* date format - one of the following values can be used to define the date format for the field: <code>date</code>, <code>datetime</code> or <code>time</code>. Defaults to <code>date</code>.
* date/time resolution - the smallest unit of time the datefield should consider. Can be set to <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code>, or <code>undefined</code> (default).

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

datefield [( [<dateFormat>] [<dateResolution>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
datefield MyDate
}
}

</syntaxhighlight>

In the above example, a date field is created with the <code>datefield</code> keyword, the Vaadin UI provides a date picker along with the field.

=====<code>decimalField</code>=====

A decimal field contains floating point numbers and is generated with the <code>decimalField</code> keyword. Decimal fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following may be defined in parentheses between the keyword and the given name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.
* <code>precision</code> - this option controls the number of digits after the decimal point to be displayed (integer). Defaults to 2.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

decimalField [( [noGrouping] [noMarkNegative] [precision=<precision>] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview main {
form Person {
decimalField (noGrouping precision=3) noGrp
decimalField (precision=5) Grp
}
}

</syntaxhighlight>

In the example above, decimal fields are created by the <code>decimaField</code> keyword. Mechanisms for controlling the number grouping and for adding a CSS class for negative numbers are available. The desired precision can be set optionally.

=====<code>label</code>=====

A label is generated with the <code>label</code> keyword. Labels can receive a name, an <code>i18n</code> key and a string with CSS styles.

Databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

label [( [i18n <i18nKey>] [styles <stylesString>] [<name>] )] {
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
label MyLabel
}
}

</syntaxhighlight>

The above example will show a label, the most basic UI element.

=====<code>listSelect</code>=====

A list is generated with the <code>listSelect</code> keyword. Lists can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a list may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and <code>readonly</code> may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specfied.

'''Syntax''':

<syntaxhighlight lang="java">

listSelect [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
form ConvertibleForm_left {
listSelect someType {
type net.osbee.sample.pos.dtos.general.SomeType
}
bind convertible.someType <--> [this.someType].selection
} align top-left
}

</syntaxhighlight>

In the above example, options groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>numericField</code>=====

A numeric field contains integers and is generated with the <code>numericField</code> keyword. Numeric fields can receive a name, an <code>i18n</code> key, a string with CSS styles and a readonly flag. Furthermore, the following
may be defined in parentheses between the keyword and the name:

* <code>noGrouping</code> - if this option is given, then the number in the field will not be grouped according to the current locale.
* <code>noMarkNegative</code> - by default, the CSS class "<code>lun-negative-value</code>" is added to the field if the value is negative. This can be disabled with this setting.

Validator assignments, databinding instructions and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">

numericField [( [noGrouping] [noMarkNegative] [i18n <i18nKey>] [styles <stylesString>] [readonly] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]

</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Main {
form person {
numericField (noGrouping) noGrp
numericField Grp
}
}

</syntaxhighlight>

In the above example, numeric fields are generated with the <code>numericField</code> keyword. Among other features, there are options to control the number grouping and a CSS class for negative numbers.

=====<code>optionsgroup</code>=====

An optionsgroup is generated with the <code>optionsgroup</code> keyword. Optionsgroups can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, an optionsgroup may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. The selection type (<code>single</code>, <code>multi</code> or <code>none</code>) can optionally be controlled with the <code>selectionType</code> keyword. If a specific caption to be displayed is stored in the datatype, it can be addressed with the captionField keyword. If images should be displayed in the optionsgroup, the image source path within the datatype can be set with the <code>imagefield</code> keyword.

Furthermore, the flags <code>useBeanService</code> (to look for registered OSGi services from where data can be retrieved) and readonly may be set. Validator assignments, databinding instructions and visibility processor directives may be defined.

After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
optionsgroup [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[selectionType <selectionType>]
[captionFiend <captionField>]
[imageField <imageField>]
[useBeanService]
[readonly]
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
datasource ds : net.osbee.sample.dtos.onetype
verticalLayout Demo {
optionsgroup Buttons {
type net.osbee.sample.dtos.othertype
captionField name
imageField imagePath
}
}
bind list ds.others --> [this.Demo.Buttons].collection
}

</syntaxhighlight>

In the above example, option groups are created with the <code>optionsgroup</code> keyword. The values displayed are retrieved via databinding.

=====<code>progressbar</code>=====

A progress bar is generated with the <code>progressbar</code> keyword. Progress bars can receive a name, an i18n key and a string with CSS styles. The value that is displayed by the progressbar is a floating point number between 0 and 1. It can be determined by databinding (see section "databinding" below"). Validator assignments, databinding instructions, and visibility processor directives may be defined in braces. After the closing braces, an alignment may be specified.

'''Syntax''':

<syntaxhighlight lang="java">
progressbar [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[<validator assignments>]
[bind <binding>]
[<visibility directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
progressbar Bar
decimalField (precision=2) ValueField
}
bind [ValueField].value --> [Bar].value
}

</syntaxhighlight>

In the above example, a progress bar is created with the <code>progressbar</code> keyword, displaying a value between 0 (0%) and 1 (100%), and the value is retrieved via databinding from a <code>decimalField</code>.

=====<code>referenceField</code>=====

A bean reference field is generated with the <code>referenceField</code> keyword. Bean reference fields look like combo boxes. They are used to display values from collections (tables etc.) that are only referenced in the entity or DTO model. Bean reference fields can receive a name, an <code>i18n</code> key and a string with CSS styles.

Within curly braces, a bean reference field accepts the source of the reference it is supposed to resolve and display after the <code>refSource</code> keyword. Additionally, it may be given a datatype (e.g. a DTO) that can be set with the <code>type</code> keyword. If a specific caption to be displayed is stored in the reference target datatype, it can be addressed with the <code>captionField</code> keyword. If images should be displayed, the image source path within the datatype can be set with the <code>imageField</code> keyword. Furthermore, an in-memory bean provider service may be specified. Validator assignments, databinding instructions and visibility processor directives may be set. After the closing braces, an alignment may be defined.

'''Syntax''':

<syntaxhighlight lang="java">
referenceField [( [i18n <i18nKey>] [styles <stylesString>] )] [<name>] {
[type <type>]
[refSource <type : field>]
[captionField <captionField>]
[imageField <imageField>]
[inMemoryService <inMemoryBeanProvider>]
[<validator assignments>]
[bind <binding>]
[visibility <directive>]
} [align <alignment>]
</syntaxhighlight>

'''Example''':

<syntaxhighlight lang="java">

package net.osbee.sample.pos.uimodels

ideview Sample {
verticalLayout Demo {
textfield description {
MinLengthValidator(3)
MaxLengthValidator(125)
}
checkbox(readonly) dirty
referenceField weightUom {
type net.osbee.sample.pos.dtos.general.UnitOfMeasureDto
captionField description
refSource net.osbee.sample.pos.dtos.general.WeightDto:uom
}
referenceField priceCurrency {
type net.osbee.sample.pos.dtos.general.CurrencyDto
captionField iso3code
refSource net.osbee.sample.pos.dtos.general.PriceDto:currency
}
bind main.description <--> [this.description].value
bind main.dirty --> [this.dirty].value
bind main.weight.uom <--> [this.weightUom].value
bind main.price.currency <--> [this.priceCurrency].value
}
}

</syntaxhighlight>

In the above example, Reference fields are created with the <code>referenceField</code> keyword. The values displayed are retrieved from a referenced entity or DTO.

=====<code>searchfield</code> and <code>searchPanel</code>=====

=====<code>table</code>=====

=====<code>textarea</code>=====

=====<code>textfield</code>=====

===Mobile UI===

===Alignment===

===i18n===

===Datasources===

===Databinding===

===Shared State Groups===

===Validation===

====<code>BeanValidationValidator</code>====

====<code>Expression</code>====

====<code>MaxLengthValidator</code>====

====<code>MinLengthValidator</code>====

====<code>RegexValidator</code>====

===Commands===

===Search===

===Exposed Actions===

===Visibility Processing===

UI DSL

2017-10-26T13:57:16Z

Wu: /* progressbar */

UI DSL

2017-10-26T11:52:59Z

Wu: /* optionsgroup */

UI DSL

2017-10-26T09:28:33Z

Wu: /* numericField */

UI DSL

2017-10-25T16:30:06Z

Wu: /* listSelect */

UI DSL

2017-10-25T16:29:26Z

Wu: /* listSelect */

UI DSL

2017-10-25T14:55:20Z

Wu: /* label */

UI DSL

2017-10-24T16:05:19Z

Wu:

UI DSL

2017-10-23T16:32:15Z

Wu:

UI DSL

2017-10-19T15:58:11Z

Wu:

UI DSL

2017-10-19T15:46:41Z

Wu: /* searchdialog */

UI DSL

2017-10-17T14:58:46Z

Wu: /* RegexValidator */

UI DSL

2017-10-17T14:56:16Z

Wu: /* Validators */

UI DSL

2017-10-17T14:55:51Z

Wu: /* Mobile UI */

UI DSL

2017-10-17T14:51:28Z

Wu: /* Dialogs */

UI DSL

2017-10-16T09:39:51Z

Wu: /* Dialogs */

UI DSL

2017-10-13T14:40:54Z

Wu: /* dialog */

UI DSL

2017-10-12T16:01:45Z

Wu: /* Tabs and Tabsheets */

UI DSL

2017-10-10T11:59:49Z

Wu: /* =Dialogs */

UI DSL

2017-10-10T11:59:37Z

Wu: /* Tabs and Tabsheets */

File:Uidsl-5.png

2017-10-10T11:52:06Z

Wu:

UI DSL

2017-10-10T11:51:47Z

Wu: /* Tabs and tabsheets */

UI DSL

2017-10-10T11:47:37Z

Wu: /* form */

UI DSL

2017-10-10T10:01:01Z

Wu: /* verticalLayout */

UI DSL

2017-10-10T10:00:28Z

Wu: /* gridlayout */

UI DSL

2017-10-06T09:42:28Z

Wu: /* gridlayout */

UI DSL

2017-10-06T09:42:18Z

Wu: /* verticalLayout */

UI DSL

2017-10-06T09:41:42Z

Wu: /* verticalLayout */

UI DSL

2017-10-05T07:52:41Z

Wu: /* verticalLayout */

UI DSL

2017-10-05T07:52:31Z

Wu: /* horizontalLayout */

UI DSL

2017-10-04T16:09:22Z

Wu: /* horizontalLayout */

UI DSL

2017-10-04T09:33:18Z

Wu: /* horizontalLayout */

UI DSL

2017-10-04T09:33:04Z

Wu: /* mobile */

File:Uidsl 03.png

2017-10-04T08:17:51Z

Wu:

UI DSL

2017-10-04T08:17:27Z

Wu: /* ideview */

UI DSL

2017-09-29T16:10:12Z

Wu: /* Views */