行列ブロッククエリ

行列ブロッククエリを使用して、テンプレートや PHP コード内で行列ブロックを取得できます。

{# Create a new Matrix block query #}
{% set myMatrixBlockQuery = craft.matrixBlocks() %}

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

TIP

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

実例

次の操作を行うことで、エレメントのすべての行列ブロックのコンテンツを表示できます。

  1. craft.matrixBlocks() で行列ブロッククエリを作成します。
  2. ownerfieldId、および、type パラメータをセットします。
  3. .all() で行列ブロックを取得します。
  4. for タグを使用して行列ブロックをループ処理し、コンテンツを出力します。
{# Create a Matrix block query with the 'owner', 'fieldId', and 'type' parameters #}
{% set myMatrixBlockQuery = craft.matrixBlocks()
    .owner(myEntry)
    .fieldId(10)
    .type('text') %}

{# Fetch the Matrix blocks #}
{% set matrixBlocks = myMatrixBlockQuery.all() %}

{# Display their contents #}
{% for block in blocks %}
    <p>{{ block.text }}</p>
{% endfor %}

WARNING

返される行列ブロックにカスタムフィールドのコンテンツが代入されるよう、fieldId または id パラメータを設定する必要があります。

パラメータ

行列ブロッククエリは、次のパラメータをサポートしています。

anyStatus

status および enabledForSite() パラメータをクリアします。

{# Fetch all Matrix blocks, regardless of status #}
{% set MatrixBlocks = craft.matrixBlocks()
    .anyStatus()
    .all() %}

asArray

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

{# Fetch Matrix blocks as arrays #}
{% set MatrixBlocks = craft.matrixBlocks()
    .asArray()
    .all() %}

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 Matrix blocks created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set MatrixBlocks = craft.matrixBlocks()
    .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 Matrix blocks updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

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

fieldId

フィールドの ID ごとに、行列ブロックが属するフィールドに基づいて、クエリの結果を絞り込みます。

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

取得する行列ブロック
1ID が 1 のフィールド内。
'not 1'ID が 1 のフィールド内ではない。
[1, 2]ID が 1 または 2 のフィールド内。
['not', 1, 2]ID が 1 または 2 のフィールド内ではない。
{# Fetch Matrix blocks in the field with an ID of 1 #}
{% set MatrixBlocks = craft.matrixBlocks()
    .fieldId(1)
    .all() %}

fixedOrder

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

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

id

行列ブロックの ID に基づいて、クエリの結果を絞り込みます。

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

取得する行列ブロック
1ID が 1。
'not 1'ID が 1ではない。
[1, 2]ID が 1 または 2。
['not', 1, 2]ID が 1 または 2 ではない。
{# Fetch the Matrix block by its ID #}
{% set MatrixBlock = craft.matrixBlocks()
    .id(1)
    .one() %}

TIP

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

inReverse

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

{# Fetch Matrix blocks in reverse #}
{% set MatrixBlocks = craft.matrixBlocks()
    .inReverse()
    .all() %}

limit

返される行列ブロックの数を決定します。

{# Fetch up to 10 Matrix blocks  #}
{% set MatrixBlocks = craft.matrixBlocks()
    .limit(10)
    .all() %}

offset

結果からスキップされる行列ブロックの数を決定します。

{# Fetch all Matrix blocks except for the first 3 #}
{% set MatrixBlocks = craft.matrixBlocks()
    .offset(3)
    .all() %}

orderBy

返される行列ブロックの順序を決定します。

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

owner

指定されたエレメントに基づいて、ownerId および siteId パラメータをセットします。

{# Fetch Matrix blocks created for this entry #}
{% set MatrixBlocks = craft.matrixBlocks()
    .owner(myEntry)
    .all() %}

ownerId

オーナーの ID ごとに、行列ブロックのオーナーエレメントに基づいて、クエリの結果を絞り込みます。

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

取得する行列ブロック
1ID が 1 のエレメントによって作成されたもの。
'not 1'ID が 1 のエレメントによって作成されたものではない。
[1, 2]ID が 1 または 2 のエレメントによって作成されたもの。
['not', 1, 2]ID が 1 または 2 のエレメントによって作成されたものではない。
{# Fetch Matrix blocks created for an element with an ID of 1 #}
{% set MatrixBlocks = craft.matrixBlocks()
    .ownerId(1)
    .all() %}

relatedTo

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

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

{# Fetch all Matrix blocks that are related to myCategory #}
{% set MatrixBlocks = craft.matrixBlocks()
    .relatedTo(myCategory)
    .all() %}

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

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

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

{# Fetch all Matrix blocks that match the search query #}
{% set MatrixBlocks = craft.matrixBlocks()
    .search(searchQuery)
    .all() %}

site

行列ブロックを照会するサイトを決定します。

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

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

取得される行列ブロック
'foo'ハンドルが foo のサイトから。
craft\models\Site オブジェクトオブジェクトで表されるサイトから。
{# Fetch Matrix blocks from the Foo site #}
{% set MatrixBlocks = craft.matrixBlocks()
    .site('foo')
    .all() %}

siteId

サイトの ID ごとに、行列ブロックを照会するサイトを決定します。

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

{# Fetch Matrix blocks from the site with an ID of 1 #}
{% set MatrixBlocks = craft.matrixBlocks()
    .siteId(1)
    .all() %}

status

行列ブロックのステータスに基づいて、クエリの結果を絞り込みます。

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

取得する行列ブロック
'enabled'(デフォルト)有効になっているもの。
'disabled'無効になっているもの。
{# Fetch disabled Matrix blocks #}
{% set MatrixBlocks = craft.matrixBlocks()
    .status('disabled')
    .all() %}

trashed

ソフトデリートされた行列ブロックだけに、クエリの結果を絞り込みます。

{# Fetch trashed Matrix blocks #}
{% set MatrixBlocks = {twig-function}
    .trashed()
    .all() %}

type

行列ブロックのブロックタイプに基づいて、クエリの結果を絞り込みます。

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

取得する行列ブロック
'foo'ハンドルが foo のタイプ。
'not foo'ハンドルが foo のタイプではない。
['foo', 'bar']ハンドルが foo または bar のタイプ。
['not', 'foo', 'bar']ハンドルが foo または bar のタイプではない。
MatrixBlockType オブジェクトオブジェクトで表されるタイプ。
{# Fetch Matrix blocks with a Foo block type #}
{% set MatrixBlocks = myEntry.myMatrixField
    .type('foo')
    .all() %}

typeId

タイプの ID ごとに、行列ブロックのブロックタイプに基づいて、クエリの結果を絞り込みます。

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

取得する行列ブロック
1ID が 1 のタイプ。
'not 1'ID が 1 のタイプではない。
[1, 2]ID が 1 または 2 のタイプ。
['not', 1, 2]ID が 1 または 2 のタイプではない。
{# Fetch Matrix blocks of the block type with an ID of 1 #}
{% set MatrixBlocks = myEntry.myMatrixField
    .typeId(1)
    .all() %}

uid

行列ブロックの UID に基づいて、クエリの結果を絞り込みます。

{# Fetch the Matrix block by its UID #}
{% set MatrixBlock = craft.matrixBlocks()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

with

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

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

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