power source*

前回までの記事に続いて、UTWテンプレートタグについてのメモ。
公式 HELP では、どの場面でどのテンプレートタグを使うのかが見にくかったので、一覧的にまとめる。詳細は Help > Theme Integration を参照、ということで。

追記 2007.11.1: 以下の UTWテンプレートタグは、WordPress 2.3 対応のプラグイン「UTW Theme Compatibility Thing」 でも使えるようになりました。（UTW_AddTagToCurrentPost() を除く。別プラグインあり）

UTWテンプレートタグについて

各記事に付けられたタグリストやブログ中で使用中のタグセットを 任意の位置・フォーマットで表示させたい場合² には、次の様式のコード「UTWテンプレートタグ」をテーマのテンプレートファイルに挿入する。

UTWテンプレートタグの記述様式：

<?php UTW_FunctionTitle("$formattype", "$format", "$limit") ?>

• UTW_FunctionTitle : UTWテンプレートタグ名（関数名）。
• $formattype : 表示形式のタイプ。
  • 定義済みフォーマット（Predefined Formats）表の Format Name より選択。
  • これを指定するときは、次項は指定しない。
• $format : 表示形式を独自に定義したい場合に使用。
  • 下記 Custom Formatting 参照。
  • これを指定するときは、前項は指定しない。
  • 定義済みフォーマットを使い、この項は指定せず、次の表示件数を指定するときは、この項には "" を書く。
• $limit : 表示件数

定義済みフォーマットと表示件数を指定するときはこんな感じ。

<?php UTW_FunctionTitle("$formattype", "", 10) ?>

UTWテンプレートタグの種類（用途別）

各記事で使うもの

• メインページ（index.php）、記事アーカイブ表示（index.php, archives.php等）、単体記事表示（single.php）、「ページ」表示等にて使用できる。
• ループ中に挿入。³
• Help > Formatting single.php and index.php 参照。

UTW_ShowTagsForCurrentPost()

現在の記事に付けられたタグを表示する。

cf. Help > Tags for the current post

（例） 定義済みフォーマット commalisticons を使用。表示されるアイコンは、環境設定の Global Formatting Settings でチェックしたもののみ。
コード： <?php UTW_ShowTagsForCurrentPost("commalisticons") ?>
表示：

UTW_ShowRelatedTagsForCurrentPost()

現在の記事に付けられたタグに関連するタグを表示する。

cf. Help > Related tags for the current post

（例）この記事のタグに関連するタグ：

UTW_ShowRelatedPostsForCurrentPost()

現在の記事に関連する記事を表示する。

使える定義済みフォーマットは postsimplelist, posthtmllist, postcommalist の3つ。

cf. Help > Related posts for the current post

UTW_AddTagToCurrentPost()

インライン・タグ追加機能（An inline tag-adder）

アーカイブや単体記事ページ等、記事を表示しているその画面上でタグを追加できる（Ajax 使用）。

記事をリスト表示しつつサクサクとタグを追加できるので、記事を一覧表示するページ（アーカイブ等）への設置がオススメ。

うちではログイン中のみ表示させている。

cf. Help > An inline tag-adder

タグ・アーカイブページ表示時に使うもの

tag.php（なければ index.php）に挿入。

UTW_ShowCurrentTagSet()

現在のタグ・アーカイブページのタグセットを表示（「現在の記事の」でない）。当ページの見出しなどに。

定義済みフォーマットの tagsetsimplelist と tagsetcommalist は、この用途のために用意されたもの。

cf. Help > Display the current tag set

（例） <?php UTW_ShowCurrentTagSet("tagsetcommalist") ?> とすると、http://～/tags/Apple+Banana+Orange のタグ・アーカイブページを表示しているときに、「Apple, Banana and Orange」と表示する。

