-
Notifications
You must be signed in to change notification settings - Fork 139
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'release/5.1.2' into main
- Loading branch information
Showing
43 changed files
with
511 additions
and
219 deletions.
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,17 @@ | ||
| # Element Types | ||
|
|
||
| Selecting which Element Type to import into is the first step in using Feed Me. As each Element Type is different, you'll have different attributes to map depending on which you'd like to create. | ||
| Selecting which element type your import targets is the first step in using Feed Me. As each element type is different, the presented [mapping](../feature-tour/field-mapping.md) options will be unique. | ||
|
|
||
| ## Built-in Importers | ||
|
|
||
| Feed Me can import content for the following element types out of the box: | ||
| The following element types are supported by Feed Me, out of the box: | ||
|
|
||
| - **Core element types:** entries, categories, tags, assets, and users | ||
| - **[Craft Commerce](https://plugins.craftcms.com/commerce):** products | ||
| - **[Digital Products](https://plugins.craftcms.com/digital-products):** digital products | ||
| - **[Calendar by Solspace](https://plugins.craftcms.com/calendar):** events | ||
| - **[Verbb Comments](https://plugins.craftcms.com/comments):** comments | ||
| - **[Core element types](https://craftcms.com/docs/4.x/elements.html):** Assets, categories, entries, tags, and users; | ||
| - **[Craft Commerce](https://plugins.craftcms.com/commerce):** Products and variants; | ||
| - **[Digital Products](https://plugins.craftcms.com/digital-products):** Digital products; | ||
| - **[Calendar by Solspace](https://plugins.craftcms.com/calendar):** Events; | ||
| - **[Verbb Comments](https://plugins.craftcms.com/comments):** Comments; | ||
|
|
||
| ::: tip | ||
| Plugins can add support for their own [custom element types](../developers/element-types.md), as well. | ||
| ::: |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,102 @@ | ||
| # Field Mapping | ||
|
|
||
| Field Mapping provides an interface to match items in your feed to fields in Craft. Depending on the element you’ve selected to import into will determine what fields you have available to map against. | ||
| Now that you’ve told Feed Me where your data comes from, it’s time to define how individual items in the feed map to new or existing elements in Craft. | ||
|
|
||
| While the specifics will vary widely depending on your content model (and the structure of the incoming data), the same pattern applies to most map configuration: | ||
|
|
||
| 1. Find the _target_ field in the **Field** column; | ||
| 1. Choose a _source_ for that field’s data from the menu in its row’s **Feed Element** column; | ||
| 1. Customize options for the type of data being imported; | ||
| 1. (Optional) Set a static or dynamic [default value](#default-values); | ||
|
|
||
| ## Native Fields | ||
|
|
||
| The native fields you have available to map against depend on the element type you’ve selected as the target for the import—for example, entries support a **Title**, **Slug**, **Parent**, **Post Date**, **Expiry Date**, **Status**, and **Author** in addition to the [custom fields](#custom-fields) attached via its field layout. | ||
|
|
||
| ::: tip | ||
| Native fields have similar options to [custom fields](#custom-fields), so we’ll only cover the novel ones, in this section. | ||
| ::: | ||
|
|
||
| ### Element IDs | ||
|
|
||
| You can map data in your feed to the Element ID, which is useful if you know for certain an element you want to update. This can be when updating for content in other locales, or bulk-updating existing items. | ||
| You can map data in your feed to the element ID, which is useful if you are certain which element you want a given feed item to update. This can be when updating for content in other locales, or bulk-updating existing items. | ||
|
|
||
| ::: danger | ||
| Do not use this when importing new data. If you’re importing your content from another system (ExpressionEngine, WordPress, etc.), your new content will almost assuredly not have the same ID between systems. This is how Craft’s Elements work, and if you specify the wrong Element ID to update, you could be updating the wrong content altogether (an Asset when you meant to update an Entry). | ||
| Do not use this when importing “new” data! Content from another system (ExpressionEngine, WordPress, etc.) will _not_ have the same IDs as their corresponding elements in Craft, by virtue of how records are created in the database. If you specify the _wrong_ element ID (deliberately or coincidentally), you run the risk of updating completely unrelated content (i.e. an asset when you meant to update an entry). | ||
|
|
||
| There are only two situations in which setting IDs is recommended: | ||
| - When re-importing data that was exported from Craft, then modified; | ||
| - Importing or synchronizing data from external systems that already track Craft element IDs; | ||
|
|
||
| In most cases, incoming data should be matched based on a different [unique identifier](#unique-identifiers). | ||
| ::: | ||
|
|
||
| ### Unique Identifiers | ||
| ## Custom Fields | ||
|
|
||
| It's important to select a Unique Identifier for your feed to assist with the Import Strategy you’ve chosen. When comparing against existing entries, it will compare the fields you select here with the data in your feed. Most commonly, this would be the Title for the element, but is also a good idea to be against a unique ID. | ||
| Like native fields, each custom field type’s configuration options depend on what kind of data it stores. | ||
|
|
||
| ::: danger | ||
| Updating content based on a Unique Identifier will not work for content stored in Matrix and other nested, Matrix-like fields such as Super Table and Neo. | ||
| ### Scalar Data | ||
|
|
||
| Text, numbers, booleans, and other basic data types require no additional configuration. Color, dropdown, email, lightswitch, money, radio, and URL fields all use “scalar” values. | ||
|
|
||
| ### Dates | ||
|
|
||
| Feed Me can parse [most date formats](https://www.php.net/manual/en/function.strtotime.php), but to handle cases where it may be ambiguous (i.e. `01-02-2023`), you can lock the mapping to a specific pattern. | ||
|
|
||
| ### Relational Fields | ||
|
|
||
| When setting up related content through an assets, categories, entries, tags, or users field, you will be asked how Feed Me should locate the referenced element(s). | ||
|
|
||
| For example, if you were importing a list of AKC winners that contained a `breed` property with values like `Dachshund` or `Greyhound`, you might tell Feed Me to look up existing _Breed_ entries by their **Title**, and to **Create entries if they do not exist**. The same holds true for other element types and their corresponding relational field types. | ||
|
|
||
| #### Nested Fields | ||
|
|
||
| When importing relational data, you have an opportunity to map values onto those elements’ fields, as well. Enable **Element fields (x)** to expand controls for those nested fields. | ||
|
|
||
| ::: warning | ||
| Keep in mind that nested field values will be applied uniformly to all relations. | ||
| ::: | ||
|
|
||
| ### Default Value | ||
| ### Matrix | ||
|
|
||
| See the [Importing into Matrix](../guides/importing-into-matrix.md) guide to learn more about this special field type. | ||
|
|
||
| ### Plugin Fields | ||
|
|
||
| Feed Me comes with support for the following plugin-provided field types: | ||
|
|
||
| You can set a default value for any field, and depending on the field, this may be in the form of a text field or a select field. You can also provide a default value using shorthand Twig (if you enable `parseTwig` in your [Configuration](../get-started/configuration.md)), referring to other fields in the element you're importing. | ||
| Field Type | Developer | ||
| --- | --- | ||
| [Calendar Events](https://plugins.craftcms.com/calendar) | Solspace | ||
| [Commerce Products](https://plugins.craftcms.com/commerce) | Pixel & Tonic | ||
| [Commerce Variants](https://plugins.craftcms.com/commerce) | Pixel & Tonic | ||
| [Entries Subset](https://plugins.craftcms.com/entriessubset) | Nathaniel Hammond | ||
| [Google Maps](https://plugins.craftcms.com/google-maps) | Double Secret Agency | ||
| [Linkit](https://plugins.craftcms.com/linkit) | Pressed Digital | ||
| [Simplemap](https://plugins.craftcms.com/simplemap) | Ether Creative | ||
| [Super Table](https://plugins.craftcms.com/supertable) | Verbb | ||
| [Typed Link](https://plugins.craftcms.com/typedlinkfield) | Sebastian Lenz | ||
|
|
||
| ::: tip | ||
| Make sure you select `Use default value` in the “Feed Element” dropdown, otherwise it won’t work! | ||
| Other fields that store simple text values (like [Redactor](https://plugins.craftcms.com/redactor)) will work automatically. | ||
| ::: | ||
|
|
||
|  | ||
| ## Default Values | ||
|
|
||
| The screenshot above shows three columns. The first is for your Craft field, the second is a dropdown for selecting the node in your feed, and the third is for setting the default value. | ||
| When the source for a native or custom field is set to “Use default value,” you may provide a value in the third column that will supersede any default value defined by the field itself. If `parseTwig` is enabled in your [Configuration](../get-started/configuration.md), textual fields are treated as Twig “object templates,” and have access to other fields on the element you're importing: | ||
|
|
||
| You’ll notice the `Assets` field has a Plain Text row in slight grey below it. This represents a field on the element itself. | ||
| ```txt | ||
| {title} was last imported on {{ now | date }} | ||
| ``` | ||
|
|
||
| ## Unique Identifiers | ||
|
|
||
| It's important to select a **unique identifier** for your feed to assist with the **Import Strategy** you’ve chosen. When comparing against existing entries, it will compare the fields you select here with the data in your feed. In addition to the element’s native fields (like title, slug, status, or ID), you may use custom field values for matching. | ||
|
|
||
| ::: warning | ||
| There are _some_ limitations to the matching engine, though—it will not work for content stored in Matrix and other nested, Matrix-like fields such as Super Table and Neo which can’t be easily or reliably serialized. | ||
| ::: | ||
|
|
||
| ::: danger | ||
| If data that is used as part of a unique identifier is altered between imports by a user (or any other means—including a different import), Feed Me may not be able to match it again! When combined with the **Delete missing elements** [import strategy](creating-your-feed.md#import-strategy), this can result in inadvertent data loss. | ||
| ::: |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.