The Rank It WP theme was built to allow simple modification through child themes, hooks, filters, and redefinable display functions. This section outlines the best way to make modifications to the theme using these approaches. If you find a portion of the theme that more easily allow customization, please let me know. I’m a theme builder (obviously) and like to do what I can to make my fellow builders’ lives easier!
The main philosophy behind these techniques is to allow site owners to customize how their theme appears and functions without breaking the ability to upgrade to new versions. Rank It WP allows automatic updates in wp-admin which will remove any custom work that has been done to the main theme. By using the techniques below, you can modify your site without missing out on future bug fixes and features.
Child Themes
The best way to make changes to the Rank It WP theme is to create a child theme. This lets you override specific theme files while keeping others intact. When you upgrade, the parent theme is modified and your changes stay in place. Otherwise, you’ll either have to stick with your older, modified theme (might be problematic if we release security fixes) or keep track of what was modified for each upgrade (hard to do and prone to mistakes).
How? Your child theme will hold files that take precedence over the parent theme. The WordPress Codex has the best information on creating child themes that I’ve found. I created a sample child theme that will give you a head start on this process.
Download Rank It WP child theme »
To use this child theme:
- Add the overriding theme files (reference the Codex link above for information on how to do this) and make your desired changes in functions.php. There are a few example actions and filters (explained below) that can be changed and activated by uncommenting their add_filter or add_action call. The first one, for example, will load the CSS and JS files included with the child theme.
- Upload, install, and activate the child theme according to these instructions
- Make changes to the child theme files, leaving the parent theme unmodified
Actions and Filters
Hooks and filters are the main way that WordPress is extended and there are several of them built into the Rank It WP theme. Hooks are used to add functionality to certain parts of the theme while filters are used to change text or data as it passes through the flow of the theme.
The child theme above documents several of the hooks and filters that are being used in the theme and a full list of them is below. For more information on how to use hooks and filters generally, see this Smashing Magazine article on actions and filters.
Rank It WP Hooks
- wpri_content_top – Runs at the top of the content section, after the header
- wpri_listing_wrap_before – Runs before the containing box for content listings
- wpri_listing_wrap_top – Runs inside the containing box for content listings at the top
- wpri_listing_wrap_bottom – Runs inside the containing box for content listings at the bottom
- wpri_listing_wrap_after– Runs after the containing box for content listings
- wpri_submit_form_top – Runs at the top of the submit form, inside of the form tag
- wpri_submit_form_middle – Runs after the URL field of the submission form
- wpri_submit_form_bottom – Runs at the bottom of the submit form, inside of the form tag
- wpri_modal_login_form_top – Runs at the top of the login form, inside of the form tag
- wpri_modal_login_form_bottom – Runs at the bottom of the login form, inside of the form tag
- wpri_modal_register_form_top – Runs at the top of the register form, inside of the form tag
- wpri_modal_register_form_below_submit – Runs at the bottom of the register form, inside of the form tag
- wpri_user_profile_header – Runs in the user profile header after all core display features
- wpri_comment_listing_wrap_before – Runs before the containing box for comment listings [added v1.3.1]
- wpri_comment_listing_wrap_top – Runs inside the containing box for comment listings at the top [added v1.3.1]
- wpri_comment_listing_wrap_bottom – Runs inside the containing box for comment listings at the bottom [added v1.3.1]
- wpri_comment_listing_wrap_after– Runs after the containing box for comment listings [added v1.3.1]
- wpri_submission_widget_single_top – Runs at the beginning of a single submission in the submissions widget [added v1.3.1]
- wpri_submission_widget_single_bottom – Runs at the end of a single submission in the submissions widget [added v1.3.1]
- wpri_content_bottom – Runs at the bottom of the content section, before the footer
Rank It WP Filters
- wpri_archive_title – Used to change the main page title on submission and other content listing pages like date, category, and tag archives.
- wpri_custom_submit_fields – Used to add new submission form fields
- wpri_submit_link – Used to change the URL used on linked submission titles on listing and single pages.
- wpri_insert_post_args – Used to change the data being saved for new submissions
- wpri_cron_update_rating_go – Used to turn off and on wp-cron rank processing
- wpri_cron_update_rating_number – Number of submissions to process at a time, default 1500
- wpri_vote_icon – Filter the voting icon class
- wpri_submission_widget_args – Filter the WP_Query arguments used to query for widget submissions, passed to a new WP_Query after the widget form settings have been applied [added v1.3.1]
- wpri_submit_cat_widget_args – Filter the wp_list_categories() arguments after defaults and widget form settings are passed [added v1.3.1]
Function Overrides
Another simple way to change how your site functions is overriding specific functions by re-declaring them in a child theme or plugin. These functions are located in /includes/theme-display-functions.php and are preceded by a function_exists check. simply copy the function definition into a child theme or plugin, keeping the same name, and change the output.
