ToraToraWiki

エクスポート機能 (ToraToraWikiManual/ja/Export)

ToraToraWikiにはToraToraWikiで作成したページをhtmlファイル,画像ファイル,cssファイル等に書き出し, 静的コンテンツのサイトを構築できる機能があります. これをエクスポート機能と呼びます.

エクスポート機能を用いるとサイトの内容やデザイン,サイトを管理する画面をWiki記法で管理することができます. 大げさに表現するならばToraToraWikiはCMS(Content Management System)自体を構築,管理できるCMSMSであるといえます. すなわち,サイトの管理者がサイトの編集者に必要最低限のCMSや,親切な説明を加えたCMSを簡単に提供することができます.

有効化

エクスポート機能はデフォルトでは無効になっています. 使用する場合はindex.phpに

define('EXPORT_ENABLE', 'true');

を追記します.(index.phpについてはサイトの高度な設定参照)

またエクスポート機能を使用できるのは管理者かエクスポートの権限を与えられたユーザーのみです.

基本的な設定

エクスポート機能を使用するにはどのページをどのファイルに書き出すかを設定する必要があります. この設定をするには好きなページにWiki記法の表を用いて設定表を書きます. 設定表は1列目にページへのリンク, 2列目に書き出すファイル名を書きます. 例えばWiki記法で

|ページ名          |ファイル名   |h
|[[トップページ]]  |index.html   |
|[[スタイルシート]]|css/style.css|

のように書きます.ヘッダ行(上記の例では1行目)は無視されますので省略しても,お好みのヘッダにしても構いません.

設定表を書いたら,表でリンクにしたページを作成しておいて下さい. htmlファイルにしたいページは種別wikiのページで,その他のページは種別textか種別fileのページで作成するのがおすすめです.

次にこの設定にしたがって実際にファイルの書き出しを行うためのボタンを作成します. このボタンを作成するには

&export;

と書きます.これは先ほどの設定表の上でも下でも構いませんし,別のページ書いても構いません. ただし,別のページに書いた場合は

&export([[設定表のあるページ]]);

と書いてください. &export;のより高度な使用方法はこちらを参照して下さい. これでボタンが作成され,押せば実際にファイルの書き出し(エクスポート)が行われます.

ファイルは設定表の2列目に設定したファイル名で, 設定項目EXPORT_DIR_PATH で設定されているディレクトリの下に保存されます. このディレクトリに対してWebサーバーの設定を行い,公開することでhtmlファイル等で構成された静的なサイトが構築できます. もしToraToraWikiを設置したWebサーバーとは別のWebサーバーにあるコンテンツを管理したい場合はエクスポート後の処理を参照して下さい.

テンプレート

上記の例ではindex.htmlとcss/style.cssというファイルを書き出しましたが, index.htmlはcss/style.cssをスタイルとして使用するようにはなっていないためcss/style.cssが無意味になってしまいます. この問題は,エクスポート用のテンプレートを設定することで解決できます. テンプレートを使用するには設定表の3列目を作成し,テンプレートになるページへのリンクを書きます.例えば

|ページ名          |ファイル名   |テンプレート              |h
|[[トップページ]]  |index.html   |[[通常ページテンプレート]]|
|[[スタイルシート]]|css/style.css|                          |

のように書きます.設定表にテンプレートを書いたらテンプレートを作成します. テンプレートになるページは種別textか種別fileにして下さい. 例えば以下のような内容にします.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>$title$</title>
    <link rel="stylesheet" type="text/css" href="./css/style.css"/>
  </head>
  <body>
    $contents$
  </body>
</html>

このようなテンプレートを設定しエクスポートをすると,index.htmlにはテンプレートの内容が書き出されますが, テンプレート内の$title$の部分がページ名になり, $contents$の部分が設定表の1列目で指定したページの内容になります.

設定表の3列目,すなわちテンプレートの欄に何も書かなければ1列目の内容がそのまま書き出されます.

エクスポート機能でのテンプレートとWiki記法の&pages&writepageでのテンプレートは異なるものです.注意して下さい.

テンプレートの書き方

上記の$title$や$contents$のようにテンプレート内で特定のキーワードを書けば別の内容に置き換わります. キーワードには以下のようなものがあります.

$title$
ページ名または&titleで設定されたタイトル
$contents$
ページの内容
$[[ページ名]]$
ページ名で指定したページの内容に置き換えます. ページ名はテンプレートのページから見た相対的な名前でも構いません.
$mtime$

ページの更新日時

$mtime?format=%Y/%m/%d$

のように書くことで任意のフォーマットにできます. フォーマットはstrftimeのフォーマットに従います.

$btime$
ページの作成日時 (フォーマットの指定は$mtime$と同様)
$exporttime$
エクスポートした日時 (フォーマットの指定は$mtime$と同様)
$tags$

