RSS is extensible using XML namespaces, but not so the default syndication parser of the Feeds module. Feeds namespaces provides an RSS parser and an API to extend it.

Declaring support for a namespace: hook_feeds_namespaces()

hook_feeds_namesaces() returns an associative array keyed by namespace URL, that contains information about the namespace.

function hook_feeds_namespaces() {
  $ns['http://example.com/example-namespace-url'] = array(
    'name' => t('The name of the namespace'),
    'description' => t('A longer description of the namespace'),
    'sources' => array(
      // Available mapping sources
    ),
  );

  return $ns;
}

Mapping sources

The sources array contains information about available mapping sources. The user can select those sources on the mappings page.

This is an example feed:

<rss version="2.0">
  <channel>
    ...
    <item>
      <title>The title of the feed item</title>
      ...
    </item>
  </channel>
</rss>

To map a single element you can simply use:

'sources' => array(
  'title' => array( // the key is the name of the element <title>
    'name' => t('Title'),
    'description' => t('Title of the item'),
  ),
  ...
),

There are however more advanced settings:

Property Default Description
name required The human readable name of the mapping source. Should usually be passed through t().
description no description A description of the mapping source in a few sentences. Should usually be passed through t().
element the array key of the mapping source The name of the element to use, that is a direct child of an <item>.
xpath use element instead

Use an XPath query to get an element, relative to the current item. If the xpath property is given, element will be ignored.

If you are doing an XPath query in any namespace other than the core RSS namespace, use ns as the namespace prefix.

Note that / and // refer to the root of the whole feed. You might want to use ./ and .// instead.
attribute get the element content, not an attribute The name of the element's attribute. Use this to get attribute values, instead of the selected element's content.
attribute namespace FALSE

Only useful together with attribute, to get namespaced attributes like: <elem ns:attr="value" />

With FALSE no namespace is used for the attribute.

With TRUE the current namespace is used for the attribute.

Other than TRUE or FALSE you can directly give the namespace URL.
multiple FALSE

TRUE, to allow multiple values.

If there are multiple elements selected using xpath or if an element of the given name appears multiple times, those elements are usually ignored and only the first value is returned. But if multiple is on, you get an array of values.

If there are multiple elements and you use attribute, an array will be returned as well.
callback feeds_namespaces_default_callback Use a custom callback function to get a value. The default callback implements the element, element namespace, xpath, attribute and multiple properties. You can use your own properties for your custom callback. See "Custom callbacks" section.
default value NULL If no value is found (callback returning NULL) use this value. The default callback doesn't find a value, if no element or attribute matches.
default value callback feeds_namespaces_return_default_value The default callback returns the default value, but you can use custom logic for default values. See "Custom callbacks" section.
rewriters array() An array of rewriter callbacks or a single rewriter callback. The first callback gets the value as an argument. The return value is then used as the new value. If there are more callbacks, the value will be passed through all of them. Useful, for example, to quickly pass a value through strtotime.

 

Custom callbacks

The callback and default value callback properties allow the use of custom callbacks.
Those callbacks look like that:

function example_callback_name($namespace, $sourcename, $feed, $entry, $source) {
  ...
}
  • $namespace is the URL of the namespace specification. It will be FEEDS_NAMESPACES_RSS for the core RSS namespace.
  • $sourcename is the array key from the sources array.
  • $feed is a SimpleXMLElement. It is the whole feed.
  • $entry is the current feed entry as a SimpleXMLElement.
  • $source is an array of options. It is the source definition. It contains at least name, description, callback, default value callback and rewriters, but there can be more options specific to the callback.

The returned value will be mapped.

Altering already supported namespaces: hook_feeds_namespaces_alter()

To alter namespaces that are already declared, implement hook_feeds_namespaces_alter().

function hook_feeds_namespaces_alter(&$ns) {
  ...
}

You will be given, by reference, an array of all the namespaces. It is structured just as in hook_feeds_namespaces().

Use the FEEDS_NAMESPACES_RSS constant as the array key, if you want to alter the core RSS namespace.