improve documentation

SUMMARY.md

@@ -16,6 +16,9 @@
 * [Modules]({%}?page=example_module/module)
 * [Packages]({%}?page=example_module/packages)
 
+## Application Specific
+* [Language Files]({%}?page=basics/language_files)
+
 ## API
 ### Message
 * [Uri]({%}?page=services/uri)

basics/dispatching.md

@@ -14,7 +14,7 @@ The `dispatch()` function accepts additionally a variable amount of parameters w
 
 #### 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.
+The module function can be called by providing the namespace followed by the function name concatonated with a colon `:` between the function name and the namespace.
 
 ```php
 $dispatcher->dispatch('\My\Namespace:methodToCall', $methodToCallPara1, $methodToCallPara2, ...);
@@ -22,7 +22,7 @@ $dispatcher->dispatch('\My\Namespace:methodToCall', $methodToCallPara1, $methodT
 
 #### 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.
+A static function can be called by providing the namespace followed by the function name concatonated with two colons `::` between the function name and the namespace.
 
 ```php
 $dispatcher->dispatch('\My\Namespace::staticToCall', $staticToCallPara1, $staticToCallPara2, ...);
@@ -44,7 +44,7 @@ The dispatcher accepts the results from the `route()` method of the router which
 $dispatcher->dispatch($router->route($request->uri->getRoute()));
 ```
 
-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.
+Based on the function definition returned by the router it's possible to pass additional parameters to the function such e.g. request and response objects.
 
 ```php
 $dispatcher->dispatch($router->route($request->uri->getRoute()), $request, $response);

basics/language_files.md

@@ -0,0 +1,39 @@
+# Language Files
+
+Language files are used for static/custom translations. Depending on the request and response localization the correct language files are loaded and used for the translations invoked by `getHtml()` in the views.
+
+## Naming
+
+The naming convention of the files is `language.lang.php` e.g. `en.lang.php`. In some cases it may be necessary to provide language files for other modules in such a case the name of the language file is `module_name.language.lang.php` e.g. `Navigation.en.lang.php`.
+
+## Content
+
+The content of the language files is very simple. All you need is the module name, a key/identifier for the string and the translation.
+
+```php
+<?php
+/**
+ * Orange Management
+ *
+ * PHP Version 8.0
+ *
+ * @copyright Dennis Eichhorn
+ * @license   OMS License 1.0
+ * @version   1.0.0
+ * @link      https://orange-management.org
+ */
+declare(strict_types=1);
+
+return ['Auditor' => [
+    'Audit'   => 'Prüfung',
+    'Auditor' => 'Prüfer',
+    'Audits'  => 'Prüfungen',
+    'By'      => 'Von',
+]];
+```
+
+It is recommended to create the translations in a spreadsheet software and export it as csv, as it is much easier to create all the translations for the different languages. You can install the **demo application**, install **your module** and then go to the Exchange module. In here you can navigate to the **OMS** exchange (exporter) and export the language/translations. This will provide a csv file for all modules and all templates with all the different supported languages. Simply search for your module and create the missing translations.
+
+Afterwards you can import the modified csv file in the OMS exchange which will create the language files based on this file.
+
+> Please note that the csv must be `;` deliminated and `"` escaped.

basics/requests.md

@@ -7,29 +7,39 @@ Requests can be either incoming requests such as http requests on the server sid
 A http request in its' most basic form only consists of a uri.
 
 ```php
-$request = new Request(new HttpUri('http://your_request.com/url?to=call'));
+$request = new HttpRequest(new HttpUri('http://your_request.com/url?to=call'));
 ```
 
