Jingga/Developer-Guide
1
0
Fork 0
mirror of https://github.com/Karaka-Management/Developer-Guide.git synced 2026-01-11 20:38:42 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch 'develop' of https://github.com/karaka-management/Developer-Guide into develop

Browse Source
This commit is contained in:
Dennis Eichhorn 2022-04-08 17:57:11 +02:00
commit 0a87e7259a
10 changed files with 165 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/image.yml vendored
View File

@ -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 }}

3
SUMMARY.md
View File

@ -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)

1
basics/responses.md
View File

@ -16,7 +16,6 @@ The `{stringifiable_element}` accepts all supported types from the `StringUtils:
* \JsonSerializable
* array
* \Serializable
* string
* int
* float

2
basics/views.md
View File

@ -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.

29
frontend/elements/dragndrop/dragndrop.md Normal file
View File

@ -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
<div class="dragcontainer">
</div>
```
## Draggable elements
Elements which should be draggable in the container must be marked with `draggable="true"`.
```html
<div class="dragcontainer">
<div draggable="true">1</div>
<div draggable="true">2</div>
<div draggable="true">3</div>
<div draggable="true">4</div>
</div>
```
> If new draggable elements are dynamically added to the container they automatically get recognized, no additional event binding is necessary.
![Button normal](Developer-Guide/frontend/elements/dragndrop/dragndrop.png)

BIN
frontend/elements/dragndrop/dragndrop.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

60
frontend/forms/forms.md Normal file
View File

@ -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

9
general/contribution.md Normal file
View File

@ -0,0 +1,9 @@
# Contribution Guidelines
* Getting started
* Permissions
* Setup
* Code style
* Tests
* Code of conduct
* Code review

49
general/setup.md
View File

@ -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

41
quality/inspections.md
View File

@ -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.
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
```