Usage Guide

Quick Demo Importer runs one click demo import from Tools → Demo Importer. You need the manage_options capability. Each demo is a profile: a folder with a required config.json that defines an ordered pipeline of steps. Steps run one by one over AJAX. If a step fails, later steps do not run.

Profile locations

• Bundled: wp-content/plugins/quick-demo-importer/demos/{slug}/
• Custom: wp-content/uploads/quick-demo-importer/profiles/{slug}/

When the same slug exists in both places, the custom profile is used first.

Typical files inside a profile folder:

{slug}/
  config.json     # required
  content.xml     # optional WXR export
  images/         # optional local media
  tasks.php       # optional PHP tasks

config.json root fields

• name (required) — display title
• description (optional) — short summary
• pipeline (required) — non-empty array of step objects

Unknown step types are skipped while parsing. If nothing valid remains, the profile is rejected.

Minimal example:

{
  "name": "My Demo",
  "description": "Theme only",
  "pipeline": [
    { "step": "install_theme", "slug": "twentytwentyfour" }
  ]
}

Pipeline steps for one click demo import

Every item needs "step": "<type>" plus type-specific fields. Array order is execution order. Use this structure when you want reliable WordPress demo import that installs packages, media, and content in one flow.

1. install_theme

Installs a theme. Activation defaults to on.

• slug — theme stylesheet / wordpress.org slug
• zip_url — HTTPS ZIP URL (optional alternative or complement to slug)
• activate — default true; set false to install only

Provide at least slug or zip_url.

{ "step": "install_theme", "slug": "twentytwentythree" }

{
  "step": "install_theme",
  "slug": "my-theme",
  "zip_url": "https://example.com/my-theme.zip",
  "activate": true
}

• Already installed + activate: true → switches theme when needed
• Already installed + activate: false → left as-is (not force-deactivated)

2. install_plugin

Installs a plugin. Activation defaults to on.

• slug — plugin folder / wordpress.org slug
• zip_url — HTTPS ZIP URL
• activate — default true; set false to install only

{ "step": "install_plugin", "slug": "classic-editor" }

{
  "step": "install_plugin",
  "slug": "hello-dolly",
  "activate": false
}

{
  "step": "install_plugin",
  "slug": "debug-bar",
  "zip_url": "https://downloads.wordpress.org/plugin/debug-bar.latest-stable.zip"
}

When zip_url is set, that archive is used and the wordpress.org API is skipped. Keep slug aligned with the installed folder name so activation can resolve the plugin file.

3. import_media

Imports image files from a profile subdirectory into the Media Library.

• directory — default "images"

Allowed extensions: jpg, jpeg, png, gif, webp, ico.

{ "step": "import_media", "directory": "images" }

• Attachment post_name = sanitized file name without extension
• Existing slug → skipped (safe to re-run)
• Reuse those slugs later in site_icon, custom_logo, or theme_mods_attachments

4. import_content

Imports WXR/XML through the official WordPress Importer (WP_Import). This is the standard path for WordPress XML import and exported demo content.

• content_url — remote HTTPS WXR URL (used when non-empty)
• content_file — relative file under the profile (default content.xml)
• fetch_attachments — default true
• rewrite_urls — default true

{
  "step": "import_content",
  "content_file": "content.xml",
  "fetch_attachments": true,
  "rewrite_urls": true
}

{
  "step": "import_content",
  "content_url": "https://example.com/exports/demo.xml",
  "fetch_attachments": true,
  "rewrite_urls": true
}

WordPress Importer must be active. The Demo Importer screen can install it when needed.

5. apply_setup

Applies generic site configuration. Put demo-specific logic in run_task instead.

Reading / front page

• show_on_front — page or posts
• page_on_front / page_for_posts — page slug or title

Branding

• site_icon — attachment slug
• custom_logo — attachment slug

Menus

• menus — object map: { "location_slug": "Menu Name" }

Theme mods

• theme_mods — scalar values
• theme_mods_attachments — theme mod key → attachment slug → stored as URL

Options

• options — WordPress options object (scalars)
• permalink_structure inside options updates structure and flushes rewrite rules

{
  "step": "apply_setup",
  "show_on_front": "page",
  "page_on_front": "welcome",
  "page_for_posts": "notes",
  "site_icon": "demo-three-icon",
  "custom_logo": "demo-three-logo",
  "menus": { "primary": "Main Menu" },
  "theme_mods": { "my_setting": "value" },
  "theme_mods_attachments": { "hero_image": "hero-banner" },
  "options": {
    "blogname": "Demo Site",
    "permalink_structure": "/%postname%/",
    "posts_per_page": 5
  }
}

6. run_task

Runs a method from the profile tasks.php class.

• name (required) — method name
• tasks_class (optional) — must start with QDIMP_Tasks_

{ "step": "run_task", "name": "setup_primary_menu" }

{
  "step": "run_task",
  "name": "pin_welcome_note",
  "tasks_class": "QDIMP_Tasks_demo_three"
}

Example class shape:

<?php
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class QDIMP_Tasks_my_demo {
	public function my_method() {
		return 'Done.';
	}
}

Class resolution: step tasks_class → QDIMP_Tasks_{demo_slug} → first loaded QDIMP_Tasks_* class that has the method. Custom profiles imported in the UI strip all run_task steps for security.

Full pipeline example

{
  "name": "Starter Shop",
  "description": "Theme, WooCommerce, media, content, setup, menu task",
  "pipeline": [
    { "step": "install_theme", "slug": "twentytwentyfour" },
    { "step": "install_plugin", "slug": "woocommerce" },
    { "step": "import_media", "directory": "images" },
    {
      "step": "import_content",
      "content_file": "content.xml",
      "fetch_attachments": true,
      "rewrite_urls": true
    },
    {
      "step": "apply_setup",
      "show_on_front": "page",
      "page_on_front": "home",
      "page_for_posts": "blog",
      "site_icon": "site-icon",
      "options": {
        "blogname": "Starter Shop",
        "permalink_structure": "/%postname%/"
      }
    },
    { "step": "run_task", "name": "setup_primary_menu" }
  ]
}

Admin workflows

Run a bundled demo

1. Open Tools → Demo Importer
2. Ensure WordPress Importer is ready
3. Select a demo, review steps, start import

Import a custom profile

1. Paste full config.json or choose a local .json file (read in the browser)
2. Import profile
3. Select the new Custom entry and run it

• JSON size limit about 512 KB
• Only known step types are kept
• run_task steps are removed on custom import
• Profiles are stored under uploads and can be deleted in the UI

Practical tips

• Order matters: install theme/plugins before dependent content; run import_media before apply_setup when you reference image slugs.
• Re-runs: installed themes/plugins are not reinstalled blindly; existing media slugs are skipped; task methods should tolerate a second run.
• Pretty permalinks: set permalink_structure under apply_setup → options so rewrite rules refresh (important on nginx).
• Keep setup generic: one-off cleanup or menu rebuilds belong in tasks.php.
• Omit empty keys: do not add "zip_url": ""; leave the field out when unused.

Errors and security

Each step returns a success message or an error. The UI shows the message and stops the pipeline. Common causes include a missing page slug in apply_setup, inactive WordPress Importer, invalid ZIP URL, missing images/ folder, or a missing task method.

• Only administrators can run imports
• Remote URLs must be valid http/https targets
• Path traversal is blocked for content and media paths
• Do not ship arbitrary PHP through custom profile import; use bundled tasks.php only for trusted demos

With a well-ordered profile, one click demo import becomes a repeatable way to deliver WordPress demo import results: packages, media, WXR content, and finishing site options in one controlled pass.