诗语，作者 WP All Import 文档

WP-CLI

You may run an import using WP All Import's WP-CLI integration. Imports run with WP-CLI tend to process about 50% faster than those run through the WordPress admin panel.

You can list the imports to find the ID you want to run:

$ wp all-import list

Then, to run an import, you just need to specify the import ID:

$ wp all-import run

Or, if you prefer to run several imports in sequence, a comma-delimited list of import IDs can be specified:

$ wp all-import run ,,

While imports can be run with WP-CLI, you still need to create and edit them in the WordPress admin panel. After saving your import, you can see the import ID on the Manage Imports page, or use the list command above.

Options

A single import ID, or comma delimited list of IDs, to run.

$ wp all-import run 1
$ wp all-import run 1,2,3

[--force-run] A flag to force the import to run even if it's already triggered.

$ wp all-import run 1 --force-run

[--disable-log] A flag to disable the import history log for this run.

$ wp all-import run 1 --disable-log

Add-On Compatibility

In order to be run with WP-CLI, import add-ons must be written using a singleton, a class limited to a single instance. You can read more about this here: https://www.wpallimport.com/documentation/addon-dev/best-practices/

Using Hooks, Filters, and Actions with WP All Import and WP All Export

WordPress makes heavy use of filters and actions to allow for its extensible nature. Collectively called hooks, those filters and actions do the heavy lifting to allow WordPress to support plugins and themes. WP All Import and WP All Export both have their own set of filters and actions that allow for modifying how each import or export works.

How Do Actions Work?

Actions are essentially a simple means for custom code you write to be called automatically when some action/event takes place. For example, say an order is made in WooCommerce and you wanted to trigger an alert at a remote API endpoint. You could call your code with the appropriate hook to make that possible.

Here's the full explanation of Actions in WordPress: https://developer.wordpress.org/plugins/hooks/actions/

How Do Filters Work?

In simplest terms, filters are actions that expect some piece of data to be returned. These filters will include a piece of data, your code would be expected to manipulate that data, then it would be returned for further processing.

Here's the WordPress reference for Filters: https://developer.wordpress.org/plugins/hooks/filters/

What Else Should I Know?

Most of the filters and actions included in WP All Import can be used directly in the Function Editor. For those that can't, it will be noted in our Action Reference and any example snippets as appropriate.

What's Next?

WP All Import Action Reference

Helpful Example Code Snippets

Inline PHP

Add-On API

Export ACF Repeater and Group Fields to CSV or XML

ACF Repeater and ACF Group fields are automatically detected by WP All Export and added to the ACF section in Available Data.

Exporting ACF Repeater Fields

The ACF Repeater field allows content to be added as a set of subfields, like slides, team members, etc. Any ACF field can be included as the child of a repeater field. This field acts as a parent to a set of subfields that can be repeated again and again.

For example, this repeater field contains a number field and a text field:

During export, repeater fields add a column for each field that it contains. Following the previous example, this ACF repeater field would export:

A Repeater_number column that contains all repeated numbers separated by a pipe ( | ) character.A Repeater_text column that contains all repeated text strings separated by a pipe ( | ) character.

Here's what that ACF export file looks like:

Exporting ACF Group Fields

The ACF Group field acts as a parent, with grouped fields acting as child items. The parent group field does not contain any data but rather acts as a container for other fields. It is primarily used to organize the ACF user interface.

For example, this ACF group field contains a text field and an image field:

The ACF group field adds an export column for each field that it contains. Following the previous example, this ACF group field exports:

A Group_text column that contains the inserted text string.A Group_image column that contains the URL to the selected image.

Here's what that ACF export file looks like:

How to Map Custom Fields

Mapping is used when the value you need imported to your site is different than the value in your file. A visual interface is available for mapping for Custom Fields and Custom Taxonomies. To map elsewhere, you can use a custom PHP function.

Visual Mapping Tool

For example, you may have a file with product categories that are written in Dutch, but you want to import these products to categories that already exist on your site with English names.

Or, your theme or plugin requires the value of a Custom Field it uses be either 1 or 0, but in your XML or CSV file, the values are expressed as Yes or No.

You need to map the values in your file to the values you actually imported to your site.

Example – Mapping For A Dropdown

In the previous article, Importing to Theme & Plugin Fields, we explained how to detect the fields used by your theme or plugins, and their possible values.

Our theme has a dropdown to specify whether a Property Listing is for rent, or for sale.

Rent or Buy Example

The field name is 「rob_value」, and the possible values, as stored in the database, are 「Rent」 and 「Buy」.

Field Example

Note: You can see the values as they are stored in the database by clicking inside the Value textbox for the 「rob_value」 field in WP All Import. The values stored in the database may not be the same as values shown inside the select box in the theme. We must map to the values as they are stored in the database.

Our XML file has a element that is set to FORSALE if the property is for sale (Buy), and FORRENT if the property is for rent (Rent).

XML Data

Without mapping, simply dragging & dropping to the Value box for rob_value would not work, because the value of is not correct for our theme.

To solve this problem, we use the Mapping feature.

Mapping

Click Field Options… and then click Mapping.

A dialog box will pop up allowing you specify the mapping rules.

Mapping Rules Example

Now, when the import is run, FORSALE in your file will be translated to Buy, and FORRENT in your file will be translated to Rent, so your data will be imported correctly, as per the requirements of your theme and plugins.

Export ACF Choice Fields to CSV or XML

The available ACF choice fields would appear under Available Data › ACF. To add a field, drag and drop from right to left:

The following ACF choice fields that can be exported: Select, Checkbox, Radio Button, Button Group, and True/False. Here's more on each field, along with an example of what's exported:

Select: The Select field contains a drop-down list with choices to select fromCheckbox: The Checkbox field contains a list of check-able inputs. Multiple values are separated by a pipe ( | ) character.Radio Button: The Radio Button field contains a list of selectable inputs.Button Group: This field enables a neat UI to select a value.True / False: This field allows selecting a value of either 1 (true) or 0 (false).

Processing and Grouping Multiple Elements with FOREACH Loops

WP All Import supports a FOREACH syntax that makes it easy to make adjustments to multiple elements from your file at the same time. This is useful when building custom HTML in the Content section, or when preparing other data from your file for fields that require a specific format.

Here's an example showing how to implement a FOREACH loop in WP All Import.

Here's an example XML file that contains some image information – It is assumed the default (/element) was chosen as the XPath in Step 2.

My Caption
Another Caption
We will use these for alt text
More text

Here』s an example import template where FOREACH is used to loop through each img element in the above XML.

[FOREACH({images/img})]
{.}
[ENDFOREACH]

Passing {images/img} to the FOREACH means we will loop through each element matching that XPath. To get this XPath, just drag one of the matching elements from the XML tree on the right to the post content box. You』ll get something like {images/img[1]}. Just remove the [1] and you』re good to go.

Inside the FOREACH loop, the XPath is relative. You can』t access 「higher-level」 elements inside the FOREACH loop. For example, you wouldn't be able to access the 'id' element from within the FOREACH loop.

{@url} will return the url attribute of the element you are looping through - '1-1.jpg', '1-2.jpg', etc.

{.} will return the value of the element you are looping through – in this case, each img - 'My Caption', 'Another Caption', etc.

{element_name} will return the value of the element_name child element of the element you are looping through.

Inline PHP

IF Statements

Serialized Fields

If you aren』t a developer and don』t know what 「serialization」 is, this article will probably be over your head.

Developers, read on…

In very rare cases, some themes store multiple data points in a single field. Themes shouldn』t do this. It』s not nice, and the practice is generally frowned upon. But, some do. These fields are often called 「serialized」 fields.

Serialized Selected

Serialized Dialog

You can either use the serialization feature in WP All Import to import the key and value pairs, or you can use a custom PHP function to return the value in the proper format needed by your theme or plugin.

The Serialize feature generates an array with the key => value pairs you specify, and then returns the serialize()』d value of the array.

Export ACF Flexible Content Fields to CSV or XML

Flexible Content fields in ACF are automatically detected by WP All Export and added to the ACF section in Available Data.

ACF Flexible Content fields enable a simple block-based editor that allows using layouts and subfields to organize the data. Similar to a Repeater field, any field can be added to a Flexible Content field as a child.

This Flexible Content field has 1 layout that contains 3 subfields, a Text field, an Image field, and a Color Picker field:

When more layouts are added, each exports its own set of columns. The above field exports the following:

Flexible Content__0_text: Exports the string from the text field.Flexible Content__0_image: Exports the URL of the added image.Flexible Content__0_color: Exports the HEX code selected in the color picker.

Here's what that ACF export file looks like:

Mapping Values From Your File with IF Statements

As WP All Import allows you to use PHP functions on your data, you can create your own custom PHP functions that can be passed values from your data file, and return a certain result based on if/else conditions you set in your function.

Example A – If an element is empty

In this example, we』re checking to see if the element passed is empty or not, and returning a simple text string.

function is_element_empty($element) {
if(empty($element)) {
return "This element is empty.";
} else {
return "This element is not empty!";
}
}

Example B – If an element contains a value

In this example, we』re passing two parameters: the element from the data file that we want to check, and the value we want to search this element for.

function my_contains_function($element, $value_to_search_for) {
if (stripos($element, $value_to_search_for) !== false) {
return $element;
} else {
return;
}
}

If the element passed to this function contains the value to search for, then the element will be returned. Otherwise, an empty result will be returned.

Example C – If one element contains a greater value than another element

In this example, we』re passing two parameters again, this time in the context of comparing two elements that contain prices.

function choose_price_to_return($price1, $price2) {
if ($price1 > $price2) {
return $price1;
} else {
return $price2;
}
}

If the first element passed has a greater value than the second element, the first element will be returned. Otherwise, the second element will be returned.

Overview

In this tutorial you』ll learn how to use WP All Import to import data from your XML or CSV into any plugin or theme.

Many themes and plugins have 「custom」 places to enter in data – not just the post title and content boxes on normal Posts or Pages.

The technical term for these extra fields is Custom Fields or post meta.

WP All Import has full support for Custom Fields and can even auto-detect the names of the fields used by your themes and plugins so you don』t have to ask the author, guess, or look at any code.

Watch the video tutorial below to see how easy it is:

Auto-Detecting The Fields

For WP All Import to detect a field, it must exist at least once in your database in a published post (not draft or any other post status).

If you already have posts on your site that have the fields you want to import to filled out, WP All Import will detect the fields.

If not, simply create a dummy post, enter in dummy values for the fields you want to import data to, then publish it.

Click See Detected Fields to see the detected fields.

See Detected Fields

Once you click See Detected Fields, WP All Import will show you all of the detected fields.

Populated Detected Fields

WP All Import can also show you the different possible values for your fields. So for example, if you need to know what the possible values of a 「select」 option is, just manually create a post with the 「select」 option in every state you want to know the field value for.

Example – Select Box In OpenDoor Theme

Rent or Buy Select Field

Saving two posts, one with the select set to 「Rent」 and the other with the select set to 「Buy」, results in WP All Import auto-detecting the possible values:

Of course, you can import to fields without WP All Import auto-detecting their names and values – you just have to know the names and possible field values yourself.