5 Min.cornerstone

Dynamic Content API

This article is a guide instructing you how to get started building your own Dynamic Content integration.

When Dynamic Content Boots
How do I add my own Dynamic Content?
How do I render dynamic content?
Sample Class
Dynamic Options

Actions

When Dynamic Content Boots

`cs_dynamic_content_register`

The action fired when it's time to register fields

<?php

// Dynamic content is system ready
add_action( 'cs_dynamic_content_register', function() {
  // Our sample field prefixed by `cs_dynamic_content_`
  // for filters
  // EX: {{dc:example:test}}
  add_filter( 'cs_dynamic_content_example', function($result, $field, $args = []) {
    // Test field
    if ($field === "test") {
      // Useful for testing
      $result = json_encode($args);
    }

    // Return any value
    // although string is usually the expected
    return $result;
  }, 0, 3 );

});

Hooks

How do I add my own Dynamic Content?

`cs_dynamic_content_{$GROUP}`

Add a filter with this style and this will be called whenever your group is called first. EX in {{dc:post:id}}, cs_dynamic_content_post would be called first before cs_dynamic_content_post_id.

<?php
add_filter( 'cs_dynamic_content_example', function($result, $field, $args = []) {
  // Test field
  if ($field === "test") {
    // Useful for testing
    $result = json_encode($args);
  }

  // Return any value
  // although string is usually the expected
  return $result;
}, 0, 3 );

`cs_dynamic_content_{$GROUP}_{$FIELD}`

Add a filter with this style and this will be called whenever your dynamic content group and field is called. EX in {{dc:post:id}}, cs_dynamic_content_post_id would be called.

<?php
add_filter( 'cs_dynamic_content_example_test', function($result, $args = []) {
  // Useful for testing
  $result = json_encode($args);

  // Return any value
  // although string is usually the expected
  return $result;
}, 0, 2 );

Functions

How do I render dynamic content?

cs_dynamic_content(string $content, bool $asString = true)

This function acts as the main gateway for template expansion. This internally will call all the filters above to return the dynamic content.

<?php

$str = "{{dc:post:id}}";

$id = cs_dynamic_content($str); // EX: 1

@returns mixed based on second parameter

`cs_dynamic_content_string(string $content)`

Helper for cs_dynamic_content. Calls with $asString parameter as true

@returns string

`cornerstone_dynamic_content_register_group(array $params)`

Registers a group for the UI to use.

Array parameters

name => string
label => string

// UI for example earlier
cornerstone_dynamic_content_register_group([
  'name'  => 'example',
  'label' => __('Example'),
]);

`cornerstone_dynamic_content_register_field`

Inside a group will display fields registered to it. This also sets the controls used or no controls at all like Post Title.

Array Parameters

name => string,
group => string, // 'example'
type => string, // 'mixed', 'number', 'string',
label => string,
controls => array, // 'example-dynamic-field', 'post' ,
deep => boolean, // false

<?php
// Register controls for
// {{dc:example:test}}
cornerstone_dynamic_content_register_field([
  'name'  => 'test',
  'group' => 'example',
  'type'  => 'mixed',
  'label' => __('Example'),
  'controls' => [ 'example-dynamic-field', 'post' ],
  'deep' => true,
]);

Sample Class

This can serve as a template for creating your own group and touches on the basic features of Dynamic Content.

<?php

class DynamicContentExample {

  /**
   * This is the group in the dynamic content
   * {{dc:GROUP}}
   */
  const GROUP = "example";

  // Set filters
  static public function setup() {
    // Every {{dc:GROUP}} will filter to this function
    add_filter('cs_dynamic_content_' . self::GROUP, [self::class, 'supplyField'], 0, 4);

    // When cornerstone loads and wants to see what fields
    // it can provide in the UI
    add_action('cs_dynamic_content_setup', [self::class, 'register']);
  }

  // Register names and fields for use with
  // the UI
  static public function register() {
    // Register the Group name
    cornerstone_dynamic_content_register_group([
      'name'  => self::GROUP,
      'label' => "Example Group",
    ]);

    // Register a field called 'Field'
    cornerstone_dynamic_content_register_field([
      'name'  => 'field',
      'group' => self::GROUP,
      'label' => 'Field',
      'controls' => [
        [
          'key'     => 'key',
          'type'    => 'text',
          'label'   => 'Key',
        ],
      ],
    ]);
  }

  // Runs when the group has been called
  // through {{dc:GROUP:SOME_FIELD}}
  static public function supplyField($result, $field, $args = []) {
    // Which field
    switch ( $field ) {
      case 'field':
        // Filtering args is a keyed array when used
        $result = 'Field Called with ' . json_encode($args);
        break;
      default:
        break;
    }

    // Accepts all return types
    // although arrays won't display without
    // {{dc:GROUP:SOME_FIELD type='json'}} or another type return
    // or used via a looper
    return $result;
  }

}

// Load through how you see fit
add_action("init", [DynamicContentExample::class, "setup"]);

Then in the UI, it will look something like this.

Dynamic Options

Throughout Cornerstone there are various select boxes that dynamically grab their list of choices through the Dynamic Options API. The function to register a Dynamic Option is cs_dynamic_content_register_dynamic_option. The first argument is the key you'll reference later in either a custom element or a parameter via dynamic:YOUR_KEY. The second argument is your config array. Typically you only need filter setup which is a function that returns the results.

The following is an example from our WooCommerce product Dynamic Options.

The PHP to extend a new Dynamic Option

<?php
// Dynamic Choices for Product
// dynamic:product
cs_dynamic_content_register_dynamic_option("product", [
  'key' => "product",
  'type' => "select",
  'label' => __("WooCommerce Product", CS_LOCALIZE),
  'options' => [
    'choices' => "dynamic:product",
    'placeholder' => __("Enter Product ID", CS_LOCALIZE),
  ],

  // Product graber to select
  'filter' => function() {
    // Product choices setup
    $out = [
      [
        'value' => "",
        'label' => "Current Product",
      ],
    ];

    // Grab products for options
    $products = wc_get_products([
      'limit' => apply_filters( 'cs_locator_limit', 100 ),
      'orderby' => 'date',
      'order' => 'DESC',
      'return' => 'objects',
    ]);

    // Create select choices from products
    foreach ($products as $product) {
      $out[] = [
        'value' => $product->id,
        'label' => $product->get_title(),
      ];
    }

    return $out;
  }
]);

Then we would reference this by dynamic:product. Note that this is passed just as string where an array would be.

{
  "product" : {
    "label" : "Product",
    "type" : "select",
    "initial" : "",
    "options" : "dynamic:product"
  }
}

See something inaccurate? Let us know