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

dashboard widgets are configurable via config (#269)

Browse Source
This commit is contained in:
Kevin Papst
2018-08-17 23:17:02 +02:00
committed by GitHub
parent 7804ef83ce
commit dbbb434723
49 changed files with 2011 additions and 938 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
var/docs/README.md
View File

@@ -8,18 +8,18 @@ try to add it as soon as possible.
## User manual
For the most part Kimai usage should be self-explanatory, so we will only cover topics here which were
For the most parts Kimai usage should be self-explanatory, so we will only cover topics here which were
[requested](https://github.com/kevinpapst/kimai2/issues) by the community.
- [Timesheets](timesheet.md) - information about timesheets
## Developer & Administrator
- [Kimai configurations](configurations.md) - application configs, which can only be changed in config files
- [Developer docu](developers.md) - how to extend Kimai's feature set
- [Timesheets](timesheet.md) - information about timesheets
- [User and Security](users.md) - docu for user and security topics, like authentication, registration and roles
- [Configurations](configurations.md) - intro into the global application configs
- [Emails](emails.md) - transport configuration and handling of emails
- [Dashboard & widgets](dashboard.md) - how to configure widgets and dashboard sections
- [Calendar](calendar.md) - the Timesheet calendar view
- [Developer docu](developers.md) - how to extend Kimai's feature set
- [Theme settings](theme.md) - theme related settings
- [FAQ](faq.md) - some answers to frequently asked questions
- [Emails](emails.md) - transport configuration and handling of emails
- [API](developers_api.md) - how to use the JSON API
- [Translations](translations.md) - all about languages and translations

45
var/docs/calendar.md Normal file
View File

@@ -0,0 +1,45 @@
# Calendar
Kimai 2 provides a calendar view, which displays your timesheet entries in a easy readable format.
You can choose between a monthly, weekly and daily view.
The calendar view look and feel is configured with the config keys below `kimai.calendar` in `kimai.yaml`:
```yaml
kimai:
calendar:
week_numbers: true
day_limit: 4
businessHours:
days: [1, 2, 3, 4, 5]
begin: '08:00'
end: '20:00'
```
- `week_numbers` - whether week numbers should be displayed in the monthly view (default: true)
- `day_limit` defined the max amount of items to be displayed for one day in the monthly view (default: 4)
- `businessHours.days` defines your working days, which will be highlighted in the weekly and daily view. counting starts with sunday and the index 0, so 1 = monday, ..., 6 = saturday. (default: 1-5 / monday to friday)
- `businessHours.begin` the start time of your working day, which will be highlighted in the weekly and daily view (default: 08:00 / 8am)
- `businessHours.end` the end time of your working day, which will be highlighted in the weekly and daily view (default: 20:00 / 8pm)
#### Integrating google calender
If you want to embed Google calendars e.g. to display regional holidays or company events you can import (multiple) Google calendars.
- read how to obtain your [Google API key and find the Calender ID](https://fullcalendar.io/docs/google-calendar)
- add the optional `kimai.calendar.google` configuration
- you can add any number of sources under the `kimai.calendar.google.sources` node, each must have its own name (like `holidays` and `company` in this example)
```yaml
kimai:
calendar:
google:
api_key: 'your-restricted-google-api-key'
sources:
holidays:
id: 'de.german#holiday@group.v.calendar.google.com'
color: '#ccc'
company:
id: 'de.german#holiday@group.v.calendar.google.com'
color: '#cc0000'
```

61
var/docs/configurations.md
View File

@@ -17,13 +17,20 @@ Configuration of Kimai is spread in all files in the `config/`directory but main
- `.env` - environment specific settings
- `config/packages/kimai.yaml` - Kimai specific settings
- `config/packages/admin_lte.yaml` - theme specific settings ([read more](https://github.com/kevinpapst/AdminLTEBundle/blob/master/Resources/docs/configurations.md))
- `config/packages/admin_lte.yaml` - Kimai base theme
- `config/packages/fos_user.yaml` - user management and email settings
- `config/packages/local.yaml` - your local configuration settings
There are several other configurations that could potentially be interesting for you in [config/packages/*.yaml](../../config/packages/).
If you want to adjust a setting from any of these files, use `local.yaml`.
If you want to adjust a setting from any of these files, use `local.yaml` (see below).
#### Other topics
- [Theme settings](theme.md) - in `kimai.yaml` and `admin_lte.yaml`
- [Email configuration](emails.md) - in `swiftmailer.yaml`
- [Dashboard widgets](dashboard.md) - in `kimai.yaml`
- [Calendar](calendar.md) - in `kimai.yaml`
## Overwriting local configs (local.yaml)
@@ -63,10 +70,6 @@ bin/console cache:warmup --env=prod
Depending on your setup it might be necessary to execute these commands as webserver user,
please read the [UPGRADING guide](../../UPGRADING.md) for more details.
## Emails (swiftmailer.yaml)
Read more about [email configuration](emails.md).
## Security
Kimai uses the FOSUserBundle for security related tasks like user management. Its configuration can be found in [fos_user.yaml](../../config/packages/fos_user.yaml).
@@ -176,7 +179,7 @@ kimai:
duration: 60
```
A rule which is often used is to round to a mulitple of 10:
A rule which is often used is to round up to a mulitple of 10:
```yaml
kimai:
@@ -219,47 +222,3 @@ kimai:
days: ['saturday','sunday']
factor: 1.5
```
### Timesheet - Calendar view (kimai.yaml)
The calendar view look and feel can be be configured with the config keys below `kimai.calendar`:
```yaml
kimai:
calendar:
week_numbers: true
day_limit: 4
businessHours:
days: [1, 2, 3, 4, 5]
begin: '08:00'
end: '20:00'
```
- `week_numbers` - whether week numbers should be displayed in the monthly view (default: true)
- `day_limit` defined the max amount of items to be displayed for one day in the monthly view (default: 4)
- `businessHours.days` defines your working days, which will be highlighted in the weekly and daily view. counting starts with sunday and the index 0, so 1 = monday, ..., 6 = saturday. (default: 1-5 / monday to friday)
- `businessHours.begin` the start time of your working day, which will be highlighted in the weekly and daily view (default: 08:00 / 8am)
- `businessHours.end` the end time of your working day, which will be highlighted in the weekly and daily view (default: 20:00 / 8pm)
#### Integrating google calender
If you want to embed Google calendar events e.g. to display regional holidays or company partys you can import (multiple) Google calendars.
- read how to obtain your [Google API key and find the Calender ID](https://fullcalendar.io/docs/google-calendar)
- add the optional `kimai.calendar.google` configuration
- you can add any number of sources under the `kimai.calendar.google.sources` node, each must have its own name (like `holidays` and `company` in this example)
```yaml
kimai:
calendar:
google:
api_key: 'your-restricted-google-api-key'
sources:
holidays:
id: 'de.german#holiday@group.v.calendar.google.com'
color: '#ccc'
company:
id: 'de.german#holiday@group.v.calendar.google.com'
color: '#cc0000'
```

126
var/docs/dashboard.md Normal file
View File

@@ -0,0 +1,126 @@
# Dashboard
Read the [configuration chapter](configurations.md) before you start changing your configs.
## Widgets
Widgets are defined in the configuration node `kimai.widgets` and you find the pre-defined ones in [kimai.yaml](../../config/packages/kimai.yaml).
Here is an example of one widget definition:
```yaml
kimai:
widgets:
userDurationToday: { title: stats.durationToday, query: duration, user: true, begin: '00:00:00', end: '23:59:59', icon: duration, color: green }
```
Widgets are currently only used in the Dashboard, but maybe used in other template parts as well in the future.
### Widget settings
- `title` - the title of your widget (will be translated)
- `query` - the allowed queries to use for populating the widget data are `duration`, `rate`, `active` and `users`
- `user` - whether the query is executed for the current user or for all users. possible values are `true` and `false` (default: `false` - all data is used to calculate the result)
- `begin` - setting the start date for the query, formatted with the [PHP DateTime syntax](http://php.net/manual/en/datetime.formats.relative.php) (default: `null` - a query matching any start date)
- `end` - setting the end date for the query, formatted with the [PHP DateTime syntax](http://php.net/manual/en/datetime.formats.relative.php) (default: `null` - a query matching any end date)
- `color` - a color name, see all possible names in [theme settings](theme.md) (default: ``)
- `icon` - an icon alias from [theme settings](theme.md) or any other icon from [Font Awesome 5](https://fontawesome.com/icons) (default: `null` - no icon)
## Dashboard sections
Within the dashboard all widgets are placed in sections (rows) like this:
```yaml
kimai:
dashboard:
user_duration:
title: dashboard.you
order: 10
permission: ROLE_USER
widgets: [userDurationToday, userDurationWeek, userDurationMonth, userDurationYear, userDurationTotal]
```
### Section settings
- `permission` - the name of a role who is allowed to see the widgets, see [users](users.md)
- `title` - the title of a section, if omitted no title will be shown (default: `null`)
- `widgets` - an array of widget names (see above for an example)
- `order` - allows to define the order of the section
### Default sections
The dashboard has the following default sections:
- `user_duration` - order 10
- `user_rates` - order 20
- `duration` - order 30
- `active_users` - order 40
- `rates` - order 50
- `admin` - order 100 (this section is programmatically added)
### Overwriting sections
A section with an empty list of widgets will not be rendered.
If you don't like the default sections you can remove them by overwriting their widget list like this:
```yaml
kimai:
dashboard:
user_duration: { widgets: [] }
user_rates: { widgets: [] }
duration: { widgets: [] }
active_users: { widgets: [] }
rates: { widgets: [] }
```
It's also possible to change the title or the list of widgets for every section like this:
```yaml
kimai:
dashboard:
user_duration:
title: 'some fancy widgets'
widgets: [userDurationWeek, userDurationMonth, userDurationYear]
```
### Reorder sections
If you want to reorder the sections, you can overwrite as many sections as you want and simply change their `order` key.
Lower numbers will be rendered before higher numbers.
```yaml
kimai:
dashboard:
user_duration: { order: 30 }
user_rates: { order: 90 }
duration: { order: 40 }
active_users: { order: 20 }
rates: { order: 50 }
```
### Test widgets for the "brave users"
While working on the widgets, some of them were created for testing future functionalities of Kimai.
You can try them out, but I can't guarantee that they will be supported in the future, as I don't consider them to be `stable` for now.
You can try this configuration in your `local.yaml` to see a chart instead of plain boxes for the last 2 years of monthly times:
```yaml
kimai:
widgets:
userRecapTwoYears: { title: stats.durationToday, query: monthly, user: true, begin: '01 january last year 00:00:00', end: '31 december this year 23:59:59', color: '#3b8bba|rgba(0,115,183,0.6);#c1c7d1|rgb(210,214,222,0.9)' }
dashboard:
user_duration:
type: chart
widgets: [userRecapTwoYears, userDurationToday, userDurationWeek, userDurationMonth, userDurationYear]
```
A brief description: the `monthly` query allows to fetch data by month and year, but the default widgets are not able to render this data.
So internally a __chart section template__ (`type: chart`) is used to render the data, which is also able to fetch and display the data for
all of the following widgets in the configured section (the above example overwrites the widget config of the default `user_duration` section).
In order to work, the chart widget `userRecapTwoYears` needs to be the first in the section.
This widgets setup and configuration will likely change in the future, so keep an eye on this config if this widget
doesn't work after one of the next updates!

21
var/docs/developers.md
View File

@@ -135,7 +135,8 @@ And that's how to use it:
```php
use App\Event\DashboardEvent;
use App\Model\WidgetRow;
use App\Model\DashboardSection;
use App\Model\Widget;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class MyDashboardSubscriber implements EventSubscriberInterface
@@ -147,14 +148,19 @@ class MyDashboardSubscriber implements EventSubscriberInterface
public function onDashboardEvent(DashboardEvent $event)
{
$row = new WidgetRow('my_id', 'optional.row.title');
// this needs to be a valid twig template string
$row->add("{{ widgets.info_box_counter('a title', 100, 'far fa-hourglass', 'green') }}");
$event->addWidgetRow($row);
$section = new DashboardSection('optional.row.title');
$widget = new Widget('A title', 100);
$widget
->setIcon('duration')
->setColor('purple')
->setType(Widget::TYPE_COUNTER)
;
$section->addWidget($widget);
$event->addSection($section);
}
}
```
For more details check the [official dashboard subscriber](../../src/EventSubscriber/DashboardSubscriber.php).
For more details check this [dashboard subscriber](../../src/EventSubscriber/DashboardSubscriber.php).
## Adding tabs to the "control sidebar"
@@ -172,7 +178,8 @@ admin_lte:
icon: "fas fa-question-circle"
template: sidebar/home.html.twig
```
You have to define the `icon` (FontAwesome 5) to be used and one of: `controller` action or twig `template`.
You have to define the `icon` ([read more](theme.md)) to be used and either `controller` action or twig `template`.
Both follow the default naming syntax and you can 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 or the `local.yaml` [config](configurations.md),
otherwise they might get lost during an update.

2
var/docs/installation.md
View File

@@ -1,7 +1,7 @@
# Installation
If you want to install Kimai v2 in your production environment and have SSH access, then switch to the official
installation instruction in our [README](https://github.com/kevinpapst/kimai2/blob/master/README.md).
installation instruction in our [README](https://github.com/kevinpapst/kimai2/#installation).
You need GIT and [Composer](https://getcomposer.org/doc/00-intro.md) on the machine where you want to install Kimai.

98
var/docs/theme.md Normal file
View File

@@ -0,0 +1,98 @@
# Theme
Kimai uses the [AdminLTE theme](https://github.com/kevinpapst/AdminLTEBundle/) which can be configured in the file `config/packages/admin_lte.yaml`.
You find the theme specific documentation [here](https://github.com/kevinpapst/AdminLTEBundle/blob/master/Resources/docs/configurations.md).
All Kimai specific theme settings will be available in the twig templates with the global `kimai_context` key, e.g.
```twig
{{ kimai_context.box_color }}
```
## Active entries warning
A small colored warning sign will be shown, if a user has more than 3 active timesheet entries.
You can change this soft limit by setting the config key `kimai.theme.active_warning` in your `local.yaml`:
```yaml
kimai:
theme:
active_warning: 2
```
## Colors
Kimai allows you to configure colors in several places throughout the theme.
Possible values are:
- `aqua`
- `black`
- `blue`
- `gray`
- `green`
- `purple`
- `red`
- `yellow`
### Fallback color
Whenever a color is required but none is configured, Kimai uses a fallback language from the config key `kimai.theme.box_color`.
You can change the default color `green` to any one from the above in your `local.yaml`:
```yaml
kimai:
theme:
box_color: 'blue'
```
The fallback color should be applied whenever an optional color is configurable by the user:
```twig
<div class="info-box bg-{{ color|default(kimai_context.box_color) }}"></div>
```
## Icons
Kimai allows you to configure icons in several places (provided by [Font Awesome 5](https://fontawesome.com/icons)) and ships
with a pre-defined list of icon aliases to guarantee a consistent look.
The pre-defined icons aliases are:
- `user`
- `customer`
- `project`
- `activity`
- `admin`
- `invoice`
- `timesheet`
- `dashboard`
- `logout`
- `trash`
- `delete`
- `repeat`
- `edit`
- `manual`
- `help`
- `start`
- `start-small`
- `stop`
- `stop-small`
- `filter`
- `create`
- `list`
- `print`
- `visibility`
- `calendar`
- `money`
- `duration`
Icon aliases can be used by applying the `icon` filter, e.g.
```
<i class="{{ 'money'|icon }}"></i>
```

14
var/docs/timesheet.md
View File

@@ -2,26 +2,18 @@
User manual on the timesheet tables and actions.
## Edit timesheet
Kimai 2 provides also a [calendar view](calendar.md), which displays your timesheet entries in an easy readable format.
### Duration only
## Duration only
When the `duration_only` mode is activated, you will only see the `date` and `duration` fields (see [configurations chapter](configurations.md)).
The `duration` field supports entering data in the following formats:
| Name | Format | Description | Examples |
|---|---|---|
|---|---|---|---|
| Colons | {hours}:{minutes}[:{seconds}] | Seconds are optional, overflow is supported for every field | `2:27` = 2 Hours, 27 Minutes / `3:143:13` = 5 Hours, 23 Minutes, 13 Seconds|
| Natural | {hours}h{minutes}m[{seconds}s] | Seconds are optional, overflow is supported for every field | `2h27m` = 2 Hours, 27 Minutes / `3h143m13s` = 5 Hours, 23 Minutes, 13 Seconds |
| Seconds | {seconds} | | `3600` = 1 Hour / `8820` = 2 Hours, 27 Minutes |
Please note: if time rounding is activated (which is the default behaviour), then your entered seconds might be removed after submitting the form.
## Calendar view
Kimai 2 provides a calendar view, which displays your timesheet entries in a easy readable format.
You can choose between a monthly, weekly and daily view.
It's also possible to include further [Google calendar sources](configurations.md) from Google, e.g. if you want to display regional holidays.

6
var/docs/users.md
View File

@@ -1,9 +1,9 @@
# Users
There are multiple pre-defined roles in Kimai, which define the ACLs. A user can only inherit one role, where the roles extend each user.
## Roles & Permissions
There are multiple pre-defined roles in Kimai, which define the ACLs. A user can only inherit one role, where the roles extend each user.
| Role name | extends | Gives permission for |
|---|---|---|
| ROLE_CUSTOMER | - | Currently has no permissions, but was reserved for future functionality |
@@ -14,7 +14,7 @@ There are multiple pre-defined roles in Kimai, which define the ACLs. A user can
## Login
- User can login with their username or email
- User can login with username or email
- If you activate the `Remember me` option, you can use use the most common functions within the next days without a new login
### Remember me login