Digital inclusion toolkit – An open source WordPress child theme

Before you start

Before using this WordPress theme for your own project you should consider:

1. The theme is provided ‘as is’ under the open source MIT Licence without support or warranty of any kind.
2. You will need access to a web hosting environment that supports WordPress.
3. The Toolkit chapters are edited as WordPress posts and use Advanced Custom Fields Pro (ACF Pro) – a WordPress plugin that requires a yearly subscription. Without ACF Pro the chapter edit page and automatic contents menu will not function. However there are some steps that can be taken to bypass the functionality offered by ACF pro, see the Replace ACF Pro functionality section.

Parent and child theme

The Digital Inclusion Toolkit uses the free Understrap parent theme. Understrap uses Bootstrap 4 as the HTML and CSS framework.

The custom child theme is called ‘Digital Inclusion Toolkit Child’. Our child theme includes various customisations and improvements building on the out of the box WordPress functionality:

• Improved search to show matches relating to author and category names along with the chapter content
• Comments presented in a ‘Discussion’ tab
• Chapter page headings and sections are added as reorderable fields using the Advanced Custom Fields Pro repeater
• Assign sections of chapter content as ‘Contributed’ and set the contributor author name and contribution date
• Chapter page sticky contents menu, populated by the headings in your chapter
• Automatic feed for categories on the Toolkit homepage
• Custom settings pages for miscellaneous language (wording) and content blocks that appear on multiple pages

Installing the themes

To install both parent and child themes all you need to do is download the theme Zip file using the link at the top of this page. Install the theme by uploading the Zip file in the same way you would install any other WordPress theme.

The theme download includes the child theme files only. The Understrap parent theme is automatically installed as a dependency.

For installation instructions refer to the README.txt file in the theme download.

Re-theming using Bootstrap 4 variables or advanced CSS

If you are familiar with npm, gulp.js and SASS you can set up a local gulp package.

The benefits of this approach are:

• Add your own custom JavaScript functions and compile into minified JS
• Re-define the theme colour palette, fonts and any other Bootstrap 4 variables, then compile into the minified CSS

If the above hurts your head and you only have CSS knowledge, it’s not the best approach but you can override styles using the WordPress Advanced CSS editor.

For re-theming instructions refer to the README.txt file in the theme download.

Child theme PHP templates

The child theme contains a number of php templates, these are used to adjust and add additional functionality to the UnderStrap parent theme. For example the improved search and tabbed layout mentioned previously.

You can make changes to these custom files. And should you wish to customise other aspects of the Understrap parent theme, you can simply copy the files you need to overwrite from the parent directory into the child theme directory and amend them. The way you would with any other custom child theme.

For more details on the php files contained within the child theme, refer to the README.txt file in the theme download.

Custom WordPress functions

There are a number of custom functions contained within the child theme functions.php file. These include:

• Breadcrumb – Outputs the page title, parent and homepage link
• Registering Advanced Custom fields settings pages
• Tweaking excerpt length
• Hiding widget titles if they start with an exclamation mark
• Aways show Excerpt and Author fields in post admin pages
• Excluding (footer menu) pages from search results
• Including author names in search results
• Showing most recently modified posts first in search results

Custom JavaScript

There are a number of custom JavaScript functions:

• Making the comment tab open and focus on the comment field when clicking a comment call to action, or when including #discussion at the end of the page URL
• Smooth scroll anchoring to section titles when clicking links in the contents menu
• Automatic page highlight in the contents menu when scrolling through sections
• ‘Back to contents’ button at the bottom right of the screen when scrolling below the contents menu on mobile

WordPress Plugins

We’ve tried to keep the number of plugins to a minimum:

Advanced Custom Fields Pro

Provides reorderable section headings and content blocks when adding chapter content. Allows the highlighting of contributed content within chapters and provides settings pages for some common content blocks and site language (wording).

Advanced Custom Fields Better Search

Enables the content of advanced custom fields to be indexed for search.

Category Order

Provides drag and drop functionality for setting category order, so the homepage can be curated.

Post Types Order

Provides drag and drop functionality for setting post order, so the category archive pages can be curated.

Classic Editor

Disables the Gutenburg WordPress editor in favour of the classic view.

WP User Avatar

Allows upload of custom avatar images to the user profile pages. Checks first for a Gravatar image and secondly for the custom upload.

For the full list of required plugins and their settings refer to the README.txt file in the theme download.

Editing site content

We’ve made a set of instruction videos for all the key editing tasks:

• Editing the homepage
• Add a new chapter
• Ordering chapters and categories
• Add a new category
• Edit contribute call to actions
• Editing wording – Miscellaneous language
• Add new pages to the footer menu
• Site appearance settings
• Add contributors and other users

You’ll find a link to the videos in the README.txt file contained in the theme download.

Replace ACF Pro functionality

If you would like to use the theme but you are unable to fund a subscription for the Advanced Custom Fields Pro Plugin. We will be releasing a non ACF Pro version.

You’ll lose the ability to re-order chapter sections and highlight contributor content, instead falling back to the standard WordPress editor for the chapter pages.

You’ll also need to install a an additional plugin for the automatic page contents menu.

Watch out for more details on this, coming soon in the first theme release.