カテゴリ
カテゴリを利用して、エントリ、ユーザー、および、アセットの分類を作成できます。
# カテゴリグループ
カテゴリを作成する前に、それらを含めるためのカテゴリグループを作成しなければなりません。それぞれのカテゴリグループには、次のことを定義できます。
- カテゴリグループの名前
- カテゴリグループのハンドル(テンプレートから、そのカテゴリグループを参照する方法)
- そのグループの中にネストできるカテゴリの最大レベル
- カテゴリ URI 形式
- カテゴリ URL にアクセスされたとき、どのテンプレートを読み込むか
- グループ内のカテゴリがどんなフィールドを持つべきか
新しいカテゴリグループを作るには、「設定 > カテゴリ」に移動し、「新しいカテゴリーグループ」ボタンをクリックします。
少なくとも1つのカテゴリグループを作成すると、そのグループのカテゴリを作成できるようになります。
# カテゴリフィールドレイアウト
それぞれのカテゴリグループは、グループ内のカテゴリに関連付けられたデータをカスタマイズできる独自のフィールドレイアウトを持っています。デフォルトでは、すべてのカテゴリはタイトルフィールド(カテゴリ名)を持っています。
Craft 内で利用可能なすべてのフィールドタイプを使って、フィールドを追加することもできます。まだフィールドが存在しなければ、先に「設定 > フィールド」から作成しなければなりません。新しいフィールドは、カテゴリグループのフィールドレイアウトに割り当てられるようになります。
# カテゴリの作成と編集
少なくとも1つのカテゴリグループがあれば、コントロールパネルのメインナビゲーションに「カテゴリ」タブが表示されます。クリックすると、カテゴリのインデックスに移動します。サイドバーからカテゴリグループを選択すると、そのグループに含まれるカテゴリを追加 / 並び替え / 削除できます。
カテゴリをダブルクリックすると、カテゴリの名前やスラグ、および、グループに関連付けられたすべてのフィールドを編集できるモーダルウィンドウが開きます。
カテゴリを作成するときのオプションは、次の通りです。
- カテゴリフィールドへの記入(フィールドを定義していなければ、タイトルフィールドだけが利用可能となります)
- スラグの編集(タイトルに基づいて、自動的に入力されます)
- 親カテゴリの選択。新しいカテゴリは、親カテゴリと階層的な関係を持ちます。これはマルチレベルで分類を作成する際に役立ちます。親を割り当てる際に新しいカテゴリを作成するオプションもあります。
カテゴリグループの設定にある最大レベル欄で指定したレベルまでしか、カテゴリをネストできません。レベルを指定していない場合、無制限にネストできます。
# カテゴリの割り当て
項目(エントリ、アセット、ユーザーなど)にカテゴリを割り当てるには、先にカテゴリフィールドを作成しなければなりません。
それぞれのカテゴリフィールドは、1つのカテゴリグループに接続されています。そのフィールドが付加されたものは何でも、グループに含まれるすべてのカテゴリとのリレーションを持つことができます。
# カテゴリの照会
カテゴリクエリを利用して、テンプレートや PHP コード内でカテゴリを取得できます。
カテゴリクエリを作成すると、結果を絞り込むためのparametersをセットできます。さらに、.all()
を呼び出して実行できます。Category (opens new window) オブジェクトの配列が返されます。
エレメントクエリがどのように機能するかについては、エレメントクエリを参照してください。
# 実例
次の操作を行うことで、「Topics」カテゴリグループに含まれるすべてのカテゴリのナビゲーションを表示できます。
craft.categories()
でカテゴリクエリを作成します。- group パラメータをセットします。
.all()
でカテゴリを取得します。- nav タグを利用してカテゴリをループ処理し、ナビゲーションの HTML を作成します。
{# Create a category query with the 'group' parameter #}
{% set myCategoryQuery = craft.categories()
.group('topics') %}
{# Fetch the categories #}
{% set categories = myCategoryQuery.all() %}
{# Display the navigation #}
<ul>
{% nav category in categories %}
<li>
<a href="{{ category.url }}">{{ category.title }}</a>
{% ifchildren %}
<ul>
{% children %}
</ul>
{% endifchildren %}
</li>
{% endnav %}
</ul>
# パラメータ
カテゴリクエリは、次のパラメータをサポートしています。
パラメータ | 説明 |
---|---|
ancestorDist | ancestorOf で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。 |
ancestorOf | 指定したカテゴリの先祖であるカテゴリだけに、クエリの結果を絞り込みます。 |
anyStatus | ステータスに基づくエレメントのフィルタを削除します。 |
asArray | Category (opens new window) オブジェクトではなく、データの配列として、マッチしたカテゴリをクエリが返します。 |
clearCachedResult | キャッシュされた結果をクリアします。 |
dateCreated | カテゴリの作成日に基づいて、クエリの結果を絞り込みます。 |
dateUpdated | カテゴリの最終アップデート日に基づいて、クエリの結果を絞り込みます。 |
descendantDist | descendantOf で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。 |
descendantOf | 指定したカテゴリの子孫であるカテゴリだけに、クエリの結果を絞り込みます。 |
fixedOrder | クエリの結果を id で指定された順序で返します。 |
group | カテゴリが属するカテゴリグループに基づいて、クエリの結果を絞り込みます。 |
groupId | グループの ID ごとに、カテゴリが属するカテゴリグループに基づいて、クエリの結果を絞り込みます。 |
hasDescendants | カテゴリが子孫を持つかどうかに基づいて、クエリの結果を絞り込みます。 |
id | カテゴリの ID に基づいて、クエリの結果を絞り込みます。 |
ignorePlaceholders | craft\services\Elements::setPlaceholderElement() (opens new window) によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするカテゴリをクエリが返します。 |
inReverse | クエリの結果を逆順で返します。 |
leaves | カテゴリが「leaves」(子孫のないカテゴリ)であるかどうかに基づいて、クエリの結果を絞り込みます。 |
level | ストラクチャー内のカテゴリのレベルに基づいて、クエリの結果を絞り込みます。 |
limit | 返されるカテゴリの数を決定します。 |
nextSiblingOf | 指定したカテゴリの直後にあるカテゴリだけに、クエリの結果を絞り込みます。 |
offset | 結果からスキップされるカテゴリの数を決定します。 |
orderBy | 返されるカテゴリの順序を決定します。(空の場合、デフォルトは dateCreated DESC です。単一のグループに group または groupIdパラメータがセットされている場合、カテゴリグループによって定義された順序になります。 |
positionedAfter | 指定したカテゴリの後に位置するカテゴリだけに、クエリの結果を絞り込みます。 |
positionedBefore | 指定したカテゴリの前に位置するカテゴリだけに、クエリの結果を絞り込みます。 |
preferSites | unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します |
prevSiblingOf | 指定したカテゴリの直前にあるカテゴリだけに、クエリの結果を絞り込みます。 |
relatedTo | 特定の他のエレメントと関連付けられたカテゴリだけに、クエリの結果を絞り込みます。 |
search | 検索クエリにマッチするカテゴリだけに、クエリの結果を絞り込みます。 |
siblingOf | 指定したカテゴリの兄弟であるカテゴリだけに、クエリの結果を絞り込みます。 |
site | カテゴリを照会するサイトを決定します。 |
siteId | サイトの ID ごとに、カテゴリを照会するサイトを決定します。 |
slug | カテゴリのスラグに基づいて、クエリの結果を絞り込みます。 |
status | カテゴリのステータスに基づいて、クエリの結果を絞り込みます。 |
title | カテゴリのタイトルに基づいて、クエリの結果を絞り込みます。 |
trashed | ソフトデリートされたカテゴリだけに、クエリの結果を絞り込みます。 |
uid | カテゴリの UID に基づいて、クエリの結果を絞り込みます。 |
unique | クエリによってユニークな ID のエレメントだけが返されるかを決定します。 |
uri | カテゴリの URI に基づいて、クエリの結果を絞り込みます。 |
with | 関連付けられたエレメントを eager-loaded した状態で、マッチしたカテゴリをクエリが返します。 |
# ancestorDist
ancestorOf で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。
{# Fetch categories above this one #}
{% set categories = craft.categories()
.ancestorOf(myCategory)
.ancestorDist(3)
.all() %}
# ancestorOf
指定したカテゴリの先祖であるカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの上層。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの上層。 |
{# Fetch categories above this one #}
{% set categories = craft.categories()
.ancestorOf(myCategory)
.all() %}
どれだけ離れた先祖カテゴリを対象にするか制限したい場合、ancestorDist と組み合わせることができます。
# anyStatus
ステータスに基づくエレメントのフィルタを削除します。
{# Fetch all categories, regardless of status #}
{% set categories = craft.categories()
.anyStatus()
.all() %}
# asArray
Category (opens new window) オブジェクトではなく、データの配列として、マッチしたカテゴリをクエリが返します。
{# Fetch categories as arrays #}
{% set categories = craft.categories()
.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 categories created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}
{% set categories = craft.categories()
.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 categories updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}
{% set categories = craft.categories()
.dateUpdated(">= #{lastWeek}")
.all() %}
# descendantDist
descendantOf で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。
{# Fetch categories below this one #}
{% set categories = craft.categories()
.descendantOf(myCategory)
.descendantDist(3)
.all() %}
# descendantOf
指定したカテゴリの子孫であるカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの下層。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの下層。 |
{# Fetch categories below this one #}
{% set categories = craft.categories()
.descendantOf(myCategory)
.all() %}
どれだけ離れた子孫カテゴリを対象にするか制限したい場合、descendantDist と組み合わせることができます。
# fixedOrder
クエリの結果を id で指定された順序で返します。
{# Fetch categories in a specific order #}
{% set categories = craft.categories()
.id([1, 2, 3, 4, 5])
.fixedOrder()
.all() %}
# group
カテゴリが属するカテゴリグループに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
'foo' | ハンドルが foo のグループ内。 |
'not foo' | ハンドルが foo のグループ内ではない。 |
['foo', 'bar'] | ハンドルが foo または bar のグループ内。 |
['not', 'foo', 'bar'] | ハンドルが foo または bar のグループ内ではない。 |
CategoryGroup (opens new window) オブジェクト | オブジェクトで表されるグループ内。 |
{# Fetch categories in the Foo group #}
{% set categories = craft.categories()
.group('foo')
.all() %}
# groupId
グループの ID ごとに、カテゴリが属するカテゴリグループに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のグループ内。 |
'not 1' | ID が 1 のグループ内ではない。 |
[1, 2] | ID が 1 または 2 のグループ内。 |
['not', 1, 2] | ID が 1 または 2 のグループ内ではない。 |
{# Fetch categories in the group with an ID of 1 #}
{% set categories = craft.categories()
.groupId(1)
.all() %}
# hasDescendants
カテゴリが子孫を持つかどうかに基づいて、クエリの結果を絞り込みます。
(これは leaves の呼び出しと反対の効果を持っています。)
{# Fetch categories that have descendants #}
{% set categories = craft.categories()
.hasDescendants()
.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
クエリの結果を逆順で返します。
{# Fetch categories in reverse #}
{% set categories = craft.categories()
.inReverse()
.all() %}
# leaves
カテゴリが「leaves」(子孫のないカテゴリ)であるかどうかに基づいて、クエリの結果を絞り込みます。
(これは hasDescendants の呼び出しと反対の効果を持っています。)
{# Fetch categories that have no descendants #}
{% set categories = craft.categories()
.leaves()
.all() %}
# level
ストラクチャー内のカテゴリのレベルに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | レベルが 1。 |
'not 1' | レベルが 1 ではない。 |
'>= 3' | レベルが 3 以上。 |
[1, 2] | レベルが 1 または 2。 |
['not', 1, 2] | レベルが 1 または 2 ではない。 |
{# Fetch categories positioned at level 3 or above #}
{% set categories = craft.categories()
.level('>= 3')
.all() %}
# limit
返されるカテゴリの数を決定します。
# nextSiblingOf
指定したカテゴリの直後にあるカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの後。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの後。 |
{# Fetch the next category #}
{% set category = craft.categories()
.nextSiblingOf(myCategory)
.one() %}
# offset
結果からスキップされるカテゴリの数を決定します。
{# Fetch all categories except for the first 3 #}
{% set categories = craft.categories()
.offset(3)
.all() %}
# orderBy
返されるカテゴリの順序を決定します。(空の場合、デフォルトは dateCreated DESC
です。単一のグループに group または groupIdパラメータがセットされている場合、カテゴリグループによって定義された順序になります。
{# Fetch all categories in order of date created #}
{% set categories = craft.categories()
.orderBy('dateCreated asc')
.all() %}
# positionedAfter
指定したカテゴリの後に位置するカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの後。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの後。 |
{# Fetch categories after this one #}
{% set categories = craft.categories()
.positionedAfter(myCategory)
.all() %}
# positionedBefore
指定したカテゴリの前に位置するカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの前。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの前。 |
{# Fetch categories before this one #}
{% set categories = craft.categories()
.positionedBefore(myCategory)
.all() %}
# preferSites
unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します
例えば、エレメント “Foo” がサイト A とサイト B に存在し、エレメント “Bar” がサイト B とサイト C に存在し、ここに ['c', 'b', 'a']
がセットされている場合、Foo will はサイト C に対して返され、Bar はサイト B に対して返されます。
これがセットされていない場合、現在のサイトが優先されます。
{# Fetch unique categories from Site A, or Site B if they don’t exist in Site A #}
{% set categories = craft.categories()
.site('*')
.unique()
.preferSites(['a', 'b'])
.all() %}
# prevSiblingOf
指定したカテゴリの直前にあるカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの前。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの前。 |
{# Fetch the previous category #}
{% set category = craft.categories()
.prevSiblingOf(myCategory)
.one() %}
# relatedTo
特定の他のエレメントと関連付けられたカテゴリだけに、クエリの結果を絞り込みます。
このパラメーターがどのように機能するかの詳細については、リレーションを参照してください。
{# Fetch all categories that are related to myCategory #}
{% set categories = craft.categories()
.relatedTo(myCategory)
.all() %}
# search
検索クエリにマッチするカテゴリだけに、クエリの結果を絞り込みます。
このパラメーターがどのように機能するかの詳細については、検索を参照してください。
{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}
{# Fetch all categories that match the search query #}
{% set categories = craft.categories()
.search(searchQuery)
.all() %}
# siblingOf
指定したカテゴリの兄弟であるカテゴリだけに、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のカテゴリの横。 |
Category (opens new window) オブジェクト | オブジェクトで表されるカテゴリの横。 |
{# Fetch categories beside this one #}
{% set categories = craft.categories()
.siblingOf(myCategory)
.all() %}
# site
カテゴリを照会するサイトを決定します。
デフォルトでは、現在のサイトが使用されます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
'foo' | ハンドルが foo のサイトから。 |
['foo', 'bar'] | ハンドルが foo または bar のサイトから。 |
['not', 'foo', 'bar'] | ハンドルが foo または bar のサイトではない。 |
craft\models\Site (opens new window) オブジェクト | オブジェクトで表されるサイトから。 |
'*' | すべてのサイトから。 |
複数のサイトを指定した場合、複数のサイトに属するエレメントは複数回返されます。単一のエレメントだけを返したい場合、これと併せて unique を利用してください。
{# Fetch categories from the Foo site #}
{% set categories = craft.categories()
.site('foo')
.all() %}
# siteId
サイトの ID ごとに、カテゴリを照会するサイトを決定します。
デフォルトでは、現在のサイトが使用されます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
1 | ID が 1 のサイトから。 |
[1, 2] | ID が 1 または 2 のサイトから。 |
['not', 1, 2] | ID が 1 または 2 のサイトではない。 |
'*' | すべてのサイトから。 |
{# Fetch categories from the site with an ID of 1 #}
{% set categories = craft.categories()
.siteId(1)
.all() %}
# slug
カテゴリのスラグに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
'foo' | スラグが foo 。 |
'foo*' | スラグが foo ではじまる。 |
'*foo' | スラグが foo で終わる。 |
'*foo*' | スラグが foo を含む。 |
'not *foo*' | スラグが foo を含まない。 |
['*foo*', '*bar*'] | スラグが foo または bar を含む。 |
['not', '*foo*', '*bar*'] | スラグが foo または bar を含まない。 |
{# Get the requested category slug from the URL #}
{% set requestedSlug = craft.app.request.getSegment(3) %}
{# Fetch the category with that slug #}
{% set category = craft.categories()
.slug(requestedSlug|literal)
.one() %}
# status
カテゴリのステータスに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
'enabled' (デフォルト) | 有効なもの。 |
'disabled' | 無効なもの。 |
{# Fetch disabled categories #}
{% set categories = craft.categories()
.status('disabled')
.all() %}
# title
カテゴリのタイトルに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するカテゴリ |
---|---|
'Foo' | タイトルが Foo 。 |
'Foo*' | タイトルが Foo ではじまる。 |
'*Foo' | タイトルが Foo で終わる。 |
'*Foo*' | タイトルが Foo を含む。 |
'not *Foo*' | タイトルが Foo を含まない。 |
['*Foo*', '*Bar*'] | タイトルが Foo または Bar を含む。 |
['not', '*Foo*', '*Bar*'] | タイトルが Foo または Bar を含まない。 |
{# Fetch categories with a title that contains "Foo" #}
{% set categories = craft.categories()
.title('*Foo*')
.all() %}
# trashed
ソフトデリートされたカテゴリだけに、クエリの結果を絞り込みます。
# uid
カテゴリの UID に基づいて、クエリの結果を絞り込みます。
{# Fetch the category by its UID #}
{% set category = craft.categories()
.uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
.one() %}
# unique
クエリによってユニークな ID のエレメントだけが返されるかを決定します。
一度に複数のサイトからエレメントを照会する際、「重複する」結果を望まない場合に使用します。
{# Fetch unique categories across all sites #}
{% set categories = craft.categories()
.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 category with that URI #}
{% set category = craft.categories()
.uri(requestedUri|literal)
.one() %}
# with
関連付けられたエレメントを eager-loaded した状態で、マッチしたカテゴリをクエリが返します。
このパラメーターがどのように機能するかの詳細については、エレメントの Eager-Loading を参照してください。