Abandonment Notice: I'm afraid I simply don't have the time to maintain my Grav themes and plugins. Those interested in taking over should refer to the "Abandoned Resource Protocol". Feel free to fork and replace. So long, and thanks for all the fish.
The Table Importer Plugin is for Grav CMS. It imports tables from JSON, YAML, and CSV formats into a page.
For a demo, visit my blog.
Installing the Table Importer plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
The simplest way to install this plugin is via the Grav Package Manager (GPM) through your system's terminal (also called the command line). From the root of your Grav install type:
bin/gpm install table-importer
This will install the Table Importer plugin into your /user/plugins directory within Grav. Its files can be found under /your/site/grav/user/plugins/table-importer.
To install this plugin, just download the zip version of this repository and unzip it under /your/site/grav/user/plugins. Then, rename the folder to table-importer. You can find these files on GitHub or via GetGrav.org.
You should now have all the plugin files under
/your/site/grav/user/plugins/table-importer
NOTE: This plugin is a modular component for Grav which requires Grav and the Error, Problems and Shortcode Core plugins to operate.
To edit the configuratino, first copy table-importer.yaml from the user/plugins/table-importer folder to your user/config/plugins folder and only edit that copy.
The only configuration setting is enabled, which turns the plugin off and on.
This plugin extends the Shortcode Core infrastructure. See that documentation to learn how to disable/enable shortcode processing on a page-by-page basis.
This plugin converts JSON, YAML, and CSV files into HTML code and can be used in conjunction with other table plugins like Tablesorter. It only works with simple, even data (see the next section for details). If you wish to accomplish something more complex, then consider combining the Import plugin with some custom twig code.
The plugin is naive and assumes that your data is well formed and that your tables have even row lengths (the table is rectangular). If the plugin can't find the data file or can't understand its format, then the shortcode will be replaced by an error message. Otherwise, the only evidence something is wrong will be the shortcode still showing or weird table rendering.
The only requirement is that your data file parse to a two-dimensional array: an array of rows from top to bottom, each row containing cells from left to right. Each cell must be a value PHP can natively render as a string.
Some samples—json, then yaml, then CSV:
[
["Col1", "Col2", "Col3"],
["Val1", "Val2", "Val3"],
["Val4", "Val5", "Val6"],
["Val7", "Val8", "Val9"]
]-
- Col1
- Col2
- Col3
-
- Val1
- Val2
- Val3
-
- Val4
- Val5
- Val6
-
- Val7
- Val8
- Val9Col1,Col2,Col3
Val1,Val2,Val3
Val4,Val5,Val6
Val7,Val8,Val9
This plugin uses the Shortcode Core infrastructure. Read those docs for the nitty gritty of how shortcodes work.
The Table Importer shortcode is a self-closing [ti option1="value1" option2="value2" ... /], and it accepts the following options:
-
fileis the only required parameter. It points to the datafile you wish to load. By default, the plugin looks in the same folder as the page file. This is adequate for most usage. You can also load files from theuser/datafolder by prefixing your file name withdata:(e.g.,file=data:tables/mytable.yaml).If all you're passing is the file name, then you can shorten the code to the form
[ti=mytable.yaml/]. -
typeis usually unnecessary. It tells the plugin what format the data file is in. The only acceptable values areyaml,json, andcsv. However, the plugin looks at the file name extension first. If it'syaml,yml,json, orcsv, then there's no need to use thetypeoption. -
captionwill insert a<caption>tag containing the value of this option after being run through PHP'shtmlspecialchars. -
headertells the plugin whether you want a header row or not. By default, the first row is rendered as a header. Passing any value toheaderwill disable the header row. -
classlets you assign class definitions to the table itself. Whatever you put here will be escaped (via PHP'shtmlspecialchars) and placed into the opening<table>tag. -
idlets you specify the table tag'sidattribute (e.g.[ti file="mytable.yaml" id="my-custom-table-id"]yields<table id="my-custom-table-id">...</table>). -
By default, the content of each cell is escaped using PHP's
htmlspecialcharsfunction. If therawoption is set to anything at all, the escaping will be disabled. Only do this if you trust the incoming data! -
Finally, for CSV files only, you can customize how it will be parsed using any of the following three options:
-
delimiterdefines how columns are separated. By default, the value is a comma (,). -
enclosuredefines how cells with special characters are contained. By default, the value is a double quotation mark ("). -
escapedefines how special characters can be escaped. By default, the value is a backslash (\).
-
-
[ti=test.json](basic import of json table in the same folder as the page itself) -
[ti=data:test.yaml](basic import of yaml table in theuser/datafolder) -
[ti file=json-as-yaml.json type=yaml](parse a file as yaml regardless of extension) -
[ti file=file.csv enclosure='](parse a CSV file that uses a single quote to enclose items) -
[ti file=file.yaml header="false" class="imported"](basic yaml table with no header and a class ofimported)
Because PHP's builtin CSV support is...let's just say inelegant, this plugin incorporates the most excellent PHPLeague CSV library.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
![https://upload.wikimedia.org/wikipedia/commons/0/02/Luther_Blissett.jpg[/u]](https://upload.wikimedia.org/wikipedia/commons/0/02/Luther_Blissett.jpg%5B/u%5D){kind=link}