Grav Data Manager Plugin

The Data Manager Plugin for Grav adds the ability to visualize data. This is particularly useful for the admin and form plugins. Additional plugins may store data content, and the Data plugin - properly configured - is able to show their data too.

| IMPORTANT!!! This plugin is currently in development as is to be considered a beta release. As such, use this in a production environment at your own risk!. More features will be added in the future.

Installation

The Data plugin is easy to install with GPM.

$ bin/gpm install data-manager

Or clone from GitHub and put in the user/plugins/data-manager folder.

Configuration

You don't need any configuration to start using the plugin. Knowing how to configure it, as illustrated later, will allow you to take advantage of a few handy customization options.

Remember: copy the user/plugins/data-manager/data-manager.yaml into user/config/plugins/data-manager.yaml and make your modifications in your user folder.

Usage

Once installed the Data plugin shows a Data Manager item in the admin menu. Click that, and the Data plugin will show you the available data types found in the user/data folder.

Clicking a data type will show the list of items. For example you might have a contact form setup in your site, using the Form plugin. A Contact type should show up, depending on how you called that form data items (data types names are taken from the user/data/ folder names, unless customized - see below).

For example you might have a form.md contact form with:

---
title: A page with a form
form:
    name: contactform
    fields:
        - name: name
          label: Name
          placeholder: Enter your name
          autofocus: on
          autocomplete: on
          type: text
          validate:
            required: true

        - name: email
          label: Email
          placeholder: Enter your email address
          type: text
          validate:
            rule: email
            required: true

    buttons:
        - type: submit
          value: Submit
        - type: reset
          value: Reset

    process:
        - save:
            fileprefix: contact-
            dateformat: Ymd-His-u
            extension: yaml
            body: "{% include 'forms/data.txt.twig' %}"
        - message: Thank you for your feedback!
---

# Nice contact form

In this case, you have a name and an email field. If you enable the plugin and go in the admin side, you'll see under the Data menu the Contactform type.

Click that, and all the contact information entered is browsable, listed by filename, and you can click an item to show its details.

Customization

All the things listed above come out of the box, without you needing to do anything special. Now, let's make the list more user friendly.

List customization

By default the list shows items listed by the filename. You might want to show some more information in the list, so you can for example have 2 columns, name and email.

Open the user/config/plugins/data-manager.yaml and add the structure of the data files, and the files extension. The name of the type is the one of the data/ subfolder (in the case of the Form plugin, set by form.name)

types:
  contactform:
    list:
      columns:
        -
            field: name
            label: Name
        -
            field: email
            label: Email

Columns with nested content

To show in the items list nested content, use an array:

list:
  columns:
    -
      field: ['address', 'email']
      label: Email

Will render the address.email value.

Single item customization

enabled: true

types:
  contactform:
    item:
      fields:
        name:
          name: Token
        email:
          name: Email

Will render those fields listed, and just those fields. By default, the single item view lists all the fields found in the file.

File extension customization

Usually data is saved in .yaml files. You can change that per-type by setting:

types:
  contactform:
    file_extension: '.txt'

Customize the type name

By default the Types list shows the folder name. You can add

types:
  contactform:
    name: Contact Form

to provide a better name.

Override items list and item detail templates

You can override items list and item details Twig templates using a plugin.

By doing this, you can build plugins that

store data in the data/ folder
have complete control over the data rendering in the admin-side

You can register the templates in the admin-side and put them in your plugin templates folder under partials/data-manager/[typename]/item.html.twig and/or partials/data-manager/[typename]/items.html.twig.

Programmatically exclude a data folder from the Data Manager

Say you are developing a plugin that stores in the data/ folder, and you want to create your own admin interface to show the data. No problem! You can instruct the Data Manager plugin to ignore your data type (data/ subfolder).

Just listen for the onDataTypeExcludeFromDataManagerPluginHook event

$this->enable([
    'onDataTypeExcludeFromDataManagerPluginHook' => ['onDataTypeExcludeFromDataManagerPluginHook', 0],
]);

and add the data type you want to exclude by adding it to a property of the Admin Plugin:

 public function onDataTypeExcludeFromDataManagerPluginHook()
 {
     $this->grav['admin']->dataTypesExcludedFromDataManagerPlugin[] = 'comments';
 }

Future improvements

This is a first revision of the plugin.

Ideas for the near future:

Allow plugins to define yaml for data,
Better integration with the Form plugin (auto-determine types definition)
Add a "process" field in the columns/fields to filter raw data (e.g. dates or booleans)

getgrav / grav-plugin-data-manager