2015年1月27日火曜日

TiddlyWikiの「tiddler マクロ」と「テンプレート」の活用法

この投稿では TiddlyWiki classic (TWc)の標準マクロの一つ 「tiddler マクロ」について書いています。

TiddlyWiki には標準でいくつかのマクロが組み込まれています。これらのマクロは TiddlyWiki 記法を使った内部関数の呼び出し機能ともいえます。「新規作成」や「保存」「検索」ボタン、タブ形式の tiddler リストの表示など、コンテンツのいろいろなパーツはこれらのマクロを組み合わせて作られています。



tiddler マクロとは

マクロについては本家のドキュメントの中で簡単な説明が書かれています。
TiddlyWiki | tiddler macro

The tiddler macro allows you to transclude the text of other tidders, or sections of other tiddlers, into your current tiddler.

翻訳すると、「tiddler マクロは、現在の tiddler の中に他の tiddler テキスト、あるいは他の tiddler の一部をトランスクルードできます。」とあります。

はじめてこのマクロを知ったときは、「なるほど、他の tiddler コンテンツを参照する機能なんだ。」という程度の理解でした。 ところが最近、改めて使ってみると意外にも便利なマクロであることがわかりました。ここで少し例を挙げながら紹介したいと思います。



tiddler マクロの機能

tidder Transclusion:

このマクロの基本機能は前述のように tidder のトランスクルージョン機能です。この機能では対象の tiddler タイトル の記述方法によって、トランスクルードするコンテンツの範囲を指定することが可能です。指定できる範囲は、tiddler 全体、セクション、スライスの3種類となっています。


tiddler全体をトランスクルード

書式

<<tiddler TranscludeContent>>

この書式の場合、現在の tiddler コンテンツ中のマクロを記述した位置に、指定した tiddler タイトル (書式例では "TranscludeContent" )のコンテンツ全体を参照表示します。

サンプルとして参照する "TranscludeContent" の内容です。

<!--{{{-->
!sectionHeading
sliceLabel: Lorem ipsum dolor sit amet, consectetur adipisicing elit

|key1:|value1|
|key2|value2|

!sectionHeading2
Hello $1!  Hello $2.
<!--}}}-->

実行結果はこのようになります。

このマクロはコンテンツ全体を参照表示することから、トランスクルード対象のテキスト量が多い場合は画面表示が冗長になりすぎる傾向があります。その場合は、この書式の使用はお勧めできません。代わりの方法として tiddler リンクを記述して、対象の tiddler を別に表示するほうが良いと思います。

TiddlyWiki の実際の使用例では、"WindowTitle" が、このマクロを使い "SiteTitle" と "SiteSubtitle" を参照表示しています。どちらもシンプルなテキスト量の tiddler です。


セクション・トランスクルージョン

書式

