Kalastatic Functions and Filters

Custom filters and functions?

While Twig provides almost every function, filter, and tag you might need to create a complicated static site, Kalastatic will include and define some additional filters and functions that are needed both to integrate with Drupal and also provide functions needed to easily create complex static sites.

drupal-twig-extensions

Installing Kalastatic includes the drupal-twig-extensions library, which provides twig.js with additional functions and filters that are provided when using Twig within drupal.

Some filters and functions are fully-implemented, while others merely return their input or a blank string so that when the templates are used outside of Drupal they do not throw errors when called.

Filters

clean_class
clean_id
drupal_escape
format_date
render
safe_join
t
trans
without

Functions

active_theme
active_theme_path
attach_library
create_attribute
file_url
link
path
render_var
url

The filters and functions provided by the drupal-twig-extensions library, with those that are partially implemented or merely stubs shown in italics.

attach_library()

Even though the attach_library function provided by the drupal-twig-extensions library is just a stub that does not do anything when called, Kalastatic provides its own attach_library function that actually works the same way as the Drupal feature.

After you define a library in your Kalastatic configuration, you can call the attach_library function in a Twig template, and the specified stylesheet and script files will be included on the rendered page.

{{ attach_library('details-tabs') }}

Very simple example of calling the function with the library name.

get_namespaces() and get_namespace_files()

While Twig contains many helpful files for inclding content from other files, such as embed and source, one limitation is that Twig doesn't know what files exist without explicity declaring them in the code.

In order for Kalastatic to create things like styleguide pages that are dynamically generated based on whatever files are present, Kalastatic provides two functions for Twig to know what files are present: get_namespaces() and get_namespace_files().

The get_namespaces() function simply returns the keys of the namespaces specified in the package.json file for your project, and the get_namespace_files() function returns the list of files within that namespace, with the namespace already prefixed, so you can immediately use that filename in twig embed and include tags.

For reference, here is the code that the Kalastatic demo styleguide uses to look for .sample.twig files to include in the styleguide:

{# Create the styleguide and component library by finding sample files in each of the namespaces. #}
<div class="styleguide">
{% for namespace in get_namespaces() %}
  {% for filename in get_namespace_files(namespace) %}
    {% if '.sample.twig' in filename %}
      {# Embed the sample, providing the namespace and filename root, so it can look for related files with different extensions. #}
      {% embed filename with {'namespace': namespace, 'file_root': filename|replace({'.sample.twig': ''}) } %}{% endembed %}
    {% endif %}
  {% endfor %}
{% endfor %}
</div>

Twig markup that gets the files within each namespace, and then looks through them for sample.twig files to embed on the styleguide page.

Another example is the template for the main menu of this site, which is automatically generated by looking through all of the files in the pages namespace:

{# Get the url for each section, which is the directory without the pages namespace and index.html.twig. #}
{% set sections = [] %}
{% for filename in get_namespace_files('pages') %}
{% if 'index.html.twig' in filename %}
  {% set sections = [filename|replace({'@pages': '', 'index.html.twig': ''})]|merge(sections) %}
{% endif %}
{% endfor %}

{# Iterate through all of the component files and output the pages as menu items. #}
{% set menu_items = [] %}
{% for section in sections|sort %}
  {% import '@pages' ~ section ~ 'index.html.twig' as page %}
  {% if page.menu_title is defined %}
    {% set menu_items = menu_items|merge([{ 'href': section, 'title': page.menu_title() }]) %}
  {% endif %}
{% endfor %}

Twig markup that gets the files within the page namespace, and then checks each for a menu_title() macro that provides a name for the menu link.

Note that since these functions are specific to Kalastatic, they should only be used when generating static pages, and cannot be used in any templates that are also going to be used by Drupal.