（使用例）[plugin＋UTW」タグ・アーカイブページ(http://bono.s201.xrea.com/tag/plugin+utw/)のページタイトル（ブラウザバー）や、見出し「Archive for the 'plugin and UTW' Tags」

UTW_ShowRelatedTagsForCurrentTagSet()

現在のタグ・アーカイブページのタグセットに関連するタグを表示する。

Help > Display the tags related to the current tag set

UTW_ShowRSSFeedIcon()

現在のタグ・アーカイブページの RSSフィードへのリンク付きアイコンを表示。

ultimate-tag-warrior.php 92行目参照。HELP には載っていない。

（使用例）「plugin＋UTW」タグアーカイブのタイトル「Archive for the 'plugin and UTW' Tags」の右端の。本来は URI 表記をパーマリンク型にできるが、うちでは問題があって臨時修正してある。⁴

サイト中で使われている全タグを表示するもの

• sidebar.php や、その他の表示したい箇所、tags.php⁵ を作ってそこに表示することも出来る。
• フォーマットは、タグクラウド、棒グラフ、weighted bar thing のほか、ただのカンマリストとかも使える。
• $limit を指定すれば、表示するタグ数を絞れる。
• Help > Formatting tags.php 参照。

UTW_ShowWeightedTagSet()

よく使われているタグ順に表示

UTW_ShowWeightedTagSetAlphabetical()

アルファベット順に表示

date.php/archive.phpでの特殊機能

次の UTWテンプレートタグを使うと、月別アーカイブ等、表示中のページの対象期間の記事で使われているタグのみが表示される、らしい。 cf. Help > Special Functionality for date.php/archive.php

• UTW_ShowTimeSensitiveWeightedTagSet()
• UTW_ShowTimeSensitiveWeightedTagSetAlphabetical()

Predefined Formats - 定義済みフォーマット表

Help > Predefined Formats

• 定義済みのフォーマットについて、概要・表示例・そのフォーマットを使える場所をまとめた表。
• 表中の + について補足：
  • 「Wordpress loop」に + が付いているものは、ループ中でのみ使用可（現在の記事のタグを出力するタイプ）
  • 「tag.php」は、タグページで使用可。Wordpress loopに + が付いていなければループ外でも使用可。
  • 「tags.php」は、全タグを表示する用途で使用。（tags.php 以外のテンプレートでもよい。）
• 'superajax' 等、内部的に定義はされていて 定義済みフォーマット表に載っていないものがいくつかあるが、これについては Help > Adding UTW Tags to Themes > The deprecated one に説明あり。作者さん自身まだ練りきれていないらしく、存在しないこととしている模様。（オプション画面では選べてしまうけれども。）

Custom Formatting

Help > Custom Formatting 参照

カスタムフォーマットで表示するときのコードの書き方

1. 先に、$format にカスタム定義を代入する。
2. 次に、表示するための UTWテンプレートタグを書く。
   と思ったが、合体させても OK。

例えば、

• 記事のタグリストを 「Tags: tagA, tagB, tagC and tagD のように表示
• タグ付けされていないときは、オプション画面の 'The text to display when there are no tags' に設定したテキスト（'No Tags' だとする）を表示

したい場合、次のように書く:
（かなり無理矢理な例だけど、説明用ということで。。。(^^;）

<?php 
$format = array("pre"=>"【","first"=>"Tags: %tagdisplay%","default"=>", %tagdisplay%","last"=>" and %tagdisplay%","post"=>"】","none"=>$notagtext);
UTW_ShowTagsForCurrentPost("",$format);
 ?>

または、2行を合体させて:

<?php UTW_ShowTagsForCurrentPost("",$format = array("pre"=>"【","first"=>"Tags: %tagdisplay%","default"=>", %tagdisplay%","last"=>" and %tagdisplay%","post"=>"】","none"=>$notagtext)); ?>

上のコードの実際の表示:

$format の右辺の書き方

• The parts of a custom format 参照。
• 表示上の位置「パート」（default, pre, first 等）毎に分けて、表示フォーマットを書く。
• 1パート分は "パート名"=>"フォーマット"。これをカンマで繋げて、array() で包む（↓）。
  array("パート1"=>"フォーマット1","パート2"=>"フォーマット2",～以降同様に～);
• 各パートの説明
  default は必須。その他は、特に定義したいパートだけでいい。
  • pre -- 接頭辞。一連の先頭に付けたいテキスト・HTMLタグ（<p>, <span class="○○">等）があるときに。 【Tags: tagA, tagB, tagC and tagD】
  • single -- タグが一つしかないときの表示。 【Tag: tagA】
  • タグや記事が複数あるときの:
    • first -- 先頭のタグ・記事のフォーマットが default と違うときに。【Tags: tagA, tagB, tagC and tagD】
    • default -- [必須] 中間のタグ・記事 1つ分のフォーマット。【Tags: tagA, tagB, tagC and tagD】中間のタグが複数あれば（この例では tagB と tagC）、このフォーマットが繰り返し使われる。
    • last — 最後のタグ・記事のフォーマットが default と違うときに。【Tags: tagA, tagB, tagC and tagD】
  • post — 接尾辞。一連の表示の最後に付けたいテキスト・HTMLタグ（</p>, </span>等）があるときに。【Tags: tagA, tagB, tagC and tagD】
  • none — タグが一つもないときの表示。【No Tags】
• フォーマットの書き方
  • The Parts of a Format String 参照。
  • 1パート分の表示フォーマットを、テキスト、HTMLタグ、Placeholder、$notagtext 等を組み合わせて定義する。
  • Placeholder は、よく使われる表示項目を簡単に使えるように定義してあるもの。
    例えば、フォーマット中に %taglink% と書けばリンク付きタグ名に置換される。
    参照： Help に一覧（Replacement bits for a tag format, Replacement bits for a posts format）あり。
  • 一から考えるより、Predefined Formats の定義が参考になりそう。 wp-content/plugins/UltimateTagWarrior/ultimate-tag-warrior-core.php 1369行目から。

具体例

• （例1） tagA, tagB, tagC, tagD と表示したいとき
  $format = array ("default"=>", %taglink%", "first"=>"%taglink%", "none"=>$notagtext );
  中間と最後（強調部分）が同じ形式で、最初だけカンマなし。 → default（中間）と first（最初）、タグがないとき用に none を定義。

1. アクセスで負荷がかかると申し訳ないので、配布元ではなく自分のにしてあります。[back]
2. 各記事・Ext. Live Archive での表示は、UTW の環境設定によって自動的に表示できる（「1)基本編」参照）。自動表示されない箇所へ表示したいときや、表示フォーマットを詳細にカスタマイズしたいとき等に、このコードを手動でテンプレートに挿入する。[back]
3. 手動でテーマテンプレートに挿入するときは、自動表示と重複しないよう、オプション > Tags パネルにて、automatically include tags options をオフにする。異なる使い方をするなら両方使ってもよいとは思うけど。[back]
4. URI 整形上のバグ(?)修正済み。さらに、パーマリンク型URI（http://～/tag/wordpress+plugin/feed/rss2）でのフィード生成が上手くいかなくなっていたため、http://～/index.php?tag=wordpress+plugin&feed=rss2 へリンクするよう臨時修正（こちらはUTW 導入当初は問題なかったので、私のカスタムか別件とのコンフリクトが原因かも）。この2件については別記事にて。[back]
5. tags.php は、サイト中で使われている全タグを表示するページ専用の「ページテンプレート」。これを作ると、ページ作成画面の「ページテンプレート」でこれを選べるようになる。[back]

関連ページ

• WP plugin: UTWテンプレートタグを WP2.3 で使う - UTW Theme Compatibility Thing
• WP plugin: 記事にタグ付け - Ultimate Tag Warrior 4) 本体のカスタマイズ
• WP plugin: 記事にタグ付け - Ultimate Tag Warrior 2) テーマ編集編
• WP plugin: 記事にタグ付け - Ultimate Tag Warrior 1) 基本編