e3v3a / mmm-tabulator

A MagicMirror Demo for using Tabulator

MagicMirror Module: Tabulator

STATUS:	Version	Date	Maintained?
Working	1.0.2	2018-03-05	YES

What is this module doing?

MMM-Tabulator is just a demonstration module for using the Tabulator npm package on your MagicMirror. Tabulator is a very nice tool for producing dynamic HTML tables from various sources, like JSON, CSV and XML etc. However, although very well documented, the examples are very hard to understand and implement in practice, for non-experts.

Why I should use Tabulator?

• Very flexible for manipulating all aspects of table data
• Can sort table columns in several ways and in multiple stages
• Can use graphics in tables
• Can easily enable/disable various table items
• Help reduce all the clutter of HTML generating JS code
• You never have to write DOM code again!
• You don't need to think about converting XML or JSON to HTML table
• Very well used and maintained repository

Why I should not use Tabulator for my MM:

• It is totally overkill for showing small and simple tables
• It is a very large library, easily bloating your MMs if used repeatedly
• It is definitely slowing down load times somewhat
• It is dependent on: jquery and jqeuery-ui.

Example Screenshots

In this repo there are 2 demo examples.

1. The demo.html file, that has the JSON embedded and can be run directly from your browser.
2. The MMM-Tabulator Module, that is importing the same JSON data from the file demo.json.

Screenshot of the demo.html output:

Screenshot of the MMM-Tabulator output:

The flight JSON data shown, was provided by FlightRadar24.

---

Dependencies

This module depend on the following npm packages:

• jquery - is a fast, small, and feature-rich JavaScript library
• jquery-ui - for user interface interactions, effects, widgets, and themes
• tabulator - for an overkill use of JSON to HTML table generation

These are also listed in the package.json file and should be installed automatically when using npm. However, those may require other packages.

---

Installation

Manual Installation:

cd ~/MagicMirror/modules
git clone https://github.com/E3V3A/MMM-Tabulator.git
cd MMM-Tabulator

# To locally install: jquery, jquery-ui and tabulator, do:
chmod 755 install_deps.sh
./install_deps.sh

# ToDo:
#npm install

Easy Installation [ToDo]:

npm install mmm-tabulator

Configuration

To configure the Tabulator for MM, you need to do the following:

• Add the Module to the global MM config.js

• Edit node_helper.js to select the correct JSON file or JSON input file:

  const myfile = 'modules/MMM-Tabulator/demo.json';

• Edit MMM-Tabulator.js to:

  • select & configure the table rows you want to show
  • edit the column formatting to be used
  • [TBA] select the filename or URL from where to load the JSON data
  • select the default Tabulator CSS

• Edit MMM-Tabulator.css for your own CSS taste

Add the module to the modules array in the config/config.js file by adding the following section.

{
    module: 'MMM-Tabulator',
    header: 'Tabulator Demo',
    position: 'top_left',
    config: {
        //fileUrl: "demo.json",     // The local filename or URL to JSON source
        updateInterval: 180,        // [seconds] Read the file every 3 min
        maxItems: 10,               // Max table rows shown
    }
},
...

You can change this configuration later when you see that it works.

Configuration Options

Option	Default	Description
header	"Tabulator Demo"	This Module's header text
updateInterval	180	Module data update in [seconds]
maxItems	10	Number of table rows to show
fileUrl*	"demo.json"	A local filename or URL to a JSON API

* - not yet implemented - ToDo!

---

Tabulator configuration

The main part to configure is found under the loadTabulator() function:

