Difference between revisions of "Action DSL"

From OS.bee documentation
Jump to: navigation, search
(→‎Items&item)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
  
−
===CRUD for toolbar===
+
==Purpose==
  
−
Editing data is nice but data must be persisted otherwise all effort invested in editing data would be lost. For this reason, OS.bee apps come with a set of create, read, update and delete functionality (CRUD) to manipulate data in a database. OS.bee can be operated with different database products.
+
Editing data is nice, but it must be persisted otherwise all effort invested in its editing would be lost. For this reason, OS.bee apps come with a set of create, read, update and delete functionality (CRUD) to manipulate data in a database. OS.bee can be operated with different database products by allowing user to:
 +
* Create: Create or add new entries.
 +
* Read: Read, retrieve, search or view existing entries from the database.
 +
* Update: Update or edit existing entries in the underlying database.
 +
* Delete: Delete, deactivate or remove existing entries from the database.
 +
Each one of those functions is made available in OS.bee through the application for interactions with the user, after being defined in the Action DSL Model. In the following sections, you will get a closer look on how to the Action DSL works and how you can create basic and custom commands in order to make them available to the user.  
  
−
====Create====
 
  
−
Create or add new entries.
+
==Overview==
 +
The ActionDSL facilitates the implementation of certain interactions done by users through the application. It currently allows you to define toolbars after setting up beforehand the commands that will be triggered and executed. Custom made functions can also be implemented and attached (bound) to some items in the same manner as described in the sections below.
  
−
If you want to create new data entry, please press the “new data” action button, after the action has been executed, a new unique id must be created. <br><br>[[File:ActionDSL_01.png|600px]]<br><br>
+
It provides a Command Provider, which encapsulates a Binding Context to the application view model (based on E4) and a Command Handler listing all defined actions (commands), which can be executed either application wide or in a single view.  
  
−
====Read====
+
[[File:ActionDSLOverview.png|center|frame|''Figure 1: Architectur Action DSL'']]
  
−
Read, retrieve, search or view existing entries.
 
  
−
Existed data can be read from the database. If you request existed data to be displayed in the UI, you must either retrieved a unique id to the database so it can select the requested data, or you can search and select one.
+
==Action Model Files==
 +
The Action DSL works for Os.bee models, it defines the actions for '''task''', '''select workload''', '''dialog''', '''report''', '''chart''', '''workflow''', '''datainterchange''', '''functions''' and '''user interface'''. These actions are defined in text files with the file extension .action. Action model files carry the information necessary to create interaction components that will be executed in the background of the user interface.  
  
−
In Os.bee web site, for example the perspective of “Persons”, you can click one row from the table on the left, then the detail data will be read from database and shown in the dialog on the right. <br><br>[[File:ActionDSL_02.png|600px]]<br><br>
+
Action model files are made up of the following sections:
 +
* Package declaration: The Action model file must have a unique fully qualified name that can be specified with the keyword package at the beginning of the file.
 +
* Import section: Action model files can address definitions from other models (e.g. Datainterchange, Function Library or Message DSL’s specifications) or other action model files. 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 * wildcard.
 +
* Command section: The command section contains all the action command definitions that have to be defined to be used later on in the same model file.
 +
* Toolbar section: The toolbar section contains all toolbar definitions, which are later used to build part of the user interface through the Dialog DSL among others.
  
−
====Update====
+
===package defintion===
 +
With the keyword '''package''' followed by a qualified name, you define the root element that contains all the other elements. A model can contain multiple packages.
  
−
Update or edit existing entries.
+
► '''Syntax''':
 +
<syntaxhighlight lang="java">
 +
package <package name>[{
  
−
After editing your data, please press the “save” button and the data will be saved in the underlying database. <br><br>[[File:ActionDSL_03.png|600px]]<br><br>  
+
command <command name> [describedBy <description>] [key binding <binding combination>] [key binding <binding combination>] actionType <action rule>
  
−
====Delete====
+
toolbar <toolbar name> [describedBy <description>] [items { . . .}]
 +
. . .
 +
} ]
 +
</syntaxhighlight>
  
−
Delete, deactivate or remove existing entries.
 
  
−
If you don’t need an existing entry, please select it and press the “delete” button, then this data will be remove from the underlying database.
+
One or more '''command''' can be defined in the same '''package''', as well as the many '''toolbars''' using those commands.  The keyword '''describedBy''' is optional and can be used to define the description of this toolbar.
 +
In the following example, the '''commands''' NEW and SAVE and 1 '''toolbar''' Dialog are defined in the same '''package'''.  
  
−
<br><br>[[File:ActionDSL_04.png|600px]]<br><br>
 
  
−
==ActionDSl==
+
► '''Example''':
 +
<syntaxhighlight lang="java">
 +
