△ Table Importer Plugin

https://github.com/Perlkonig/grav-plugin-table-importer の README.md

Table Importer Plugin

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.

Table Importer Plugin は、Grav CMS に、JSON、YAML、CSV形式のテーブルをページに取り込むことができます.

デモ こちらのブログに訪問ください.

インストール

Table Importer Plugin のインストールは、2つの方法のいずれかで行います。GPM (Grav Package Manager) によるインストール方法は、ターミナルのコマンドで素早く簡単にプラグインをインストールでき、手動による方法は、ZIPファイルを介してインストールすることが可能です。

GPM Installation (Preferred)

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.

Manual Installation

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.

環境設定

設定を変更するには、user/plugins/table-importer フォルダから table-importer.yaml を user/config/plugins フォルダにコピーして、そのコピーだけを編集してください。

設定項目は enabled のみで、このプラグインをオフにしたりオンにしたりすることができます。

このプラグインは、Shortcode Core plugi を拡張するものです。ページごとにショートコードの処理を無効化/有効化する方法については、そのドキュメントを参照してください。

利用方法

このプラグインは、JSON、YAML、CSVファイルを HTML コードに変換し、Tablesorter などの他のテーブルプラグインと組み合わせて使用することができます。単純で均一なデータに対してのみ動作します (詳細は次のセクションを参照してください)。もっと複雑なことをしたい場合は、The Import plugin といくつかのカスタム Twig コードを組み合わせることを検討してください。

Formatting Your Data

このプラグインは素朴なもので、データがうまく形成されており、テーブルの行の長さが均等である（テーブルが長方形である）ことを想定しています。もしプラグインがデータファイルを見つけられなかったり、そのフォーマットを理解できなかったりした場合は、ショートコードがエラーメッセージに置き換えられます。そうでない場合は、ショートコードが表示されたままになったり、テーブルのレンダリングがおかしくなったりすることだけが、何か問題がある証拠となります。

唯一の要件は、データファイルを二次元配列にパースすることです。つまり、上から下に向かう行の配列で、各行には左から右に向かうセルが含まれます。各セルは、PHP がネイティブに文字列としてレンダリングできる値でなければなりません。

json, yaml, CSV のサンプル

[
  ["Col1", "Col2", "Col3"],
  ["Val1", "Val2", "Val3"],
  ["Val4", "Val5", "Val6"],
  ["Val7", "Val8", "Val9"]
]
-
  - Col1
  - Col2
  - Col3
-
  - Val1
  - Val2
  - Val3
-
  - Val4
  - Val5
  - Val6
-
  - Val7
  - Val8
  - Val9
Col1,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:

  • file is 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 the user/data folder by prefixing your file name with data: (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/].

  • type is usually unnecessary. It tells the plugin what format the data file is in. The only acceptable values are yaml, json, and csv. However, the plugin looks at the file name extension first. If it's yaml, yml, json, or csv, then there's no need to use the type option.

  • caption will insert a <caption> tag containing the value of this option after being run through PHP's htmlspecialchars.

  • header tells the plugin whether you want a header row or not. By default, the first row is rendered as a header. Passing any value to header will disable the header row.

  • class lets you assign class definitions to the table itself. Whatever you put here will be escaped (via PHP's htmlspecialchars) and placed into the opening <table> tag.

  • id lets you specify the table tag's id attribute (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 htmlspecialchars function. If the raw option is set to anything at all, the escaping will be disabled. Only do this if you trust the incoming data!

  • CSV ファイルのみ、以下の 3 つのオプションのいずれかを使用して、解析方法をカスタ マイズすることができます。

    • delimiter defines how columns are separated. By default, the value is a comma (,).

    • enclosure defines how cells with special characters are contained. By default, the value is a double quotation mark (").

    • escape defines how special characters can be escaped. By default, the value is a backslash (\).

　コード例

  • [ti=test.json] (ページと同じフォルダーにある、テーブル形式の json ファイルのインポートします。)

  • [ti=data:test.yaml] (user/data フォルダーにある yaml ファイルをインポートします。)

  • [ti file=json-as-yaml.json type=yaml] (拡張子に関係なく、ファイルを yaml としてパースします。)

  • [ti file=file.csv enclosure='] (' で項目を囲むCSVファイルのパース)

  • [ti file=file.yaml header="false" class="imported"] (basic yaml table with no header and a class of imported)

Credits

PHP の内蔵 CSV 機能は少々不便...なので、このプラグインは PHPLeague CSV library を組み込んでいます。