...
    flightTable.tabulator({
        height:flightTableHeight,           // Set height of table, this enables the Virtual DOM and improves render speed
        //layout:"fitColumns",                // Fit columns to width of table (optional)
        //headerSort:false,                   // Disable header sorter
        resizableColumns:false,             // Disable column resize
        responsiveLayout:true,              // Enable responsive layouts
        placeholder:"No Data Available",    // Display message to user on empty table
        initialSort:[                       // Define the sort order:
            {column:"altitude",     dir:"asc"},     // 1'st
            //{column:"flight",     dir:"desc"},    // 2'nd
            //{column:"bearing",    dir:"asc"},     // 3'rd
        ],
        columns:[
            ...
            {title:"Time", field:"timestamp", headerSort:false, sortable:false, visible:false, responsive:1, formatter:"ep2time"},
...

For further details about configuring the many Tabulator options, see:

• http://tabulator.info/
• https://github.com/olifolkerd/tabulator
• http://tabulator.info/docs/3.4?#css
• http://tabulator.info/examples/3.4?#theming

---

Bugs and Warnings

⚠️ If you provide your own JSON data, other than what is provided in the demo.json file, then it has to be in proper JSON format. For some reason the MM socket seem to not accept loosely formatted JSON. There is an extremely simple JSON sanitizer, used (for my own purposes), but it doesn't handle any characters outside [A-Za-z0-9_\-]. Not sanitizing your JSON data is a security issue that could lead to code injection! Also check if your source is using UTF-8 or something else.

Please refer to the issue tracker for details and updates.

Other Modules using Tabulator:

• MMM-FlightsAbove - A flight radar showing flight & airplane details for planes above a certain location.

Contribution

Feel free to post issues and PR's related to this module.
For all other or general questions, please refer to the MagicMirror Forum.

Credits

Most grateful thanks to Ray Wojciechowski for sharing his module develpment experince and thus helping me solve all my issues. Do check out his many great MMM modules in his repository.

License

MIT

mmm-tabulator's Issues

Make module accept dirty JSON data

Currently the module only renders perfectly formatted JSON data. However, APIs are often very relaxed when providing JSON data.

# cat dirty.json

  { id: '1',
    somenumber: 112233,
    somestring: 'ABCD',
    somenull: null 
  },
  { id: '2',
    somenumber: 445566,
    somestring: 'EFGH',
    somenull: null
  }

# cat clean.json

  { "id": "1",
    "somenumber": 112233,
    "somestring": "ABCD",
    "somenull": null
  },
  { "id": "2",
    "somenumber": 445566,
    "somestring": "EFGH",
    "somenull": null
  }

• Also, how should we handle null?

I already tried using JSON.stringify(data); before sending it down the socket, but that didn't work as I expected, and no error reason was given...AFAICR.

Here is some more JSON documentation.

Use seconds for updateInterval

The module currently use units of milliseconds [ms] for the updateInterval option in config.js. This is silly, and I would like to see seconds (and possibly minutes) instead.

Move images code to its own subdirectory

Move all images to its own subdirectory: ./images/.

Automatically adjust table height

It would be good to have the table height being automatically adjusted to the number of table items to be shown. So let's try to adjust the Tabulator height according to either:

1. The config option maxItems max value, or if there are less items available, then
2. Adjust the number of rows to be shown to be what's available.

See: flightTable.tabulator({ height:205,...

Fix table artifact rendering

There is a difference in the rendering of the table, depending on if you are looking at the local host Mirror or on the server. The artifact renders like this:

On the local host (RPi3):

On the remote host using Firefox:

I'd like to get rid of this difference.

Tabulator 4.0 is no longer jQuery dependent

Good News from @olifolkerd (dev of Tabulator library)

You will be happy to hear that as of version 4.0 Tabulator is no longer jQuery dependent and now comes with a tabulator_core.min.js without all the modules installed to make it even more light weight.

I've been away from developing for a few months, so I currently don't know if there is any side effects because of this. Please report, if you find any.

Cannot load a long list with 70.000 entries

Expected Behaviour:
Expected to see 20 items displayed on the mirror.

Actual Behaviour:
Instead of seeing the items, I see a message "Waiting for data". If I cut the list to 150 items (see attached file), it works as it should but if I expand it to 250 items (rows) then it doesn't work => "Waiting for data".
ListaCuvinte.txt
My girlfriend wants to learn Danish and I this is a list with all the Danish words, I want to make the mirror display 20 words at a time in DK, EN, RO and cycle through randomly every 3 min or so.
I tried everything with this list but I don't seem to get it work. Any help would be very much appreciated.

Steps to Reproduce the Issue:
Please have a look at the attached file. It's saved as UTF-8 and all I did was to change the extension to JSON. If you replace the demo.json with this one and change column names accordingly in the config files, it will not work (works with 150 words for example but not the rest). I don't know if it's an error in the file or the module cannot handle so much data.
Any input would be much appreciated.

---

For new bugs and issues, please make sure to:

• include detailed information on what you did before the error/issue occurred.
• get info about your system configuration, if relevant.
• make sure to use code mark-down using 3 backticks, ```, to enclose mulyi-line code/input/output.
• include a screenshot! for issues concerning layouts, formatting, or other UI stuff.

Move demo code to its own subdirectory

Move all the demo code to a new subdirectory ./demo.

Test and compare performance of DOM vs Tabulator tables

It would be very useful to measure exactly what the performance impact is when using Tabulator as compared to using a home-made JS DOM generator, as is often used in MMM's.

If someone find it easy to write DOM in JS, I would be extremely happy for PR into dev repo.
(Personally I hate writing DOM, which is why I started this repo in the first place.)

📊