タグ

タグを利用して、エントリユーザー、および、アセットの分類を作成できます。

# タググループ

タグを作成する前に、それらを含めるためのタググループを作成しなければなりません。

新しいタググループを作るには、「設定 > タグ」に移動し、「新しいタググループ」ボタンをクリックします。

それぞれのタググループには、ユニークなタグのセットがあり、グループ内のタグが利用可能な独自のフィールドのセットを定義できます。 しかしながら、そのグループを利用するために、必ずしもタググループのフィールドレイアウトでフィールドを割り当てる必要はありません。

# タグの割り当て

どこか(エントリなど)にタグを割り当てるには、タグフィールドを作成し、フィールドレイアウトで追加しなければなりません。

それぞれのタグフィールドは、1つのタググループに接続されています。そのフィールドが付加されたもの(エントリ、アセット、ユーザーなど)は何でも、新しいタグを作成したり、グループに含まれるタグとのリレーションを持つことができます。

# タグの照会

タグクエリを利用して、テンプレートや PHP コード内でタグを取得できます。

{# Create a new tag query #}
{% set myTagQuery = craft.tags() %}

タグクエリを作成すると、結果を絞り込むためのパラメータをセットできます。さらに、.all() を呼び出して実行できます。Tag オブジェクトの配列が返されます。

エレメントクエリがどのように機能するかについては、エレメントクエリを参照してください。

# 実例

次の操作を行うことで、「Blog Tags」タググループに含まれるタグのリストを表示できます。

  1. craft.tags() でタグクエリを作成します。
  2. group パラメータをセットします。
  3. .all() でタグを取得します。
  4. for タグを利用してタグをループ処理し、リストの HTML を作成します。
{# Create a tag query with the 'group' parameter #}
{% set myTagQuery = craft.tags()
    .group('blogTags') %}

{# Fetch the tags #}
{% set tags = myTagQuery.all() %}

{# Display the tag list #}
<ul>
    {% for tag in tags %}
        <li><a href="{{ url('blog/tags/'~tag.id) }}">{{ tag.title }}</a></li>
    {% endfor %}
</ul>

# パラメータ

タグクエリは、次のパラメータをサポートしています。

パラメータ 説明
anyStatus ステータスに基づくエレメントのフィルタを削除します。
asArray Tag オブジェクトではなく、データの配列として、マッチしたタグをクエリが返します。
clearCachedResult キャッシュされた結果をクリアします。
dateCreated タグの作成日に基づいて、クエリの結果を絞り込みます。
dateUpdated タグの最終アップデート日に基づいて、クエリの結果を絞り込みます。
fixedOrder クエリの結果を id で指定された順序で返します。
group タグが属するタググループに基づいて、クエリの結果を絞り込みます。
groupId グループの ID ごとに、タグが属するタググループに基づいて、クエリの結果を絞り込みます。
id タグの ID に基づいて、クエリの結果を絞り込みます。
ignorePlaceholders craft\services\Elements::setPlaceholderElement() によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするタグをクエリが返します。
inReverse クエリの結果を逆順で返します。
limit 返されるタグの数を決定します。
offset 結果からスキップされるタグの数を決定します。
orderBy 返されるタグの順序を決定します。(空の場合、デフォルトは title ASC
preferSites unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します
relatedTo 特定の他のエレメントと関連付けられたタグだけに、クエリの結果を絞り込みます。
search 検索クエリにマッチするタグだけに、クエリの結果を絞り込みます。
site タグを照会するサイトを決定します。
siteId サイトの ID ごとに、タグを照会するサイトを決定します。
title タグのタイトルに基づいて、クエリの結果を絞り込みます。
trashed ソフトデリートされたタグだけに、クエリの結果を絞り込みます。
uid タグの UID に基づいて、クエリの結果を絞り込みます。
unique クエリによってユニークな ID のエレメントだけが返されるかを決定します。
uri タグの URI に基づいて、クエリの結果を絞り込みます。
with 関連付けられたエレメントを eager-loaded した状態で、マッチしたタグをクエリが返します。

# anyStatus

ステータスに基づくエレメントのフィルタを削除します。

{# Fetch all tags, regardless of status #}
{% set tags = craft.tags()
    .anyStatus()
    .all() %}

# asArray

Tag オブジェクトではなく、データの配列として、マッチしたタグをクエリが返します。

{# Fetch tags as arrays #}
{% set tags = craft.tags()
    .asArray()
    .all() %}

# clearCachedResult

キャッシュされた結果をクリアします。

# dateCreated

タグの作成日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
'>= 2018-04-01' 2018-04-01 以降に作成されたもの。
'< 2018-05-01' 2018-05-01 より前に作成されたもの。
['and', '>= 2018-04-04', '< 2018-05-01'] 2018-04-01 から 2018-05-01 の間に作成されたもの。
{# Fetch tags created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set tags = craft.tags()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

# dateUpdated

タグの最終アップデート日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
'>= 2018-04-01' 2018-04-01 以降にアップデートされたもの。
'< 2018-05-01' 2018-05-01 より前にアップデートされたもの。
['and', '>= 2018-04-04', '< 2018-05-01'] 2018-04-01 から 2018-05-01 の間にアップデートされたもの。
{# Fetch tags updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set tags = craft.tags()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

# fixedOrder

クエリの結果を id で指定された順序で返します。

{# Fetch tags in a specific order #}
{% set tags = craft.tags()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

# group

タグが属するタググループに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
'foo' ハンドルが foo のグループ内。
'not foo' ハンドルが foo のグループ内ではない。
['foo', 'bar'] ハンドルが foo または bar のグループ内。
['not', 'foo', 'bar'] ハンドルが foo または bar のグループ内ではない。
TagGroup オブジェクト オブジェクトで表されるグループ内。
{# Fetch tags in the Foo group #}
{% set tags = craft.tags()
    .group('foo')
    .all() %}

# groupId

グループの ID ごとに、タグが属するタググループに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
1 ID が 1 のグループ内。
'not 1' ID が 1 のグループ内ではない。
[1, 2] ID が 1 または 2 のグループ内。
['not', 1, 2] ID が 1 または 2 のグループ内ではない。
{# Fetch tags in the group with an ID of 1 #}
{% set tags = craft.tags()
    .groupId(1)
    .all() %}

# id

タグの ID に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
1 ID が 1。
'not 1' ID が 1ではない。
[1, 2] ID が 1 または 2。
['not', 1, 2] ID が 1 または 2 ではない。
{# Fetch the tag by its ID #}
{% set tag = craft.tags()
    .id(1)
    .one() %}

特定の順序で結果を返したい場合、fixedOrder と組み合わせることができます。

# ignorePlaceholders

craft\services\Elements::setPlaceholderElement() によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするタグをクエリが返します。

# inReverse

クエリの結果を逆順で返します。

{# Fetch tags in reverse #}
{% set tags = craft.tags()
    .inReverse()
    .all() %}

# limit

返されるタグの数を決定します。

{# Fetch up to 10 tags  #}
{% set tags = craft.tags()
    .limit(10)
    .all() %}

# offset

結果からスキップされるタグの数を決定します。

{# Fetch all tags except for the first 3 #}
{% set tags = craft.tags()
    .offset(3)
    .all() %}

# orderBy

返されるタグの順序を決定します。(空の場合、デフォルトは title ASC

{# Fetch all tags in order of date created #}
{% set tags = craft.tags()
    .orderBy('dateCreated asc')
    .all() %}

# preferSites

unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します

例えば、エレメント “Foo” がサイト A とサイト B に存在し、エレメント “Bar” がサイト B とサイト C に存在し、ここに ['c', 'b', 'a'] がセットされている場合、Foo will はサイト C に対して返され、Bar はサイト B に対して返されます。

これがセットされていない場合、現在のサイトが優先されます。

{# Fetch unique tags from Site A, or Site B if they don’t exist in Site A #}
{% set tags = craft.tags()
    .site('*')
    .unique()
    .preferSites(['a', 'b'])
    .all() %}

# relatedTo

特定の他のエレメントと関連付けられたタグだけに、クエリの結果を絞り込みます。

このパラメーターがどのように機能するかの詳細については、リレーションを参照してください。

{# Fetch all tags that are related to myCategory #}
{% set tags = craft.tags()
    .relatedTo(myCategory)
    .all() %}

検索クエリにマッチするタグだけに、クエリの結果を絞り込みます。

このパラメーターがどのように機能するかの詳細については、検索を参照してください。

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all tags that match the search query #}
{% set tags = craft.tags()
    .search(searchQuery)
    .all() %}

# site

タグを照会するサイトを決定します。

デフォルトでは、現在のサイトが使用されます。

利用可能な値には、次のものが含まれます。

取得するタグ
'foo' ハンドルが foo のサイトから。
['foo', 'bar'] ハンドルが foo または bar のサイトから。
['not', 'foo', 'bar'] ハンドルが foo または bar のサイトではない。
craft\models\Site オブジェクト オブジェクトで表されるサイトから。
'*' すべてのサイトから。

複数のサイトを指定した場合、複数のサイトに属するエレメントは複数回返されます。単一のエレメントだけを返したい場合、これと併せて unique を利用してください。

{# Fetch tags from the Foo site #}
{% set tags = craft.tags()
    .site('foo')
    .all() %}

# siteId

サイトの ID ごとに、タグを照会するサイトを決定します。

デフォルトでは、現在のサイトが使用されます。

利用可能な値には、次のものが含まれます。

取得するタグ
1 ID が 1 のサイトから。
[1, 2] ID が 1 または 2 のサイトから。
['not', 1, 2] ID が 1 または 2 のサイトではない。
'*' すべてのサイトから。
{# Fetch tags from the site with an ID of 1 #}
{% set tags = craft.tags()
    .siteId(1)
    .all() %}

# title

タグのタイトルに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
'Foo' タイトルが Foo
'Foo*' タイトルが Foo ではじまる。
'*Foo' タイトルが Foo で終わる。
'*Foo*' タイトルが Foo を含む。
'not *Foo*' タイトルが Foo を含まない。
['*Foo*', '*Bar*'] タイトルが Foo または Bar を含む。
['not', '*Foo*', '*Bar*'] タイトルが Foo または Bar を含まない。
{# Fetch tags with a title that contains "Foo" #}
{% set tags = craft.tags()
    .title('*Foo*')
    .all() %}

# trashed

ソフトデリートされたタグだけに、クエリの結果を絞り込みます。

{# Fetch trashed tags #}
{% set tags = craft.tags()
    .trashed()
    .all() %}

# uid

タグの UID に基づいて、クエリの結果を絞り込みます。

{# Fetch the tag by its UID #}
{% set tag = craft.tags()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

# unique

クエリによってユニークな ID のエレメントだけが返されるかを決定します。

一度に複数のサイトからエレメントを照会する際、「重複する」結果を望まない場合に使用します。

{# Fetch unique tags across all sites #}
{% set tags = craft.tags()
    .site('*')
    .unique()
    .all() %}

# uri

タグの URI に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するタグ
'foo' URI が foo
'foo*' URI が foo ではじまる。
'*foo' URI が foo で終わる。
'*foo*' URI が foo を含む。
'not *foo*' URI が foo を含まない。
['*foo*', '*bar*'] URI が foo または bar を含む。
['not', '*foo*', '*bar*'] URI が foo または bar を含まない。
{# Get the requested URI #}
{% set requestedUri = craft.app.request.getPathInfo() %}

{# Fetch the tag with that URI #}
{% set tag = craft.tags()
    .uri(requestedUri|literal)
    .one() %}

# with

関連付けられたエレメントを eager-loaded した状態で、マッチしたタグをクエリが返します。

このパラメーターがどのように機能するかの詳細については、エレメントの Eager-Loading を参照してください。

{# Fetch tags eager-loaded with the "Related" field’s relations #}
{% set tags = craft.tags()
    .with(['related'])
    .all() %}