For arlanix/product-feed 1.0.0

Field catalogs

This page is for the developer who adds a platform to the feed's Type list, or corrects what the module knows about one. A field catalog describes a platform's fields: which ones it requires, how long a text may be, which values it accepts, and where each field's value usually comes from. A mapping may still hold fields the catalog does not name.

The module reads every catalog from the etc/feed_catalog.xml files of the enabled modules. Each catalog becomes:

a choice in the feed form's Type list, and in the feed grid's Type column;
an entry under Field catalogs in the mapping's Copy from, which fills the mapping from the catalog's defaults;
the rules a run checks the rows against. A row that breaks one is a warning in Why? and Preview, never a reason to leave the product out. Only the mapping's Required mark, dictionaries and row transformers leave products out.

The module ships the catalogs generic, google_shopping, meta_catalog, tiktok_catalog, pinterest_catalog, snapchat_catalog and microsoft_shopping, in vendor/arlanix/module-feed/etc/feed_catalog.xml.

Add a feed type

To add a type, create etc/feed_catalog.xml in your module:

<?xml version="1.0"?>
<catalogs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="urn:magento:module:Arlanix_Feed:etc/feed_catalog.xsd">
    <catalog type="example_shopping" label="Example Shopping">
        <field name="sku" required="true" maxlength="64" label="SKU" default_attribute="sku"/>
        <field name="name" required="true" maxlength="200" label="Name" default_attribute="name"
               default_modifiers="strip_tags|truncate:200"/>
        <field name="price" required="true" label="Price" default_resolver="price"/>
        <field name="stock" required="true" values="in stock,out of stock" label="Stock"
               default_attribute="stock_status" default_dictionary="Example stock"/>
        <field name="condition" values="new,used" label="Condition" default_value="new"/>
        <field name="ean" label="EAN"/>
    </catalog>
</catalogs>

Then clear the configuration cache, where the merged catalogs are kept:

bin/magento cache:clean config

Example Shopping is then in the feed form's Type list. A feed of that type is mapped and delivered like any other: the channel decides where it goes, the catalog only what it holds.

The catalog element

Attribute	Value
`type`	Required. The code a feed stores: lower-case letters, digits and underscores, starting with a letter. Keep it once a feed uses it.
`label`	What the form and the grid show. Without it, the code with spaces and capitals: `example_shopping` shows as Example Shopping.

The field element

Attribute	Value
`name`	Required. The field's name in the platform's file or API, which becomes a column of the file.
`required`	`true` for a field the platform cannot do without. Copy from ticks Required on its row, and a run warns about a product whose value is empty when the row is not ticked.
`maxlength`	The longest text the platform takes, in characters. A run warns about a longer value and suggests a `truncate` modifier.
`values`	The only values the platform accepts, separated by commas. Spaces around each are dropped; the comparison is exact, case included. A run warns about any other value.
`label`	The field's name in messages. Without it, `name`.
`default_resolver`	The alias of a resolver that Copy from sets as the row's source, such as `price`. See Resolvers.
`default_attribute`	The attribute Copy from sets as the row's source, such as `sku` or `parent.sku`.
`default_value`	The fixed value or template Copy from sets as the row's source, such as `new` or `{name} {color}`.
`default_dictionary`	The name of the dictionary Copy from attaches to the row, as Arlanix → Dictionaries shows it.
`default_modifiers`	The modifiers Copy from puts on the row, as they are typed in the mapping: `strip_tags

What Copy from builds

Copy from adds one mapping row for each field that is required, has a default source, or names a dictionary, in the order the catalog lists them. Fields with none of these are left for the store to add.

A row's source is the first of default_resolver, default_attribute and default_value that the field sets. A resolver's arguments are left empty: an argument, such as an image size, is a choice about the store's own feed, and the row shows the control for it.

A default_dictionary is looked up by name when Copy from runs. If no dictionary has that name, the row gets none, without a message. Ship the dictionary with your module, in a data patch through Arlanix\Feed\Api\DictionaryRepositoryInterface, or ask the store to create it under Arlanix → Dictionaries before they copy.

Copying is the only time the defaults are read. A feed's saved mapping is its own; changing a default changes the next copy, not existing feeds. The required, maxlength and values rules are read on every run, so a change to them shows in the next run's warnings.

Change a field of another catalog

Files are merged by catalog type, then by field name, so a catalog in your module can change one attribute of a field another module declares. For example, to make Copy from read the brand of a Google Shopping feed from an attribute named brand:

<catalogs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="urn:magento:module:Arlanix_Feed:etc/feed_catalog.xsd">
    <catalog type="google_shopping">
        <field name="brand" default_attribute="brand"/>
    </catalog>
</catalogs>

The field keeps every other attribute it had. Your module must load after Arlanix_Feed, through <sequence> in its etc/module.xml, for its value to win; see Extend the module.