カレンダープラグイン「The Event Calendar」での日付降順処理 #wpacja2013

初めまして！
WordPress Advent Calendar 2013 ６日目担当の木谷（@kimipooh）です。
今年初めての参加です。
本日は、私以外に鳥山さん（@sysbird）もご担当ですね。はやい….もうアップされてる…。しかも綺麗で纏まったデザインですよねぇ。そこはマネできない部分なので、マイペースで行きたいと思います！
また本サイトのデザイン・レイアウトは全くカスタマイズしてません。というか個人サイトぐらいは管理運用から離れたいので、もういいや！みたいな感じです…そのため多少見づらいかもしれません、そのあたりはご容赦を…

皆さんカレンダープラグインは何をお使いでしょうか

私はたまたま探して出会った「The Event Calendar」および有料拡張版の「The Event Calendar PRO」を使っています。最初に触って慣れてしまったから、そのまま使い続けるっていうパターンです。このプラグインは、カスタム投稿の機能を使っており、アクセス地図などGoogle Map連携もあることから利用者側からは好評です。ただ、管理者としては結構苦労しますが…

１日目を担当された井村さんの記事「WordPress 3.7で追加された「date_query」を使って複雑な日時指定のループを作って見よう」を見て、おお〜そんな機能があるんだ〜と思い、これに触発されて、このプラグインにおける日付処理について話してみたいと思います。

The Event Calendarにおける日付処理における問題

tribe_get_eventsという関数が用意されていますが、get_postsを使っているのに、「order」パラメータが無視されてしまいます（昇順である「ASC」固定してる！）。従って、たとえば降順に並び替えるためには

一旦取得した後に、PHPソート機能を使う
WP_Query等を直接使ってorder指定して取得する

などの手段を講じる必要があります。
筆者は前者の方法を当初採用し（短期間でとにかく実現することが優先だったため、後者の方法にたどり着けなかった）、その後フォーラムでのやり取りを経て後者を知りました。このような背景もあり、今回は後者について説明したいと思います。ただし説明する方法は、The Event Calendar 3.0以降とします。
※前者については、すでに本ブログ「The Event Calendarプラグイン記事の「降順」一覧表示」にてざっと説明しています。ただしtribe_get_events関数の使い方そのものには触れていないので、これについては末尾の「Appendix: イベント情報取得関数「tribe_get_events」の使用例」に載せておきました。

WP_Queryを使ってイベント情報を降順で取得しよう

条件として、

「公開」されている「今日」以降のイベントを「１０」件「降順」に箇条書きで表示

とします。降順とは、新しい日付が上に来るようにするということです。

Step 1. パラメータ設定

<?php
$current_date = date('Y-m-d');

$args = array(
  'post_status'  => 'publish',
  'post_type' => array(TribeEvents::POSTTYPE),
  'posts_per_page' => 10,
  'start_date' => $current_date,
  'meta_key' => '_EventStartDate',
  'orderby' => '_EventStartDate',
  'order' => 'DESC',
  'eventDisplay' => 'custom'
);
?>

post_status

公開しているもの限定するために「publish」にしています。
もし未来の記事も含めたい場合には「publish,future」とすればいいでしょう。
メンテナンス予定などを事前掲載するときに使えます。もっとも特定の未来の記事についてのみ表示したい場合には、プラグインなどを使って特定の未来記事のみステータスをpublishへ変更するなどの手段を使う事になるとは思います。
その他使えるパラメータについては、WP_Queryのドキュメント内の「Status Parameters」を参照してみてください。

post_type

「tribe_events」も使えますが、その名前が将来的に変更された場合を見越すなら上記記載の方がよいと思います。

start_date

eventDisplayパラメータを「custom」にした時のみ、The Event Calendarプラグインのパラメータが使えるようになります。
（プラグイン3.0以降の機能）
start_date以外に、end_dateも使えます。
これはThe Event Calendarのカスタム投稿に付与される「Start Date」「End Date」をチェックします。

start_dateやend_dateに記載できるフォーマットとして、以前のドキュメントには
「date(‘j M Y’); 」
と書かれています。でも実際使ってみると「date(‘Y-m-j’)」でなければ動作しませんでした。でも3.0ぐらいから「date(‘Y-m-d’)」にしないと動作しなくなりました….何故そんなフラフラしているのか分かりませんけどね。
いずれにしても、現状では「Y-m-d H:i:s」フォーマットを使えってサポートフォーラム（下記のリンク）で開発者が投稿してます。

