From cb4aa7702a25c0b05527cddb63820fed9f0216d0 Mon Sep 17 00:00:00 2001
From: Dennis Eichhorn <spl1nes.com@googlemail.com>
Date: Sat, 27 May 2017 10:00:13 +0200
Subject: [PATCH] Added action manager

---
 services/action_manager.md | 79 ++++++++++++++++++++++++++++++++++++++
 services/events.md         | 19 +++++----
 2 files changed, 90 insertions(+), 8 deletions(-)
 create mode 100644 services/action_manager.md

diff --git a/services/action_manager.md b/services/action_manager.md
new file mode 100644
index 0000000..5979bb3
--- /dev/null
+++ b/services/action_manager.md
@@ -0,0 +1,79 @@
+# Action Manager
+
+The action manager is only available for the frontend as its purpose is to execute/trigger events based on UI events. The action manager allows to define procedures for UI events without writing any inline JavaScript and reducing the necessary JavaScript code in general thanks to this modular approach.
+
+## Binding Action Events
+
+In order to perform actions on UI events it is necessary to define listeners for elements that need to be observed. Usually these elements are input and button elements. The following action has one `click-listener` executing the defined actions if this listener is triggered.
+
+```
+<button data-action='[
+    {
+        "listener": click, "action": [...]
+    }
+]'>
+```
+
+Now we have to define the actions that should be executed when a click-event is performed.
+
+```
+<button data-action='[
+    {
+        "listener": "click", "action": [
+            {"key": 1, "type": "dom.popup", "tpl": "some-tpl", "aniIn": "fadeIn"},
+            {"key": 2, "type": "message.request", "uri": "http://api.uri.com/?para=123", , "method": "GET", "request_type": "json"},
+            {"key": 3, "type": "dom.table.append", "id": "some-tpl", "aniIn": "fadeIn", "data": [], "bindings": {"id": "id", "name": "name/0"}, "position": -1}
+        ]
+    }
+]'>
+```
+
+Actions can be executed synchronously or asynchronously depending on the actions implementation. Every action needs a `key` which has to be unique locally for this listner. Also every action needs a type; the type is used to identify which code to execute if the action is triggered. The framework comes with a set of pre-defined actions that can be used. All other object properties depend on the action.
+
+In the example above, if the button is clicked it will look for a template with the id `some-tpl` and insert it into the DOM with a fade-in animation effect. Afterwards a GET request is performed to the API. The resultset of the API is then appended to a table in the previously opened popup. The binding in this example are used to map the API resultset to the table columns.
+
+The API request URI doesn't have to be static but could be dynamic by using the URI factory which would allow to fetch values from other input fields as parameter value etc.
+
+### Child Elements
+
+In some situations it is required to define listeners and actions for all child elements. Writing listeners and action for every list element for example is tedious and confusing. For this purpose the parent element can specify a selector for a listener.
+
+```
+<ul id="click-list" data-action='[
+    {
+        "listener": "...", "selector": "#click-list li", "action": [...]
+    }
+]'>
+    <li>...
+    <li>...
+</ul>
+```
+
+This registers the same listener to all `<li>` elements. Another advantag is that in case a new `<li>` element gets added it will automatically also receive this listener.
+
+## Defining Actions
+
+### Definition
+
+A action event skeleton looks as follows:
+
+```
+const uniqueFunctionName = function(action, callback, data)
+{
+    "use strict";
+
+    // some code here
+
+    callback(newData);
+};
+```
+
+The action parameter contains all the action configuration values, the callback is the next action event that should be triggered afterwards and the data parameter is either data that is passed from a previous action event or data you would like to pass to the next action event.
+
+### Binding
+
+A action event can be registered simply by adding it to the action manager:
+
+```
+this.uiManager.getActionManager().add('some.new.action', uniqueFunctionName);
+```
\ No newline at end of file
diff --git a/services/events.md b/services/events.md
index 934964d..c669a06 100644
--- a/services/events.md
+++ b/services/events.md
@@ -7,13 +7,13 @@ Events are available in the frontend and the backend. Both implementations provi
 Every event requires a unique trigger key as well as a `\Closure` which should be called once the event is triggered.
 
 ```
-$this->eventManager->attach('eventId', function() { echo 'Hello World'; });
+$this->eventManager->attach('eventId', function($data) { echo 'Hello World'; });
 ```
 
-If a event should only be able to be triggered once another boolean parameter has to be edded to the `attach()` function call. 
+If an event should only be able to be triggered once another boolean parameter has to be edded to the `attach()` function call. 
 
 ```
-$this->eventManager->attach('eventId', function() { echo 'Hello World'; }, true);
+$this->eventManager->attach('eventId', function($data) { echo 'Hello World'; }, true);
 ```
 
 Now the event will be removed from the event manager once executed.
@@ -28,20 +28,23 @@ $this->eventManager->trigger('eventId');
 
 ## Multi Condition Events
 
-In some cases it is required that multiple conditions are met before an event is supposed to be triggered. This can be achived by registering these conditions through the `addGroup()` function.
+In some cases it is required that multiple conditions are met before an event is supposed to be triggered. This can be achived by registering these conditions through the `addGroup()` function. 
 
 ```
 $this->eventManager->addGroup('eventId', 'conditionName');
 $this->eventManager->addGroup('eventId', 'conditionName2');
 ```
 
-Now the event will only be triggered once every registered condition was triggered.
+Now the event will only be triggered once every registered condition was triggered. If requried it's also possible to pass data to the event closure.
 
 ```
-$this->eventManager->trigger('eventId', 'conditionName'); // No output
-$this->eventManager->trigger('eventId', 'conditionName2'); // Hello World
+$data = [1, 2, new Object()];
+$this->eventManager->trigger('eventId', 'conditionName', $data); // No output
+$this->eventManager->trigger('eventId', 'conditionName2', $data); // Hello World
 $this->eventManager->trigger('eventId'); // Hello World
 $this->eventManager->trigger('eventId', 'conditionName'); // Hello World
 ```
 
-The order in which these conditions are triggered doesn't mapper. A multi condition event SHOULD be atteched with the optional boolean parameter `true`. These events can only be executed once and will be removed afterwards. In case the optional boolean parameter was not set to `true` the event will remain in the event manager and will be triggered whenever `trigger('eventId')` is called.
\ No newline at end of file
+The order in which these conditions are triggered doesn't mapper. A multi condition event SHOULD be atteched with the optional boolean parameter `true`. These events can only be executed once and will be removed afterwards. In case the optional boolean parameter was not set to `true` the event will remain in the event manager and will be triggered whenever `trigger('eventId')` is called.
+
+Another optional boolean parameter can be added at the end if the event should stay active in the event manager but all trigger conditions should be reset after executed once. 
\ No newline at end of file