Merlin WP aims to address the tedious and exhausting WordPress theme setup and onboarding process. It makes installing a new WordPress theme, recommended WordPress plugins, Customizer settings, widgets, and demo content an exciting and gratifying user experience. Read more...
Merlin WP is currently in beta, it's not suggested to use Merlin WP in production just yet, as there's still a few kinks and features to be added. If you run into anything, raise an issue and let's work on it.
In the package, I've included a fork of one of my themes, York Pro, with Merlin WP already integrated. If you want to run a live test of Merlin WP, install this theme anywhere and give it a spin.
First, download the merlin.zip file located within the /dist/ directory. Next, copy all of the files within this archive into your themes inc sub-directory.
Now all you need to do is require the merlin.php class, merlin-config.php and the composer autoload files in your functions.php.
Refer to the example below:
require_once get_parent_theme_file_path( '/inc/merlin/vendor/autoload.php' );
require_once get_parent_theme_file_path( '/inc/merlin/merlin.php' );
require_once get_parent_theme_file_path( '/inc/merlin-config.php' );Note: In the example above, the
/merlin/directory and themerlin-config.phpfile are both placed within the theme's/inc/directory location.
If you have TGMPA included within your theme, please ensure Merlin WP is included after it.
The merlin-config.php file tells Merlin WP where the class is installed. It also let's you modify any of the text strings throughout the wizard.
** The important configuration settings: **
directory— The location in your theme where the/merlin/directory is placed
Other settings:
merlin_url— The admin url where Merlin WP will existchild_action_btn_url— The url for the child theme generator's "Learn more" linkhelp_mode— A wizard for your wizard, if you need help (beta)dev_mode— Retain the "Theme Setup" menu item under the WordPress Admin > Appearance section for testing. Also enables JS/CSS minified files. This is on by default during the beta.branding— Show Merlin WP's logo or not (beta)
You'll need the following files:
content.xml— Exported demo content using the WordPress Exporterwidgets.wie— Exported widgets using Widget Importer & Exportercustomizer.dat— Exported Customizer settings using Customizer Export/Import
Once you have those files, you can upload them to your server (recommeded), or include them somewhere in your theme.
Next you have to define a filter in your theme, to let WP Merlin know, where these files are located. Depending on where you placed the import files, you have two ways to define the filter:
1. If you uploaded the import files to your server, then use this code example and edit it, to suit your file locations:
function merlin_import_files() {
return array(
array(
'import_file_name' => 'Demo Import 1',
'import_file_url' => 'http://www.your_domain.com/merlin/demo-content.xml',
'import_widget_file_url' => 'http://www.your_domain.com/merlin/widgets.json',
'import_customizer_file_url' => 'http://www.your_domain.com/merlin/customizer.dat',
'import_preview_image_url' => 'http://www.your_domain.com/merlin/preview_import_image1.jpg',
'import_notice' => __( 'A special note for this import.', 'your-textdomain' ),
'preview_url' => 'http://www.your_domain.com/my-demo-1',
),
);
}
add_filter( 'merlin_import_files', 'merlin_import_files' );
2. If you included the import files somewhere in the theme, then use this code example:
function merlin_local_import_files() {
return array(
array(
'import_file_name' => 'Demo Import 1',
'local_import_file' => trailingslashit( get_template_directory() ) . 'merlin/demo-content.xml',
'local_import_widget_file' => trailingslashit( get_template_directory() ) . 'merlin/widgets.json',
'local_import_customizer_file' => trailingslashit( get_template_directory() ) . 'merlin/customizer.dat',
'import_preview_image_url' => 'http://www.your_domain.com/merlin/preview_import_image1.jpg',
'import_notice' => __( 'After you import this demo, you will have to setup the slider separately.', 'your-textdomain' ),
'preview_url' => 'http://www.your_domain.com/my-demo-1',
),
);
}
add_filter( 'merlin_import_files', 'merlin_local_import_files' );
If you have multiple demo imports, then just define multiple arrays with appropriate data. For an example of two predefined demo imports, please look at the merlin-filters.php file.
Inside the package download exists a merlin-filters.php file which includes examples of the different filters you may use to modify Merlin. A primary example would be to use to merlin_generate_child_functions_php filter to modify the contents of the generated child theme's functions.php file.
You may also need to filter your theme demo's home page, so that Merlin WP knows which pages to set as the home page once it's done running.
To test, you'll want to create a new standard WordPress installation and add your theme build with Merlin WP integrated. You can then use the WP Reset plugin to reset and run through more tests.
Anyone is welcome to contribute to Merlin WP. Please read the guidelines for contributing to this repository.
There are various ways you can contribute:
- Raise an Issue on GitHub
- Send a Pull Request with your bug fixes and/or new features
- Provide feedback and suggestions on enhancements
The open source license is designed for you to use Merlin WP to build open source and personal projects. The Merlin WP open source license is GPLv3. The GPLv3 has many terms, but the most important is how it is sticky when you distribute your work publicly. From the GPL FAQ:
If you release the modified version to the public in some way, the GPL requires you to make the modified source code available to the program's users, under the GPL.
Releasing your project that uses Merlin WP under the GPLv3, in turn, requires your project to be licensed under the GPLv3.