Version three breaks custom event display using (WP_Query)

なお、end_dateを組み合わせれば期間限定で取得できるでしょう。

order

orderbyで指定された基準項目をもとにソートされます。
今回はThe Event Calendarで入力する「開始日時」をベースに降順ソート

Step 2. データ取得

<?php 
$get_events = null;
$get_events = new WP_Query($args);
?>

一行目は変数の初期化です。
二行目で準備とパラメータを渡してデータを取得します。
そして次に触れますが、WP_Queryで取得したものについては使い終わった後に「wp_reset_postdata();」でリセットしておきましょう。とりあえずおまじないと思っておいてください（知りたいなら検索してみてください、いろいろ情報が出てきます）。

Step 3. 取得したデータの活用（表示）

li, dt, ddタグを使っていますが、このあたりの体裁については割愛します….

上記のような感じで表示させるサンプルコードとしては下記のようになります。

<?php 
while( $get_events->have_posts() ){
   $get_events->the_post();
?>
  <li>
    <dl>
       <dt><?php echo tribe_get_start_date( $post->ID, false, 'Y/m/d' ); ?></dt>
       <dd><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></dd>
    </dl>
  </li>
<?php 
}
wp_reset_postdata();
?>

ループ（while）

$get_events変数内に記事がある限りループします。
次のthe_postの行で、$postに現在の投稿内容をセットし、次送りにします。
イメージとしては、$get_events[$count++][記事] というような感じかな。

記事の日時を取得（tribe_get_start_date）

この関数で取得できます。ただしデフォルトでは「年月日時:分:秒」となります。
一般的には「年月日」だけの表示で十分です。そのフォーマットについては
上記の設定で変更可能です（Y/m/d は、date関数の表示形式に依存）

リンクとタイトル表示

リンクは、the_permalink関数で$postから自動的にリンク情報を取得して表示までします。
タイトルは、the_title関数が使えます。

Appendix: イベント情報取得関数「tribe_get_events」の使用例

この使い方については、開発元のドキュメント（英語）にサンプルとともに掲載されているので使うこと自体はそれほど難しくありません。ドキュメントの冒頭に「2.X用だから3.0についてはメインドキュメントを見てね」って書いてありますが、メインドキュメントを見ても、結局は2.X用のドキュメントを参照することになるという….まぁそのあたりの細かい事は脇に置いておきます。

全イベント情報を取得

<?php
$args = array(
   'eventDisplay'      => 'all',
   'posts_per_page' =>  -1
);
$events = tribe_get_events($args);
?>

eventDisplayパラメータには、「all」「upcoming」「day」「month」「past」が使えるます。

特定日時のみのイベント情報を取得

今日から３０日後まで

<?php
$current_date = date ('Y-m-d'); 
$end_date = date ('Y-m-d',  strtotime('30 days'));
$args = array(
  'eventDisplay'      => 'all',
  'start_date'           => $current_date,
  'end_date'            => $end_date,
  'posts_per_page'  =>  -1
);
$events = tribe_get_events($args);
?>

ドキュメントでは、日付フォーマットとは date(‘j M Y’); と書かれていますが、私の環境ではうまく出来ず。
「Y-m-d」は「YYYY-MM-DD」となります。
このあたりは、Version three breaks custom event display using (WP_Query)で開発者自身がY-m-d使えと書いているので、それが正しいのでしょう。

今日以降の１０件

<?php
$current_date = date ('Y-m-d'); 
$args = array(
  'eventDisplay'      => 'all',
  'start_date'           => $current_date,
  'posts_per_page'  =>  10
);
$events = tribe_get_events($args);
?>

これからのイベント通知用に使えるかなと思います。
posts_per_pageは取得件数です。「-1」は制限しないという意味になります。

最後に

ちょっと書くつもりが、結構本格的になってしまいました…
私自身もまだまだWordPressをうまく使いこなせていない部分もあります。
本記事を書くことで、私自身も処理について少し詳しくなったよかったなぁと思います。

さて、明日はわたさんです。よろしく〜。

2013年12月6日　木谷