Advanced Integration Guide
Less common One Click Demo Import hooks that theme authors can take advantage of.
Define Theme Demos With Local Import files
You have to use the same filter as in the Define Theme Demos section, but with slightly different array keys: local_*. The values have to be absolute paths (not URLs) to your import files. To use local import files, that reside in your theme folder, please use the below code. Note: make sure your import files are readable!
function ocdi_import_files() {
return [
[
'import_file_name' => 'Demo Import 1',
'categories' => [ 'Category 1', 'Category 2' ],
'local_import_file' => trailingslashit( get_template_directory() ) . 'ocdi/demo-content.xml',
'local_import_widget_file' => trailingslashit( get_template_directory() ) . 'ocdi/widgets.json',
'local_import_customizer_file' => trailingslashit( get_template_directory() ) . 'ocdi/customizer.dat',
'local_import_redux' => [
[
'file_path' => trailingslashit( get_template_directory() ) . 'ocdi/redux.json',
'option_name' => 'redux_option_name',
],
],
'import_preview_image_url' => 'http://www.your_domain.com/ocdi/preview_import_image1.jpg',
'preview_url' => 'http://www.your_domain.com/my-demo-1',
],
[
'import_file_name' => 'Demo Import 2',
'categories' => [ 'New category', 'Old category' ],
'local_import_file' => trailingslashit( get_template_directory() ) . 'ocdi/demo-content2.xml',
'local_import_widget_file' => trailingslashit( get_template_directory() ) . 'ocdi/widgets2.json',
'local_import_customizer_file' => trailingslashit( get_template_directory() ) . 'ocdi/customizer2.dat',
'local_import_redux' => [
[
'file_path' => trailingslashit( get_template_directory() ) . 'ocdi/redux.json',
'option_name' => 'redux_option_name',
],
[
'file_path' => trailingslashit( get_template_directory() ) . 'ocdi/redux2.json',
'option_name' => 'redux_option_name_2',
],
],
'import_preview_image_url' => 'http://www.your_domain.com/ocdi/preview_import_image2.jpg',
'preview_url' => 'http://www.your_domain.com/my-demo-2',
],
];
}
add_filter( 'ocdi/import_files', 'ocdi_import_files' );
Before Import Custom Code Execution
If you need to run some custom code just before the content import starts, you can use this hook ocdi/before_content_import. This action has an optional parameter $selected_import which is an array of the selected demo defined in the ocdi/import_files hook.
function ocdi_before_content_import( $selected_import ) {
if ( 'Demo Import 1' === $selected_import['import_file_name'] ) {
// Here you can do stuff for the "Demo Import 1" before the content import starts.
echo "before import 1";
}
else {
// Here you can do stuff for all other imports before the content import starts.
echo "before import 2";
}
}
add_action( 'ocdi/before_content_import', 'ocdi_before_content_import' );
After Import Custom Code Execution
There are a lot of use cases for wanting to execute some custom code after the demo has imported. For example:
- set the correct Front and Posts pages
- assign imported menus to theme menu locations
- setup custom theme/plugin integrations
You can easily do that with the ocdi/after_import hook.
function ocdi_after_import_setup() {
// Assign menus to their locations.
$main_menu = get_term_by( 'name', 'Main Menu', 'nav_menu' );
set_theme_mod( 'nav_menu_locations', [
'main-menu' => $main_menu->term_id, // replace 'main-menu' here with the menu location identifier from register_nav_menu() function in your theme.
]
);
// Get the front page.
$front_page = get_posts(
[
'post_type' => 'page',
'title' => 'Demo Front Page',
'post_status' => 'all',
'numberposts' => 1,
'update_post_term_cache' => false,
'update_post_meta_cache' => false,
]
);
if ( ! empty( $front_page ) ) {
update_option( 'page_on_front', $front_page[0]->ID );
}
// Get the blog page.
$blog_page = get_posts(
[
'post_type' => 'page',
'title' => 'Demo Blog Page',
'post_status' => 'all',
'numberposts' => 1,
'update_post_term_cache' => false,
'update_post_meta_cache' => false,
]
);
if ( ! empty( $blog_page ) ) {
update_option( 'page_for_posts', $blog_page[0]->ID );
}
if ( ! empty( $blog_page ) || ! empty( $front_page ) ) {
update_option( 'show_on_front', 'page' );
}
}
add_action( 'ocdi/after_import', 'ocdi_after_import_setup' );
How to handle different after import custom code executions depending on which predefined demo was imported?
The ocdi/after_import hook has an optional parameter $selected_import which is an array of the selected demo defined in the ocdi/import_files hook.
Let’s say we have predefined two demo imports with the following names: ‘Demo Import 1’ and ‘Demo Import 2’, the code for after import setup would be (using the ocdi/after_import filter):
function ocdi_after_import( $selected_import ) {
echo "This will be displayed on all after imports!";
if ( 'Demo Import 1' === $selected_import['import_file_name'] ) {
echo "This will be displayed only on after import if user selects Demo Import 1";
// Set logo in customizer
set_theme_mod( 'logo_img', get_template_directory_uri() . '/assets/images/logo1.png' );
}
elseif ( 'Demo Import 2' === $selected_import['import_file_name'] ) {
echo "This will be displayed only on after import if user selects Demo Import 2";
// Set logo in customizer
set_theme_mod( 'logo_img', get_template_directory_uri() . '/assets/images/logo2.png' );
}
}
add_action( 'ocdi/after_import', 'ocdi_after_import' );
Before Widgets Import Custom Code Execution
You can execute custom code before the widgets import by using the ocdi/before_widgets_import WP hook. This action has an optional parameter $selected_import which is an array of the selected demo defined in the ocdi/import_files hook.
function ocdi_before_widgets_import( $selected_import ) {
echo "Add your code here that will be executed before the widgets get imported!";
}
add_action( 'ocdi/before_widgets_import', 'ocdi_before_widgets_import' );
Change OCDI plugin page intro text
You can change the plugin intro text by using the ocdi/plugin_intro_text filter. If you want your added text to have the same design as the default one, you should wrap your text in a div with a class of ‘ocdi__intro-text’ and a paragraph, just like in this code example:
function ocdi_plugin_intro_text( $default_text ) {
$default_text .= '<div class="ocdi__intro-text"><p>This is a custom text added to this plugin intro text.</p></div>';
return $default_text;
}
add_filter( 'ocdi/plugin_intro_text', 'ocdi_plugin_intro_text' );
Modify plugin page attributes
If you do not like the location of the “Import Demo Data” plugin page in Appearance -> Import Demo Data, you can change that with the filter below. Apart from the location, you can also change the title or the page/menu and some other parameters as well.
function ocdi_plugin_page_setup( $default_settings ) {
$default_settings['parent_slug'] = 'themes.php';
$default_settings['page_title'] = esc_html__( 'One Click Demo Import' , 'one-click-demo-import' );
$default_settings['menu_title'] = esc_html__( 'Import Demo Data' , 'one-click-demo-import' );
$default_settings['capability'] = 'import';
$default_settings['menu_slug'] = 'one-click-demo-import';
return $default_settings;
}
add_filter( 'ocdi/plugin_page_setup', 'ocdi_plugin_page_setup' );
Set Recommended Plugins based on the Selected Demo
Your theme might require different recommended plugins based on which demo is selected by the user. You can modify the list of Recommended Plugins with a few conditions to achieve this. Before we go to the code example, it’s good to know that the theme demos are zero-based numbered. That means that the first demo will have an index of 0, the second demo will have an index of 1, and so on. This is important to keep in mind when editing the code example below.
This code should replace any existing ocdi/register_plugins filter code that you might have already configured from the general recommended plugins section.
You still have to list all plugins that are using in all demos at the beginning. Only then can you add the demo specific conditions.
function ocdi_register_plugins( $plugins ) {
// Required: List of plugins used by all theme demos.
$theme_plugins = [
[ // A WordPress.org plugin repository example.
'name' => 'Advanced Custom Fields', // Name of the plugin.
'slug' => 'advanced-custom-fields', // Plugin slug - the same as on WordPress.org plugin repository.
'required' => true, // If the plugin is required or not.
],
[ // A locally theme bundled plugin example.
'name' => 'Some Bundled Plugin',
'slug' => 'bundled-plugin', // The slug has to match the extracted folder from the zip.
'source' => get_template_directory_uri() . '/bundled-plugins/bundled-plugin.zip',
'required' => false,
],
[
'name' => 'Self Hosted Plugin',
'description' => 'This is the plugin description',
'slug' => 'self-hosted-plugin', // The slug has to match the extracted folder from the zip.
'source' => 'https://example.com/my-site/self-hosted-plugin.zip',
'preselected' => true,
],
];
// Check if user is on the theme recommeneded plugins step and a demo was selected.
if (
isset( $_GET['step'] ) &&
$_GET['step'] === 'import' &&
isset( $_GET['import'] )
) {
// Adding one additional plugin for the first demo import ('import' number = 0).
if ( $_GET['import'] === '0' ) {
$theme_plugins[] = [
'name' => 'Page Builder by SiteOrigin',
'slug' => 'siteorigin-panels',
'required' => true,
];
$theme_plugins[] = [
'name' => 'SiteOrigin Widgets Bundle',
'slug' => 'so-widgets-bundle',
'required' => true,
];
}
// List of all plugins only used by second demo import [overwrite the list] ('import' number = 1).
if ( $_GET['import'] === '1' ) {
$theme_plugins = [
[
'name' => 'Advanced Custom Fields',
'slug' => 'advanced-custom-fields',
'required' => true,
],
[
'name' => 'Portfolio Post Type',
'slug' => 'portfolio-post-type',
'required' => false,
],
];
}
}
return array_merge( $plugins, $theme_plugins );
}
add_filter( 'ocdi/register_plugins', 'ocdi_register_plugins' );
We recommend defining a core group of plugins that all your theme demos are using and then conditionally add or removed demo specific plugins based on which demo is selected (first example of the if block above). Or you can overwrite the whole list of recommended plugins for a specific demo (second if block in code above), but all plugins used in all demos should always be specified at the top without any conditions (that is required for the plugin installer to work properly).
How to include OCDI in your theme?
The best way to include OCDI in your theme is to not actually include it 🙂
One Click Demo Import is a standalone WordPress plugin, which is available to download for free, by anyone. It can be done via the WordPress plugin repository or a direct install inside the user’s WordPress dashboard. So, the best way is to recommend your theme users to install the One Click Demo Import plugin on their site. If you have a theme dashboard page (like a welcome page), then you can create a custom button on it to install and active the OCDI plugin. Another way to recommend installing the OCDI plugin is with the TGMPA library. With it, users will see an admin notice asking them to install certain plugins. Adding OCDI to the list of recommended plugins would be a good solution.
You might be tempted to simply copy & paste the OCDI code into your theme, but that’s not a good idea. Firstly we can’t offer support for these kinds of integrations and secondly, you will have to keep the code up to date. If we fix something in the plugin, you would also have to update the code and release a new version of your theme. With the above solutions, the user would simply need to update the OCDI plugin from their WP dashboard.
Whatever way you choose to include/recommend OCDI in your theme, always have clear instructions on what the user should do in your theme documentation.