+### Localization
+
+The request localization can be defined witht he second parameter
+
+```php
+$request = new HttpRequest(new HttpUri('http://your_request.com/url?to=call'), new Localization());
+```
+
+In all web applications (e.g. backend, api, etc.) the localization and uri are automatically propagated during the initialization of the application.
+
 ## Rest Requests
 
 With the rest implementation it's possible to make http requests and read the response.
 
 ```php
-$request = new Request(new HttpUri('http://your_request.com/url?to=call'));
-$result  = Rest::request($request);
+$request = new HttpRequest(new HttpUri('http://your_request.com/url?to=call'));
+$result  = Rest::Httprequest($request);
 ```
 
 Alternatively it's also possible to make a rest request directly from the Http request object.
 
 ```php
-$request = new Request(new HttpUri('http://your_request.com/url?to=call'));
+$request = new HttpRequest(new HttpUri('http://your_request.com/url?to=call'));
 $result  = $request->rest();
 ```
 
 The result contains the raw response text. By defining the request method it's also possible to make other requests such as `PUT` requests.
 
 ```php
-$request = new Request(new HttpUri('http://your_request.com/url?to=call'));
+$request = new HttpRequest(new HttpUri('http://your_request.com/url?to=call'));
 $request->setMethod(RequestMethod::PUT);
 $result = Rest::request($request);
 ```

basics/responses.md

@@ -1,9 +1,93 @@
 # Responses
 
-Responses can be either outgoing responses such as http or socket responses on the server side or responses generated on the client side for socket/websocket requests. Responses usually get generated based on a request.
+Responses can be either outgoing responses such as http or socket responses on the server side or responses generated on the client side for socket/websocket requests.
 
 ## Http Response
 
+A response can be defined with the `set()` function and the body of the response can be generated/rendered witth the `getBody()` function.
+
+```php
+$response->set('response_id', {stringifiable_element});
+```
+
+The `response_id` is a unique internal id which allows you to create multiple response elements. All response elements will get combined (usually concatenated) during the rendering process.
+
+The `{stringifiable_element}` accepts all supported types from the `StringUtils::stringify` function. e.g.
+
+* \JsonSerializable
+* array
+* \Serializable
+* string
+* int
+* float
+* bool
+* null
+* \DateTimeInterface
+* RenderableInterface
+* \__toString()
+
+All other types will be rendered as null during `getBody()`.
+
+### Localization
+
+The response localization can be defined witht he second parameter
+
+```php
+$response = new HttpResponse(new Localization());
+```
+
+In all web applications (e.g. backend, api, etc.) the localization is automatically propagated during the initialization of the application. This means all templates, views and controller endpoints may use the localization in order to generate localized responses.
+
+### Default Headers
+
+The default headers for all web applications are:
+
+* 'content-type' => 'text/html; charset=utf-8'
+* 'x-xss-protection' => '1; mode=block'
+* 'x-content-type-options' => 'nosniff'
+* 'x-frame-options' => 'SAMEORIGIN'
+* 'referrer-policy' => 'same-origin'
+
+In order to change the response type the header `content-type` must be changed.
+
+```php
+$response->header->set('content-type', '....', true);
+```
+
+The boolean flag at the end forces an overwrite of the previous response type. If this flag is not set the response type will not be overwritten. The reason for this flag is to protect header elements from accidentially getting overwritten.
+
+### Sending Headers
+
+> After the headers are sent it is not possible to change the headers or re-send them, the header is locked!. Usually you don't have to worry about this since the headers are automatically sent just bevore the content gets rendered.
+
+### Text/Html Response
+
+In most cases the text/html response is created based on a `View` which has a template assigned which then gets rendered during the response rendering process. The `View` implements `RenderableInterface` (see above). In case of frontend web applications only a view needs to be created in the controller endpoints which is then returned from the controller endpoint.
+
+```php
+public function controllerEndpoint(HttpRequest $request, HttpResponse $response, array $data = []) : RenderableInterface
+{
+	$view = new View($this->app->l11nManager, $request, $response);
+	$view->setTemplate('....');
+	$view->setData('data_id', ....);
+
+	return $view;
+}
+```
+
+### JSON Response
+
+A json response can be created by defining the correct header and adding `\JsonSerializable` elements to the response.
+
+```php
+$response->header->set('Content-Type', MimeType::M_JSON . '; charset=utf-8', true);
+$response->set('response_id' {array or \JsonSerializable};
+```
+
+### Other
+
+Other response types besides the above described ones are all handled in the same way. You must set the response type/header and provide an element which can be converted by `StringUtils::stringify()`.
+
 ## Socket Response
 
 ## Websocket Response

basics/routing.md

