Shortcode Customizations

Use PHP and JavaScript hooks to customize shortcode content, functionality, and styles to suite your needs.

Table of Contents

1. Enqueueing Custom Assets
2. JavaScript Hooks
   1. Finding available hooks

Enqueueing Custom Assets

In the 'wp_footer' action hook of WordPress, Completionist enqueues the scripts and styles for each of its shortcodes that have rendered for the current page load. As Completionist processes each detected shortcode tag, the 'ptc_completionist_shortcode_enqueue_assets' action hook in PHP is executed for third-party customizations.

Note that this action hook only runs for shortcodes that have been executed. This ensures assets are enqueued only once per page load and only when they are needed.

This sample code enqueues a custom JavaScript file and CSS stylesheet whenever the [ptc_asana_project] shortcode has been rendered at least once for the current page load:

add_action(
  'ptc_completionist_shortcode_enqueue_assets',
  'custom_completionist_shortcode_enqueue_assets',
  10,
  1
);

function custom_completionist_shortcode_enqueue_assets( string $shortcode_tag ) {
  if ( 'ptc_asana_project' === $shortcode_tag ) {
    
    wp_enqueue_script(
      'custom-asana-project-script',
      plugins_url( '/assets/js/script.js' , __FILE__ ),
      array( 'ptc-completionist-shortcode-asana-project' ),
      '1.0.0',
      true
    );
    
    wp_enqueue_style(
      'custom-asana-project-styles',
      plugins_url( '/assets/css/styles.css' , __FILE__ ),
      array( 'ptc-completionist-shortcode-asana-project' ),
      '1.0.0'
    );
  }
}

See WordPress’s documentation for usage of wp_enqueue_script() and wp_enqueue_style().

JavaScript Hooks

Completionist uses WordPress’s @wordpress/hooks npm package to implement custom action and filter hooks in JavaScript.

Using the method described above, enqueue a custom JavaScript file that registers your modifications.

This example customizes the project section “Section” label text in Completionist Pro:

window.Completionist.hooks.addFilter(
  'task_modal_project_section_label',
  'my-custom-plugin',
  ( label, task ) => {

    // Project section names acting as statuses.
    const statuses = [
      'To Do',
      'In Progress',
      'Needs Review',
      'Done',
    ];
    
    if ( statuses.includes( task.project_section_name ) ) {
      // Label the project section as a "Status".
      label = 'Status';
    }

    return label;
  }
);

Finding available hooks

The best way to find action and filter events that you can hook customizations into is by examining the following JavaScript global variables in your browser console:

// Contains the action hooks that have fired for the given client session.
window.console.log( window.Completionist.hooks.actions );
// Contains the filter hooks that have fired for the given client session.
window.console.log( window.Completionist.hooks.filters );

Note that these global variables only contain hooks that have executed at least once before you log their contents. This means you should interact with Completionist’s elements until a behavior happens or a view is displayed that you want to hook into.

If you need me to add more action or filter hooks, please let me know!