タグ
タグを利用して、エントリ、ユーザー、および、アセットの分類を作成できます。
# タググループ
タグを作成する前に、それらを含めるためのタググループを作成しなければなりません。
新しいタググループを作るには、「設定 > タグ」に移動し、「新しいタググループ」ボタンをクリックします。
それぞれのタググループには、ユニークなタグのセットがあり、グループ内のタグが利用可能な独自のフィールドのセットを定義できます。 しかしながら、そのグループを利用するために、必ずしもタググループのフィールドレイアウトでフィールドを割り当てる必要はありません。
# タグの割り当て
どこか(エントリなど)にタグを割り当てるには、タグフィールドを作成し、フィールドレイアウトで追加しなければなりません。
それぞれのタグフィールドは、1つのタググループに接続されています。そのフィールドが付加されたもの(エントリ、アセット、ユーザーなど)は何でも、新しいタグを作成したり、グループに含まれるタグとのリレーションを持つことができます。
# タグの照会
タグクエリを利用して、テンプレートや PHP コード内でタグを取得できます。
タグクエリを作成すると、結果を絞り込むためのパラメータをセットできます。さらに、.all()
を呼び出して実行できます。Tag (opens new window) オブジェクトの配列が返されます。
エレメントクエリがどのように機能するかについては、エレメントクエリを参照してください。
# 実例
次の操作を行うことで、「Blog Tags」タググループに含まれるタグのリストを表示できます。
craft.tags()
でタグクエリを作成します。- group パラメータをセットします。
.all()
でタグを取得します。- for (opens new window) タグを利用してタグをループ処理し、リストの 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 (opens new window) オブジェクトではなく、データの配列として、マッチしたタグをクエリが返します。 |
clearCachedResult | キャッシュされた結果をクリアします。 |
dateCreated | タグの作成日に基づいて、クエリの結果を絞り込みます。 |
dateUpdated | タグの最終アップデート日に基づいて、クエリの結果を絞り込みます。 |
fixedOrder | クエリの結果を id で指定された順序で返します。 |
group | タグが属するタググループに基づいて、クエリの結果を絞り込みます。 |
groupId | グループの ID ごとに、タグが属するタググループに基づいて、クエリの結果を絞り込みます。 |
id | タグの ID に基づいて、クエリの結果を絞り込みます。 |
ignorePlaceholders | craft\services\Elements::setPlaceholderElement() (opens new window) によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするタグをクエリが返します。 |
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 (opens new window) オブジェクトではなく、データの配列として、マッチしたタグをクエリが返します。
# 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 (opens new window) オブジェクト | オブジェクトで表されるグループ内。 |
# 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 ではない。 |
特定の順序で結果を返したい場合、fixedOrder と組み合わせることができます。
# ignorePlaceholders
craft\services\Elements::setPlaceholderElement() (opens new window) によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするタグをクエリが返します。
# inReverse
クエリの結果を逆順で返します。
# limit
返されるタグの数を決定します。
# offset
結果からスキップされるタグの数を決定します。
# 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() %}
# search
検索クエリにマッチするタグだけに、クエリの結果を絞り込みます。
このパラメーターがどのように機能するかの詳細については、検索を参照してください。
{# 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 (opens new window) オブジェクト | オブジェクトで表されるサイトから。 |
'*' | すべてのサイトから。 |
複数のサイトを指定した場合、複数のサイトに属するエレメントは複数回返されます。単一のエレメントだけを返したい場合、これと併せて unique を利用してください。
# 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
ソフトデリートされたタグだけに、クエリの結果を絞り込みます。
# 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 を参照してください。