help text and link for form labels #138 (#143)

* added help for timesheet duration form field - fixes #138
* added label option to link to manual chapter
* created docu chapter "timesheet" and added duration mode docu
* allow field and form option "documentation" to link to chapters in the documentation

composer.lock

@@ -52,12 +52,12 @@
             "source": {
                 "type": "git",
                 "url": "https://github.com/kevinpapst/AdminThemeBundle.git",
-                "reference": "d0d849ac59889ad6f4408fee84e23b09d7d65d36"
+                "reference": "909be9b2d19bc31db1751990b93cf0192893ae5c"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/kevinpapst/AdminThemeBundle/zipball/d0d849ac59889ad6f4408fee84e23b09d7d65d36",
-                "reference": "d0d849ac59889ad6f4408fee84e23b09d7d65d36",
+                "url": "https://api.github.com/repos/kevinpapst/AdminThemeBundle/zipball/909be9b2d19bc31db1751990b93cf0192893ae5c",
+                "reference": "909be9b2d19bc31db1751990b93cf0192893ae5c",
                 "shasum": ""
             },
             "require": {
@@ -111,7 +111,7 @@
             "support": {
                 "source": "https://github.com/kevinpapst/AdminThemeBundle/tree/kevinpapst"
             },
-            "time": "2018-01-21T19:07:18+00:00"
+            "time": "2018-06-19T21:30:20+00:00"
         },
         {
             "name": "beberlei/DoctrineExtensions",

config/services.yaml

@@ -73,6 +73,10 @@ services:
         tags:
             - { name: form.type }
 
+    App\Form\Extension\DocumentationLinkExtension:
+        tags:
+            - { name: form.type_extension, extended_type: Symfony\Component\Form\Extension\Core\Type\FormType }
+
     # ================================================================================
     # THEME
     # ================================================================================

src/Form/Extension/DocumentationLinkExtension.php

@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Form\Extension;
+
+use Symfony\Component\Form\AbstractTypeExtension;
+use Symfony\Component\Form\Extension\Core\Type\FormType;
+use Symfony\Component\Form\FormInterface;
+use Symfony\Component\Form\FormView;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+/**
+ * Adds a linked help text with the link to the given documentation
+ */
+class DocumentationLinkExtension extends AbstractTypeExtension
+{
+    /**
+     * @return string
+     */
+    public function getExtendedType()
+    {
+        return FormType::class;
+    }
+
+    /**
+     * @param FormView $view
+     * @param FormInterface $form
+     * @param array $options
+     */
+    public function buildView(FormView $view, FormInterface $form, array $options)
+    {
+        $view->vars['documentation'] = $options['documentation'] ?? '';
+    }
+
+    /**
+     * @param OptionsResolver $resolver
+     */
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefined(array('documentation'));
+        $resolver->setDefaults(['documentation' => null]);
+    }
+}

src/Form/TimesheetEditForm.php

@@ -94,6 +94,7 @@ class TimesheetEditForm extends AbstractType
             'csrf_token_id' => 'timesheet_edit',
             'duration_only' => false,
             'include_user' => false,
+            'documentation' => 'timesheet',
         ]);
     }
 }

templates/default/_form.html.twig

@@ -1,7 +1,13 @@
 <div class="box box-primary">
     <div class="box-header with-border">
-        <h3 class="box-title">{{ title }}</h3>
+        <h3 class="box-title">
+            {{ title }}
+            {% if form.vars.documentation is defined and form.vars.documentation is not empty %}
+                <a href="{{ path('help_chapter', {'chapter': form.vars.documentation}) }}"><i class="fa fa-question-circle"></i></a>
+            {% endif %}
+        </h3>
     </div>
+    {% form_theme form 'form/kimai-theme.html.twig' %}
     {{ form_start(form) }}
     <div class="box-body">
          {{ form_widget(form) }}

templates/form/kimai-theme.html.twig

@@ -0,0 +1,8 @@
+{% extends "@AvanzuAdminTheme/layout/form-theme.html.twig" %}
+
+{% block form_label %}
+    {% if form.vars.documentation is defined and form.vars.documentation is not empty %}
+        <a href="{{ path('help_chapter', {'chapter': form.vars.documentation}) }}"><i class="fa fa-question-circle"></i></a>
+    {% endif %}
+    {{ parent() }}
+{% endblock form_label %}

var/docs/README.md

@@ -2,9 +2,15 @@
 
 Welcome to the official Kimai v2 documentation. 
 
+The first chapters are meant for developers and administrators:
+
 - [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 ...  
+- [User and Security](users.md) - everything related to user and security, like authentication and roles  
+
+The following chapters are meant for users:
+
+- [Timesheets](timesheet.md) - information about timesheets  
 
 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 

var/docs/configurations.md

@@ -17,6 +17,8 @@ The `start` date is only visible in these forms when editing an active or starti
 
 You can activate the `duration_only` mode by switching the configuration key `kimai.timesheet.duration_only` to `true` in the file [kimai.yaml](../../config/packages/kimai.yaml).
 
+For supported formats while entering the `duration` please see the [timesheet chapter](timesheet.md) 
+
 ## Remember me login
 
 The default period for the `Remember me` option can be changed in the config file [security.yaml](../../config/packages/security.yaml). 

var/docs/timesheet.md

@@ -0,0 +1,19 @@
+# Timesheet
+
+User manual on the timesheet tables and actions.
+
+## Edit timesheet
+
+### 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.