This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -38,76 +38,78 @@ ImpEx provides a foundation of core functionality to easily integrate custom Wor
### Third-party data integration
Third-party WordPress plugins or themes often persist data in custom database tables, `wp_options` or other data sources.
Third-party WordPress plugins and themes often persist data in custom database tables, `wp_options` or other data sources.
ImpEx provides [WordPress actions](https://developer.wordpress.org/plugins/hooks/actions/) and [WordPress filters](https://developer.wordpress.org/plugins/hooks/filters/) to integrate custom data into the export.
Third-party plugins can easily contribute their own data provider to the export by registering [actions](https://developer.wordpress.org/plugins/hooks/actions/) and [filters](https://developer.wordpress.org/plugins/hooks/filters/) with ImpEx.
Third-party plugins can easily contribute their own data provider by registering [actions](https://developer.wordpress.org/plugins/hooks/actions/) and [filters](https://developer.wordpress.org/plugins/hooks/filters/) with ImpEx.
> A ImpEx Data Provider is a import /export definition exposes plugin data to be used by other developers to integrate the data in their own export.
### API
Custom export profiles can be defined using the [ImpEx API](api/configuration.html).
Custom profiles can be defined using the [ImpEx API](api/configuration.html).
That does not mean that your own code depends on the ImpEx plugin to be installed and active. ImpEx uses [WordPress actions](https://developer.wordpress.org/plugins/hooks/actions/) and [WordPress filters](https://developer.wordpress.org/plugins/hooks/filters/)your plugin will work as is also if ImpEx is not installed.
That does not mean that your own code depends on the ImpEx plugin to be installed and active. ImpEx uses [WordPress actions](https://developer.wordpress.org/plugins/hooks/actions/) and [WordPress filters](https://developer.wordpress.org/plugins/hooks/filters/), so your plugin will also work fine is ImpEx is not installed.
The ImpEx API provides an interface for
The ImpEx API provides interfaces for
- Data provider
Data provider expose data (Export) or consume data (Import). Typically a third-party plugin will register a Import Provider and Export Provider to ImpEx. Theses providers can be used by ImpEx profiles to to integrate the plugin data into export and import.
Data provider expose data (Export) or consume data (Import). Typically a third-party plugin will register a Import Provider and Export Provider to ImpEx. Theses providers can be used by ImpEx profiles to integrate the plugin data into export and import.
- Profiles
A ImpEx profile is a set of configuration options to define what data to export and/or import.
A ImpEx profile is a set of configuration options and tasks defining what data to export/import.
Furthermore ImpEx provides a foundation of helpers to create custom ImpEx profiles within a few lines for post types, while database tables or wp_options.
>ImpEx provides a foundation of helpers to create custom ImpEx profiles with a few lines for posts, database tables and wp_options.
## Managed WordPress support
If you operate your WordPress website using a managed WordPress hosting service, you often have limited or not direct access to the WordPress database and installation.
If you operate your WordPress website using a managed WordPress hosting service, you often have limited or no direct access to the WordPress database / installation.
In these scenarios most WordPress Import / Export plugins does not work as expected.
In these scenarios most WordPress Import / Export plugins will not work.
ImpEx only needs access to the WordPress REST API an works like a charm in almost any managed WordPress hosting environment.
**ImpEx only needs access to the WordPress REST API an works like a charm in almost any managed WordPress hosting environment.**
## Commandline interface (CLI)
[wp-cli](https://wp-cli.org/) is a great tool for managing WordPress installations. Unfortunately it needs direct access to the WordPress installation and database.
Thus ImpEx provides a [CLI interface](impex-cli.html) to interact with a WordPress installation using pure WordPress REST API. The [ImpEx CLI](impex-cli.html) works perfectly on managed WordPress instances.
Thus ImpEx provides a [CLI interface](impex-cli.html) to interact with a WordPress installation using pure WordPress REST API. **The [ImpEx CLI](impex-cli.html) works perfectly on managed WordPress instances.**
## REST API support
ImPEx provides a [WordPress REST API](https://developer.wordpress.org/rest-api/) extension for importing and exporting data. [All ImpEx functions are available as REST API endpoints](index.html#rest-api).
## Scalability
It's easy to export a WordPress website with a few pages. But what if you have a lot of pages and hundreds of images ?
It's easy to export a WordPress website with a few pages. But about a WordPress website with a lot of pages and hundreds of images ?
ImpEx is designed to be scalable. It can can handle hundreds of pages/posts and media files from scratch.
**ImpEx is designed to be scalable. It can can handle hundreds/thousands of pages/posts and media files from scratch.**
### Streaming API
ImpEx API is designed to import/export a WordPress website in _chunks_ of _slices_.
A chunk is a part of the export data. It basically results in a directory containing a number of exported slices. Each slice is a json file describing (and most times also containing) data like post(s) or any other WordPress data.
A chunk is a partial unit of the exported data. Its basically a directory containing a part of the exported slices. Each slice is a json file describing (and most times also containing) data like post(s) or any other WordPress data.
The API ist designed to be resumable. A aborted export (and even import) can be resumed at any time.
_cancel/resume support will be part of a future release._
## Import Framework for websites from third-party website builders
ImpEx is also a great choice to import a website from a third-party website builder or even a static website.
ImpEx provides a [Framework to convert any existing website to ImpEx](cm4all-wp-impex-generator/index.html).
ImpEx provides a [NodeJS Framework to convert any existing content to ImpEx WordPress content](cm4all-wp-impex-generator/index.html) : [@cm4all-wp-impex/generator](https://www.npmjs.com/package/@cm4all-wp-impex/generator).
Using [@cm4all-wp-impex/generator](cm4all-wp-impex-generator/index.html) you can convert html pages to valid WordPress content.
**Using [@cm4all-wp-impex/generator](https://www.npmjs.com/package/@cm4all-wp-impex/generator) you can convert html pages or any other content to WordPress content.**
Since this [package](<[@cm4all-wp-impex/generator](cm4all-wp-impex-generator/index.html)>) provides an API you can easily add custom transformations to third-party site builder specialties into valid ImpEx export data.
Since this [package](https://www.npmjs.com/package/@cm4all-wp-impex/generator) provides an API you can easily add custom transformations to suppport third-party site builder specialties into valid ImpEx export data.
# Generating custom content
Even more, [@cm4all-wp-impex/generator](cm4all-wp-impex-generator/index.html) allows you to transform **any** data from anywhere into WordPress content.
There ist actually no limit - everything can be transformed into WordPress content using [@cm4all-wp-impex/generator](cm4all-wp-impex-generator/index.html). See the [Static website conversion tutorial](./cm4all-wp-impex-generator/static-website-tutorial.html).
There ist actually no limit - everything can be transformed into WordPress content using [@cm4all-wp-impex/generator](cm4all-wp-impex-generator/index.html). See the [Static website conversion tutorial](./cm4all-wp-impex-generator/static-website-tutorial.html) as a starting point.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -38,7 +38,7 @@ ImpEx imports slice files ordered by name. So the slices in sub directory `chunk
Same rule for `slice-*.json` files within the same `chunk-\*` sub directory : `slice-0001.json` will be imported before `slice-0002.json` and so on.
> Know that import order is important. If you import content referencing images/videos in the wrong order, you will get broken links in your posts. ImpEx will rewrite/fix media links in the content if you **import content as first and media afterwards.**
> Knowing that import order is important. If you import content referencing images/videos in the wrong order, you will get broken links in your posts. ImpEx will rewrite/fix media links in the content if you **import content as first and media afterwards.**
Have a look at this [sample ImpEx export](https://github.com/IONOS-WordPress/cm4all-wp-impex/tree/develop/impex-cli/tests/fixtures/simple-import) provided by the ImpEx plugin to get a clue about a minimal working ImpEx export containing content and referencing images.
Expand DownExpand Up
@@ -206,7 +206,7 @@ If you import the slice file using ImpEx, the image will appear in the WordPress
>
> This can be achieved by naming content slicing with a lower number than the media slices or - much simpler - keeping the content slices in a lower numbered `chunk-*` directory than the attachments.
>
> See [simple-import](https://github.com/IONOS-WordPress/cm4all-wp-impex/tree/develop/impex-cli/tests/fixtures/simple-import) example for a full featured manually written import at the [ImpEx WordPress Plugin GitHub repository](https://github.com/IONOS-WordPress/cm4all-wp-impex).
> See [simple-import](https://github.com/IONOS-WordPress/cm4all-wp-impex/tree/develop/impex-cli/tests/fixtures/simple-import) example for a full featured manually written import at the [ImpEx WordPress plugin GitHub repository](https://github.com/IONOS-WordPress/cm4all-wp-impex).
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This is a full featured example of converting a regular static website of a fictive dentist to a WordPress site.
This is a full featured example of converting a regular static website of a fictional german dentist to a WordPress site.
The web site is available offline at folder`./homepage-dr-mustermann`.
The web site is available offline at directory`./homepage-dr-mustermann`.
You can view the website by starting the PHP built-in webserver (`php -S localhost:8080 -t homepage-dr-mustermann/`) and open the browser to `http://localhost:8080/`.
- and open the website in your browser : `http://localhost:8080/`.
## [Watch the walk-trough on YouTube](https://img.youtube.com/vi/pjG69RmULYo/2.jpg)
[](https://www.youtube.com/watch?v=pjG69RmULYo)
_(German audio with english sub titles.)_
# Conversion process
The conversion process is implemented in a single file `./index.js` :
-reading the html and media files from the filesystem using plain NodeJS
-scanning for html and media files from the filesystem using plain NodeJS
- converting the HTML files to [ImpEx slice JSON](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#content-aka-wordpress-postspages) using `ImpexTransformer` and `ImpexSliceFactory` from package [`@cm4all-wp-impex/generator`](https://www.npmjs.com/@cm4all-wp-impex/generator). The HTML transformation is set up in the `setup(...)` function.
- converting the HTML files to [ImpEx slice JSON](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#content-aka-wordpress-postspages) using `ImpexTransformer` and `ImpexSliceFactory` from package [`@cm4all-wp-impex/generator`](https://www.npmjs.com/@cm4all-wp-impex/generator). The HTML transformation is customized in the `setup(...)` function.
- creating [ImpEx slice JSON](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#attachments-like-pictures-and-videos) for the media files using `ImpexSliceFactory` from package [`@cm4all-wp-impex/generator`](https://www.npmjs.com/@cm4all-wp-impex/generator)
- saving the [ImpEx slice JSON](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#data-files) to the filesystem using paths generated by `ImpexSliceFactory.PathGenerator` from package [`@cm4all-wp-impex/generator`](https://www.npmjs.com/@cm4all-wp-impex/generator)
- the media files are saved to the filesystem using paths adapted from the `ImpexSliceFactory.PathGenerator` generated paths for the slice files (as expected by the [ImpEx Export format](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#attachments-like-pictures-and-videos)).
The conversion is implemented in less than 240 lines of code thanks to package [`@cm4all-wp-impex/generator`](https://www.npmjs.com/@cm4all-wp-impex/generator).
The conversion process is implemented in less than 240 lines of code thanks to package [`@cm4all-wp-impex/generator`](https://www.npmjs.com/@cm4all-wp-impex/generator).
You can run the conversion script by executing `./index.js`
You can run the conversion script by executing `./index.js` (don't forget to activate the right nodejs version before using `nvm use` and to install the required NodeJS dependencies using `npm ci`).
> Ensure the right nodejs version is active before using `nvm install` and to install the required NodeJS dependencies using `npm ci`.
The result is a folder `generated-impex-import/` containing the the[ImpEx export folder layout](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#preparation)including the generated ImpEx slice JSON files and media files.
The result is a folder `generated-impex-import/` containing the generated [ImpEx export folder layout](https://ionos-wordpress.github.io/cm4all-wp-impex/migrating-content.html#preparation)containing the ImpEx slice JSON files and media files.
This export can now be imported into WordPress using [ImpEx CLI](https://ionos-wordpress.github.io/cm4all-wp-impex/impex-cli.html) :
_(Replace the `<placeholder>` with your own values.)_
> Ensure your WordPress instance is empty (does not have any pages/posts/media).
> Ensure your WordPress instance is empty (does not contain any pages/posts/media).
After executing the command the website contents are imported into your WordPress instance.
Expand All
@@ -54,13 +65,25 @@ Possible improvements:
- The navigation bar could be converted to a custom WordPress nav_menu.
But : navigation is different handled in FSE and classic themes. In a FSE you would generate a [Navigation block](https://wordpress.org/support/article/navigation-block/), in a classic theme it works different. In other words it depends on the target WordPress environment how to take over navigation.
Navigation is different handled in FSE and classic themes. In a FSE you would generate a [Navigation block](https://wordpress.org/support/article/navigation-block/), in a classic theme it works different. It depends on the target WordPress environment how to take over navigation.
- Styles are ignored in the example.
Because it depends on the goal of the transformation. If the content should be styled completely by a WordPress theme providing the complete styling, this is not needed.
But if needed, style properties like fonts and colors could be introspected and transformed to FSE theme.json settings.
- Contact form will be taken over as `core/html` block. Submitting the form does not work in the example.
WordPress/Gutenberg does not provide a generic Form block. There is no option to convert the HTML form to something matching using plain WordPress / Gutenberg.
But the form could be easily converted into a [Ninja Form](https://ninjaforms.com/) or any other form builder plugin available for WordPress.
- Styles are also not taken over in the example.
To keep the example simple and working without depending on additional plugins like [Ninja Forms](https://ninjaforms.com/)the example ist just converted to a `core/html` block.
Because it depends on the goal of the transformation. If the content should be placed in a WordPress theme providing the complete styling, this is not needed. But if needed, style properties like fonts and colors could be introspected and transformed to FSE theme.json settings.
_So it depends on your target WordPress environment (and available plugins) how the conversion will be implemented._
- The overall layout (header/footer/main section) could be converted to [FSE part templates](https://developer.wordpress.org/themes/block-themes/templates-and-template-parts/).
- The overall layout (header/footer/main section) is also ignored (but could be converted to [FSE part templates](https://developer.wordpress.org/themes/block-themes/templates-and-template-parts/)).
But : as you might guess - all these improvements may vary depending on the goal.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
"description": "Foundation for transforming any data to Gutenberg block annotated WordPress content into WordPress ImpEx Plugin (https://github.com/IONOS-WordPress/cm4all-wp-impex) export format",
"tags": [
"version": "1.3.2",
"description": "Foundation for transforming any data to Gutenberg block annotated WordPress content into WordPress ImpEx plugin (https://github.com/IONOS-WordPress/cm4all-wp-impex) export format",
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Documentation is in a very early stage and is not yet complete.
It's available at the [Impex Plugin GitHub pages](https://ionos-wordpress.github.io/cm4all-wp-impex/)
It's available at the [Impex plugin GitHub pages](https://ionos-wordpress.github.io/cm4all-wp-impex/)
Please file bugs and feature requests at the [Impex Plugin GitHub issues](https://github.com/IONOS-WordPress/cm4all-wp-impex/issues)
Please file bugs and feature requests at the [Impex plugin GitHub issues](https://github.com/IONOS-WordPress/cm4all-wp-impex/issues)
= Why ImpE written in PHP 8 ? =
Expand All
@@ -64,9 +64,9 @@ Because PHP 8
* allows a much cleaner PHP code
The Plugin version available here (at WordPress plugin directory) is transpiled down to PHP 7.4
The plugin version available here (at WordPress plugin directory) is transpiled down to PHP 7.4
If you prefer to use the PHP 8 version, you can download it from the [ImpEx WordPress Plugin GitHub repository](https://github.com/IONOS-WordPress/cm4all-wp-impex)
If you prefer to use the PHP 8 version, you can download it from the [ImpEx WordPress plugin GitHub repository](https://github.com/IONOS-WordPress/cm4all-wp-impex)