────────────────────────────────────
[モジュール] Csv2Doc － CSVを使ってドキュメントやウェブリンクを一括登録
────────────────────────────────────
2009-06-18

────────────────────────────────────
概要
────────────────────────────────────

CSVファイルを使って、MODXのドキュメントやウェブリンクを一括で作成・更新
するモジュールです。
MODX標準のドキュメント変数はもちろん、ユーザが設定したテンプレート変数も
使えます。
ちなみに、実際に登録する前に、確認表示が出ますので、安心して更新できます。
また、適用作業にあわせていくつでもモジュール実行画面を追加でき、
モジュール実行時に入力するパラメータも個々に設定できます。

ダウンロード
http://www.hikidas.com/hikidas/modx_resource/Csv2Doc.php

────────────────────────────────────
インストールとアンインストール
────────────────────────────────────

■インストール

下記の通り、一般的なMODXモジュールと同様にインストールします。
１．ダウンロードしたファイルを全て展開します。
２．展開した「Csv2Doc-****/assets/modules/」の中にある「csv2doc」を、
　　サーバの「assets/mudules/」の中に、FTPでアップロードします。
　　（「****」部分はバージョンによります）
３．展開した中にある「module.Csv2Doc.ja.php」を、UTF-8が利用可能なテキス
　　トエディタで開きます。
４．MODX管理画面のモジュール／モジュール管理から、モジュールの作成を行い、
　　「module.Csv2Doc.ja.php」のソースコードをすべてコピーして、モジュー
　　ルコード欄に貼り付けます。
　　モジュール名は、「Csv2Doc」か、もしくは、適用作業にあわせて、たとえ
　　ば「商品データ更新」などにします。
５．デフォルトのままでも使えますが、適用作業にあわせる等必要に応じて「設
　　定」タブのモジュール設定も入力します。

■アンインストール

下記の通り、一般的なMODXモジュールと同様にアンインストールします。
１．MODX管理画面から作成したモジュールを削除します。
２．FTPでアップロードしたファイルを削除します。

────────────────────────────────────
使い方
────────────────────────────────────

１．Excel等を使って、CSVファイルを作成します。
２．ファイルマネージャーやFTPを使って、CSVファイルをアップロードします。
３．モジュール実行画面で「確認する」をクリックします。
４．確認表示を見て、問題なければ「登録する」をクリックします。

■CSVファイル

以下のようなCSVファイル(*1)を用意し、あらかじめ「assets/files/」にアップ
ロードしておきます。

１．1行目：フィールド名行(*2)(*3)
　　フィールド名として、ドキュメント変数名やテンプレート変数名を入力しま
　　す。
２．2行目：コメント行(*4)
　　後でわかる（再利用できる）ように、任意のコメント（説明文等）を記入し
　　ます。
３．3行目以降：データ行
　　実際に登録するデータを入力します。

*1：デフォルトでは、文字コード等は日本語版Excelで作成されたCSVファイルを
　　想定しています。
*2：設定により、フィールド名行を省略し、フィールドの並びを固定にすること
　　もできます。
*3：MODXで定義されていないフィールド名については、確認表示で警告が出ます
　　が、そのまま登録することは可能です。
*4：設定により、コメント行は省略可能です。

■更新に使う場合の注意

新規作成だけにCSVを使う場合を除き、既存のドキュメントの更新にもCSVを使う
場合、あらかじめ、各ドキュメントを識別するためのフィールドを用意しておく
必要があります。

例えば、メニューインデックスを特に使っていないのでしたら、CSVに
「menuindex」フィールドを用意し、これに連番を振っておく等して、ドキュメ
ントを一意に識別できるようにしておき、モジュール実行画面で「更新用一致判
定フィールド」に「menuindex」を入力します。
（もしくは、設定パラメータ「matching_fieldname」に「menuindex」を設定し
ておきます）

CSVファイルの例
|menuindex                 |pagetitle|content            |
|識別番号（重複させない！）|タイトル |内容               |
|                         1|データ1  |1番目のデータです。|
|                         2|データ2  |2番目のデータです。|
|                         3|データ3  |3番目のデータです。|

■設定パラメータ

一般的なMODXモジュールと同様に、MODX管理画面（モジュール管理）で設定がで
きますが、それ以外にも、モジュール実行画面で、直接パラメータを入力するこ
とも可能になってます。

デフォルトでは、以下のパラメータをモジュール実行画面で指定できるようになっ
ています。(*5)
・ドキュメントを作成するフォルダのドキュメントID
・ドキュメントに使用するテンプレートID（プルダウンメニュー）
・更新用一致判定フィールド
・フォルダ内の不要なレコードを削除する（Yes/No）
・デフォルトで公開日時に現在時刻を設定する（Yes/No）
・アップロードされたCSVファイルのファイル名
・2行目からデータレコードまで読み飛ばす行数
・CSVファイルエンコーディング（プルダウンメニュー）
・確認表示列数

*5：モジュール実行時に入力するパラメータは、モジュール設定で変更できます。

●主な設定パラメータ
runparams：実行時パラメータ
	モジュール実行画面で入力するパラメータ名を指定します。
	カンマ区切りで複数指定可能。
	デフォルトは「doc_parent,doc_template,matching_fieldname,
	delete_in_parent,set_pub_date,csv_fname,csv_skiplines,csv_encoding,
	num_verify_cols」です。
