diff --git a/basics/dispatching.md b/basics/dispatching.md
index 0d7b3e4..67ce0b3 100644
--- a/basics/dispatching.md
+++ b/basics/dispatching.md
@@ -1,17 +1,51 @@
# Dispatching
-The dispatching is the follow up on the routing. In the dispatcher the route destination get resolved and executed.
+The dispatching is the follow up on the routing. In the dispatcher the route destination get resolved and executed. Dispatching can be performed on module instance methods, static functions and anonymous functions.
-The dispatching is fairly simple as it only requires a single function call.
+The result of the `dispatch()` call is an array of renderable views which will be rendered at the end when the response object is finalized.
+## Basic
+
+The dispatcher accepts a string representation of the method or static function which should be dispatched, a closure which should be executed or an array of the above.
+
+The `dispatch()` function accepts additionally a variable amount of parameters which will be passed to the routed method/function.
+
+### String
+
+#### Module
+
+The string representation for a module method is almost the same as the static function representation. The only difference is that a module method has only one colon `:` between the function name and the namespace.
+
+```php
+$dispatcher->dispatch('\My\Namespace:methodToCall', $methodToCallPara1, $methodToCallPara2, ...);
```
-$this->dispatcher->dispatch($this->router->route($request))
+
+#### Static
+
+The string representation for a module method is almost the same as the static function representation. The only difference is that a module method has two colons `::` between the function name and the namespace.
+
+```php
+$dispatcher->dispatch('\My\Namespace::staticToCall', $staticToCallPara1, $staticToCallPara2, ...);
+```
+
+### Closure
+
+The closure simply takes a closure as first parameter which will be called and executed during the dispatching process.
+
+```php
+$dispatcher->dispatch(function($para1, $para2) { ... }, $staticToCallPara1, $staticToCallPara2, ...);
+```
+
+## Routing
+
+The dispatcher accepts the resoults from the `route()` method of the router which is an array of routes.
+
+```php
+$dispatcher->dispatch($router->route($request))
```
Based on the function definition returned by the router it's possible to pass more parameters to the function such e.g. request and response objects.
+```php
+$dispatcher->dispatch($router->route($request), $request, $response)
```
-$this->dispatcher->dispatch($this->router->route($request), $request, $response)
-```
-
-The result of the `dispatch` call is an array of results.
\ No newline at end of file
diff --git a/basics/routing.md b/basics/routing.md
index 0f05e27..9501472 100644
--- a/basics/routing.md
+++ b/basics/routing.md
@@ -9,14 +9,14 @@ Routes are defined as RegEx. It is recommended to match the desired route as clo
Resolving a route can be done by providing a request to the router
-```
-$this->router->route(new Request());
+```php
+$router->route(new Request());
```
or a route
-```
-$this->router->route('foo/bar', RouteVerb::GET);
+```php
+$router->route('foo/bar', RouteVerb::GET);
```
The result is an array of either string references or closures.
@@ -25,8 +25,8 @@ The result is an array of either string references or closures.
For routes it's possible to define a `\Closure` which will get returned upon using the specified route.
-```
-$this->router->add('foo/bar', function() {
+```php
+$router->add('foo/bar', function() {
return 'Hellow World';
});
```
diff --git a/basics/views.md b/basics/views.md
index bd2262e..1e53956 100644
--- a/basics/views.md
+++ b/basics/views.md
@@ -18,7 +18,7 @@ In the template you can simply use `$this->getText({TEXT_ID})` for localized tex
Templates can be set with the `setTemplate()` method. It is important to note that templates MUST have the file ending `.tpl.php`. Other file endings are not supported.
-```
+```php
$view->setTemplate('/Modules/Test/Theme/Backend/template_file');
```
diff --git a/components/modules.md b/components/modules.md
index 4fd5a89..cfa70ef 100644
--- a/components/modules.md
+++ b/components/modules.md
@@ -55,7 +55,7 @@ are almost stand-alone without the possibility to get extended.
In contrast to the install file for other moduels this file has to follow more strict standards. The following example shows you the bare minimum requirements of a installation file:
-```
+```php
[
'StringID' => 'Your localized string',
@@ -197,7 +197,7 @@ All other language files are optional and usually are only required by other mod
The `info.json` file contains general module information used during installation as well for identification and display in the module database.
-```
+```json
{
"name": {
"id": {UniqueModuleId_INT},
@@ -260,7 +260,7 @@ The name category contains the names used for internel as well as external ident
The version is automatically incremented by Orange Management. The version might be used by other modules in order to require a specific version of a module. Versions must follow the following format:
-```
+```js
major.minor.build = 2.512.19857
```
@@ -296,7 +296,7 @@ The `load` category contains all the files (controllers, language files) that ne
The `pid` (page identifier) is a sha1 hash of the uri where the `file` is supposed to be loaded. The pid needs to be defined in the following matter (e.g. http://127.0.0.1/en/app/path/sub&some=thing):
-```
+```php
sha1('apppath');
```
diff --git a/components/packages.md b/components/packages.md
index bb68b86..c73f25f 100644
--- a/components/packages.md
+++ b/components/packages.md
@@ -33,7 +33,7 @@ In the files directory all files are stored.
The `package.json` file contains information of the package.
-```
+```json
```
### Other
diff --git a/datastorage/cache.md b/datastorage/cache.md
index 378eb61..5010e72 100644
--- a/datastorage/cache.md
+++ b/datastorage/cache.md
@@ -8,7 +8,7 @@ By default only stylesheets, javascript and layout images as well as module imag
Example usage for 30 days caching:
-```
+```php
$resposne->setHeader('Cache-Control', 'Cache-Control: max-age=2592000');
```
@@ -16,6 +16,6 @@ In order to trigger a re-cache of stylesheets or javascript files make sure to u
Example usage:
-```
+```php
$head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/Controller.js?v=' . self::MODULE_VERSION);
```
\ No newline at end of file
diff --git a/datastorage/database/datamapper.md b/datastorage/database/datamapper.md
index 5168f1b..c915a7b 100644
--- a/datastorage/database/datamapper.md
+++ b/datastorage/database/datamapper.md
@@ -4,7 +4,7 @@
Models can be constructed in what ever way you like, all of the mapping logic is defined in the data mapper itself. It is however recommended to provide the following member variables if applicable (names can be different):
-```
+```php
private $id = 0;
private $createdAt = null;
private $createdBy = null;
@@ -36,11 +36,11 @@ One model can only be stored in one table. With the `$table` variable it's possi
In the `$columns` array all columns, respective model variables and data types need to be specified.
-```
+```php
protected static $columns = [
- 'db_field_name_1' => ['name' => 'db_field_name_1', 'type' => 'int', 'internal' => 'model_var_name_1'],
- 'db_field_name_2' => ['name' => 'db_field_name_2', 'type' => 'string', 'internal' => 'model_var_name_2'],
- ]
+ 'db_field_name_1' => ['name' => 'db_field_name_1', 'type' => 'int', 'internal' => 'model_var_name_1'],
+ 'db_field_name_2' => ['name' => 'db_field_name_2', 'type' => 'string', 'internal' => 'model_var_name_2'],
+];
```
The `name` contains the field name in the database, the `type` represents the data type and `internal` is the string representation of the model variable name.
@@ -60,56 +60,71 @@ Possible types are:
With the `$hasMany` variable it's possible to specify other models that belong to this model.
-```
+```php
protected static $hasMany = [
- 'model_var_name_3' => [
- 'mapper' => HasManyMapper::class,
- 'table' => 'relation_table_name',
- 'dst' => 'relation_destinaiton_name',
- 'src' => 'relation_source_name',
- ],
- ];
+ 'model_var_name_3' => [
+ 'mapper' => HasManyMapper::class,
+ 'table' => 'relation_table_name',
+ 'dst' => 'relation_destinaiton_name',
+ 'src' => 'relation_source_name',
+ ],
+];
```
The `mapper` contains the class name of the mapper responsible for the many models that belong to this model. The `table` contains the name of the table where the relations are defined (this can be the same table as the source model or a relation table). If a model is only in relation with one other model this relation can be defined in the same table as the model and this `table` field can be `null`. The `dst` field contains the name of field where the primary key of the destination is defined. The `src` field is only required for models which have a relation table. This field contains the name of the field where the primary key of the source model is defined.
A one to many relation would look like the following:
-```
+```php
protected static $hasMany = [
- 'model_var_name_3' => [
- 'mapper' => HasManyMapper::class,
- 'table' => null,
- 'dst' => 'relation_destinaiton_name',
- 'src' => null,
- ],
- ];
+ 'model_var_name_3' => [
+ 'mapper' => HasManyMapper::class,
+ 'table' => null,
+ 'dst' => 'relation_destinaiton_name',
+ 'src' => null,
+ ],
+];
```
A many to many relation which can only be defined in a relation table looks like the following:
-```
+```php
protected static $hasMany = [
- 'model_var_name_3' => [
- 'mapper' => HasManyMapper::class,
- 'table' => 'relation_table_name',
- 'dst' => 'relation_destinaiton_name',
- 'src' => 'relation_source_name',
- ],
- ];
+ 'model_var_name_3' => [
+ 'mapper' => HasManyMapper::class,
+ 'table' => 'relation_table_name',
+ 'dst' => 'relation_destinaiton_name',
+ 'src' => 'relation_source_name',
+ ],
+];
```
### Has one
It's possible to also define a relation in the destination module itself. This can be acomplished by using the `$hasOne` variable. In this case the model itself has to specify a field where the primary key of the source model is defined.
-```
+```php
protected static $hasOne = [
- 'model_var_name_4' => [
- 'mapper' => HasOneMapper::class,
- 'src' => 'relation_source_name',
- ],
- ];
+ 'model_var_name_4' => [
+ 'mapper' => HasOneMapper::class,
+ 'src' => 'relation_source_name',
+ ],
+];
```
-The `mapper` field contains the class name of the mapper of the source model. The `src` field contains the database field name where the primary key is stored that is used for the realation.
\ No newline at end of file
+The `mapper` field contains the class name of the mapper of the source model. The `src` field contains the database field name where the primary key is stored that is used for the realation.
+
+### Belongs to
+
+The reverse of a has one/has many is a belongs to. This allows to also load models that a specific model belongs to. This can be acomplished by using the `$belongsTo` variable. In this case the model itself has to specify a field where the primary key of the source model is defined.
+
+```php
+protected static $belongsTo = [
+ 'model_var_name_5' => [
+ 'mapper' => BelongsToMapper::class,
+ 'dest' => 'relation_destination_name',
+ ],
+];
+```
+
+The `mapper` field contains the class name of the mapper of the destination model. The `dest` field contains the database field name where the primary key is stored that this model belongs to.
\ No newline at end of file
diff --git a/frontend/styles_and_layout.md b/frontend/styles_and_layout.md
index b53c238..8190bc0 100644
--- a/frontend/styles_and_layout.md
+++ b/frontend/styles_and_layout.md
@@ -8,7 +8,7 @@ This project only supports scss and css. All css files need to be provided with
This project uses font-awesome for its icons, the following example allows for stacked icons e.g. creating new/undread email notifications:
-```
+```html
333
diff --git a/security/security_guidelines.md b/security/security_guidelines.md
index a2da81e..9076228 100644
--- a/security/security_guidelines.md
+++ b/security/security_guidelines.md
@@ -6,7 +6,7 @@ The tool to protect clients from CSRF is a randomly generated CSRF token, that c
Example usage:
-```
+```html
@@ -18,7 +18,7 @@ Since the validation of the CSRF token is performed automatically it is only nec
Example usage in a module handling a API request:
-```
+```php
if($request->getData('CSRF') === null) {
$response->setStatusCode(RequestStatus::R_403);
@@ -55,13 +55,13 @@ Scripts and frames must be provided by the own server or google. This is importa
The default CSP looks like the following:
-```
+```php
$response->getHeader()->set('content-security-policy', 'script-src \'self\'; frame-src \'self\'', true);
```
In order to whitelist inline javascript you can use the following logic. This however requires you to know the inline script beforehand `$script`. After setting the CSP header they automatically get locked so that further changes are not possible. This is a security measure in order to prevent any malicious adjustments.
-```
+```php
$response->getHeader()->set('content-security-policy', 'script-src \'self\' \'sha256-' . base64_encode(hash('sha256', $script, true)) . '\'; frame-src \'self\'', true);
```
@@ -69,7 +69,7 @@ $response->getHeader()->set('content-security-policy', 'script-src \'self\' \'sh
This header tells the client browser to use local xss protection if available.
-```
+```php
$response->getHeader()->set('x-xss-protection', '1; mode=block');
```
@@ -77,7 +77,7 @@ $response->getHeader()->set('x-xss-protection', '1; mode=block');
By using this header browsers which support this feature will ignore the content/mime and recognize the file by the provided header only.
-```
+```php
$response->getHeader()->set('x-content-type-options', 'nosniff');
```
@@ -85,7 +85,7 @@ $response->getHeader()->set('x-content-type-options', 'nosniff');
The x-frame-options is providing the same protection for frames as the content-security-policy header. Please only use this header in addition to the content-security-policy if you have to but make sure the rules don't contradict with the content-security-policy.
-```
+```php
$response->getHeader()->set('x-frame-options', 'SAMEORIGIN');
```
@@ -122,7 +122,7 @@ These are just a few examples but it is very important to make sure, that these
Example usage:
-```
+```php
if(($pathNew = realpath($path)) === false || strpos($pathNew, self::MODULE_PATH) === false) {
throw new PathException($path);
}
@@ -130,10 +130,10 @@ if(($pathNew = realpath($path)) === false || strpos($pathNew, self::MODULE_PATH)
The example throws an exception if the path either doesn't exist or is trying to access a path that doesn't contain the path defined in `self::MODULE_PATH`. Another validation could be:
-```
-if(($pathNew = realpath($path)) === false || !StringUtils::startsWith($pathNew, ROOT_PATH)) {
+```php
+if(($pathNew = realpath($path)) === false) {
throw new PathException($path);
}
```
-This example now is not only checking if the path exists and if it contains a path element, it also makes sure that the path is inside the application root path. You could as easily replace `ROOT_PATH` with `self::MODULE_PATH` and this validation would make sure `$path` only directs within a module.
\ No newline at end of file
+This example now is not only checking if the path exists and if it contains a path element, it also makes sure that the path is inside the application root path.
\ No newline at end of file
diff --git a/services/events.md b/services/events.md
index 934964d..e50ffbe 100644
--- a/services/events.md
+++ b/services/events.md
@@ -6,42 +6,56 @@ 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.
+```php
+$eventManager->attach('eventId', function() { echo 'Hello World'; });
```
-$this->eventManager->attach('eventId', function() { echo 'Hello World'; });
-```
+
+### Repeating events
If a 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);
+```php
+$eventManager->attach('eventId', function() { echo 'Hello World'; }, true);
```
-Now the event will be removed from the event manager once executed.
+Now the event will be removed from the event manager once executed.
+
+### Resetting events
+
+In case an event should be reset (all conditions mut be met again befor it can be triggered) after it got successfully triggered one more parameter can be added.
+
+```php
+$eventManager->attach('eventId', function() { echo 'Hello World'; }, false, true);
+```
+
+This only works if also the event **isn't** removed after triggering
## Triggering Events
An event can be triggered by calling the `trigger()` function.
-```
-$this->eventManager->trigger('eventId');
+```php
+$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.
-```
-$this->eventManager->addGroup('eventId', 'conditionName');
-$this->eventManager->addGroup('eventId', 'conditionName2');
+```php
+$eventManager->addGroup('eventId', 'conditionName');
+$eventManager->addGroup('eventId', 'conditionName2');
```
Now the event will only be triggered once every registered condition was triggered.
-```
-$this->eventManager->trigger('eventId', 'conditionName'); // No output
-$this->eventManager->trigger('eventId', 'conditionName2'); // Hello World
-$this->eventManager->trigger('eventId'); // Hello World
-$this->eventManager->trigger('eventId', 'conditionName'); // Hello World
+```php
+$eventManager->trigger('eventId', 'conditionName'); // No output
+$eventManager->trigger('eventId', 'conditionName2'); // Hello World
+$eventManager->trigger('eventId'); // Hello World
+$eventManager->trigger('eventId', 'conditionName'); // Hello World (if remove = false && reset = false)
+$eventManager->trigger('eventId', 'conditionName'); // No output (if remove = false && reset = true)
+$eventManager->trigger('eventId', 'conditionName'); // No output (if remove = true)
```
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
diff --git a/services/filesystem.md b/services/filesystem.md
index 12c959e..1686d6f 100644
--- a/services/filesystem.md
+++ b/services/filesystem.md
@@ -22,7 +22,7 @@ The file system provides a simple way to handle operations on the file system. S
Custom implementations can be created by implementing the FileSystemInterface. These implementations must get registered in the file system and can be used afterwards as the pre-defined implementations.
-```
+```php
FileSystem::register('custom1', '\implementation\namespace');
FileSystem::env('custom1')->list();
```
\ No newline at end of file
diff --git a/services/localization.md b/services/localization.md
index 8b0c5c4..3ea11f9 100644
--- a/services/localization.md
+++ b/services/localization.md
@@ -6,13 +6,13 @@ Most of the localization is stored inside the localization object which is part
Language specific text can be used through the `LocalizationManager`, either by directly calling the `getText()` function of the localization manager
-```
-$this->l11nManager->getText({LANGUAGE}, {MODULE}, {THEME}, {TEXT})
+```php
+$l11nManager->getText({LANGUAGE}, {MODULE}, {THEME}, {TEXT})
```
or indirectly by calling the `getText()` in the view context.
-```
+```php
$this->getText({TEXT})
```
@@ -52,7 +52,7 @@ The currency code of the localization object is the 3 character ISO4217 code. Th
The currency symbol can be placed either in front or at the end of a value. The `Money` class provides a function called `getCurrency()` which returns a localized representation by specifying the thousands and decimal separator as well as the currency symbol and its position.
-```
+```php
$money->getCurrency(2, ',', '.', '$', 0);
```
diff --git a/services/logging.md b/services/logging.md
index d8aa6ac..f813414 100644
--- a/services/logging.md
+++ b/services/logging.md
@@ -16,7 +16,7 @@ Both logging implementations provide the following logging functions for the dif
All functions take at least two parameters where one is the message and the other one is the optional context that should be injected into the message.
-```
+```php
$log->error(FileLogger::MSG_FULL, ['message' => 'Log me!']);
```
@@ -24,7 +24,7 @@ $log->error(FileLogger::MSG_FULL, ['message' => 'Log me!']);
The file logging should only be used for database and application problems. The file logging is part of the framework and is always available. The file logger implements the singleton pattern and can be aquired by calling the `getInstance()` function.
-```
+```php
$log = FileLogger::getInstance('logging/path', false);
```
@@ -38,6 +38,6 @@ The database logging is recommended for activity logs and abstract high level is
On the client side a logger is also implemented providing the same functions as described above. The only difference is that this logger can remote log messages. Logging messages will get forwarded to the server which will log these messages with the file logger.
-```
+```js
let log = jsOMS.Log.Logger.getInstance(true, false, true);
```
diff --git a/services/money.md b/services/money.md
index e046b73..52b0bbb 100644
--- a/services/money.md
+++ b/services/money.md
@@ -18,7 +18,7 @@ The `Money` class follows the builder pattern. The provided operations are addit
## Example
-```
+```php
$money = new Money(1234567, ',', '.', '$', 0);
$money->add(1.0)->sub(10000)->mult('-1.0')->div(new Money(-1.0));
echo $money->getCurrency(); // $123.46
diff --git a/services/uri.md b/services/uri.md
index 6abfcc5..414211b 100644
--- a/services/uri.md
+++ b/services/uri.md
@@ -6,13 +6,13 @@ The `UriFactory` is used in order to build URIs. The factory generates the URIs
The raw uri string supports parameters that will be replaced with manual or default values. Parameters are always enclosed by `{}` and have a special prefix such as `#./?@$%`
-```
+```php
$rawUri = 'http://www.yoururl.com/en/some/{/path}?foo=bar&id={@data}'
```
These placeholders will be filled by values that are defined by the `setQuery()` function.
-```
+```php
UriFactory::setQuery('/path', 'thing');
UriFactory::setQuery('@data', 1);
UriFactory::build($rawUri) // http://www.yoururl.com/en/some/thing?foo=bar&id=1
@@ -51,7 +51,7 @@ While it's also possible to define parameters at the frontend and make use of th
Sometimes a parameter shouldn't be globally defined but is necessary to parse for a specific uri, in that case it's possible to pass an array or object of parameter definitions to the build function where the key is the parameter key and the value is the parameter value it should replace.
-```
+```js
jsOMS.Uri.UriFactory.build('yoururl.com/en/some/{/path}?id={@data}', {'@data': 1});
```
diff --git a/standards/documentation.md b/standards/documentation.md
index 4b651ef..b308a30 100644
--- a/standards/documentation.md
+++ b/standards/documentation.md
@@ -8,7 +8,7 @@ The php documentation is based on PhpDocumentor, therefore only valid PhpDocumen
A file documentation MUST be implemented in the following form:
-```
+```php
/**
* File description
*
@@ -16,8 +16,6 @@ A file documentation MUST be implemented in the following form:
*
* @category Category name
* @package Package name
- * @author Your Author 1
- * @author Your Author 2
* @copyright Orange Management
* @license OMS License 1.0
* @version 1.0.0
@@ -29,14 +27,12 @@ A file documentation MUST be implemented in the following form:
A class documentation MUST be implemented in the following form:
-```
+```php
/**
* Class description.
*
* @category Category name
* @package Package name
- * @author Your Author 1
- * @author Your Author 2
* @license OMS License 1.0
* @link http://your.url.com
* @since 1.0.0
@@ -47,7 +43,7 @@ A class documentation MUST be implemented in the following form:
A member variable documentation MUST be implemented in the following form:
-```
+```php
/**
* Member variable description.
*
@@ -60,7 +56,7 @@ A member variable documentation MUST be implemented in the following form:
A function/method documentation MUST be implemented in the following form:
-```
+```php
/**
* Function/method description.
*
@@ -72,7 +68,6 @@ A function/method documentation MUST be implemented in the following form:
* @return return_type
*
* @since 1.0.0
- * @author Your Author 2
*/
```
@@ -82,7 +77,7 @@ Variable documentation is not mandatory and can be omitted. However it's recomme
Example:
-```
+```php
/** @var TestObject[] $myArray */
```
@@ -106,15 +101,14 @@ The scss documentation is based on SassDoc, therefore only valid SassDoc comment
### File
-```
-////
-// Documentation
-//
-// Optional example or more detailed description.
-//
-// @since 1.0.0
-// @author Your Author 2
-////
+```js
+/**
+ * Documentation
+ *
+ * Optional example or more detailed description.
+ *
+ * @since 1.0.0
+ */
```
### Class
diff --git a/standards/php.md b/standards/php.md
index abecc44..13a7fe0 100644
--- a/standards/php.md
+++ b/standards/php.md
@@ -38,7 +38,7 @@ Method names MUST be declared in camelCase().
Php code embedded into template files SHOULD use the alternative syntax for control structures in order to improve the readability:
-```
+```php
if($a === 5) : ?>
This is html