Grouper: RSS manager, XML converter, website scraper
Web This Site

Grouper - Documentation


Getting Started: Free Download | Purchase | Install
Reference: Functions | Plugins | Themes
Etc.: Configure | Affiliates


XML plugin

The XML plugin converts XML documents to RSS. It requires additional configuration to define the mapping between the other XML format and RSS, and if the original data is to be altered, rather than simply copied into RSS elements as is, requires additional code to perform the alterations. Helper plugins are provided to handle the configuration and extra processing needed for such formats as Atom 0.3 and 1.0, Amazon.com's associates XML, etc.

Installation:
To use the XML plugin, xml.php and any helper plugins must be located in the "plugins" folder inside the folder containing grouper.php. This is their default location when Grouper Evolution is installed.

Loading the plugins:
To load the plugins, use code like the following. Note that the XML plugin must be loaded before any helper plugins are loaded.

<?php
require_once '/YOUR/PATH/TO/grouper/grouper.php';
GrouperLoadPlugin('xml.php');
GrouperLoadPlugin('HELPER-PLUGIN-FILENAME');
GrouperSourceURL('http://example.com/document.xml');
GrouperShow('','CACHE-FILE-NAME');
?>

Note: if you are using Grouper version 1.4.2 or earlier, you must replace the call to GrouperSourceURL with something like the following:

GrouperSourceConf('searchdomain','example.com');
GrouperSourceConf('querystart','/document.xml');

Configuration:
The behavior of the XML plugin is configured using the function GrouperSourceConf, as follows:

GrouperSourceConf('OptionNameFromBelow','new value');

The XML plugin has the following configuration options. You will rarely, if ever, need to change any of the options other than perhaps "mustparsedate":

Helper Plugin Developer Technical Information

Helper plugins must set certain configuration options in the XML plugin to define the mapping from the source XML format to RSS, and may also provide additional functions to process the data. We recommend using one of the helper plugins included with Grouper Evolution as a starting point and model when developing your own helper plugins.

The XML to RSS mapping is defined by the "element-map" configuration setting. This setting is a nested array with the following structure. Note that pretty much everything is optional under most circumstances. If in doubt of whether you can omit something, try it out and see if it works: Paths to elements and attributes
Paths to source elements and attributes are specified using a subset of XPath syntax. Process and Process-Children Callback Functions
The prototype for "process" and "process-children" functions is:

function FunctionName($element_name, &$attributes, $source_data)

$element_name is the name of the RSS element being created. $attributes is an array containing the attributes of the source element as name/value pairs. For "process" functions, $source_data is the contents of the source element. It does not include any child elements defined in the element map, but does include any child elements from the source data. For "process-children" functions, $source_data is the fully constructed child elements.

The return value of the "process" and "process-children" functions will take the place of $source_data in the content of the RSS element that is being created.

Inline Elements
The "inline-elements" setting lists any elements whose content is unescaped XHTML or HTML (which must be well-formed XML). These elements and their children are not parsed (technically, they're immediately reconstituted) during the XML parsing phase. List the full XPath of each element as an array key with the value 1, like this:

$xmlgrouperconf['inline-elements']=array(
'/feed/subtitle'=>1,
'/feed/entry/content'=>1,
'/feed/entry/summary'=>1
);