Hooks and filters in the Dirigible theme

Hooks are spots in the theme where your own code can run. There are two kinds:

• Actions let you add something at that spot, such as a banner under the header or a note after every blog post.
• Filters hand your code a value, such as a link or a block of settings, so you can change it before the theme uses it. A filter must always return the value.

This page lists the WordPress hooks and filters Dirigible Studio provides for customization. Standard WordPress and WooCommerce hooks work too but aren't covered here.

Before you start

• Where the code goes: your child theme's functions.php, or a code snippets plugin such as Code Snippets. Never edit the parent Dirigible Studio theme. Theme updates replace its files and your changes are lost.
• Test on a staging copy first. A typo in PHP can stop the site loading. Make sure you can reach your files through your host or SFTP so you can undo a bad change.
• Escape what you print. Wrap text in esc_html() and links in esc_url(), as the examples below do.

Each hook below lists its arguments in the order your function receives them.

Add content to pages and posts

All of these are actions. None pass arguments except ds_post_meta.

Add a newsletter prompt after every blog post. Blog comments are added at the default priority (10), so priority 5 puts your prompt above them:

add_action('dirigible_after_post_content', function () {
  if (!is_singular('post')) {
    return;
  }
  echo '<p class="mt-8"><strong>Enjoyed this post?</strong> <a href="' . esc_url('/newsletter/') . '">Join our newsletter</a>.</p>';
}, 5);

Add a reading-time line to post details:

add_action('ds_post_meta', function ($context) {
  if ($context !== 'postmeta') {
    return;
  }
  $words = str_word_count(wp_strip_all_tags(get_the_content()));
  $minutes = max(1, (int) round($words / 200));
  echo '<p class="mb-0">' . esc_html($minutes . ' min read') . '</p>';
});

Header, menu, and pop-up

All actions, no arguments.

Add a phone link next to the menu, using the Phone number from Footer & Contact → Contact Information. ds_get_setting() reads any Dirigible Customizer value:

add_action('ds_nav_links', function () {
  $phone = ds_get_setting('ds_footer_phone');
  if (!$phone) {
    return;
  }
  $tel = preg_replace('/[^0-9+]/', '', $phone);
  echo '<a href="' . esc_url('tel:' . $tel) . '">' . esc_html($phone) . '</a>';
});

Because ds_nav_links also runs in the mobile menu, the link shows in both places.

Footer

add_action('ds-footer', function () {
  echo '<p class="py-4 text-center">' . esc_html('Proudly serving Dane County since 1998.') . '</p>';
}, 5);

Blog post links (filters)

$prev_post and $next_post are the neighboring posts. The older and newer filters also run for the smaller links in the post sidebar layout. Return an empty string to hide a link.

add_filter('ds_prev_post_link', function ($html) {
  return str_replace('Older Post', 'Previous article', $html);
});

add_filter('ds_next_post_link', function ($html) {
  return str_replace('Newer Post', 'Next article', $html);
});

Structured data (filters)

Dirigible adds structured data (JSON-LD) that tells search engines about your business and content. See Structured Data for Search Engines.

Dirigible saves the results to keep pages fast. Changes from ds_jsonld_global_schema appear after you next click Publish in the Customizer. Changes to a single item appear after you next update that post. ds_jsonld_schemas and ds_jsonld_output run on every page load.

Mark the business as a more specific type:

add_filter('ds_jsonld_global_schema', function ($schema) {
  $schema['@type'] = 'Dentist';
  $schema['priceRange'] = '$$';
  return $schema;
});

SVG uploads and inline SVG (filters)

The three inline filters only matter when Inline SVG is on in Appearance → Customize → Settings → General.

Let editors upload SVGs:

add_filter('ds_svg_upload_capability', function () {
  return 'edit_pages';
});

Only widen the allowed tags and attributes if you know the SVGs come from a trusted source. The cleanup is there to block harmful code hidden in image files.

Media uploads (filters)

Dirigible stops anyone uploading an exact copy of a file that's already in the Media Library. Both filters receive $value (default false) and $file, the upload being checked. Return true to let the upload through.

Let administrators upload duplicates:

add_filter('dirigible_allow_duplicate_upload', function ($allow) {
  return current_user_can('manage_options') ? true : $allow;
});

Dashboard and admin (filters)

Useful for agencies that want to brand the WordPress Dashboard for a client.

add_filter('ds_dashboard_welcome_description', function () {
  return 'Need help? Email support@example.com and we will get back to you within a day.';
});

Add a Dashboard panel. The callback prints the panel and receives the panel's settings:

add_filter('ds_dashboard_welcome_sections', function ($sections) {
  $sections[] = [
    'id' => 'ds-welcome-agency',
    'label' => 'Support',
    'callback' => function ($section) {
      echo '<div id="' . esc_attr($section['id']) . '" class="ds-docs-group ds-docs-panel">';
      echo '<h2>Support</h2><p>Call us at (555) 555-0123.</p>';
      echo '</div>';
    },
  ];
  return $sections;
});

For plugin developers (filters)

These are how Dirigible's own plugins plug into the theme.

Each toast in $toasts is an array with id, token, type (working, success, error, or info), and message. Optional keys are detail, dismissible, dismiss_on_navigate, and poll_interval (milliseconds, for working toasts that should keep checking back). Toasts missing an id, token, or message are dropped.

add_filter('ds_admin_toasts', function ($toasts, $context) {
  if (get_transient('my_plugin_import_running')) {
    $toasts[] = [
      'id' => 'my-plugin/import',
      'token' => 'import-1',
      'type' => 'working',
      'message' => 'Importing products…',
      'poll_interval' => 3000,
    ];
  }
  return $toasts;
}, 10, 2);

Each sample data source is an array with id, title, an optional description, and wxr: the full path to a WordPress export file. Add requires with plugin file names (such as 'my-plugin/my-plugin.php') to show the entry only when those plugins are active.

Tools & Maintenance limits (filters)

See Using Tools & Maintenance for what each tool does.

Related guides

• Use a child theme
• Use Code Snippets with Dirigible
• Using magic classes
• Adding custom CSS with Additional CSS
• Styling one section with Section block CSS