package net.osbee.sample.foodmart.actions {
  
−
The ActionDSL works for Os.bee models, it defines the toolbar actions for task, select workload, dialog, report, chart, workflow, datainterchange, ect..
+
command  NEW describedBy    "create new item" dialogAction    New
 +
command  SAVE describedBy    "save an item" dialogAction    Save
  
−
The main semantic elements of the ActionDSL are:
+
toolbar    Dialog describedBy    "Toolbar for Dialogs"   items { . . . }
 +
}
 +
</syntaxhighlight>
  
−
* “package” - the root element that contains all the other elements. A model can contain multiple packages.
 
  
−
* “toolbar” - define the action details, e.g. toolbar name, description and items…
+
====Commands====
 +
The command section is the main part of this model. All Actions are to be defined here by declaring every command that can be later executed. For each command, a java file named <commandName>+Action.java will be generated in folder ./src-gen/<package name>/. The <action rule> is predefined in '''Action Type''' and will be introduced in the next section.
  
−
* “items” – define the items for this action.
 
  
−
* “item” -  define the function and action type for the item …
+
► '''Syntax''':
 +
<syntaxhighlight lang="java">
 +
command <command name> [key binding <binding combination>] actionType <action rule>
  
−
===Syntax===
 
  
−
====package defintion====
+
actionType:
 +
'''chartAction''' defines action applicable to chart elements.
 +
 
 +
'''datainterchangeAction''' defines action using datainterchange units.
 +
'''dialogAction''' defines basic dialog actions (CRUD).
 +
'''functionalAction''' defines custom actions using operations from the function library.
 +
'''reportAction''' defines report type actions.
 +
'''selectWorkloadAction''' defines select workload actions.
 +
'''taskAction''' defines task actions.
 +
'''userinterfaceAction''' defines actions with direct access and effect on the user interface.
 +
'''workflowAction''' defines workflow actions.
  
−
► '''Syntax''':
 
−
<syntaxhighlight lang="java">
 
−
package <package name>[{
 
−
toolbar <toolbar name> [described by <description>]
 
−
[items { . . .}]
 
−
. . .
 
−
} ]
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
For each toolbar, one .java file named <code><toolbar name>+Action.java</code> will be generated in folder <code>./src-gen/<package name>/</code>.
 
  
−
* One or more '''toolbars''' can be defined in the same '''package'''.
+
The keyword '''describedBy''' is optional and can be used to define the description of a command. With the optional keyword '''keyBinding''' you are able to bind key combinations to commands.
  
−
* Keyword '''descrbied by''' is optional; you can use this keyword to define the description of this toolbar
 
  
−
* One or more '''item''' can be defined in the same '''items''' block.
+
► '''Syntax''':
 +
<syntaxhighlight lang="java">
 +
keyBinding <binding combination >
 +
</syntaxhighlight>
 +
 
 +
The following example illustrates the creation of the four basic dialog action commands (CRUD).
 +
 
  
 
► '''Example''':
 
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
 
package net.osbee.sample.foodmart.actions {
 
package net.osbee.sample.foodmart.actions {
−
toolbar StartTask described by "Toolbar for tables showing tasks"
+
. . .
−
items { . . . }
+
command  NEW describedBy    "create new item" keyBinding  "CTRL ALT N" dialogAction    New
−
toolbar Dialog described by "Toolbar for Dialogs" items { . . . }
+
command  SAVE describedBy    "save an item" keyBinding  "CTRL ALT S" dialogAction    Save
−
toolbar HandleTask described by "Toolbar for BPM oriented perspectives"  
+
command  DELETE describedBy    "delete1 an item" keyBinding  "CTRL ALT D" dialogAction    Delete
−
items { . . . }
+
command  CANCEL describedBy    "undo changes" keyBinding  "CTRL ALT Z" dialogAction    Cancel
−
toolbar Report described by "Toolbar for reports" items { . . . }
+
. . .
−
toolbar WorkloadSelect described by "Toolbar for Workload Selects"  
+
−
items { . . . }
+
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
In this example, 5 '''toolbars''' are defined in the same '''package'''; they are ''StartTask'', ''Dialog'', ''HandleTask'', ''Report'' and ''WorkloadSelect''.
+
Each command has its own key binding combination to be pressed as an alternative action trigger.
  
−
====Items&item====
 
  
−
This is the main part of this model. All the action details can be defined here. For each item, a java file named <code><toolbar name>+<action rule>+Action.java</code> will be generated in folder <code>./src-gen/<package name>/. <action rule></code> is defined in '''ActionType''' and it will be introduced in the next section.
+
====ActionTypes====
 +
 
 +
As already mentioned above there are there are currently eight '''ActionTypes''' to set the command type.  
 +
=====dialogAction=====
 +
 
 +
With the keyword '''dialogAction''' followed by a corresponding action rule, you can define actions for dialogs.  
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
items {
+
dialogAction <dialogAction rule>
−
item <item name> [described by <description>]
+
−
[icon <URI string>]
+
−
[group <func.FunctionLibraryGroup name>
+
−
  [canExecute <func.FunctionLibraryFunction name>]
+
−
& [executeParameter <func.FunctionLibraryFunction name>]
+
−
]
+
−
ActionType
+
−
[message <msg.MessageItem name |QualifiedName>]
+
−
. . .
+
−
}]
+
−
. . .
+
−
} ]
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* Keyword '''icon''' is optional, it define the identifier for a resource, e.g. icon file
+
As you can see in the last example, these are the 4 different dialogAction rules:
 +