@@ -1,7 +1,6 @@
 # Routing
 
-Routing allows to bind a string representation to a function. This is required in order to execute request specific code segments.
-One very common scenario for routing is to take the url of a http(s) request and assign it to a function located in a controller.
+Routing allows to bind a string representation to a function. This is required in order to execute request specific code segments. One very common scenario for routing is to take the url of a http(s) request and assign it to a function located in a controller.
 
 ## Routes
 
@@ -45,7 +44,7 @@ Instead of defining closures it's possible to define a string representation of
 $router->add('foo/bar', '\foo\controller:barFunction');
 ```
 
-Static functions can be defined in the following fashion:
+Static functions can be defined in the following way:
 
 ```php
 $router->add('foo/bar', '\foo\controller::barFunction');
@@ -144,7 +143,7 @@ The state allows a module to have different permissions. E.g. a news module has
 
 ## CSRF Protection
 
-Often you would like to enable `CSRF` protection for certain urls or routing paths. The router can check if a CSRF protection is needed for a certain path and if it is needed it will check if a CSRF token is provided. If no CSRF protection is required it will ignore the CSRF token, but if it is necessary the router will check if it is available.
+Often you would like to enable `CSRF` protection for certain urls or routing paths. The router can check if a CSRF protection is needed for a certain path and if it is needed it will check if the correct CSRF token is provided. If no CSRF protection is required it will ignore the CSRF token.
 
 ```php
 $router->add('foo/bar', function() {

basics/views.md

@@ -14,7 +14,22 @@ The base view class contains the request as well as the response objects hence i
 
 In the template you can simply use `$this->getText({TEXT_ID})` for localized text. All other localization elements can be accessed in a similar way e.g. `$this->l11n->getTemperature()`.
 
-In html templates it's recommended to use `$this->getHtml({TEXT_ID})` as this will savely escape defined strings for html output. In case you would like to escape none pre-defined language strings use `$this->printHtml('string to escape')`.
+In html templates it's recommended to use `$this->getHtml({TEXT_ID})` as this will savely escape static/defined strings (see language files) for html output. By default the language file of the current module is used for the translation, if you would like to use a translation from another module you have to specify the module name and the template name e.g. `<?= $this->getHtml('Word', 'ModuleName', 'TemplateName'); ?>`. This only works if the specified module is available and therefore it is only recommended to use this if the current module has a dependency defined on the specified module which ensures its availability.
+
+Furthermore there is also a global translation file for common translations, this can be accessed as follows `<?= $this->getHtml('Word', '0', '0'); ?>`. Common translations are for example `ID`, `Submit`, `Send`, `Cancel` etc.
+
+In case you would like to escape none pre-defined language strings use `$this->printHtml('string to escape')`.
+
+Other important functions are:
+
+* getNumeric()
+* getPrecentage()
+* getCurrency()
+* getDateTime()
+
+## HTML Encoding
+
+The `printHtml()` function already escapes the localized output. However, in some cases no static localization is available and a simple string needs to be encoded (e.g. a string from a model like the title of a news article). In this case the member function `printHtml()` or the static function `html()` can be called to correctly escape whatever input string is provided.
 
 ## Templates
 

example_module/module.md

@@ -160,7 +160,7 @@ final class Installer extends InstallerAbstract
 If your application doesn't need to implement any database tables for itself the switch statement can be omitted. From the directory structure at the beginning we can however see that some modules accept information form other modules. The following example shows how the navigation module is accepting information during the installation of other modules:
 
 ```php
-public static function installExternal(Pool $dbPool, array $data)
+public static function installExternal(Pool $dbPool, array $data) : array
 {
     /* What do you want to do with the data provided by $data? */
 }

example_module/packages.md

@@ -64,5 +64,4 @@ The `package.json` file contains information of the package.
 
 ### Other
 
-All other files are related to updates, patches, extensions and installation. These files can be simple assets that will be used or
-replaced in modules, classes in the framework that need to be updated and sql methods for updating the database schema.
+All other files are related to updates, patches, extensions and installation. These files can be simple assets that will be used or replaced in modules, classes in the framework that need to be updated and sql methods for updating the database schema.