diff --git a/.github/workflows/image.yml b/.github/workflows/image.yml
index d2fb2d4..8900845 100644
--- a/.github/workflows/image.yml
+++ b/.github/workflows/image.yml
@@ -19,6 +19,6 @@ jobs:
uses: actions/checkout@master
- name: Compress Images
- uses: calibreapp/image-actions@master
+ uses: calibreapp/image-actions@main
with:
githubToken: ${{ secrets.GITHUB_TOKEN }}
\ No newline at end of file
diff --git a/SUMMARY.md b/SUMMARY.md
index b8c33cd..3d23fe4 100755
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -76,9 +76,10 @@
* [Breadcrumbs]({%}?page=frontend/elements/breadcrumbs/breadcrumbs)
* [Progress]({%}?page=frontend/elements/progress/progress)
* [Layout]({%}?page=frontend/grid/grid)
+* [Drag & Drop]({%}?page=frontend/elements/dragndrop/dragndrop)
* [Charting]({%}?page=services/charting)
### Forms
-* [Forms]({%}?page=frontend/elements/forms/forms)
+* [Forms]({%}?page=frontend/forms/forms)
* [Inputs]({%}?page=frontend/elements/inputs/inputs)
* [Tables]({%}?page=frontend/elements/tables/tables)
diff --git a/basics/responses.md b/basics/responses.md
index 1a80d67..7f15522 100755
--- a/basics/responses.md
+++ b/basics/responses.md
@@ -16,7 +16,6 @@ The `{stringifiable_element}` accepts all supported types from the `StringUtils:
* \JsonSerializable
* array
-* \Serializable
* string
* int
* float
diff --git a/basics/views.md b/basics/views.md
index ddfeed1..3094662 100755
--- a/basics/views.md
+++ b/basics/views.md
@@ -4,7 +4,7 @@ Views contain the raw information of a result which then depending on the templa
## Implementation
-A view must implement `\Serializable` and `\JsonSerializable`.
+A view must implement `__serialize/__unserialize` and `\JsonSerializable`.
In case the response header is set to JSON the view will automatically get parsed as JSON object, either by using a the JSON template or by encoding the view. For the JSON serialization the `jsonSerialize()` function will be used in all other cases the `serialize()` function will be used.
diff --git a/frontend/elements/dragndrop/dragndrop.md b/frontend/elements/dragndrop/dragndrop.md
new file mode 100644
index 0000000..a261c8f
--- /dev/null
+++ b/frontend/elements/dragndrop/dragndrop.md
@@ -0,0 +1,29 @@
+# Drag & Drop
+
+Elements can be made drag and droppable which can be helpful to allow users to re-order and re-position elements in a list, table or customize the user interface.
+
+## Container
+
+In order to make elements drag and droppable you must define a container which contains all the drag and droppable elements.
+
+```html
+
+
+```
+
+## Draggable elements
+
+Elements which should be draggable in the container must be marked with `draggable="true"`.
+
+```html
+
+```
+
+> If new draggable elements are dynamically added to the container they automatically get recognized, no additional event binding is necessary.
+
+
\ No newline at end of file
diff --git a/frontend/elements/dragndrop/dragndrop.png b/frontend/elements/dragndrop/dragndrop.png
new file mode 100644
index 0000000..13451ef
Binary files /dev/null and b/frontend/elements/dragndrop/dragndrop.png differ
diff --git a/frontend/forms/forms.md b/frontend/forms/forms.md
new file mode 100644
index 0000000..6feaa43
--- /dev/null
+++ b/frontend/forms/forms.md
@@ -0,0 +1,60 @@
+# Forms
+
+## Bindings
+
+data-tag : tells the element how to behave (e.g. turn none-form elements into forms by defining it as "form")
+data-method : method definition for none-form elements (not used for actual forms, where method can be used)
+
+data-marker=tpl : ??? maybe entries which are templates (e.g. inline add or inline edit?) **check**
+data-id : Data id (primary id value, by which it is stored in the database)
+
+data-ui-content
+data-ui-element
+
+data-tpl-text
+data-tpl-value
+data-value
+value
+
+data-add-form : form template to use for the inline add **check**
+data-add-content
+data-add-element
+data-add-tpl
+
+data-update-form : form where updates/changes are handled (this means there is an external form where the data gets copied to for modification)
+data-update-content
+data-update-element
+data-update-tpl
+
+data-tpl-text-path : remote path for the text
+data-tpl-value-path : remote path for the text
+
+
+## Todos
+
+### General
+- [x] Order
+- [ ] Remote order
+- [x] DragDrop
+- [ ] Remote DragDrop
+- [x] Remove
+- [ ] Remote Remove
+- [ ] Remote Update on change (no save button required)
+
+### Heartbeat
+- [ ] Remote adds (heartbeat checks)
+- [ ] Remote updates (heartbeat checks)
+- [ ] Remote removes (heartbeat checks)
+
+### External
+- [x] add
+- [ ] update
+- [ ] remote add
+- [ ] remote update
+- [x] cancel
+
+### Internal
+- [ ] add
+- [ ] update
+- [ ] remote add
+- [ ] remote update
\ No newline at end of file
diff --git a/general/contribution.md b/general/contribution.md
new file mode 100644
index 0000000..77c519c
--- /dev/null
+++ b/general/contribution.md
@@ -0,0 +1,9 @@
+# Contribution Guidelines
+
+* Getting started
+ * Permissions
+ * Setup
+* Code style
+* Tests
+* Code of conduct
+* Code review
diff --git a/general/setup.md b/general/setup.md
index 975d4ab..dfff002 100755
--- a/general/setup.md
+++ b/general/setup.md
@@ -8,16 +8,26 @@ Make sure your dev-environment or server fulfills the following requirements:
* PHP >= 8.0
* PHP extensions: mbstring, gd, zip, dom, pdo, pdo-mysql/pdo-pgsql/pdo-sqlsrv, sqlite, bcmath, imap\*, redis\*, memcached\*, ftp\*, socket\*, curl\*, xml\*
+ * Extension list: `php8.0 php8.0-dev php8.0-cli php8.0-common php8.0-mysql php8.0-pgsql php8.0-xdebug php8.0-opcache php8.0-pdo php8.0-sqlite php8.0-mbstring php8.0-curl php8.0-imap php8.0-bcmath php8.0-zip php8.0-dom php8.0-xml php8.0-phar php8.0-gd php-pear`
* databases: mysql/postgresql/sqlsrv
* web server: apache2/nginx
* mod_headers (apache2)
+* software: tesseract-ocr\*, pdftotext\*, pdftoppm\*
The application and frameworks can use different databases. For the normal development process you only need one (whichever you prefer). However, in order to test against all supported databases and all code paths you would have to install all above mentioned databases.
-Extensions marked with `*` are optional but recommended. They are only required in special situations. Requirements with a `/` in between mean that only one of the dependencies is necessary depending on your preferences and previous decisions.
+Extensions and software marked with `*` are optional but recommended. They are only required in special situations. Requirements with a `/` in between mean that only one of the dependencies is necessary depending on your preferences and previous decisions.
Steps which are not explained in this documentation are how to install and setup the above mentioned software and extensions. You also should configure the web server paths accordingly in order to access the application in the browser.
+### IDE / Editor
+
+Which IDE or editor a developer uses is up to the individual developer. From experience the following opinionated choices provided good results:
+
+* Visual Studio Code (vscode)
+* Sublime
+* PHPStorm (mostly for php, html, css, js)
+
### Installation Options
1. Option 1: Full installation, code checks/tests, generating documentation. **Not recomended as quick setup**
@@ -74,28 +84,6 @@ After the installation you'll have access to the following content:
During this process the database automatically gets dropped (if it exists) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation.
-## Git Hooks (Linux only)
-
-The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations.
-
-For developers it is recommended to copy the contents of the `default.sh` file in the `Build` repository under `Hooks` to your `pre-commit` file in the `.git/hooks` directory. If the `pre-commit` file doesn't exist just create it.
-
-The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files.
-
-By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` have `+x` permissions.
-
-## Tools
-
-The following tools are important to test the application and to ensure the code quality. The configurations and sample shell executions can be found in the `Build` directory. These tools are also downloaded during the setup process of the `buildProject.sh` script.
-
-* composer
-* phploc
-* phpunit
-* phpcs
-* phpmetrics
-* documentor
-* phpstan
-
## Option 3: Demo Application
This will only setup the application including some dummy data and also perform the code tests but no quality checks. Compared to option 2 this includes much more test data and it doesn't execute a unit test.
@@ -107,12 +95,14 @@ This will only setup the application including some dummy data and also perform
5. Install Composer
6. Run `composer install` inside `Karaka`
7. Create the database table `oms`
-7. Run `php demoSetup/setup.php` inside `Karaka`
+8. Run `php demoSetup/setup.php` inside `Karaka` (takes a long time: > 1h)
After the installation you'll have access to the following content:
* Application: `http://127.0.0.1`
+Instead of calling `php demoSetup/setup.php` which only uses a single thread you may also run `php demoSetup/setup.php -a 0` which will execute the install script in multiple threads leading to most likely 100% CPU and storage usage but therfore significantly reduce the execution time.
+
### Annotation
* During this process the database automatically gets dropped (if it exists) and re-created
@@ -129,3 +119,14 @@ php -dxdebug.profiler_enable=1 -dxdebug.mode=develop,debug,profile -dxdebug.outp
```
> This may use a lot of resources and storage space (≈15 GB of cachegrind data w/o trace data and ≈120 GB w/ trace data)
+
+## Tools
+
+Especially in order to ensure the code quality various tools are used. Check out the inspection guidelines for further details.
+
+## cOMS
+
+### OpenCV
+
+https://docs.opencv.org/3.4/d7/d9f/tutorial_linux_install.html
+
diff --git a/quality/inspections.md b/quality/inspections.md
index bc8118d..89230a2 100755
--- a/quality/inspections.md
+++ b/quality/inspections.md
@@ -81,7 +81,7 @@ php -dxdebug.remote_enable=1 -dxdebug.mode=coverage,develop vendor/bin/phpunit -
#### Modules
-Every module needs to have a `Admin` directory containing a class called `AdminTest.php` which is used for testing the installation, activation, deactivation, uninstall and remove of the module. Tests that install, update, remove etc. a module need to have a group called `admin`. After running the `AdminTest.php` test the final state of the module should be installed and active, only this way it's possible to further test the controller and models. A code coverage of at least 80% is mandatory for every module for integration.
+Every module needs to have a `Admin` directory containing a class called `AdminTest.php` which is used for testing the installation, activation, deactivation, uninstall and remove of the module. Tests that install, update, remove etc. a module need to have a group called `admin`. After running the `AdminTest.php` test the final state of the module should be installed and active, only this way it's possible to further test the controller and models. A code coverage of at least 90% is mandatory for every module for integration.
### PHPStan
@@ -103,7 +103,9 @@ Besides the code tests and static code analysis the code style is another very i
php vendor/bin/phpcs ./ --standard="Build/Config/phpcs.xml" -s --report-junit=Build/test/junit_phpcs.xml
```
-### Git Hooks (Linux only)
+### Custom scripts
+
+#### Git Hooks (Linux only)
The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations.
@@ -111,4 +113,37 @@ For developers it is recommended to copy the contents of the `default.sh` file i
The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files.
-By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` files have `+x` permissions.
\ No newline at end of file
+By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` files have `+x` permissions.
+
+#### Release Report
+
+The [TestReportGenerator](https://github.com/Karaka-Management/TestReportGenerator) generates a customer report which outputs various information regarding tests (unit, integration, static) and code quality. The primary purpose of this report generator is to aggregate the code inspections in a printable format that can be used for auditing purposes on the customer side.
+
+```sh
+php TestReportGenerator/src/index.php \
+ -b /home/oms \
+ -l /home/oms/Build/Config/reportLang.php \
+ -c /home/oms/tests/coverage.xml \
+ -s /home/oms/Build/test/junit_phpcs.xml \
+ -sj /home/oms/Build/test/junit_eslint.xml \
+ -a /home/oms/Build/test/phpstan.json \
+ -u /home/oms/Build/test/junit_php.xml \
+ -d /home/oms/Build/test/ReportExternal \
+ --version 1.0.0
+```
+
+## Demo setup
+
+A good way to setup a demo application with mostly randomly generated user input data is the **demoSetup** script which can be found in the repository https://github.com/Karaka-Management/demoSetup.
+
+The following command will create a demo application:
+
+```sh
+php demoSetup/setup.php
+```
+
+In some cases code changes may require changes to the demo setup script (e.g. changes in the api, new modules). Since the demo setup script tries to simulate user generated data it takes some time to run. You may speed up the runtime by parallelizing the execution. However, this may use up 100% of your CPU and storage performance.
+
+```sh
+php demoSetup/setup.php -a 0
+```