* “New” means create a new entry.
 +
* “Save” means save the changing.
 +
* “Delete” means delete the selected entry.
 +
* “Cancel” means ignore the changing.
  
−
* Keyword '''group''',  '''canExecute & executeParameter''' are used to define the predefined function which this item could use from FunctionlibraryDSL.
+
=====taskAction=====
  
−
► '''Example''':
+
With the keyword '''taskAction''' followed by a corresponding action rule, you can define actions for BPM (Business Process Management) tasks to make use of the OS.bee BLIP DSL functionalities.
 +
 
 +
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
toolbar HandleTask described by "Toolbar for BPM oriented perspectives" items {
+
taskAction <taskAction rule>
−
  item stop icon "task_action_stop" group PerspectiveToolbar
+
−
    canExecute stopCanExecute executeParameter getTaskId taskAction Stop
+
−
  . . .
+
−
}
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
In this example, the following code will be generated in the java file of '''item''' '''''stop''''':
+
There are currently 15 different taskAction rules, which correspond to BPM '''tasks''':  
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
@CanExecute
+
Claim, Start, Stop, Release, Suspend, Resume, Skip, Complete, Delegate, Forward, Fail, Register, Remove, Activate, Exit
−
public boolean canExecute() {
+
−
return net.osbee.sample.foodmart.functionlibraries.PerspectiveToolbar
+
−
.stopCanExecute(getContent());
+
−
}
+
−
 
+
−
@Execute
+
−
public void execute(final IEventBroker eventBroker) {
+
−
    log.debug("action execute called for stop");
+
−
    String uuid = (String)eclipseContext.get("HandleTask_TOOLBAR_ID");
+
−
eventBroker.send(
+
−
EventBrokerMsg.ACTION_BUTTON_EXECUTE_PREFIX+ "HandleTaskAction"+uuid,  
+
−
new EventBrokerMsg(-1,  
+
−
"Stop",  
+
−
net.osbee.sample.foodmart.functionlibraries
+
−
.PerspectiveToolbar.getTaskId(getContent())
+
−
)
+
−
);
+
−
}
+
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
* Keyword '''message''' is used to define the action message using predefined message from messageDSL.
 
  
 