ページのタグ一覧を表示します.

$tags?list=[[ページ名]]$

上のように書くことでタグのリンク先を指定できます. ページ名には&pages等でページの一覧表示を行っているページを指定します. こうすることでこのタグをクリックした先はページ一覧のうちこのタグを持っているものに限定されます. さらに

$tags?list=[[ページ名]]&prefix=この記事は&sep=と&suffix=のタグを持っています$

のようにタグがあった場合に前に表示する内容,後に表示する内容,タグの区切り文字を指定できます.

複数のページに対する設定

複数のページをエクスポートする際にすべてのページとファイル名の対応を設定表に書く必要はありません. 設定表の1列目に書かれたページから別のページにリンクがある場合,リンクされているページもエクスポートされます. 同様にリンクされているページからさらにリンクされているページもエクスポートされます. すなわち設定表に書かれたページからリンクでたどることのできるページはすべてエクスポートされます.

このようにリンクによって派生的にエクスポートされるページには, 書き出すファイル名やテンプレートが設定されていません. この場合はファイル名やテンプレートは自動で決定されますが,設定表で明示することもできます.例えば以下のように設定します.

|ページ名          |ファイル名       |テンプレート              |h
|[[トップページ]]  |index.html       |[[通常ページテンプレート]]|
|[[スタイルシート]]|css/style.css    |                          |
|ブログ/&*         |                 |[[ブログ用テンプレート]]  |
|type=wiki         |                 |[[通常ページテンプレート]]|
|&*.jpg            |images/$basename$|                          |

設定表の1列目にページへのリンクではなくページ名のパターンをワイルドカードを用いて指定できます. このパターンと一致するページはこの行を設定として使用します. Wiki記法で*や/*や*/は見出しやコメントの意味になってしまうので*の前に&記号をつけてエスケープする必要があるので注意して下さい. 上記の設定表の例ではブログというページの子ページはすべてブログ用テンプレートというテンプレートして使用し,ファイル名は空欄なので自動で決定するように設定されています.

同じく設定表の1列目に

type=ファイル種別

の形式でページ種別を指定することもできます.上記の設定表の例では種別wikiのページはすべて通常ページテンプレートをテンプレートして使用するように設定されています.

設定表の1列目の条件は上から順に検査され,最初に一致した行を設定として使用します.

設定表の2列目には書き出すファイル名を書きますが,特定のキーワードを書けばページに応じたファイル名を設定できます. キーワードには以下のようなものがあります.

$id$
自動で決定された他のページと重複しない英数字の羅列になります.
$basename$
ページ名のうち最後の/(スラッシュ)より後ろの部分になります.
$extension$
ページ名をファイル名とみなしたときの拡張子の部分になります.ドットも含みます.
$filename$
$basename$のうち拡張子に相当する部分を除いたものになります.
$args$
ひとつのページに複数のバリエーションがある時 (&pagesのcontentsパラメータを使用した際に一覧が複数ページにまたがる時や, 一覧を特定のタグで限定できるとき) にそのバリエーションを一意に識別する英数字列に置き換わります.

エクスポート後の処理

エクスポートを行った後にUNIXコマンドを実行することができます. 実行するコマンドは設定項目EXPORT_POST_COMMANDで設定できます. このコマンドはコマンド引数にエクスポート先のディレクトリを渡され, 標準入力から実際にエクスポートされたファイル名をNUL文字('\0')区切りで入力されます.

このコマンドにrsyncやftpコマンドでファイルを送信するスクリプトを設定すれば, リモートホストにあるWebサーバーのコンテンツを管理することができます.

コマンドに入力される文字列はToraToraWikiのサイトで自由に編集できる文字列であることに注意して下さい.

コマンドは0以外のステータスで終了することでエラー扱いになります.

例えばエクスポートの結果をログとして残すシェルスクリプトは以下のようになります.

#!/bin/bash
dir="$1"
log() {
    local time
    time=$(date '+%F %T')
    echo "$time: $1" >> log.txt
}
log "start export $dir"
while read -d $'\0' file; do
    log "export $file"
done
log "end export $dir"
exit 0

エクスポート先の切替え

ひとつの設定表に対してエクスポート行うボタンを複数作成しても構いません. &exportのdirectoryパラメータを用いると, 同じコンテンツを異なるディレクトリにエクスポートできます. 例えば以下のように書きます.

&export(directory=test, label=テスト環境へエクスポート);
&export(directory=real, label=本番環境へエクスポート);

これはテスト環境と本番環境のディレクトリ(testとreal)を用意し,それぞれに対してボタンを作成しています. テスト環境でエクスポート結果を確認した後で本番環境に反映させるといったような使い方ができます.

ドキュメント

ダウンロード