Reporter for Kirby

Introduction

Reporter for Kirby is a Kirby 3open in new window plugin which helps you, your editors or clients to report bugs, tasks and to discuss ideas. It provides a very handy way to collect feedback directly out of the Kirby Panel. It is a simple app, which programmatically creates issues for you. That's it.

It supports Githubopen in new window, Gitlabopen in new window and Bitbucket Cloudopen in new window out of the box.

TIP

If you need to work with another issue tracker, please let me knowopen in new window and I will evaluate it.

Since Version 4.0.0 you can send a report via E-Mail if you don't want to utilize an issue tracker.

Playground beta

We all know it can be troublesome to evaluate a Plugin – it must be downloaded, installed and configured only to find out, that it doesn't fit your needs. This is where a playground comes handy, right?

Open Playground

How does it work?

For obvious reasons the given example isn't the »real« Panel Plugin. It would be totally impractical (if not impossible) to extract all necessary Panel dependencies only for that very reason. Lucky me! I've designed the core of Reporter for Kirby to work standalone 😉 I used that fact and built a very simple App, which emulates the Panel look and feel.

Restrictions

The example provides a fully functional implementation and outlines exactly what you can expect from Reporter for Kirby. Of course there are some restrictions which are directly related to security concerns and in opposite of the »real« Panel Plugin, all text – sent to the API – is obfuscated and all links (including images and scripts), are removed.

Besides that, I'm pretty confident this example is sufficient to provide an idea how it works.

Getting started

Installation

You can install Reporter for Kirby using one of the following methods. The preferred one is Composer.

Composer recommend

composer require gearsdigital/reporter-for-kirby
1

Composer? What the heck?

If you aren't familiar with Composer, I recommend reading the cookbook article »Kirby meets Composer«open in new window by Lukas Bestleopen in new window

Submodule

git submodule add https://github.com/gearsdigital/reporter-for-kirby.git site/plugins/reporter-for-kirby
1

You need to perform this command in your Kirby root directory!

Manual

  1. Download the latest versionopen in new window
  2. Extract the archive and rename the folder to reporter-for-kirby
  3. Move the directory to /site/plugins

Setup

Reporter for Kirby supports two types of reports:

  1. Issue Tracker – Send a report to a Githubopen in new window, Gitlabopen in new window and Bitbucket Cloudopen in new window repository.
  2. E-Mail – Send a report via E-Mail.

TIP

If you need to work with another issue tracker, please let me knowopen in new window and I will evaluate it.

Issue Tracker

Before you can start sending reports to an issue tracker, we need to prepare a couple of things:

  1. Create a Personal Access Token
  2. Configure the plugin

Create a Personal Access Token (PAT)

Personal access tokens are substitute passwords for your account to avoid putting your real password into configuration files. It depends on your platform how to obtain a personal access token (or app password).

For the sake of simplicity I just refer to the related help docs:

WARNING

You should create a custom user with limited scope access!

Configure the plugin

In order to work properly, the plugin needs to be enabled and configured properly. This can be done using these options:

  1. gearsdigital.reporter-for-kirby.enabled
  2. gearsdigital.reporter-for-kirby.repository.url
  3. gearsdigital.reporter-for-kirby.repository.token

If you're using Bitbucket and its Workspace feature, you might need to set gearsdigital.reporter-for-kirby.repository.user too. You can read more about that here: #33open in new window

Example
// site/config/config.php
return [
  'gearsdigital.reporter-for-kirby' => [
    'enabled' => true,
    'repository' => [
      'url' => 'https://bitbucket.org/gearsdigital/kirby-reporter-test',
      'token' => 'c56658e7c03a5995e2e1491e6a3b93fcde6225c9',
      'user' => 'gearsdigital-dev' // optional
    ]
  ]
];
1
2
3
4
5
6
7
8
9
10
11

Email

To send the report via Email you need to setup these options:

  1. gearsdigital.reporter-for-kirby.enabled
  2. gearsdigital.reporter-for-kirby.mail.from
  3. gearsdigital.reporter-for-kirby.mail.to
  4. gearsdigital.reporter-for-kirby.mail.subject
  5. gearsdigital.reporter-for-kirby.repository.type - Optional. Default is email
Example
// site/config/config.php
return [
  'gearsdigital.reporter-for-kirby' => [
    'enabled' => true,
    'mail' => [
      'from' => 'mail@example.com',
      'to' => 'track@example.com',
      'subject' => 'Issue Report form gearsdigital.com',
    ]
  ]
];
1
2
3
4
5
6
7
8
9
10
11

Options

This is the list of all available options.


