ファンクション
Craft の Twig テンプレートで利用可能なファンクション (opens new window)は、以下の通りです。
ファンクション | 説明 |
---|---|
actionInput | 不可視項目の action を出力します。 |
actionUrl | コントローラーのアクション URL を生成します。 |
alias | 文字列をエイリアスとして解析します。 |
attr | HTML 属性を生成します。 |
attribute (opens new window) | 変数の動的属性にアクセスします。 |
beginBody | 「begin body」に登録されたスクリプトやスタイルを出力します。 |
block (opens new window) | ブロックの出力をプリントします。 |
ceil | 整数値に切り上げます。 |
className | 指定されたオブジェクトの完全修飾クラス名を返します。 |
clone | オブジェクトを複製します。 |
combine | 2つの配列を1つに結合します。 |
configure | 渡されたオブジェクトに属性をセットします。 |
constant (opens new window) | 指定された文字列の定数値を返します。 |
create | 新しいオブジェクトを作成します。 |
csrfInput | 不可視項目の CSRF トークンを返します。 |
cpUrl | コントロールパネルの URL を生成します。 |
cycle (opens new window) | 値の配列を循環します。 |
date (opens new window) | 日付を作成します。 |
dump (opens new window) | 変数に関する情報をダンプします。 |
endBody | 「end body」に登録されたスクリプトやスタイルを出力します。 |
expression | データベース式オブジェクトを作成します。 |
floor | 整数値に切り捨てます。 |
getenv | 環境変数の値を返します。 |
gql | スキーマ全体に対して、GraphQL クエリを実行します。 |
parseEnv | 文字列を環境変数、または、エイリアスとして解析します。 |
head | 「head」に登録されたスクリプトやスタイルを出力します。 |
hiddenInput | 不可視項目を出力します。 |
include (opens new window) | レンダリングされたテンプレートのコンテンツを返します。 |
input | HTML input タグを出力します。 |
max (opens new window) | 配列内の最大値を返します。 |
min (opens new window) | 配列内の最小値を返します。 |
parent (opens new window) | 親ブロックの出力を返します。 |
plugin | ハンドルに従ってプラグインのインスタンスを返します。 |
random (opens new window) | ランダムな値を返します。 |
range (opens new window) | 整数の等差数列を含むリストを返します。 |
raw | 出力時に HTML エンコードされないよう、指定された文字列をTwig\Markup オブジェクトで囲みます。 |
redirectInput | 不可視項目の redirect を出力します。 |
seq | シーケンスの次、または、現在の番号を出力します。 |
shuffle | 配列内のアイテムの順番をランダム化します。 |
siteUrl | フロントエンドの URL を生成します。 |
svg | SVG 文書を出力します。 |
source (opens new window) | レンダリングせずに、テンプレートのコンテンツを返します。 |
tag | HTML タグを出力します。 |
template_from_string (opens new window) | 文字列からテンプレートを読み込みます。 |
url | URL を生成します。 |
# actionInput
特定のコントローラーアクションのための POST リクエストをルーティングするために利用する不可視項目を出力するためのショートカット。これは、テンプレート内に直接 <input type="hidden" name="action" value="controller/action/route">
を書き込むのと実質的に同じです。
{{ actionInput('users/save-user') }}
オプションで、引数 options
を渡すことにより、タグに追加の属性をセットできます。
{{ actionInput('users/save-user', {
id: 'action-input'
}) }}
# actionUrl
相対形式と絶対形式、および、アクティブな actionTrigger 設定を自動的に考慮し、コントローラーアクションの URL を返します。
# 引数
actionUrl()
ファンクションは、次の引数を持っています。
path
– 結果となる URL がサイトで指すべきパス。それは、ベースサイト URL に追加されます。params
– URL に追加するクエリ文字列パラメータ。これは文字列(例:'foo=1&bar=2'
)または、ハッシュ(例:{foo:'1', bar:'2'}
)が利用可能です。scheme
– URL が使用するスキーム('http'
または'https'
)。デフォルト値は、現在のリクエストが SSL 経由で配信されているかどうかに依存します。そうでなければ、サイト URL のスキームが使用され、SSL 経由ならhttps
が使用されます。
# alias
その文字列がエイリアス (opens new window)ではじまるかをチェックする Craft::getAlias() (opens new window) に、文字列を渡します。(詳細については、コンフィギュレーションを参照してください。)
<img src="{{ alias('@assetBaseUrl/images/logo.png') }}">
# attr
yii\helpers\BaseHtml::renderTagAttributes() (opens new window) を利用して、指定されたハッシュに基づく HTML 属性のリストを生成します。
{% set myAttributes = {
class: ['one', 'two'],
disabled: true,
readonly: false,
data: {
baz: 'Escape this "',
qux: {
some: ['data', '"quoted"']
}
},
style: {
'background-color': 'red',
'font-size': '20px'
},
} %}
<div {{ attr(myAttributes) }}></div>
# beginBody
「begin body」に登録されたスクリプトやスタイルを出力します。<body>
タグの直後に配置する必要があります。
<body>
{{ beginBody() }}
<h1>{{ page.name }}</h1>
{{ page.body }}
</body>
# block
ブロックの出力をプリントします。
Twig コアの block
(opens new window) ファンクションと同様に機能します。
# ceil
整数値に切り上げます。
{{ ceil(42.1) }}
{# Output: 43 #}
# className
指定されたオブジェクトの完全修飾クラス名を返します。
{% set class = className(entry) %}
{# Result: 'craft\\elements\\Entry' #}
# clone
指定されたオブジェクトのクローンを作成します。
{% set query = craft.entries.section('news') %}
{% set articles = clone(query).type('articles') %}
# combine
2つの配列を1つに結合し、最初の配列をキー、2番目の配列を値に定義するために利用します。
{% set arr1 = ['a', 'b', 'c'] %}
{% set arr2 = ['foo', 'bar', 'baz'] %}
{% set arr3 = combine(arr1, arr2) %}
{# arr3 will now be `{a: 'foo', b: 'bar', c: 'baz'}` #}
# configure
Yii::configure()
(opens new window) から継承された Craft::configure()
メソッドの振る舞いを渡します。オブジェクトに属性を適用するという点で create
に似ていますが、新しいインスタンスを作成する代わりに、既存のオブジェクトを受け入れて変更します。
{# Modify an `EntryQuery` object set up by a relational field: #}
{% set myRelatedEntries = configure(entry.myEntriesField, {
section: 'blog'
}).all() %}
merge
(opens new window) フィルタの代わりに利用することもできます。
{% set myObject = { one: 'Original' } %}
{# With `merge`: #}
{% set myObject = myObject | merge({ one: 'Overridden', two: 'New' }) %}
{# With `configure`: #}
{% do configure(myObject, { one: 'Overridden', two: 'New' }) %}
あまり良いアイデアではありませんが、技術的にはモデルやエレメントの属性をセットするために利用することもできます。
{% do configure(entry, { title: 'New Title' }) %}
{% do craft.app.elements.saveElement(entry) %}
# constant
指定された文字列の定数値を返します。
Twig コアの constant
(opens new window) ファンクションと同様に機能します。
# create
与えられたクラス名やオブジェクト設定に基づいて新しいオブジェクトインスタンスを作成します。サポートされる引数の詳細については、Yii::createObject() (opens new window) を参照してください。
{# Pass in a class name #}
{% set cookie = create('yii\\web\\Cookie') %}
{# Or a full object configuration hash #}
{% set cookie = create({
class: 'yii\\web\\cookie',
name: 'foo',
value: 'bar'
}) %}
# cpUrl
相対形式と絶対形式、および、アクティブな cpTrigger 設定を自動的に考慮し、コントロールパネルの URL を返します。
<a href="{{ cpUrl('settings') }}">Visit control panel settings</a>
# 引数
cpUrl()
ファンクションは、次の引数を持っています。
path
– 結果となる URL がサイトで指すべきパス。それは、ベースサイト URL に追加されます。params
– URL に追加するクエリ文字列パラメータ。これは文字列(例:'foo=1&bar=2'
)または、ハッシュ(例:{foo:'1', bar:'2'}
)が利用可能です。scheme
– URL が使用するスキーム('http'
または'https'
)。デフォルト値は、現在のリクエストが SSL 経由で配信されているかどうかに依存します。そうでなければ、サイト URL のスキームが使用され、SSL 経由ならhttps
が使用されます。
# csrfInput
不可視項目の CSRF トークンを返します。CSRF 保護が有効になっているすべてのサイトでは、POST 経由で送信するそれぞれのフォームにこれを含めなければなりません。
{{ csrfInput() }}
オプションで、引数 options
を渡すことにより、タグに追加の属性をセットできます。
{{ csrfInput({
id: 'csrf-input'
}) }}
# endBody
「end body」に登録されたスクリプトやスタイルを出力します。</body>
タグの直前に配置する必要があります。
<body>
<h1>{{ page.name }}</h1>
{{ page.body }}
{{ endBody() }}
</body>
# expression
データベースクエリで使用するための新しい yii\db\Expression (opens new window) オブジェクトを作成して返します。
{% set entries = craft.entries()
.andWhere(expression('[[authorId]] = :authorId', {authorId: currentUser.id}))
.all() %}
# floor
整数値に切り捨てます。
{{ floor(42.9) }}
{# Output: 42 #}
# getenv
環境変数の値を返します。
{{ getenv('MAPS_API_KEY') }}
# gql
スキーマ全体に対して、GraphQL クエリを実行します。
{% set result = gql('{
entries (section: "news", limit: 2, orderBy: "dateCreated DESC") {
postDate @formatDateTime (format: "Y-m-d")
title
url
... on news_article_Entry {
shortDescription
featuredImage {
url @transform (width: 300, immediately: true)
altText
}
}
}
}') %}
{% for entry in result.data %}
<h3><a href="{{ entry.url }}">{{ entry.title }}</a></h3>
<p class="timestamp">{{ entry.postDate }}</p>
{% set image = entry.featuredImage[0] %}
<img class="thumb" src="{{ image.url }}" alt="{{ image.altText }}">
{{ entry.shortDescription|markdown }}
<p><a href="{{ entry.url }}">Continue reading…</a></p>
{% endfor %}
# parseEnv
文字列が環境変数($VARIABLE_NAME
)、および / または、エイリアス(@aliasName
)を参照しているかどうかを確認し、参照されている値を返します。
# head
「head」に登録されたスクリプトやスタイルを出力します。</head>
タグの直前に配置する必要があります。
<head>
<title>{{ siteName }}</title>
{{ head() }}
</head>
# hiddenInput
HTML input タグを出力します。
{{ hiddenInput('entryId', entry.id) }}
{# Output: <input type="hidden" name="entryId" value="100"> #}
オプションで、引数 options
を渡すことにより、タグに追加の属性をセットできます。
{{ hiddenInput('entryId', entry.id, {
id: 'entry-id-input'
}) }}
# include
レンダリングされたテンプレートのコンテンツを返します。
Twig コアの include
(opens new window) ファンクションと同様に機能します。
# input
HTML input タグを出力します。
{{ input('email', 'email-input', '') }}
{# Output: <input type="email" name="email-input" value=""> #}
オプションで、引数 options
を渡すことにより、タグに追加の属性をセットできます。
{{ input('email', 'email-input', '', {
id: 'custom-input'
}) }}
# max
配列内の最大値を返します。
Twig コアの max
(opens new window) ファンクションと同様に機能します。
# min
配列内の最小値を返します。
Twig コアの min
(opens new window) ファンクションと同様に機能します。
# plugin
ハンドルに従ってプラグインインスタンスを返します。そのハンドルでインストールされ有効化されているプラグインがない場合、null
を返します。
{{ plugin('commerce').version }}
# raw
出力時に HTML エンコードされないよう、指定された文字列をTwig\Markup
オブジェクトで囲みます。
{% set html = raw('<p>Don’t encode me.</p>') %}
{{ html }}
これは、変数が他のテンプレート/マクロに渡された場合でも Twig が HTML をエスケープしないことを覚えている点を除き、raw (opens new window) フィルタと同様に機能します。一方、|raw
フィルタは出力タグ内で直接利用した場合にのみ効果があります。
# redirectInput
<input type="hidden" name="redirect" value="{{ url|hash }}">
を入力するためのショートカットです。
{{ redirectInput(url) }}
オプションで、引数 options
を渡すことにより、タグに追加の属性をセットできます。
{{ redirectInput(url, {
id: 'redirect-input'
}) }}
# seq
name
で定義されたシーケンスの次または現在の番号を出力します。
<p>This entry has been read {{ seq('hits:' ~ entry.id) }} times.</p>
ファンクションが呼び出されるたびに、与えられたシーケンスは自動的にインクリメントされます。
オプションで特定の長さにゼロ詰めした数値にできます。
{{ now|date('Y') ~ '-' ~ seq('orderNumber:' ~ now|date('Y'), 5) }}
{# outputs: 2018-00001 #}
インクリメントせずにシーケンスの現在の数字を表示するには、引数 next
に false
をセットします。
<h5><a href="{{ entry.url }}">{{ entry.title }}</a></h5>
<p>{{ seq('hits:' ~ entry.id, next=false) }} views</p>
# shuffle
配列内のエレメントの順序をランダム化します。
{% set promos = craft.entries.section('promos').all() %}
{% set shuffledPromos = shuffle(promos) %}
{% for promo in shuffledPromos %}
<div class="promo {{ promo.slug }}">
<h3>{{ promo.title }}</h3>
<p>{{ promo.description }}</p>
<a class="cta" href="{{ promo.ctaUrl }}">{{ promo.ctaLabel }}</a>
</div>
{% endfor %}
# siteUrl
サイト上のページへの URL を作成するため だけ という点を除けば、url() と似ています。
<a href="{{ siteUrl('company/contact') }}">Contact Us</a>
# 引数
siteUrl()
ファンクションは、次の引数を持っています。
path
– 結果となる URL がサイトで指すべきパス。それは、ベースサイト URL に追加されます。params
– URL に追加するクエリ文字列パラメータ。これは文字列(例:'foo=1&bar=2'
)または、ハッシュ(例:{foo:'1', bar:'2'}
)が利用可能です。scheme
– URL が使用するスキーム('http'
または'https'
)。デフォルト値は、現在のリクエストが SSL 経由で配信されているかどうかに依存します。そうでなければ、サイト URL のスキームが使用され、SSL 経由ならhttps
が使用されます。siteId
– URL が指すべきサイト ID。デフォルトでは、現在のサイトが使用されます。
# svg
SVG 文書を出力します。
次のものを渡すことができます。
SVG ファイルのパス。
{{ svg('@webroot/icons/lemon.svg') }}
アセットフィールドから引っ張られたような、craft\elements\Asset (opens new window) オブジェクト。
{% set image = entry.myAssetsField.one() %} {% if image and image.extension == 'svg' %} {{ svg(image) }} {% endif %}
生の SVG マークアップ。
{% set image = include('_includes/icons/lemon.svg') %} {{ svg(image) }}
ファンクションにアセットまたは生のマークアップを渡した場合、デフォルトでは SVG は svg-sanitizer (opens new window) を利用して潜在的に悪意のあるスクリプトをサニタイズし、ドキュメント内の ID や class 名が DOM の他の ID や class 名と衝突しないよう名前空間を付加します。引数 sanitize
、および、namespace
を利用して、これらの動作を無効にできます。
{{ svg(image, sanitize=false, namespace=false) }}
attr フィルタを利用して、ルートの <svg>
ノードに追加する独自の class 名を指定することもできます。
{{ svg('@webroot/icons/lemon.svg')|attr({ class: 'lemon-icon' }) }}
# source
レンダリングせずに、テンプレートのコンテンツを返します。
Twig コアの source
(opens new window) ファンクションと同様に機能します。
# tag
完全な HTML タグをレンダリングします。
{{ tag('div', {
class: 'foo'
}) }}
{# Output: <div class="foo"></div> #}
属性引数に text
が含まれる場合、その値は HTML エンコードされ、タグのテキストコンテンツとしてセットされます。
{{ tag('div', {
text: 'Hello'
}) }}
{# Output: <div>Hello</div> #}
属性引数に html
が含まれている(かつ、text
が含まれていない)場合、その値はタグのインナー HTML としてセットされます(HTML エンコードされません)。
{{ tag('div', {
html: 'Hello<br>world'
}) }}
{# Output: <div>Hello<br>world</div> #}
第二引数に渡される他のすべてのキーは、yii\helpers\BaseHtml::renderTagAttributes() (opens new window) を利用してタグの属性としてセットされます。
属性が true
にセットされている場合、値なしで追加されます。
{{ tag('input', {
id: "foo",
name: "bar",
required: true
}) }}
{# Output: <input id="foo" name="bar" required> #}
null
または false
をセットされた属性は、省略されます。
# url
URL を返します。
<a href="{{ url('company/contact') }}">Contact Us</a>
# 引数
url()
ファンクションは、次の引数を持っています。
path
– 結果となる URL がサイトで指すべきパス。それは、ベースサイト URL に追加されます。params
– URL に追加するクエリ文字列パラメータ。これは文字列(例:'foo=1&bar=2'
)または、ハッシュ(例:{foo:'1', bar:'2'}
)が利用可能です。scheme
– URL が使用するスキーム('http'
または'https'
)。デフォルト値は、現在のリクエストが SSL 経由で配信されているかどうかに依存します。そうでなければ、サイト URL のスキームが使用され、SSL 経由ならhttps
が使用されます。mustShowScriptName
– ここにtrue
がセットされている場合、「index.php」を含めた URL が返され、コンフィグ設定 omitScriptNameInUrls は無視されます。(ブラウザのアドレスバーに表示されない URL と .htaccess ファイルのリダイレクトとの衝突を避けたいような、Ajax 経由の POST リクエストで使用される URL の場合に有用です。)
クエリ文字列パラメータを追加、および / または、絶対 URL にスキームを適用するために、url()
ファンクションを使用することができます。
{{ url('http://my-project.com', 'foo=1', 'https') }}
{# Outputs: "https://my-project.com?foo=1" #}