The ThemeIsle onboarding module serves as aid for theme authors to enable an easier onboarding UX, allowing to install and activate plugins, change theme mods, and import content with XML files.
- Include the ThemeIsle Onboarding Module.
- Declare theme support in your theme.
- Add the import files in your theme folder.
- Render the onboarding application in your admin page
- Disable the ThemeIsle Onboarding Module.
There are two ways in which you can use the Onboarding Module:
- Include this repository directly in your project
- Include it as a composer dependency -
composer require "codeinwp/ti-onboarding"
You have to declare theme support in order to make the Onboarding work. Here's an example:
add_theme_support( 'themeisle-demo-import', array(
'editors' => array(
'elementor',
'gutenberg',
),
'local' => array(
'elementor' => array(
'neve-main' => array(
'url' => 'https://demo.themeisle.com/neve',
'title' => 'Neve 2018',
),
),
'beaver_builder' => array(
'neve-main' => array(
'url' => 'https://demo.themeisle.com/neve',
'title' => 'Neve 2018',
),
),
),
'i18n' => array(
'templates_title' => __( 'Ready to use pre-built websites with 1-click installation', 'neve' ),
'templates_description' => __( 'With Neve, you can choose from multiple unique demos, specially designed for you, that can be installed with a single click. You just need to choose your favorite, and we will take care of everything else.', 'neve' ),
),
) );
There are three main files that must be added to your theme so that the demo import can work:
- An XML file containing the demo content - you can get that by using the WordPress exporter. It should be named
export.xml
; - A screenshot file that will be displayed for your demo instance. It should be named
screenshot.png
; - A
data.json
file containing other data. You can see the format in which it should be delivered here
After everything is loaded, you should make sure that you render the onboarding application where you want it displayed. The snippet below should do this:
if ( class_exists( '\Themeisle_Onboarding' ) ) {
$onboarding = \Themeisle_Onboarding::instance();
$onboarding->render_onboarding();
}
To disable the module, just add the snippet below:
define( 'TI_ONBOARDING_DISABLED', true );
NOTE: The styling of this might not work ideal everywhere, so you might have to tweak it with some of your own CSS magic.
The data.json
file you deliver should respect the following format:
{
"theme_mods": {
"neve_navigation_layout": "left",
"neve_theme_color": "#00a4f7",
"__ti_import_menus_location": {
"primary": "main-menu"
}
},
"widgets": {
"blog-sidebar": {
"rss-1": {
"title": "",
"url": "https:\/\/www.themeisle.com\/blog\/feed\/",
"items": 5,
"show_summary": 0,
"show_author": 0,
"show_date": 0
},
},
"shop-sidebar": {
"woocommerce_product_search-9": [],
"woocommerce_widget_cart-5": []
}
},
"recommended_plugins": {
"woocommerce": "WooCommerce",
"themeisle-companion": "Orbit Fox by ThemeIsle"
},
"front_page": {
"front_page": "neve-home",
"blog_page": "blog"
},
"shop_pages": {
"woocommerce_shop_page_id": "shop",
"woocommerce_cart_page_id": "cart",
"woocommerce_checkout_page_id": "checkout",
"woocommerce_myaccount_page_id": "my-account"
}
}
This holds key:value
pairs of the theme mod key and the value that you want to set upon importing.
Also inside the theme_mods
key you have to define where the navigation menus are going to be placed (under the __ti_import_menus_location
key). In the example above, the primary
nav menu location is assigned the menu with the main-menu
slug.
This holds the widgets that you will import. You can get the content of this using the Widget Importer & Exporter Plugin. The .wie
file that it exports holds the data you need to add here in order to properly map the widgets.
This holds the plugins that you recommend. The format used is "plugin-slug":"Plugin Nicename"
.
This holds key value pairs for the static front page setup using the page slug (neve-home
/blog
). If you don't want to set anything, you should just send null
here.
This holds key value pairs for the shop pages that you want to set in case you're importing a WooCommerce shop. The logic is the same as in the case of the front page. You should use the page slug to set this up.
The ThemeIsle Onboarding Module is licensed under the GPLv2 or later.
- The XML importer is based on the HumanMade WordPress-Importer repository, licensed under GPLv2 or later.
- The widgets importer is based on the CrunchThemes Widget Importer & Exporter, licensed under GPLv2 or later.