グローバル
グローバルは、テンプレート全体で包括的に利用可能なコンテンツを保存できます。これは、コントロールパネル経由でエントリではないコンテンツを簡単に編集できるようにする便利な方法です。
Craft はグローバル設定内でグローバルを整理します。それぞれのグローバル設定は、存在するすべてのフィールドや新しいフィールドを利用する独自のフィールドレイアウトを持ちます。
グローバル設定を作るには、「設定 > グローバル」に移動します。
少なくとも1つのグローバル設定があれば、Craft はコントロールパネルのメインナビゲーションに「グローバル」項目を追加します。これをクリックすると、サイドバーにすべてのグローバル設定のリスト、メインコンテンツエリアに選択されたグローバル設定に関連するすべてのフィールドが表示されたページに移動します。
エントリとは異なり、特定の URL と関連付けられていないグローバル設定では、ライブプレビュー機能がありません。
# テンプレートでのグローバル設定
任意のテンプレートからハンドル経由でグローバル設定にアクセスできます。
companyInfo
というハンドルのグローバル設定があり、yearEstablished
というハンドルのフィールドがある場合、次のコードを利用してそのフィールドへどこからでもアクセスできます。
{{ companyInfo.yearEstablished }}
カスタムフィールド以外で利用できる追加のグローバル設定のプロパティについては、リファレンスの craft\elements\GlobalSet (opens new window) を参照してください。
# グローバル設定の手動読み込み
メールテンプレートのような特殊な状況では、グローバル設定はデフォルトでは利用できません。グローバル設定は手動でも読み込めます。上記の例では、getSetByHandle()
で読み込むことができます。
詳細については、Globals サービスクラスのドキュメント (opens new window) を参照してください。
# マルチサイトでのグローバル設定
Craft でマルチサイトを運用している場合、グローバル設定はすべてのサイトで利用可能です。しかしながら、必要に応じていくつかのフィールドを空のままにするなど、それぞれの設定値をサイトごとにセットできます。
そのためには、グローバル設定のフィールドを編集し、それぞれの「翻訳方法」設定で「各サイトに対して翻訳」をセットします。
グローバル設定を表示中にサイトを切り替えるには、コントロールパネルのグローバル設定ページの左上にあるドロップダウンメニューを使用します。
# グローバルの照会
グローバル設定クエリを利用して、テンプレートや PHP コード内でグローバル設定を取得できます。
グローバル設定クエリを作成すると、結果を絞り込むためのパラメータをセットできます。 さらに、.all()
を呼び出して実行できます。GlobalSet (opens new window) オブジェクトの配列が返されます。
エレメントクエリがどのように機能するかについては、エレメントクエリを参照してください。
# 実例
次の操作をすることで、プライマリサイトからグローバル設置をロードし、コンテンツを表示できます。
craft.globalSets()
でグローバル設定クエリを作成します。- handle および siteId パラメータをセットします。
.one()
でグローバル設定を取得します。- コンテンツを出力します。
{# Create a global set query with the 'handle' and 'siteId' parameters #}
{% set myGlobalSetQuery = craft.globalSets()
.handle('footerCopy')
.siteId(1) %}
{# Fetch the global set #}
{% set globalSet = myGlobalSetQuery.one() %}
{# Display the content #}
<p>{{ globalSet.copyrightInfo }}</p>
すべてのグローバル設定は、Twig テンプレートのグローバル変数としてすでに利用可能です。そのため、現在のサイトとは異なるサイトのコンテンツにアクセスする場合、craft.globalSets()
を通して取得する必要があります。
# パラメータ
グローバル設定クエリは、次のパラメータをサポートしています。
パラメータ | 説明 |
---|---|
anyStatus | ステータスに基づくエレメントのフィルタを削除します。 |
asArray | GlobalSet (opens new window) オブジェクトではなく、データの配列として、マッチしたグローバル設定をクエリが返します。 |
clearCachedResult | キャッシュされた結果をクリアします。 |
dateCreated | グローバル設定の作成日に基づいて、クエリの結果を絞り込みます。 |
dateUpdated | グローバル設定の最終アップデート日に基づいて、クエリの結果を絞り込みます。 |
fixedOrder | クエリの結果を id で指定された順序で返します。 |
handle | グローバル設定のハンドルに基づいて、クエリの結果を絞り込みます。 |
id | グローバル設定の ID に基づいて、クエリの結果を絞り込みます。 |
ignorePlaceholders | craft\services\Elements::setPlaceholderElement() (opens new window) によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするグローバル設定をクエリが返します。 |
inReverse | クエリの結果を逆順で返します。 |
limit | 返されるグローバル設定の数を決定します。 |
offset | 結果からスキップされるグローバル設定の数を決定します。 |
orderBy | 返されるグローバル設定の順序を決定します。(空の場合、デフォルトは name ASC ) |
preferSites | unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します |
relatedTo | 特定の他のエレメントと関連付けられたグローバル設定だけに、クエリの結果を絞り込みます。 |
search | 検索クエリにマッチするグローバル設定だけに、クエリの結果を絞り込みます。 |
site | グローバル設定を照会するサイトを決定します。 |
siteId | サイトの ID ごとに、グローバル設定を照会するサイトを決定します。 |
trashed | ソフトデリートされたグローバル設定だけに、クエリの結果を絞り込みます。 |
uid | グローバル設定の UID に基づいて、クエリの結果を絞り込みます。 |
unique | クエリによってユニークな ID のエレメントだけが返されるかを決定します。 |
with | 関連付けられたエレメントを eager-loaded した状態で、マッチしたグローバル設定をクエリが返します。 |
# anyStatus
ステータスに基づくエレメントのフィルタを削除します。
{# Fetch all global sets, regardless of status #}
{% set globalSets = craft.globalSets()
.anyStatus()
.all() %}
# asArray
GlobalSet (opens new window) オブジェクトではなく、データの配列として、マッチしたグローバル設定をクエリが返します。
{# Fetch global sets as arrays #}
{% set globalSets = craft.globalSets()
.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 global sets created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}
{% set globalSets = craft.globalSets()
.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 global sets updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}
{% set globalSets = craft.globalSets()
.dateUpdated(">= #{lastWeek}")
.all() %}
# fixedOrder
クエリの結果を id で指定された順序で返します。
{# Fetch global sets in a specific order #}
{% set globalSets = craft.globalSets()
.id([1, 2, 3, 4, 5])
.fixedOrder()
.all() %}
# handle
グローバル設定のハンドルに基づいて、クエリの結果を絞り込みます。
利用可能な値には、次のものが含まれます。
値 | 取得するグローバル設定 |
---|---|
'foo' | ハンドルが foo 。 |
'not foo' | ハンドルが foo ではない。 |
['foo', 'bar'] | ハンドルが foo または bar 。 |
['not', 'foo', 'bar'] | ハンドルが foo または bar ではない。 |
{# Fetch the global set with a handle of 'foo' #}
{% set globalSet = craft.globalSets()
.handle('foo')
.one() %}
# 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 global sets in reverse #}
{% set globalSets = craft.globalSets()
.inReverse()
.all() %}
# limit
返されるグローバル設定の数を決定します。
{# Fetch up to 10 global sets #}
{% set globalSets = craft.globalSets()
.limit(10)
.all() %}
# offset
結果からスキップされるグローバル設定の数を決定します。
{# Fetch all global sets except for the first 3 #}
{% set globalSets = craft.globalSets()
.offset(3)
.all() %}
# orderBy
返されるグローバル設定の順序を決定します。(空の場合、デフォルトは name ASC
)
{# Fetch all global sets in order of date created #}
{% set globalSets = craft.globalSets()
.orderBy('dateCreated asc')
.all() %}
# preferSites
unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します
例えば、エレメント “Foo” がサイト A とサイト B に存在し、エレメント “Bar” がサイト B とサイト C に存在し、ここに ['c', 'b', 'a']
がセットされている場合、Foo will はサイト C に対して返され、Bar はサイト B に対して返されます。
これがセットされていない場合、現在のサイトが優先されます。
{# Fetch unique global sets from Site A, or Site B if they don’t exist in Site A #}
{% set globalSets = craft.globalSets()
.site('*')
.unique()
.preferSites(['a', 'b'])
.all() %}
# relatedTo
特定の他のエレメントと関連付けられたグローバル設定だけに、クエリの結果を絞り込みます。
このパラメーターがどのように機能するかの詳細については、リレーションを参照してください。
{# Fetch all global sets that are related to myCategory #}
{% set globalSets = craft.globalSets()
.relatedTo(myCategory)
.all() %}
# search
検索クエリにマッチするグローバル設定だけに、クエリの結果を絞り込みます。
このパラメーターがどのように機能するかの詳細については、検索を参照してください。
{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}
{# Fetch all global sets that match the search query #}
{% set globalSets = craft.globalSets()
.search(searchQuery)
.all() %}
# site
グローバル設定を照会するサイトを決定します。
デフォルトでは、現在のサイトが使用されます。
利用可能な値には、次のものが含まれます。
値 | 取得するグローバル設定 |
---|---|
'foo' | ハンドルが foo のサイトから。 |
['foo', 'bar'] | ハンドルが foo または bar のサイトから。 |
['not', 'foo', 'bar'] | ハンドルが foo または bar のサイトではない。 |
craft\models\Site (opens new window) オブジェクト | オブジェクトで表されるサイトから。 |
'*' | すべてのサイトから。 |
複数のサイトを指定した場合、複数のサイトに属するエレメントは複数回返されます。単一のエレメントだけを返したい場合、これと併せて unique を利用してください。
{# Fetch global sets from the Foo site #}
{% set globalSets = craft.globalSets()
.site('foo')
.all() %}
# siteId
サイトの ID ごとに、グローバル設定を照会するサイトを決定します。
デフォルトでは、現在のサイトが使用されます。
利用可能な値には、次のものが含まれます。
値 | 取得するグローバル設定 |
---|---|
1 | ID が 1 のサイトから。 |
[1, 2] | ID が 1 または 2 のサイトから。 |
['not', 1, 2] | ID が 1 または 2 のサイトではない。 |
'*' | すべてのサイトから。 |
{# Fetch global sets from the site with an ID of 1 #}
{% set globalSets = craft.globalSets()
.siteId(1)
.all() %}
# trashed
ソフトデリートされたグローバル設定だけに、クエリの結果を絞り込みます。
# uid
グローバル設定の UID に基づいて、クエリの結果を絞り込みます。
{# Fetch the global set by its UID #}
{% set globalSet = craft.globalSets()
.uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
.one() %}
# unique
クエリによってユニークな ID のエレメントだけが返されるかを決定します。
一度に複数のサイトからエレメントを照会する際、「重複する」結果を望まない場合に使用します。
{# Fetch unique global sets across all sites #}
{% set globalSets = craft.globalSets()
.site('*')
.unique()
.all() %}
# with
関連付けられたエレメントを eager-loaded した状態で、マッチしたグローバル設定をクエリが返します。
このパラメーターがどのように機能するかの詳細については、エレメントの Eager-Loading を参照してください。