return [
    'gearsdigital.reporter-for-kirby' => [
        /**
         * Controls the plugin state.
         * @type boolean
         */
        'enabled' => true,
        
        /**
         * Holds repository configuration options
         * 
         * []{url: string, token: string, ?user: string}
         */
        'repository' => [
            // required - Define the repository to which the reports are being sent
            'url' => 'https://bitbucket.org/gearsdigital/kirby-reporter-test',
            
            // required - Define the personal access token
            'token' => 'c56658e7c03a5995e2e1491e6a3b93fcde6225c9',
            
             // optional – Only necessary in specific bitbucket setups
            'user' => 'gearsdigital-dev'
        ],
        
         /**
         * Holds mail configuration options
         * 
         * []{from: string, to: string, subject: string, type: string}
         */
        'mail' => [
            // required - Define sender
            'from' => 'mail@example.com',
            
            // required - Define the recipient
            'to' => 'track@example.com',
            
            // required - Define the Email-Subject
            'subject' => 'Issue Report form gearsdigital.com',
            
            // required - Define the the email type
            'type' => 'text|html'
        ],
    ],
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

TIP

Learn how to configureopen in new window Kirby.

DANGER

If you define repository and mail, repository wins because it has a higher precedence!

Customization

Reporter for Kirby is designed to be highly configurable and allows to adapt the Form and the Issue Template. This guide assumes that you are familiar with Blueprintsopen in new window and Templatesopen in new window.

Form

Customize the Report Form.

Default

# /site/plugins/reporter-for-kirby/blueprints/reporter/reporter.yml
reporter:
  fields:
    description:
      label: Description
      type: textarea
      help: Please be as precise as possible.
1
2
3
4
5
6
7

Important

You can add any field you want, but you need to adapt the template in order to see the fields in your preview.

Custom

The custom blueprint will override the default blueprint, excluding the title which is, apart from translations, not configurable. You can fully customize the Form by using blueprint fieldsopen in new window.

To customize the form create a file named reporter.yml and save it to /site/blueprints/reporter/reporter.yml

# /site/blueprints/reporter/reporter.yml
reporter:
  fields:
    steps:
      label: Steps to reproduce
      type: textarea
      help: Please be as precise as possible.
    type:
      label: Issue Type
      type: select
      options:
        - value: bug
          text: Bug
        - value: feature
          text: Feature
        - value: enhancement
          text: Enhancement
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

Section

This plugin provides also a section which can be used like any other section in your blueprints. You can learn about adding sections from the Kirby Docsopen in new window.

This is a very handy way to collect feedback from anywhere in your panel.

# site.yml
sections:
  reporter:
    type: reporter
    headline: Report issue
    description: My custom description
1
2
3
4
5
6

Templating

Reporter for Kirby comes with two templates. A template is responsible to generate the actual value which is being sent. You can and do whatever you want to adapt the output.

  1. Issue Tracker
  2. E-Mail

Issue Tracker (Repository)

Default

/site/plugins/reporter-for-kirby/templates/reporter.php

## Issue Template
<?php if (isset($fields)): ?>
  <?= $fields['description']; ?>
<?php endif;?>
1
2
3
4

Preview

You can use the »Preview Tab« of the Issue Form to ensure your template is properly formatted. This doesn't work yet to preview Emails!

Custom

You can override the default easily. Create a file named reporter.php and save it to /site/templates/reporter.php.

Within the template you have access to an array of all available fields. Each field consists the key and the selected value.

/** @var array $fields */
var_dump($fields);
1
2

TIP

Output can be anything your issue tracker can deal with. Markdown might be a good start 😃

E-Mail

You can define two types of Email-Templates, html and text:

  • /site/plugins/reporter-for-kirby/templates/emails/report.html.php
  • /site/plugins/reporter-for-kirby/templates/emails/report.text.php

Which one is used depends on your configured type. Default is html. Within a template you have access to string $title and array $fields;

Default (html)

/site/plugins/reporter-for-kirby/templates/emails/report.html.php

Email HTML
Title: <?php if (isset($title)): ?><?= $title ?? ''; ?><?php endif; ?>
Fields: <?php if (isset($fields)): ?><?= $fields['description'] ?? ''; ?><?php endif; ?>
1
2
3
Default (text)

/site/plugins/reporter-for-kirby/templates/emails/report.text.php

Email TEXT
Title: <?php if (isset($title)): ?><?= $title ?? ''; ?><?php endif; ?>
Fields: <?php if (isset($fields)): ?><?= $fields['description'] ?? ''; ?><?php endif; ?>
1
2
3