4 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?

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.

See something inaccurate? Let us know