Quick Integration Guide

Are you a WP theme author and would like to offer One Click Demo Import to your clients?

Well, we got you covered! 😎

Users picked your theme because they liked your demo. What better way for them to start from, than an actual copy of your theme demo site? By integrating with One Click Demo Import, you will provide them just that – fully functional copy of your demo site and they’ll absolutely love it!

All they have to do is select which demo they want to import.

Import files

There are four import files that you can prepare and use for your demo imports:

• Content import – a normal WordPress content export file (XML format)
• Widgets import (optional) – export that file using the Widget Importer & Exporter plugin (JSON/WIE format)
• Customizer import (optional) – export that file using the Customizer Export/Import plugin (DAT format)
• Redux framework import (optional) – export that file using the Redux Framework plugin (JSON format)

For fully functional Content Imports, you should export the “All Content” option in your WordPress site (Tools > Export). This will export all your content, together with references to your media files, which have to be publicly accessible, so that they can be downloaded in the importing process.

Recommended Plugins

Every theme has some required and recommended plugins. Instead of giving users instructions on which plugins to install before the theme demo data can be imported, you can just use a simple OCDI hook and let our plugin do the work.

With the ocdi/register_plugins filter you’ll be able to list the required, recommended, preselected and/or optional plugins. OCDI can install plugins from WordPress.org plugin repository as well as from selfhosted or locally bundled plugin zip files.

Please use this code example and change the plugin items to the ones your theme needs.

function ocdi_register_plugins( $plugins ) {
	$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,
		],
	];

	return array_merge( $plugins, $theme_plugins );
}
add_filter( 'ocdi/register_plugins', 'ocdi_register_plugins' );

As you can see each plugin item has two required parameters: name and slug. If the source parameter is not provided, then OCDI will try to download and install the plugin from the WordPress.org plugin repository with the provided slug. If the source is provided it will be installed from the provided source URL.

The plugin item can be:

• required, which means the user will not be able to deselect it before importing the content
• preselected, which means the plugin item will be selected by default, but user can still deselect it and proceeed to the content import.

All plugin items that are not required or preselected are optional and user can select or deselect them and continue to the content import.

Plugins that are already installed will show up as green circles with checkmark icon.

If you want to define different recommended plugins based on which demo the user selects, please take a look at our advanced guide for the recommended plugins.

Define Theme Demos

To add your theme demos to OCDI you will need to register them with the ocdi/import_files hook.

Use the example below and input your theme’s import files.

function ocdi_import_files() {
	return [
		[
			'import_file_name'           => 'Demo Import 1',
			'categories'                 => [ 'Category 1', 'Category 2' ],
			'import_file_url'            => 'http://www.your_domain.com/ocdi/demo-content.xml',
			'import_widget_file_url'     => 'http://www.your_domain.com/ocdi/widgets.json',
			'import_customizer_file_url' => 'http://www.your_domain.com/ocdi/customizer.dat',
			'import_redux'               => [
				[
					'file_url'    => 'http://www.your_domain.com/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' ],
			'import_file_url'            => 'http://www.your_domain.com/ocdi/demo-content2.xml',
			'import_widget_file_url'     => 'http://www.your_domain.com/ocdi/widgets2.json',
			'import_customizer_file_url' => 'http://www.your_domain.com/ocdi/customizer2.dat',
			'import_redux'               => [
				[
					'file_url'    => 'http://www.your_domain.com/ocdi/redux.json',
					'option_name' => 'redux_option_name',
				],
				[
					'file_url'    => 'http://www.your_domain.com/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' );

The only required parameters for each demo item are the import_file_name and at least one of:

• import_file_urls
• import_widget_file_url
• import_customizer_file_url
• import_redux

Apart from defining the import files and the name of the demo, you can also allow your users to filter the demos by category. If your demos have categories the OCDI demo selection page will create a navigation element and the theme users will be able to filter them by clicking on the categories or searching them in a search input.

To make the demo items look good, you should include a import_preview_image_url which is a URL to the theme demo screenshot. A theme demo item with a provided screenshot would look like this.

The Preview Demo button in the above screenshot will take the user to the actual theme demo page, if you define that URL in the preview_url parameter.

For more details, you should read our advanced integration guide, where we look at all other plugin hooks which you can use to bring the meaning of “one click” to a whole new level. 😎