matching_fieldname：更新用一致判定フィールド
	既存のドキュメントを更新する際に使うレコード識別用フィールド名を
	指定します。
	詳しくは、前述の「更新に使う場合の注意」を参照してください。
require_fieldnames：必須フィールド名
	入力がなければエラーとするフィールド名を指定します。
	カンマ区切りで複数指定可能。
num_verify_cols：確認表示列数
	確認表示に表示する列の数を指定します。デフォルトは「8」です。
verify_fieldnames：確認表示フィールド名	確認表示に表示するフィールド名を
	指定します。
	カンマ区切りで複数指定可能。num_verify_colsよりこちらの指定が優先
	されます。
csv_only_data：CSVファイルはヘッダ行を含まない
	1(Yes)を指定すると、1行目からデータとして処理します。
csv_fieldnames：フィールド名
	フィールド名の並びをカンマ区切りで指定します。
doc_parent：ドキュメントを作成するフォルダのドキュメントID
	どこにドキュメントを作成（どこのドキュメントを更新）するかを指定
	します。
	CSVのフィールドに「parent」か「byname_parent」で指定したフィール
	ドがあれば、そちらが優先されます。
	※このフォルダに対する、ドキュメント作成・編集・保存権限が必要で
	す。（権限がなければエラーになります）
doc_template：ドキュメントに使用するテンプレートID
	使用するテンプレートを指定します。
	CSVのフィールドに「template」か「byname_template」で指定したフィー
	ルドがあれば、そちらが優先されます。
	デフォルトは、グローバル設定のデフォルトテンプレートに設定されて
	いるテンプレートです。
csv_fname：アップロードされたCSVファイルのファイル名
	ファイル名を指定します。デフォルトは「data.csv」です。
csv_dname：アップロードされたCSVファイルのディレクトリ名
	ディレクトリ名を指定します。デフォルトは「assets/files/」です。
csv_skiplines：2行目からデータレコードまで読み飛ばす行数
	コメント行として読み飛ばす行数を指定します。
	デフォルトは「1」です。
csv_encoding：CSVファイルエンコーディング
	CSVファイルに使用している文字コードを指定します。
	デフォルトは「SJIS（シフトJIS）」です。
delete_in_parent：フォルダ内の不要なレコードを削除する	CSVのデータ中に
	無いドキュメントがあった場合、削除するかどうかを指定します。
	1(Yes)を指定すると、フォルダ内の不要なドキュメントが削除されます。
nl2br_fieldnames：改行時にbrタグを挿入するフィールド
	複数行にわたるデータ等、改行をウェブ上で再現したいフィールド名を
	指定します。カンマ区切りで複数指定可能。
doc_published：デフォルトで公開する
	デフォルトで公開するにチェックを入れるかどうかを指定します。
	1(Yes)を指定した場合、各ドキュメントの「公開する」にチェックを入
	れます。
	CSVのフィールドに「published」か「byname_published」で指定したフィー
	ルドがあれば、そちらが優先されます。
set_pub_date：デフォルトで公開日時に現在時刻を設定する
	デフォルトで公開開始日時に現在時刻を入れるかどうかを指定します。
	デフォルトは「0(No)」です。
	CSVのフィールドに「pub_date」か「byname_pub_date」で指定したフィー
	ルドがあれば、そちらが優先されます。

■モジュール設定

一般的なMODXモジュールと同様に、MODX管理画面（モジュール管理）で設定します。

例えば、
親フォルダ「1」、識別フィールド「menuindex」、不要レコードを削除する、実
行時パラメータはCSVファイル名
とするモジュール設定は、以下のようになります。
--------
&doc_parent=親フォルダID;int;1 &matching_fieldname=識別フィールド;string;menuindex &delete_in_parent=不要レコードを削除する;int;1 &runparams=実行時パラメータ;string;csv_fname
--------

────────────────────────────────────
補足説明
────────────────────────────────────

PHPのわかる人は、Csv2Docクラスを継承して、個別にカスタマイズする等は可能
だと思います。

* 現バージョンでは、テンプレート変数とテンプレートの対応は考慮していませ
　ん。（いずれ対応するつもりですが）
* 現バージョンでは、モジュール実行画面でのファイルアップロードはできませ
　ん。（いずれ対応するつもりですが）
* トランザクション（InnoDB）には、現バージョンでは対応していません。（い
　ずれ対応するつもりですが）
* CSVデータのフィールド毎のバリデート機能等は、現バージョンではありません。
　これらチェック機能は今後の課題です。

バグ報告や仕様の不備、その他機能のご要望等、いただけるとありがたいです。
（どこまで対応できるかは確約できませんが、無理のない範囲でバージョンアッ
プしていきたいと思っています。）

────────────────────────────────────
リソースの情報
────────────────────────────────────

作者		Kazuyuki Ikeda (HIKIDAS Co.,Ltd)
Webサイト	http://www.hikidas.com/
リソース名	Csv2Doc
バージョン	0.9.2
ライセンス	GPL
動作環境	MODX 0.9.6.x
リソースの種別	モジュール