Knowledge Base

Integrating Heroic Knowledge Base with your theme

This section details advanced topics for developers wishing to integrate the standalone Heroic Knowledge Base with a third party theme.

These notes are provided for guidance only, due to the vast array of themes and configurations, we are unable to assist with theme integrations.

If you require further assistance with theme development and integration, consider using a specialist from a service such as Codeable.

Using the Templating system

For those wishing to modify the look and feel of the knowledge base the templating structure is there to help.

The templating structure works in a similar way to WordPress child themes and extends get_template_part. It will first look for a suitable template in hkb-templates folder in the theme (if one exists) in theme mode, else it will use the template  in the plugin’s hkb-templates folder, in compatability mode.

The two template modes –  Compatibility and Theme allow for greater control on functionality and styling meaning the plugin looks great out-of-the box for most themes, but can also be styled and configured as required. In compatibility mode (shown in red below), the plugin uses the theme’s standard page template and injects the knowledge base content into the_content section using  the templates in the plugin’s hkb-templates folder. For theme mode (shown in green below), the plugin will use the templates in the theme’s hkb-templates folder. In theme mode you can copy the whole hkb-templates folder to your theme (or child theme) in order to make changes which will not be overridden when the plugin is updated.

The plugin will always use the compatibility templates unless the theme template exists in the hkb-templates folder in the active theme. Reference theme template are provided in the plugins hkb-templates folder. To start using the theme template you just need to copy the hkb-templates folder from the plugin to your active (child) theme and the plugin will start using that. The theme templates can then be modified as required. Note that the main difference between the theme templates and compatibility templates are that the compatibility templates are designed to work by hijacking the_content call in your themes standard page. The theme template is designed to work as the main template, so should include calls to get_header and get_footer.

Note that in theme mode, non of the default knowledge base styles (CSS) will be loaded. In theme mode, the knowledge base should be styled using the theme’s stylesheet. Deleting the theme’s hkb-template folder will re-enable compatibility mode.

In addition to to the templating system the plugin provides a number of helper functions contained in /php/ht-knowledge-base-template-helpers.php, which can be used in the templates.

The diagram below illustrates the templating hierarchy, which works in a similar way to the WordPress template hierarchy.

Knowledge Base Templating system
The Knowledge Base templating hierarchy showing Compatibility Mode templates and Theme Mode templates

Getting started with Theme Templates

Detailed below are the basic steps required to integrate the knowledge base into your theme.

1. Copy the entire hkb-templates folder into your theme folder. If, for example, you were using the twentyfifteen theme, you would now have a folder under themes/twentyfifteen/hkb-templates containing the templates, the plugin will detect these files and use these instead.

2. You will need to style the knowledge base elements in your theme’s CSS files, as these are not loaded by the plugin in theme mode. These can be copied from ht-knowledge-base/css/hkb-style.css into your theme’s style.css file and modified to match your theme’s look and feel. So, in the case of a twentyfifteen child theme, copy the default styles from hkb-style.css to themes/twentyfifteen-child/style.css

Adding Category Icons

Your theme needs to declare support for category icons before they can be added and used by categories.

Add category icons to your knowledge base
Add category icons to your knowledge base

In your theme’s functions.php you need to add

add_theme_support( 'ht-kb-category-icons' );

You can then add icons when creating new Article Categories, or add to exisiting categories from Knowledge Base > Article Categories > Edit.

Next, add the code display the icons in your theme’s templates where you wish the category icon to appear. For example to display the icons in the Knowledge Base archive, add the following code in hkb-templates/hkb-content-archive.php

<div data-hkb-cat-icon="<?php echo hkb_has_category_custom_icon( $hkb_current_term_id ); ?>"> 
    <?php hkb_category_thumb_img( $hkb_current_term_id ); ?> 
</div>

Knowledge Base archive title

In some themes the title (H1 header tag) of the knowledge base may appear as ht_kb (the $post_type of the knowledge base custom post type). You can override this using a filter in your theme’s functions.php

function alter_ht_kb_title( $title, $id = null ) {
  if ( 'ht_kb' == $title ) {
    return 'Our Knowledge Base';
  }
  return $title;
}

add_filter( 'the_title', 'alter_ht_kb_title', 10, 2 );

For themes that don’t display a title, or if you want to display a title on Knowledge Base templates, you can use the the_title function.

This section refers to v2.7.0+

By default the knowledge base search functionality will return only relevant knowledge base articles (ht_kb). To search other post types, you will need to add the following filter to your theme’s functions.php

function search_post_types_kb_filter($post_types){
  //add WordPress posts to search results
 $post_types[] = 'post';
 return $post_types;
}

add_filter('hkb_search_post_types', 'search_post_types_kb_filter', 10, 1);

 

Was this article helpful?

Related Articles