jjsm01/kimai2
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

added rounding rules and hourly rates factor #112 (#128)

Browse Source 
* added unit tests and documentation #112
* fixed DashboardController
* added CONTRIBUTION guidelines
* fixed license year
This commit is contained in:
Kevin Papst
2018-02-07 12:51:00 +01:00
committed by GitHub
parent 65790f1fb7
commit 2e60e14132
22 changed files with 925 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
var/docs/README.md Normal file
View File

@@ -0,0 +1,11 @@
# Kimai documentation
Welcome to the official Kimai v2 documentation.
- [Kimai configurations](configurations.md) - the Kimai core configurations, which can only be set in configuration files
- [Developer docu](developers.md) - information for developer who would like to extend Kimai
- [User and Security](users.md) - everything related to authentication, security, users, roles ...
We know there is a lot missing right now and would appreciate [any help](https://github.com/kevinpapst/kimai2/pulls) in writing.
If you need information which is not available right now, [ask us](https://github.com/kevinpapst/kimai2/issues) and we
try to add it as soon as possible.

81
var/docs/configurations.md Normal file
View File

@@ -0,0 +1,81 @@
# Configurations
There are several configurations that can be configured with the yaml files in `config/packages/*.yaml
## Remember me login
The default period for the `Remember me` option can be changed in the config file [security.yaml](../../config/packages/security.yaml).
## Timesheet records - rounding of begin, end and duration
Rounding rules are used to round the begin & end dates and the duration for timesheet records.
1. You can define as many rules as you want ("default" is only an example)
2. Every matching rule will be applied, so be careful with overlapping rules
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
4. If you set one of "begin", "end", "duration" to 0 no rounding will be applied for that field and the exact time (including seconds) is used for calculation
5. The values of the rules are minutes (not the minute of an hour), so 5 for "begin" means we round down to the previous multiple of five
6. You can define different rules for different days of the week
7. "begin" will always be rounded to the floor (down) and "end" & "duration" to the ceiling (up)
8. Rounding rules will be applied on stopped timesheet records only, so you might see an un-rounded value for the start time and duration until you stop the record
You can configure your `rounding` rules by changing the configuration file [kimai.yaml](../../config/packages/kimai.yaml).
### Examples
A simple example to always charge at least 1 hour for weekend work (even if you only worked for 5 minutes) could look like this:
```yaml
kimai:
timesheet:
rounding:
weekend:
days: ['saturday','sunday']
begin: 1
end: 1
duration: 60
```
A rule which is often used is to round to a mulitple of 10:
```yaml
kimai:
timesheet:
rounding:
workdays:
days: ['monday','tuesday','wednesday','thursday','friday','saturday','sunday']
begin: 10
end: 10
duration: 0
```
## Timesheet records - hourly rates
If you want to apply different hourly rates multiplication `factor` for specific weekdays, you can use this `rates` configuration.
1. You can define as many rules as you want ("workdays" and "weekend" are only examples)
2. Every matching rule will be applied, so be careful with overlapping rules
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
4. "days" is an array of weekdays, where the days need to be written in english and in lowercase
5. "factor" will be used as multiplier for the applied hourly rate
6. Rate rules will be applied on stopped timesheet records only, as it can't be calculated before
7. There is no default rule active, by default the users hourly-rate is used for calculation
You can configure the `hourly_rate` rules by changing the configuration file [kimai.yaml](../../config/packages/kimai.yaml).
### Examples
1. The "workdays" rule will use the default "hourly rate" for each timesheet entry recorded between "monday" to "friday" as a multiplication with 1 will not change the result
2. The "weekend" rule will add 50% to each timesheet entry that will be recorded on "saturdays" or "sundays"
```yaml
kimai:
timesheet:
rates:
workdays:
days: ['monday','tuesday','wednesday','thursday','friday']
factor: 1
weekend:
days: ['saturday','sunday']
factor: 1.5
```

76
var/docs/developers.md
View File

@@ -46,7 +46,7 @@ You can find more information at:
### Rebuilding assets for use in subdirectory
If you want to run Kimai in a subdirectory, you have to rebuild the frontend assets with a different webpack configuration.
Edit the file [webpack.config.js](https://github.com/kevinpapst/kimai2/blob/master/webpack.config.js) and change `.setPublicPath('/build/')` to your needs.
Edit the file [webpack.config.js](../../webpack.config.js) and change `.setPublicPath('/build/')` to your needs.
After that re-compile the assets with:
```bash
@@ -93,7 +93,7 @@ class MySubscriber implements EventSubscriberInterface
}
}
```
For more details check the [official menu subscriber](https://github.com/kevinpapst/kimai2/blob/master/src/EventSubscriber/MenuSubscriber.php).
For more details check the [official menu subscriber](../../src/EventSubscriber/MenuSubscriber.php).
## Adding tabs to the "control sidebar"
@@ -113,6 +113,72 @@ twig:
template: sidebar/home.html.twig
```
You have to define the icon to be used and then one of controller action or template.
Both follow the default naming syntax and you can easily link your bundle here instead of the official.
You should NOT add them in `config/packages/kimai.yaml` but only in your own bundle config.
You have to define the `icon` (font-awesome without the `fa-` prefix) to be used and one of `controller` action or `template`.
Both follow the default naming syntax and you can easily link your bundle here instead of the app controller or templates.
You should NOT add them in `config/packages/kimai.yaml` but in your own bundle config, otherwise they might get lost in a Kimai update.
## Adding invoice renderer
An invoice renderer is a controller action that receives an instanceof `App\Model\InvoiceModel` and returns a HTML response.
This HTML response is the preview inside for the invoice screen.
Adding invoice renderer can be achieved by adding keys to the configuration `kimai.invoice.renderer` like this:
```
kimai:
invoice:
renderer:
default: 'App\Controller\InvoiceController::invoiceAction'
```
The name of the renderer must be unique, please prefix it with your vendor or bundle name and make sure it only contains
character as it will be stored in a database column.
## Adding invoice calculator
An invoice calculator is a class extending `App\Invoice\CalculatorInterface` and is responsible for calculating
invoice rates, taxes and such.
Adding invoice calculator can be achieved by adding keys to the configuration `kimai.invoice.calculator` like this:
```
kimai:
invoice:
calculator:
default: 'App\Invoice\DefaultCalculator'
```
The name of the calculator must be unique, please prefix it with your vendor or bundle name and make sure it only contains
character as it will be stored in a database column.
## Adding invoice-number generator
An invoice-number generator is a class extending `App\Invoice\NumberGeneratorInterface` and its only task is to generate
a number for the invoice. In most cases you do not want to mix multiple invoice-number generators througout your invoice templates.
Adding invoice-number generator can be achieved by adding keys to the configuration `kimai.invoice.number_generator` like this:
```
kimai:
invoice:
number_generator:
default: 'App\Invoice\DateNumberGenerator'
```
The name of the number generator must be unique, please prefix it with your vendor or bundle name and make sure it only contains
character as it will be stored in a database column.
## Adding timesheet calculator
A timesheet calculator will be called on stopped timesheet records. It can rewrite all values but will normally take care
of the columns `begin`, `end`, `duration` and `rate` but could also be used to apply a default `description`.
Timesheet calculator need to implement the interface `App\Timesheet\CalculatorInterface` and will be automatically tagged
as `timesheet.calculator` in the service container. They will be found and used *only* if you add them to the service container.
You can apply several rules in the config file [kimai.yaml](../../config/packages/kimai.yaml) for the existing
`DurationCalculator` and `RateCalculator` implementations. Please read the [configurations chapter](configurations.md) to find out more.
The configuration for "rounding rules" can be fetched from the container parameter `kimai.timesheet.rounding`.
The configuration for "hourly-rates multiplication factors" can be fetched from the container parameter `kimai.timesheet.rates`.

5
var/docs/users.md
View File

@@ -20,7 +20,8 @@ There are multiple pre-defined roles in Kimai, which define the ACLs. A user can
## Remember me login
If you have chosen to login with the `Remember me` option, your login will be extended to one week (default value).
After coming back and being remembered you have access to all the following features:
After coming back and being remembered you have access to all the following features:
- view your own timesheet
- start and stop new records
- edit existing records
@@ -29,4 +30,4 @@ If you are an administrator, you will see all your allowed options in the menu,
form when you try to access them. This is a security feature to prevent abuse in case you forgot to logout in public
environments.
The default period for the `Remember me` option can be changed in the config file [security.yaml](config/packages/security.yaml).
Read the [configurations chapter](configurations.md) if you want to change the value.