<<tiddler [[TranscludeContent##sectionHeading]]>>

セクション・トランスクルージョンはトランスクルードする範囲を 「見出し( Heading )」 を使って指定します。対象範囲として、「見出し」の次の行から始まり、次の「見出し」の直前までのテキストが参照されます。このとき、次の「見出し」が見つからない場合は、テキストの文末までが対象範囲として参照されます。

書式中の「見出し」の指定方法は、tiddler タイトルと「見出し」の間にセクションセパレータ記号##を記述して指定します。参考までに、TiddlyWiki 記法の「見出し」は、"!foo" や "!!bar" のように見出し文字列の先頭に!記号を付加して指定します。

上の書式例でトランスクルードする範囲は、タイトル "TranscludeContent" 内の「見出し」 "sectionHeading" 以降から次の「見出し」 "sectionHeading2" の直前までが参照対象になります。

実行結果はこのようになります


スライス・トランスクルージョン

書式

<<tiddler [[TranscludeContent::sliceLabel]]>>

スライス・トランスクルージョンは {key: valve} ペアに似ています。トランスクルードする対象を 「key:」 を使って指定します。このときの対象範囲は、「key:」 の直後から始まり、行末までのテキストが参照されます。

スライス対象の 「key」 の指定方法は、tiddler タイトルと 「key」 の間にスライスセパレータ記号::を記述して指定します。

例えば、スライス・トランスクルージョン対象のタイトル "TranscludeContent" の中に、下記のように key: valve ペアが記述されている場合。

sliceLabel: Lorem ipsum dolor sit amet, consectetur adipisicing elit

このときトランスクルードする範囲は "TranscludeContent" 内の 「key」 である "sliceLabel:" の直後から始まり、行末までのテキスト (Lorem ipsum dolor sit amet, consectetur adipisicing elit) が参照されます。

実行結果はこのようになります

他にはテーブルを使ったスライスも可能です。この場合テーブルの1列目が 「key:」 になり、2列目が 「value」 になります。また、テーブルの1列目の文字列は、 「key:」 であっても 「key」 であってもどちらでも可能です。

例えばこのようなテーブルです

|key1:|value1|
|key2|value2|

key1 を指定して値を取得してみます。

<<tiddler [[TranscludeContent::key1]]>>

実行結果はこのようになります

この記述の注意点は、テーブル幅を調節するために空白文字を入れると参照に失敗します。

スライス・トランスクルージョンの実際の TiddlyWiki での使用例は、 "ColorPalette" で見ることができます。この中では色名をキーにして、その値が取得できるように記述されています。主に、このような使い方をサポートすることがスライス・トランスクルージョンの使用目的とされています。

"ColorPalette" の中は、このような記述になっています。

Background: #fff
Foreground: #000
PrimaryPale: #8cf
PrimaryLight: #18f
PrimaryMid: #04b
PrimaryDark: #014
SecondaryPale: #ffc
SecondaryLight: #fe8
SecondaryMid: #db4
SecondaryDark: #841
TertiaryPale: #eee
TertiaryLight: #ccc
TertiaryMid: #999
TertiaryDark: #666
Error: #f88


引数付きトランスクルージョン

書式

<<tiddler TranscludeContent with:"param1" "param2">>
<<tiddler [[TranscludeContent##sectionHeading]] with:"param1" "param2">>
<<tiddler [[TranscludeContent::sliceLabel]] with:"param1" "param2">>

トランスクルードを行うときに、与えられた引数をプレースホルダに置換します。使用できるプレースホルダの数は9個までです。

トランスクルード対象のコンテンツ内でプレースホルダの指定は$1,$2, ... ,$9を記述します。このとき、「引数」に与える文字列は英数字a-ZA-Z_0-9でなければなりません。

例えば "TranscludeContent" のコンテンツが下記のように記述されている場合

Hello $1!  Hello $2.

下記の記述で 「引数付きトランスクルージョン」 を行うと

<<tiddler TranscludeContent with:"Ruby" "Python">>

2つの引数がプレースホルダに置き換えられて、このような参照結果になります。

この 「引数付きトランスクルージョン」 と 「テンプレート」 を組み合わせると便利な機能が作れます。次に、いくつかのテンプレートの使用例を紹介します。



テンプレートの使用例

TiddlyWiki の画面構成は HTML で記述されているので、tiddler 内に HTML を直接記述することも可能です。また、記述内容が定型化できる場合は、テンプレートにするとさらに便利になります。

実際の実行画面は icm7216.github.io/MyTiddlyWiki/ - TranscludeSample で確認できます。


Youtube 動画を埋め込む

tiddler マクロを使って、Youtube 動画を埋め込むテンプレート

!youtube
<html>
  <div align="center">
    <iframe width="$1px" height="$2px" src="$3?rel=0" frameborder="0" allowfullscreen></iframe>
  </div>
</html>
!end

マクロ記述 : 引数は、「横」px、「縦」px、「動画URL」を指定します。

<<tiddler [[embed##youtube]] with:"420" "315" "http://www.youtube.com/embed/pWOigTwzj_g">>

実行結果


pdfファイルを埋め込む

tiddler マクロを使って、pdf ファイルを埋め込むテンプレート

!pdf
<html>
  <div align="center">
    <embed width="$1px" height="$2px" src="$3" type="application/pdf" ></embed>
  </div>
</html>
!end

マクロ記述 : 引数は、「横」px、「縦」px、「pdfファイルのURL」を指定します。

<<tiddler [[embed##pdf]] with:"500" "300" "http://www.mozilla.jp/static/docs/press/Mozilla-Firefox_ReviewersGuide-April2014.pdf">>

実行結果

pdf ファイルは Mozilla Japan の 「Firefox レビュアーズガイド (2014年版 / PDF / 英語)」を使用しました。


バーグラフを表示

tiddler マクロを使って、バーグラフを表示を埋め込むテンプレート

!bargraph
<html>
<div style="display: block; width: $2px; border: 1px solid black;">
  <div style="width: $1%; background: none repeat scroll 0% 0% rgb(246, 244, 49);">
    <div style="text-align: left; margin-left: 10px; white-space: nowrap;">
        $1 %
    </div>
  </div>
</div>
</html>
!end

マクロ記述 : 引数は、「パーセント値」%、「横幅」pxを指定します。 この例では、値「20%」横幅「300px」の棒グラフを表示します。

<<tiddler [[embed##bargraph]] with:"20" "300">>

この棒グラフにテーブルを組み合わせると、レイアウトしやすくなります。

OSシェア
|Windows 7|<<tiddler [[embed##bargraph]] with:"56" "300">>|
|Windows XP|<<tiddler [[embed##bargraph]] with:"18" "300">>|
|Windows 8.1|<<tiddler [[embed##bargraph]] with:"9" "300">>|
|Windows 8|<<tiddler [[embed##bargraph]] with:"4" "300">>|

実行結果はこのようになります

実際の使用では、これらのテンプレートを一つの tiddler に纏めて記述しておきます。この例ではタイトル名 "embed" tiddler を作成しています。

タイトル名

embed

コンテンツ

<!--{{{-->

!youtube
<html>
  <div align="center">
    <iframe width="$1px" height="$2px" src="$3?rel=0" frameborder="0" allowfullscreen></iframe>
  </div>
</html>
!end

!pdf
<html>
  <div align="center">
    <embed width="$1px" height="$2px" src="$3" type="application/pdf" ></embed>
  </div>
</html>
!end

!bargraph
<html>
<div style="display: block; width: $2px; border: 1px solid black;">
  <div style="width: $1%; background: none repeat scroll 0% 0% rgb(246, 244, 49);">
    <div style="text-align: left; margin-left: 10px; white-space: nowrap;">
        $1 %
    </div>
  </div>
</div>
</html>
!end

<!--}}}-->

複雑な機能を TiddlyWiki に追加したい場合は、マクロやプラグインを書く必要がありますが。少しばかりの HTML を書くことで実現できる場合は、このような 「tiddlerマクロ」 と 「テンプレート」 を使えば、新しい機能を追加することができます。

0 件のコメント :