► '''Example''':
 
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
toolbar Dialog described by "Toolbar for Dialogs" items {
+
package net.osbee.sample.foodmart.actions {
−
item newItem icon "dsnew" dialogAction New
+
. . .
−
item saveItem icon "dssave" dialogAction Save message  net.osbee.sample.foodmart.messages.FoodMartErrors.DtoService.SaveMsg
+
command  STOP taskAction    Stop
−
item deleteItem icon "dsdelete" dialogAction Delete message net.osbee.sample.foodmart.messages.FoodMartErrors.DtoService.DeleteMsg
+
command  RELEASE taskAction    Release
−
item cancelItem icon "dscancel" dialogAction Cancel
+
command  SUSPEND taskAction    Suspend
 +
command  COMPLETE taskAction    Complete
 +
. . .
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The '''message''' '''''SavMsg''''' and '''''DeleteMsg''''' are defined in messageDSL as following:
 
  
 +
=====selectWorkloadAction=====
 +
 +
With the keyword '''selectWorkloadAction''' followed by a corresponding action rule, you can define actions of type '''select workload'''.
 +
 +
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
package net.osbee.sample.foodmart.messages{
+
selectWorkloadAction <selectWorkloadAction rule>
−
category FoodMartErrors {
+
−
group DtoService {
+
−
message DeleteMsg{
+
−
parameter{
+
−
Exception ex
+
−
String stackTrace
+
−
}
+
−
automatic{}
+
−
format {
+
−
log "%%ex.simpleName%%: Delete not allowed! –
+
−
%%stackTrace%%"
+
−
show "%%ex.simpleName%% - %%ex.localizedMessage%%
+
−
- Delete not allowed!"
+
−
}
+
−
}
+
−
message SaveMsg{
+
−
parameter{
+
−
Exception ex
+
−
String stackTrace
+
−
}
+
−
automatic{}
+
−
format {
+
−
log "%%ex.simpleName%%: Save not allowed! –
+
−
%%stackTrace%%"
+
−
show "%%ex.simpleName%% - %%ex.localizedMessage%%
+
−
- Delete not allowed!"
+
−
}
+
−
}
+
−
}
+
−
}
+
−
}
+
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* '''''ActionType''''' will be introduced in the next section.
+
There are currently 2 select workload action rules available:
 +
<syntaxhighlight lang="java">
 +
RemoveAll, AddAll
 +
</syntaxhighlight>
  
−
====ActionType====
 
  
−
'''ActionType''' sets the type of action for the item.
+
► '''Example''':
 +
<syntaxhighlight lang="java">
 +
package net.osbee.sample.foodmart.actions {
 +
. . .
 +
command REMOVE_ALL_WORKLOAD_ITEMS selectWorkloadAction RemoveAll
 +
command ADD_ALL_SELECTED_ITEMS_TO_THE_WORKLOAD selectWorkloadAction AddAll
 +
. . .
 +
}
 +
</syntaxhighlight>
  
−
There are 8 kinds of action types:
 
  
−
=====taskAction=====
+
=====reportAction=====
  
−
'''''taskAction''''' is used to define the action of task for bpm.
+
With the keyword '''reportAction''' followed by a by a corresponding action rule, you can define actions for '''reports'''.  
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
taskAction <taskAction rule>
+
reportAction <reportAction rule>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* taskAction rule includes 15 rules, and its <action rule> is the same as the following rule:
+
Currently there are 2 different report action rules available:  
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
Claim, Start, Stop, Release, Suspend, Resume, Skip, Complete, Delegate, Forward, Fail, Register, Remove, Activate, Exit
+
Download, PrintOnServer
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
► '''Example''':
 
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
toolbar StartTask described by "Toolbar for tables showing tasks" items {
+
package net.osbee.sample.foodmart.actions {
−
item claim icon "task_action_claim" group TaskToolbar
+
. . .
−
canExecute claimCanExecute executeParameter getTaskId taskAction Claim
+
command PRINT reportAction PrintOnServer
−
item start icon "task_action_start" group TaskToolbar
+
command PRINT_DOWNLOAD reportAction Download
−
canExecute startCanExecute executeParameter getTaskId taskAction Start
+
. . .
−
item start icon "task_action_resume" group TaskToolbar
+
−
canExecute resumeCanExecute executeParameter getTaskId taskAction Resume
+
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=====selectWorkloadAction=====
 
  
−
'''''selectWorkloadAction''''' is used to define the action of select workload.
+
=====chartAction=====
 +
 
 +
With the keyword '''chartAction''' followed by a corresponding action rule, you can define actions for '''charts'''.  
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
selectWorkloadAction <selectWorkloadAction rule>
+
chartAction <chartAction rule>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* selectWorkloadAction rule includes the 2 rules, and its <action rule> is as same as the following rule:<code> RemoveAll, AddAll</code>.
+
Currently the only rule available:
 +
 
 +
<syntaxhighlight lang="java">
 +
ChartDownload
 +
</syntaxhighlight>
 +
 
 +
This action allows you to download a chart as image file.
  
 
► '''Example''':
 
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
toolbar WorkloadSelect described by "Toolbar for Workload Selects" items {
+
package net.osbee.sample.foodmart.actions {
−
item removeAllWorkloadItems icon "task_status_obsolete" selectWorkloadAction  RemoveAll
+
. . .
−
item addAllSelectedItemsToTheWorkload icon "import"            selectWorkloadAction AddAll
+
command SAVE_CHART chartAction ChartDownload
 +
. . .
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=====dialogAction=====
 
  
−
'''DialogAction''' is used to define the actions for dialog.  
+
[[File:PaymentChart.png|center|frame|''Figure 2: Payment Chart'']]
 +
 
 +
Further information can be viewed in the [[Chart DSL]] documentation page.
 +
 
 +
 
 +
=====workflowAction=====
 +
 
 +
With the keyword '''workflowAction''' followed by a corresponding action rule, you can define actions for '''workflows'''.  
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
dialogAction <dialogAction rule>
+
workflowAction <workflowAction rule>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* dialogAction rule includes the 4 rules, and its <action rule> is as same as the following rule: <code>New, Save, Delete, Cancel</code>
+
Currently only one action rule is available:
 +
 
 +
<syntaxhighlight lang="java">
 +
Start
 +
</syntaxhighlight>
  
 
► '''Example''':
 
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
toolbar Dialog described by "Toolbar for Dialogs" items {
+
package net.osbee.sample.foodmart.actions {
−
item newItem icon "dsnew" dialogAction New
+
. . .
−
item saveItem icon "dssave" dialogAction Save message  net.osbee.sample.foodmart.messages.FoodMartErrors.DtoService.SaveMsg
+
command START workflowAction Start
−
item deleteItem icon "dsdelete" dialogAction Delete message net.osbee.sample.foodmart.messages.FoodMartErrors.DtoService.DeleteMsg
+
. . .
−
item cancelItem icon "dscancel" dialogAction Cancel
+
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* “new” means create a new entry.
 
  
−
* “save” means save the changing.
+
=====datainterchangeAction=====
  
−
* “delete” means delete the selected entry.
+
With the keyword '''datainterchangeAction''' followed by a corresponding action rule, you can define actions for data interchange, and so forth using data interchange unit functionalities.
−
 
+
−
* “cancel” means ignore the changing.
+
−
 
+
−
Here is the dialog view in perspective, in which the 4 buttons do the actions by clicking them: <br><br>[[File:ActionDSL_05.png|600px]]<br><br>
+
−
 
+
−
=====reportAction=====
+
−
 
+
−
'''''ReportAction''''' is used to define the actions for report.
+
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
reportAction <reportAction rule>
+
datainterchangeAction <datainterchangeAction rule> <datainterchangeUnit name>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* reportAction rule includes the 2 rules: PrintOnServer, Download.
+
Currently there are 2 datainterchange action rules available:  
  
−
* Its <action rule> is PrintOnServer and ReportDownload.
+
<syntaxhighlight lang="java">
 +
Import, Export
 +
</syntaxhighlight>
 +
 
 +
Please note that the data interchange units have to be already defined in the Datainterchange DSL in order to be used via imports in the Action DSL.
  
 
► '''Example''':
 
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
toolbar Report described by "Toolbar for reports" items {
+
package net.osbee.sample.foodmart.actions {
−
item print icon "print" reportAction Download
+
. . .
−
item print icon "xml" reportAction PrintOnServer
+
command CURRNAMESIMPORT datainterchangeAction Import CurrencyNames
 +
command CURRIMPORT datainterchangeAction Import Currencies
 +
. . .
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=====chartAction=====
 
  
−
'''''chartAction''''' is used to define the actions for chart.
+
 
 +
=====userinterfaceAction=====
 +
 
 +
With the keyword '''userinterfaceAction''' followed by a corresponding action rule, you can define actions which affect directly the user interface as a whole.
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
chartAction Download
+
userinterfaceAction <userinterfaceAction rule>
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* Its <action rule> is '''''ChartDownload'''''.
+
Currently only one action rule is available:
  
−
=====workflowAction=====
+
<syntaxhighlight lang="java">
 +
SwitchPart
 +
</syntaxhighlight>
  
−
'''''workflowAction''''' is used to define the actions for workflow.
+
This only option allows the user to jump from a view to another one inside a perspective.  
  
−
► '''Syntax''':
+
 
 +
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
workflowAction Start
+
command SWITCH describedBy "move to next part" keyBinding "ALT F6" userinterfaceAction SwitchPart
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* Its <action rule> is '''''start'''''.
+
The example above illustrates how a user interface action command with the command name ''SWITCH'' is defined with the option SwitchPart. You may notice here that a keyBinding has been attached to this command, which means that a user is now capable of switching between views by pressing the key combination ALT + F6. The figures bellows illustrate that effect.
  
−
=====genericAction=====
+
[[File:SwitchPartA.png|center|frame|''Figure 4: SwitchPart before'']] [[File:SwitchPartB.png|center|frame|''Figure 5: SwitchPart after'']]
  
−
'''''genericAction''''' is used to define the actions for yourself. You can define it as you will.
+
You may notice the orange rectangle on each the figure shown above, which highlights the actual '''active view''': the view which is currently '''focused''' on.
 +
 
 +
 
 +
 
 +
=====userinterfaceAction=====
 +
 
 +
The action type '''functionalAction''' is used to define custom action commands, which have to be linked with operations defined in the FunctionlibraryDSL. You can define a functional action command using the type functionalAction followed by the keywords group, canExecute and executeImmediate or executeLater like shown below.  
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
genericAction <STRING>
+
functionalAction group <FunctionGroupName> canExecute <FunctionName#1> executeImmediate|executeLater <FunctionName#2> [messageCategory-definition]
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* Its <action rule> is '''''the string'''''.
+
Those keywords are needed to make the link between the command and the predefined function inside which this item could use from Function Library DSL:
 +
* group: specifies a unique group of functions defined in the function library to be used.
 +
* canExecute: sets a test operation, which can be performed before executing the actual and expected business logic.
 +
* executeImmediate: indicates that the business logic has to be executed right away, so that any results can be observed right away.
 +
* executeLater: indicates that the business logic has to be executed with delay asynchronously.
  
−
=====datainterchangeAction=====
+
It is also possible to extend the functional action command definition with an optional message output definition. It basically allows you to define a set output messages to be seen in form of pop up dialogs, which would be shown to the user depending on the outcome of its interaction.
  
−
'''''datainterchangeAction''''' is used to define the actions for data interchange
 
  
 
► '''Syntax''':
 
► '''Syntax''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
datainterchangeAction <datainterchangeAction rule> <data.DataInterchange name>
+
[messageCategory <messageCategoryName> onFailMessage|onSuccessMessage|onStartedMessage <messageName>]
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
* datainterchangeAction type includes the following types, and its <action rule> is as same as the following rule:  '''Import, Export'''.
+
Those messages are predefined in the Message DSL and can be linked to the command using the keyword '''messageCategory''' followed by the message category name and the condition, which has to be fulfilled to show the message:
 +
* onFailMessage: shows the message after a failed outcome of the action.
 +
* onSuccessMessage: shows the message after a successful outcome of the action.
 +
* onStartedMessage: shows the message right away.  
  
−
* The data interchange should be predefined in datainterchangeDSL.
 
−
 
−
The following code will be generated in the java file of '''item''':
 
  
 +
► '''Example''':
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
@Execute
+
command FIRE_EMPLOYEE     functionalAction group Employee canExecute canFire executeImmediate fire messageCategory Employee onFailMessage FireNotAllowed onSuccessMessage Fired
−
  public void execute(final IEventBroker eventBroker) {
+
 
−
     <datainterchange qualified name> <datainerchange name> = new <datainterchange qualified name>();
+
command FIRE_EMPLOYEE_ASYNC functionalAction group Employee canExecute canFire executeLater   fire  messageCategory Employee onStartedMessage FireStarted
−
    <datainerchange name>.setFileURL(<file path URL String>
+
 
−
    <datainerchange name>.setPersistenceService(persistenceService);
+
−
    <datainerchange name>.setDirection(WorkerThreadRunnable.Direction.IMPORT);
+
−
    <datainerchange name>.setEventBroker(eventBroker);
+
−
    <datainerchange name>.setEventDispatcher(eventDispatcher);
+
−
    executorService.execute(<datainerchange name>);
+
−
  }
+
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 +
 +
[[File:ExcerptFuncLibDSL.png|center|frame|''Figure 6: Excerpt - Function Library DSL Model'']] [[File:ExcerptMessageDSL.png|center|frame|''Figure 7: Excerpt - Message DSL Model'']]
 +
 +
Please note that no information or error message will be shown to the user, unless you explicitly define and set a message category to your functional action command.
 +
 +
 +
  
 
== Copyright Notice ==
 
== Copyright Notice ==
 
{{Copyright Notice}}
 
{{Copyright Notice}}

Revision as of 08:12, 18 October 2017

Introduction

Purpose

Editing data is nice, but it must be persisted otherwise all effort invested in its editing would be lost. For this reason, OS.bee apps come with a set of create, read, update and delete functionality (CRUD) to manipulate data in a database. OS.bee can be operated with different database products by allowing user to:

  • Create: Create or add new entries.
  • Read: Read, retrieve, search or view existing entries from the database.
  • Update: Update or edit existing entries in the underlying database.
  • Delete: Delete, deactivate or remove existing entries from the database.

Each one of those functions is made available in OS.bee through the application for interactions with the user, after being defined in the Action DSL Model. In the following sections, you will get a closer look on how to the Action DSL works and how you can create basic and custom commands in order to make them available to the user.


Overview

The ActionDSL facilitates the implementation of certain interactions done by users through the application. It currently allows you to define toolbars after setting up beforehand the commands that will be triggered and executed. Custom made functions can also be implemented and attached (bound) to some items in the same manner as described in the sections below.

It provides a Command Provider, which encapsulates a Binding Context to the application view model (based on E4) and a Command Handler listing all defined actions (commands), which can be executed either application wide or in a single view.

Figure 1: Architectur Action DSL


Action Model Files

The Action DSL works for Os.bee models, it defines the actions for task, select workload, dialog, report, chart, workflow, datainterchange, functions and user interface. These actions are defined in text files with the file extension .action. Action model files carry the information necessary to create interaction components that will be executed in the background of the user interface.

Action model files are made up of the following sections:

  • Package declaration: The Action model file must have a unique fully qualified name that can be specified with the keyword package at the beginning of the file.
  • Import section: Action model files can address definitions from other models (e.g. Datainterchange, Function Library or Message DSL’s specifications) or other action model files. 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 * wildcard.
  • Command section: The command section contains all the action command definitions that have to be defined to be used later on in the same model file.
  • Toolbar section: The toolbar section contains all toolbar definitions, which are later used to build part of the user interface through the Dialog DSL among others.

package defintion

With the keyword package followed by a qualified name, you define the root element that contains all the other elements. A model can contain multiple packages.

► Syntax: 

package <package name>[{

command <command name> [describedBy <description>] [key binding <binding combination>] [key binding <binding combination>] actionType <action rule>

toolbar <toolbar name> [describedBy <description>] [items { . . .}]
. . .
} ]


One or more command can be defined in the same package, as well as the many toolbars using those commands. The keyword describedBy is optional and can be used to define the description of this toolbar. In the following example, the commands NEW and SAVE and 1 toolbar Dialog are defined in the same package.


► Example: 

package net.osbee.sample.foodmart.actions {

	command   NEW 		describedBy    "create new item"	dialogAction    New
	command   SAVE 	 	describedBy    "save an item"		dialogAction    Save

	toolbar    Dialog 	describedBy    "Toolbar for Dialogs" 			  items { . . . }
}


Commands

The command section is the main part of this model. All Actions are to be defined here by declaring every command that can be later executed. For each command, a java file named <commandName>+Action.java will be generated in folder ./src-gen/<package name>/. The <action rule> is predefined in Action Type and will be introduced in the next section.


► Syntax: 

command <command name> [key binding <binding combination>] actionType <action rule>


actionType: 
	'''chartAction'''		defines action applicable to chart elements.

	'''datainterchangeAction'''	defines action using datainterchange units.
	'''dialogAction'''		defines basic dialog actions (CRUD).
	'''functionalAction'''	defines custom actions using operations from the function library.
	'''reportAction'''		defines report type actions.
	'''selectWorkloadAction'''	defines select workload actions.
	'''taskAction'''		defines task actions.
	'''userinterfaceAction'''	defines actions with direct access and effect on the user interface.
	'''workflowAction'''		defines workflow actions.


The keyword describedBy is optional and can be used to define the description of a command. With the optional keyword keyBinding you are able to bind key combinations to commands.


► Syntax: 

keyBinding <binding combination >

The following example illustrates the creation of the four basic dialog action commands (CRUD).


► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command   NEW 		describedBy    "create new item"	keyBinding   "CTRL ALT N"	dialogAction    New
	command   SAVE 	 	describedBy    "save an item"		keyBinding   "CTRL ALT S"	dialogAction    Save
	command   DELETE 	describedBy    "delete1 an item"	keyBinding   "CTRL ALT D"	dialogAction    Delete
	command   CANCEL 	describedBy    "undo changes"		keyBinding   "CTRL ALT Z"	dialogAction    Cancel
	. . .
}

Each command has its own key binding combination to be pressed as an alternative action trigger.


ActionTypes

As already mentioned above there are there are currently eight ActionTypes to set the command type.

dialogAction

With the keyword dialogAction followed by a corresponding action rule, you can define actions for dialogs.

► Syntax: 

dialogAction <dialogAction rule>

As you can see in the last example, these are the 4 different dialogAction rules:

  • “New” means create a new entry.
  • “Save” means save the changing.
  • “Delete” means delete the selected entry.
  • “Cancel” means ignore the changing.
taskAction

With the keyword taskAction followed by a corresponding action rule, you can define actions for BPM (Business Process Management) tasks to make use of the OS.bee BLIP DSL functionalities.

► Syntax: 

taskAction <taskAction rule>

There are currently 15 different taskAction rules, which correspond to BPM tasks: 

Claim, Start, Stop, Release, Suspend, Resume, Skip, Complete, Delegate, Forward, Fail, Register, Remove, Activate, Exit

► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command   STOP 		taskAction    Stop
	command   RELEASE 	taskAction    Release
	command   SUSPEND	taskAction    Suspend
	command   COMPLETE	taskAction    Complete
	. . .
}


selectWorkloadAction

With the keyword selectWorkloadAction followed by a corresponding action rule, you can define actions of type select workload.

► Syntax: 

selectWorkloadAction <selectWorkloadAction rule>

There are currently 2 select workload action rules available: 

RemoveAll, AddAll


► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command REMOVE_ALL_WORKLOAD_ITEMS 		selectWorkloadAction 	RemoveAll
	command ADD_ALL_SELECTED_ITEMS_TO_THE_WORKLOAD 	selectWorkloadAction 	AddAll
	. . .
}


reportAction

With the keyword reportAction followed by a by a corresponding action rule, you can define actions for reports.

► Syntax: 

reportAction <reportAction rule>

Currently there are 2 different report action rules available: 

Download, PrintOnServer

► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command PRINT 		reportAction 	PrintOnServer
	command PRINT_DOWNLOAD 	reportAction 	Download
	. . .
}


chartAction

With the keyword chartAction followed by a corresponding action rule, you can define actions for charts.

► Syntax: 

chartAction <chartAction rule>

Currently the only rule available: 

ChartDownload

This action allows you to download a chart as image file.

► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command SAVE_CHART 	chartAction 	ChartDownload
	. . .
}


Figure 2: Payment Chart

Further information can be viewed in the Chart DSL documentation page.


workflowAction

With the keyword workflowAction followed by a corresponding action rule, you can define actions for workflows.

► Syntax: 

workflowAction <workflowAction rule>

Currently only one action rule is available: 

Start

► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command START	workflowAction 	Start
	. . .
}


datainterchangeAction

With the keyword datainterchangeAction followed by a corresponding action rule, you can define actions for data interchange, and so forth using data interchange unit functionalities.

► Syntax: 

datainterchangeAction <datainterchangeAction rule> <datainterchangeUnit name>

Currently there are 2 datainterchange action rules available: 

Import, Export

Please note that the data interchange units have to be already defined in the Datainterchange DSL in order to be used via imports in the Action DSL.

► Example: 

package net.osbee.sample.foodmart.actions {
	. . .
	command CURRNAMESIMPORT		datainterchangeAction Import CurrencyNames
	command CURRIMPORT 		datainterchangeAction Import Currencies
	. . .
}


userinterfaceAction

With the keyword userinterfaceAction followed by a corresponding action rule, you can define actions which affect directly the user interface as a whole.

► Syntax: 

userinterfaceAction <userinterfaceAction rule>

Currently only one action rule is available: 

SwitchPart

This only option allows the user to jump from a view to another one inside a perspective.


► Example: 

command SWITCH describedBy "move to next part" keyBinding "ALT F6" userinterfaceAction SwitchPart

The example above illustrates how a user interface action command with the command name SWITCH is defined with the option SwitchPart. You may notice here that a keyBinding has been attached to this command, which means that a user is now capable of switching between views by pressing the key combination ALT + F6. The figures bellows illustrate that effect.

Figure 4: SwitchPart before
Figure 5: SwitchPart after

You may notice the orange rectangle on each the figure shown above, which highlights the actual active view: the view which is currently focused on.


userinterfaceAction

The action type functionalAction is used to define custom action commands, which have to be linked with operations defined in the FunctionlibraryDSL. You can define a functional action command using the type functionalAction followed by the keywords group, canExecute and executeImmediate or executeLater like shown below.

► Syntax: 

functionalAction group <FunctionGroupName> canExecute <FunctionName#1> executeImmediate|executeLater <FunctionName#2> [messageCategory-definition]

Those keywords are needed to make the link between the command and the predefined function inside which this item could use from Function Library DSL:

  • group: specifies a unique group of functions defined in the function library to be used.
  • canExecute: sets a test operation, which can be performed before executing the actual and expected business logic.
  • executeImmediate: indicates that the business logic has to be executed right away, so that any results can be observed right away.
  • executeLater: indicates that the business logic has to be executed with delay asynchronously.

It is also possible to extend the functional action command definition with an optional message output definition. It basically allows you to define a set output messages to be seen in form of pop up dialogs, which would be shown to the user depending on the outcome of its interaction.


► Syntax: 

[messageCategory <messageCategoryName> onFailMessage|onSuccessMessage|onStartedMessage <messageName>]

Those messages are predefined in the Message DSL and can be linked to the command using the keyword messageCategory followed by the message category name and the condition, which has to be fulfilled to show the message:

  • onFailMessage: shows the message after a failed outcome of the action.
  • onSuccessMessage: shows the message after a successful outcome of the action.
  • onStartedMessage: shows the message right away.


► Example: 

command FIRE_EMPLOYEE	    functionalAction 	group Employee canExecute canFire executeImmediate fire messageCategory Employee onFailMessage FireNotAllowed onSuccessMessage Fired

command FIRE_EMPLOYEE_ASYNC functionalAction 	group Employee canExecute canFire executeLater	   fire  messageCategory Employee onStartedMessage FireStarted


Figure 6: Excerpt - Function Library DSL Model
Figure 7: Excerpt - Message DSL Model

Please note that no information or error message will be shown to the user, unless you explicitly define and set a message category to your functional action command.



Copyright Notice

All rights are reserved by Compex Systemhaus GmbH. In particular, duplications, translations, microfilming, saving and processing in electronic systems are protected by copyright. Use of this manual is only authorized with the permission of Compex Systemhaus GmbH. Infringements of the law shall be punished in accordance with civil and penal laws. We have taken utmost care in putting together texts and images. Nevertheless, the possibility of errors cannot be completely ruled out. The Figures and information in this manual are only given as approximations unless expressly indicated as binding. Amendments to the manual due to amendments to the standard software remain reserved. Please note that the latest amendments to the manual can be accessed through our helpdesk at any time. The contractually agreed regulations of the licensing and maintenance of the standard software shall apply with regard to liability for any errors in the documentation. Guarantees, particularly guarantees of quality or durability can only be assumed for the manual insofar as its quality or durability are expressly stipulated as guaranteed. If you would like to make a suggestion, the Compex Team would be very pleased to hear from you.

(c) 2016-2024 Compex Systemhaus GmbH

Retrieved from "https://download.osbee.org/documentation/index.php?title=Action_DSL&oldid=2571"