GUIDE
Clipkit Liquidテンプレート言語リファレンス（タグ・フィルター）
Clipkitで構築するWEBサイトのフロントエンドをコーディングするためのLiquidテンプレート言語のリファレンスです。Clipkit独自のタグとフィルターを記載しています。
INDEX
- Liquidタグ（ブロックタグ）
- paginate
- selectfor
- Liquidタグ（単体タグ）
- collection
- file
- form
- render
- widget
- Liquidフィルター（データベース操作）
- search
- where
- find_by
- limit
- order
- or
- offset
- next_to / prev_to
- size
- to_array / to_a
- type
- Liquidフィルター（カスタム属性操作）
- attribute
- search_by_attribute
- order_by_attribute
- Liquidフィルター（文字列操作）
- auto_link
- replace_regexp
- match
- render_liquid
- render_markdown
- unescape
- wpautop
- Liquidフィルター（配列・コレクション操作）
- hash_find
- headings_per_page
- Liquidフィルター（データ変換）
- to_json
- json_parse / to_hash
- format_number
- Liquidフィルター（URL・パス操作）
- find_path
- prepend_path
- resize
Clipkitはテンプレート言語として Liquid を採用しています。
本リファレンスでは、Clipkit独自の拡張機能のみを掲載しており、Liquidの基本仕様については Liquid公式リファレンス をご参照ください。
Liquidタグ（ブロックタグ）
paginate
配列またはRelationオブジェクトに対してページネーション機能を提供する
<!-- カテゴリーの記事を1ページ辺り20件ずつ表示する -->
{% paginate category.articles per 20 %}
{% for article in paginate.collection %}
{% render "article_template" %} <!-- 出力処理 -->
{% endfor %}
{% endpaginate %}
selectfor
記事コレクションから特定の属性を選択してループ処理を高速に実行する
<!-- 記事タイトル、カテゴリ名、拡張項目attr_nameを記事一覧にを表示する -->
<div class="article-list">
{% selectfor (title, category, url, attributes) in site.articles %}
<div class="article-item">
<a href="{{ url }}" class="article-link">
<span class="title">{{ title }}</span>
<span class="category">（{{ category.name }}）</span>
<span class="attr">{{ attributes.attr_name }}</span>
</a>
</div>
{% endselectfor %}
</div>
Liquidタグ（単体タグ）
collection
コレクションに登録された記事・画像・HTMLなどをを読み込む
{% collection 'top_page_slider' %}
file
リソースファイルのURLを取得する
<link rel="stylesheet" href="{% file '/theme/original/css/theme.css' %}">
form
フォームを描画する
{% form 'contact_form' %}
render
パーシャルテンプレートを描画する
<div class="article-list">
{% selectfor (title, category, url) in site.articles | limit: 3 %}
{% render "articles" %}
{% endselectfor %}
</div>
widget
ウィジェットを描画する
{% widget 'aside_ad', id: '999' %}
Liquidフィルター（データベース操作）
search
指定したクエリ（検索語）を使って、該当する要素のみを抽出するフィルター
{% assign articles = site.articles | search: request.params["q"] %}
where
SQLを使用して条件抽出を行う
{% assign articles = site.articles | where: 'kind = ?', kind %}
find_by
指定条件でユニークな列名をキーとして、単一のレコードを取得する
{% assign article = site.articles | find_by: 'key', 'xxxxx' %}
limit
取得件数を指定する
<div class="article-list">
{% selectfor (title, category, url) in site.articles | limit: 3 %}
{% render "articles" %}
{% endselectfor %}
</div>
order
取得するRelationに対して並び順を指定する
{% assign articles = site.articles | order: 'published_at ASC' %}
or
複数の配列（Liquidオブジェクトの配列）を OR 条件で結合し、1つの配列として扱える フィルター
{% assign articles_m = site.articles | search: 'category:"male"' | to_array %}
{% assign articles_f = site.articles | search: 'category:"female"' | to_array %}
{% assign articles = articles_m | or: articles_f %}
offset
レコードの取得開始位置を先頭からn件目に指定する
{% assign articles = site.articles | offset: 5 %}
next_to / prev_to
現在の記事から見て次の記事/前の記事の取得
{% assign next_article = article.category.articles | next_to: article %}
{% assign prev_article = article.category.articles | prev_to: article %}
size
レコード数を取得する
{% articles_size = articles | size %}
{% if articles_size > 0 %}
<!-- 記事が存在する時の処理 -->
{% else %}
<!-- 記事が存在しない時の処理 -->
{% endif %}
to_array / to_a
Relationを配列に変換する（最大200件で切り詰められます）
{% assign pref_array = site.articles | search: 'category:"prefecture"' | to_array %}
type
Liquid変数（配列・オブジェクトなど）の Rubyクラス名（型）を文字列で取得できるフィルター。
{{ site.articles | type }}
{{ article.title | type }}
Liquidフィルター（カスタム属性操作）
attribute
記事の拡張項目の値を取得します
{{ article.attributes.拡張項目Name(英数字) }}
<img src="{{ article.attributes.拡張項目Name(英数字)_medium }}">
search_by_attribute
拡張項目（attribute）に基づいて、記事を検索するためのフィルター
{% assign articles = site.articles | search_by_attribute: 'area', 'kanto', '= ?' %}
order_by_attribute
記事の拡張項目の値を基準にして並び替えを行うフィルター
{% assign sorted = site.articles | order_by_attribute: 'score', 'DESC' %}
Liquidフィルター（文字列操作）
auto_link
テキスト内に含まれる URLを自動的にリンク化するフィルター
{% assign sample_txt = "公式サイトはhttps://clipkit.coです。" %}
{{ sample_txt | auto_link }}
replace_regexp
正規表現を使って文字列を置換できる強力なフィルター
{% assign tag = "#ニュース" %}
{{ tag | replace_regexp: '^#', '' }}
match
引数に指定した 正規表現にマッチするかを調べ、マッチした部分文字列を返す フィルター
{% assign email = "user@example.com" %}
{% if email | match: '^[\\w._%+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$' %}
有効なメール形式です
{% else %}
メール形式が不正です
{% endif %}
render_liquid
Liquidの構文を含んだ文字列を 「その場で評価してHTMLに変換する」 フィルター
{% assign heading_template = "{{ category.name }}の記事まとめ" %}
<h2>{{ heading_template | render_liquid }}</h2>
render_markdown
Markdown形式の文字列をHTMLに変換するフィルター
{% assign markdown_text = "**お知らせ**\n\n- 新商品登場\n- セール開催中！" %}
{{ markdown_text | render_markdown }}
unescape
HTMLエンティティ（<, >, &, " など）でエスケープされた文字列を、元の記号に戻すフィルター
{% assign text = "Tom &amp; Jerry" %}
{{ text | unescape }}
wpautop
改行や段落の区切りに応じて、自動的に <p> や <br> タグを付加して、プレーンなテキストを見栄えよく整えるフィルター
{% assign body = "これは1段落目です。\n\nこれは2段落目です。" %}
{{ body | wpautop }}
Liquidフィルター（配列・コレクション操作）
hash_find
配列内のハッシュ（オブジェクト）の中から、指定した「キー」と「値」が一致する最初の1件を返す
{% assign collection = graphql_response.data.mainPage.collections | hash_find: 'namespace', 'ranking' %}
<h2>{{ collection.title }}</h2>
headings_per_page
記事の構造化済み本文（article.items）から見出しを抽出し、指定数ごとに分割された配列として返すフィルター
{% assign headings = article.items | headings_per_page: 15 %}
{% for heading in headings %}
<li><a href="#{{ heading.id }}">{{ heading.text }}</a></li>
{% endfor %}
Liquidフィルター（データ変換）
to_json
オブジェクトをJSON文字列に変換するフィルター
<script>
const articleData = {{ article | to_json }};
</script>
json_parse / to_hash
Liquidオブジェクトや配列・ハッシュをJSON文字列に変換する
{{ json_string | json_parse }}
{{ json_string | to_hash }}
format_number
数値を3桁ごとにカンマで区切ってフォーマットするフィルター
{% assign price = "123456789" %}
¥ {{ price | format_number }}
Liquidフィルター（URL・パス操作）
find_path
配列の中から指定したパス文字列と一致する要素（タグ・カテゴリなど）を探して返すフィルター
{% assign tag = site.all_tags | find_path: "/tags/tech/html" %}
<h2>{{ tag.name }}</h2>
{% assign category = site.all_categories | find_path: "/travel/japan/kyoto" %}
<h1>{{ category.name }}</h1>
prepend_path
2つのパスを結合し、先頭にパスを追加した形に整形するフィルター
{{ tag.path | prepend_path: category.path }}
resize
画像のURLに対して動的なリサイズパラメータを付与し、変換された画像を取得するフィルター
{{ item.image_original_url | resize: "width:320" }}
アスペクト比を維持したまま横幅320pxにリサイズされる
{{ item.image_original_url | resize: "width:320,height:320" }}
長辺は切り取られ、高さ・横幅320pxの正方形にリサイズされる
{{ item.image_original_url | resize: "size:320" }}
アスペクト比を維持したまま長辺が320pxにリサイズされる
123 件
