Toolset Advanced Export

Made primarily as a support plugin for
Toolset-based themes.
This plugin allows you to export and import various settings and content which is
not covered by the WordPress XML export. The purpose of exporting and importing this
data is to allow users of your Toolset-based theme to receive an exact copy of your site
without having to set options manually.
Namely, it works with:

• Reading settings (Settings → Reading)
• Customizer setup (Appearance → Customize)
• Menu setup (Appearance → Menus)
• Widget setup (Appearance → Widgets)

Currently, there is a GUI and API available for both import and export, but the import GUI is
hidden by default (see below for details).

Usage

For generating an export file,

1. Make sure your site meets all the requirements described below.
2. Download, install and activate this plugin (note: if you checkout from the
   repository directly, you need to run composer install in the plugin directory before
   activating it).
3. Go to Toolset → Export / Import in the WordPress admin menu
   and select the Theme (TBT) tab.
4. Choose what do you want to export and click on the Export button.
5. The export file will be downloaded (or, for very old browsers, you
   will see a download link).

API

This plugin offers a filter hook API for export and import.
It is possible to export or import only selected section of settings:

• settings_reading: Reading settings (Settings → Reading)
• appearance_customize: Customizer setup (Appearance → Customize)
• appearance_menu: Menu setup (Appearance → Menus)
• appearance_widgets: Widget setup (Appearance → Widgets)

toolset_export_extra_wordpress_data

The hook exports selected WordPress sections and returns them as one (nested) associative array.

@param null
@param string[] $sections_to_export Names of the sections to export.
@return array Exported data, one element for each section, indexed by section name.

Example

try{
    $export_data = apply_filters( 
        'toolset_export_extra_wordpress_data', 
        null, 
        ['appearance_widgets', 'settings_reading'] 
    );
} catch( Exception $e ) {
    // TODO handle errors
}

Note

There are other similar filters available:

• toolset_export_extra_wordpress_data_json: Export the data as a JSON string.
• toolset_export_extra_wordpress_data_raw: Only for internal usage within Toolset.

toolset_import_extra_wordpress_data

The hook imports selected WordPress sections provided as a (nested) associative array.
This is the import counterpart of toolset_export_extra_wordpress_data.

@param null
@param string[] $sections_to_import Names of the sections to import.
@param array $import_data Associative array with section data (as arrays), with section names as keys.
@return Toolset_Result_Set|Toolset_Result Operation results.

Example

try{
    $results = apply_filters( 
        'toolset_import_extra_wordpress_data', 
        null, 
        ['appearance_menu'], 
        $data 
    );
} catch( Exception $e ) {
    // TODO handle errors
}

toolset_import_extra_wordpress_data_zip

The hook imports WordPress sections provided in a ZIP file. This is the counterpart of
the ZIP file generated by the GUI.

@param null
@param string $zip_path Absolute path to the ZIP file.
@param string[] $sections_to_import Names of the sections to import.
@return Toolset_Result_Set|Toolset_Result Operation results.

Requirements and limitations

PHP

This plugin requires PHP 5.6 or above.

WordPress

Tested with WordPress 4.7.

Toolset

Currently, it runs only with development version of Toolset because of several dependencies.
One thing that needs to be handled if the plugin is to be used in a standalone
mode is the rewriting of imported URLs (for example, to header images in
Customizer settings) and importing the actual files.

Browsers

Recommended (but not required) browsers:

• Firefox 20+
• Chrome
• Edge
• IE 10+
• Opera 15+
• Safari 6.1+

Import limitations

It is required and assumed that

• the same theme is active on export and on import,
• the same plugins that register active widgets are active on export and on import,
• posts, taxonomies and terms referenced in menus or settings are already imported,
  and that post GUIDs haven’t been changed.

If this is not the case, the import may turn out to be incomplete or downright broken.
Please note also that URLs pointing to local resources (images and other files) are
not updated by this plugin. It is currently out of the scope of the plugin and
it needs to be handled manually. The main reason is that in Toolset-based themes,
there is another, more generic mechanism implemented outside of this plugin.

Credits

The relevant part of the widget export was, with the deepest gratitude to its authors, taken from the
Widget Importer & Exporter
plugin with only very little changes.
Made with ❤️ for Toolset and OnTheGoSystems.