ファンクション

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>
    <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 #}

インクリメントせずにシーケンスの現在の数字を表示するには、引数 nextfalse をセットします。

<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" #}