Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/getgrav/grav-plugin-data-manager

Grav Data Manager Plugin
https://github.com/getgrav/grav-plugin-data-manager

data data-visualization grav grav-plugin

Last synced: about 1 month ago
JSON representation

Grav Data Manager Plugin

Awesome Lists containing this project

README 

        
# Grav Data Manager Plugin



The **Data Manager Plugin** for [Grav](http://github.com/getgrav/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:



```yaml

---

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)



```yaml

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:



```yaml

list:

  columns:

    -

      field: ['address', 'email']

      label: Email

```



Will render the address.email value.



## Single item customization



```yaml

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:



```yaml

types:

  contactform:

    file_extension: '.txt'

```



## Customize the type name



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



```yaml

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



1. store data in the data/ folder

2. 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



```php

$this->enable([

    'onDataTypeExcludeFromDataManagerPluginHook' => ['onDataTypeExcludeFromDataManagerPluginHook', 0],

]);

```



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



```php

 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)