Coyomi (コヨミ) – アーカイブカレンダー

説明

多くのアーカイブカレンダーのウィジェットは、ページを表示するたびに月ごとにデータベースへ問い合わせます。何年分も記事があるサイトでは、1ページあたり 100本ほどのクエリーになります。

このウィジェットは、記事のある日を内容が変わったときに一度だけ集計し、wp-content/uploads/lwac/ の静的な JSON ファイルに書き出します。ページの表示では、そのファイルを読むだけです。

Coyomi (暦) は、日本語で「カレンダー」という意味です。

• クエリーは作り直し 1回につき 1本 (SELECT DISTINCT DATE(post_date))、ページの表示では 0本です
• 記事の公開・非公開・ゴミ箱への移動・削除・日付やカテゴリーの変更のときと、1日 1回作り直します
• 最初の月は HTML で描きます (JavaScript が無くても表示できます)。ほかの月はブラウザーで描きます
• ページ全体のキャッシュと一緒に使えます: ブラウザーはいつも最新のデータファイルを取りに行きます
• 投稿タイプとカテゴリーで絞り込めます
• レイアウトは 5種類: 月のカレンダー・週 (1週間を横一列)・年 (12か月のタイル)・ドロップダウンのみ・年 / 月 / 日のツリー
• 設定画面 (「設定 → Coyomi」) にライブプレビューがあります。ウィジェットは、自分でレイアウトと色を選ばないかぎり、この設定に従います
• 配色は 5種類 (カレンドリエ・パステル・クラシック・ダーク・シンプル)。どの色もウィジェットごとに変えられ、保存するのは変えた色だけです
• ほかのプラグインが coyomi_events フィルターで日付に予定 (セールなど) を足せます。何日も続く予定は 1行にまとめ、「開催中」か「終了」を付けます
• 外部への通信なし: カレンダーはサイトの外のサービスと通信せず、データも集めません

開発者向け

予定は coyomi_events フィルターで足します。呼ぶのはデータを作り直すときだけ (ページの表示では呼びません) なので、時間のかかる処理をしてもかまいません。1日につき 1件ずつ足します:

add_filter( 'coyomi_events', function ( $events, $dataset ) {
    try {
        foreach ( my_plugin_sale_days() as $day ) {
            $events[] = array(
                'date'   => $day,                    // 'YYYY-MM-DD' in the site's time zone
                'label'  => 'Autumn sale',           // plain text, up to 60 characters
                'url'    => get_permalink( 123 ),    // a post on this site, or ''
                'color'  => '#bf0000',               // '#rrggbb' or '#rgb', or '' for the scheme's color
                'source' => 'my-plugin',             // a-z, 0-9, _ and -, up to 32 characters
            );
        }
    } catch ( \Throwable $e ) {
        // Rebuilds also run on a reader's first page view and in cron. On failure, add nothing.
    }
    return $events;
}, 10, 2 );

予定の表示のされ方:

• label・url・source が同じで日が続く予定は、1行にまとめます (例: 「12/4–12/11」)。1つの予定では、毎日この 3つを同じにしてください。
• date・label・url が同じ予定は、2つのプラグインが足しても 1回だけ表示します。
• 一覧では、今日開かれている予定に「開催中」、終わった予定に「終了」と付けます。日付はブラウザーでの読者の日付を使うので、キャッシュされたページでも正しい状態が出ます。
• 予定があっても、カレンダーが開く月は変わりません。読者は「前へ」「次へ」のボタンで予定のある月へ移ります。
• 存在しない日付の予定と、ラベルが空の予定は捨てます。

予定を足すプラグインの決まり:

• 足すのは、自分のプラグインが持っている予定だけにしてください。ほかのプラグインから受け取った予定は渡し直さないでください。そのプラグインが自分で足せます。
• url は、このサイトの投稿か固定ページにしてください。予定のリンクには rel 属性が付かないので、アフィリエイトなどの有料リンクは使わないでください。
• date は、サイトのタイムゾーン (「設定 → 一般」) での日付です。タイムゾーン・パーマリンク構造・サイトアドレスが変わると、データを作り直します。

予定が変わったら、作り直しを頼みます。作り直しはリクエストの最後に 1回だけ走ります:

do_action( 'coyomi_request_rebuild' );

プラグインを無効化するときは、作り直しを頼む前にフィルターを外してください。外さないと、同じリクエストの最後に走る作り直しで予定がまた加わります。

データファイルの URL は、アップロードの URL ではなくサイトの URL から作るので、メディアを別のドメインや CDN から配信していても動きます。それでも別の URL が必要な構成では、次のようにします:

add_filter( 'coyomi_data_url', function ( $url, $key, $path ) {
    return $url; // must be readable from the page (same origin, or CORS allowed)
}, 10, 3 );<h3>WP-CLI</h3>

* wp coyomi status – データファイルと最後に作り直した日時
* wp coyomi rebuild – すべてのデータファイルを作り直す
* wp coyomi compare lwac_calendar-2 – 旧来の月ごとのクエリーを一度だけ流し、記事のある日を突き合わせる