4 Min.pro, cornerstone

Twig API

This is a technical summary of what is offered by the Twig API.

Overview
Custom Filters
Custom Functions
Custom Extensions
Change the Cache Directory
Twig Integration is Enabled
Disabling the Twig Integration
Changing the Default Autoescaper
Programmatic API

Overview

The API is heavily based on Timber, and extending Twig via our system can be a breeze. Let's take a look at how to get started.

Custom Filters

Use cs_twig_filters to add a new filter. Each key of this array is the filter name. Set your key value as an array using callable as the function for the filter.

// Add a filter to tap into all filters
add_filter('cs_twig_filters', function($results) {
  // Add a filter to be used as my_filter
  $results['my_filter'] = [
    'callable' => function($value, $arg1) {
      // Using an argument passed in a filter
      if (!empty($arg1)) {
        return $value . ' arg1 was added';
      }

      return $value . ' arg1 was not added or is empty';
    }
  ];

  return $results;
});

Then in the App we would utilize this through the following.

{{ post.title | my_filter(true) }}

Custom Functions

Use cs_twig_functions to add a new function. Each key of this array is the function name. Set your key value as an array using callable as the function for the filter.

// Add a filter to tap into all filters
add_filter('cs_twig_functions', function($results) {
  // Add a function to be used as phpinfo
  $results['phpinfo'] = [
    'callable' => function($value, $arg1) {
      phpinfo();

      // If your function would return a value this is where you would place it
      return '';
    }
  ];

  return $results;
});

Then in the App.

{{ phpinfo() }}

Custom Extensions

Use the action cs_twig_boot to tap into the Twig Environment. You can do much more then place a new extension here as well. The following is a sample from the Debug extension.

<?php

use Twig\Extension\DebugExtension;

add_action('cs_twig_boot', function($twig) {
  $twig->addExtension(new DebugExtension());
});

Change the Cache Directory

Use the filter cs_twig_cache_directory to change the cache directory. The default is get_temp_dir() . 'cornerstone/twig/'.

add_filter('cs_twig_cache_directory', function() {
  return '/home/user/cache_directory/twig/';
});

Twig Integration is Enabled

// Must boot after theme options
add_action('after_setup_theme', function() {
  // Twig not enabled
  if (!cs_stack_get_value('cs_twig_enabled')) {
    return;
  }

  // Your extension
  // ...
}, 999);

Disabling the Twig Integration

Use the filter cs_twig_renderer_enabled to remove the Twig integration entirely. It defaults to true. Returning false stops Cornerstone from loading the Twig renderer at all, so the Twig section of the Theme Options, the Twig Dynamic Content options, and Twig rendering are all removed. This applies even if Twig was turned on in the Theme Options.

add_filter('cs_twig_renderer_enabled', '__return_false');

This filter is checked while Cornerstone boots, before init, so you must add it before Cornerstone loads.

Pro / X: Add it to your child theme's functions.php. A child theme loads before its parent theme, so the filter is registered in time.
Cornerstone plugin: Add it to a must-use plugin (for example wp-content/mu-plugins/disable-cs-twig.php). A theme's functions.php loads too late to affect the Cornerstone plugin.

If you only want to turn Twig off and keep the option to turn it back on, use the Twig toggle in the Theme Options instead. That setting can be checked with cs_stack_get_value('cs_twig_enabled'), as shown above.

Changing the Default Autoescaper

When the autoescaper is enabled, it defaults to html as the escaper. This can be changed through the following filter.

add_filter('cs_twig_autoescape_strategy', function() {
  return 'esc_js';
});

Programmatic API

<?php

/**
 * Templates grabber from both theme options and directory templates
 *
 * @return array
 */
function cs_twig_templates() { }

/**
 * Get directories to search for templates in twig
 * Uses filter 'cs_twig_directory_templates'
 *
 * @return array
 */
function cs_twig_directory_templates() { }

/**
 * Twig cache directory
 * uses filter 'cs_twig_cache_directory'
 * Defaults to WordPress temp directory + cornerstone/twig
 *
 * @return string
 */
function cs_twig_cache_directory() { }

/**
 * Render a twig string
 *
 * @param string
 *
 * @return string
 */
function cs_twig_render($str) { }

/**
 * Get twig instance environment
 *
 * @return Twig\Environment
 */
function cs_twig_environment() { }

See something inaccurate? Let us know