Using XPath to Retrieve, Modify, And Filter File Elements

WP All Import uses PHP's XPath 1.0 support to allow for powerful manipulation of your data file during import. This allows you to quickly group and limit the fields that are pulled into a particular field. You can also perform simple text replacement.

Note: Most XPath statements that work directly in the SimpleXMLElement::xpath function will work in WP All Import: https://www.php.net/manual/en/simplexmlelement.xpath.php.

Note: If typing text into the import configuration with literal curly braces, the opening curly brace must be escaped with a backslash – \{something}

What is XPath?

Officially, "XPath is a language for addressing parts of an XML document...": https://www.w3.org/TR/1999/REC-xpath-19991116/

What that means in practice is that XPath is used behind the scenes in WP All Import to group and iterate through the data from your import file. Because of that, you have the opportunity to use custom XPath expressions to manipulate data during the import.

But How Do I Use It?

Say you have an import file with some image elements like this:

You could drag those elements to the Images section one by one, which is fine if you only have a few and the number of image elements remains the same:

However, what do you do if you have dozens per record, and each record could have any number of image elements? That's where the power of XPath can greatly simplify your import configuration.

Here's an XPath statement that would grab all of the images, regardless of the number in each record:

{./*[starts-with(local-name(), 'image')]}

You simply place this in the Images section:

Obtain Comma-separated List with XPath

If you have multiple nodes with similar data, you can remove the [1] part of the XPath to return a comma-separated list. For example, look at this XML:

Doing this:

{images[1]/image}

Would return the following:

image_example_1.jpg, image_example_2.jpg, image_example_3.jpg, image_example_4.jpg, image_example_5.jpg

XPath Cheat Sheet

Below are some usage examples for XPath 1.0 in WP All Import.

Access One Value Based on Another

{prop[propid = '144']/value[2]}

Access One Value Based on Another (When It’s An Attribute @):

{propertyList[1]/propertyGroup[@name="COLOR"]}

Access One Value Based on Another From Different Node

{specs/spec[./name="namegoeshere"]/value[1]}
{comments/item_3[./language="fr"]/title[1]}

Use XPath Position to Control How Many Records to Import

[FOREACH({Pic[position() <= 10]})]
{.},
[ENDFOREACH]

Additional Resources

https://developer.mozilla.org/en-US/docs/Web/XPath

https://www.w3schools.com/xml/xpath_intro.asp

Related Docs

Explains how to run PHP functions in your import when using WP All Import.

Processing and Grouping Multiple Elements with FOREACH Loops.

Learn how to use IF statements with WP All Import.