127 lines
5.1 KiB
Markdown
127 lines
5.1 KiB
Markdown
# 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!
|