CKAN Templates Tutorial 7(v2.9): 自訂 snippet

http://docs.ckan.org/en/2.9/theming/templates.html#adding-your-own-template-snippets

延續 上個 CKAN templates snippet tutorial，plugin 只要在它的 templates/snippets 目錄下加檔案即可自訂 snippet。

以下撰寫一個 snippet 來顯示最受歡迎群組。

在 templates/snippets 目錄下新增 snippet

建立目錄 ckanext-example_theme/ckanext/example_theme/templates/snippets，並在其下加入一個檔案：example_theme_most_popular_groups.html ，內容如下：

{#

Renders a list of the site's most popular groups.

groups - the list of groups to render

#}

<h3>熱門群組(自訂snippet)</h3>

<ul>

  {% for group in groups %}

    <li>

      <a href="{{ h.url_for('group_read', action='read', id=group.name) }}">

        <h3>{{ group.display_name }}</h3>

      </a>

      {% if group.description %}

        <p>

          {{ h.markdown_extract(group.description, extract_length=80) }}

        </p>

      {% else %}

        <p>{{ _('This group has no description') }}</p>

      {% endif %}

      {% if group.package_count %}

        <strong>{{ ungettext('{num} Dataset', '{num} Datasets', group.package_count).format(num=group.package_count) }}</strong>

      {% else %}

        <span>{{ _('0 Datasets') }}</span>

      {% endif %}

    </li>

  {% endfor %}

</ul>

• snippet 檔最開頭需以 docstring 描述需傳入的參數。在這個例子裡是：groups。
• 呼叫 url_for() 為每個 group 名稱產生超連結至群組頁面
• 若群組有 description 呼叫 markdown_extract() 產生其內容，若無則呼叫 _() 把 'This group has no description' 訊息翻譯使用者瀏覽器對應的語言。
• 呼叫 ungettext() 顯示群組的資料集數(翻譯成對應的複數表示方式)。
• 群組屬性/group attributes 如: {{ group.name }}, {{ group.display_name }}, {{ group.description }}, {{ group.package_count }}，及其他 CKAN 物件(packages/datasets, organizations, users…) 屬性可透過 CKAN API 讀取，如 group_show()。

修改 templates/home/layout1.html

如下：

{% ckan_extends %}

{% block featured_group %}

  {{ h.recently_changed_packages_activity_stream(limit=4) }}

{% endblock %}

{% block featured_organization %}

  {% snippet 'snippets/example_theme_most_popular_groups.html',

             groups=h.example_theme_most_popular_groups()  %}

{% endblock %}

重啟 CKAN，再次瀏覽網頁可看到：

覆寫預設 snippet

若 plugin 加入的 snippet 名稱與 CKAN 預設 snippet 同名，則 plugin 的 snippet 會覆寫預設 snippet，無論是否有使用它。

若兩個 plugins 有同名 snippet 便會互相覆蓋。為避免這個問題，snippet 檔名最好以它的 extension 名稱開頭，如：snippets/example_theme_*.html。

snippet 「不能」存取 template 全域環境變數 c ( Variables and functions available to templates). 但可以存取：

• h
• app_globals
• request
• 其他父 template 透過 {% snippet %} 呼叫時傳入的參數