JSON plugin for Grouper Evolution

Grouper - Documentation

JSON plugin

The JSON plugin converts JSON documents to RSS. It requires additional configuration to define the mapping between the JSON structure 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. A helper plugin is available to handle the configuration and extra processing needed for YouTube's JSON API.

Installation:
To use the JSON plugin, json.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 JSON plugin must be loaded before any helper plugins are loaded.

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

Helper Plugin Developer Technical Information

Helper plugins must set certain configuration options in the JSON plugin to define the mapping from the source JSON structure 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 JSON 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:

'channel'=>array(
- 'base' =>'path/to/the/element/containing/the/channel/data', // see notes on path formats below
- 'child'=>array(
  - '<RSS element name>'=>array( // repeat this for each RSS element
    - 'src'=>'path/from/"base"/to/source/element',
      or
      'src'=>array(
      - 'path/to/preferred/source/element',
      - 'path/to/second/choice/source/element' //etc. -- see notes below
      ),
      or
      'val'=>'static text to use as the value for this element',
    - 'required'=>1, // if an element is marked required, but it's "src" cannot be found, it's parent element will not be created
    - 'is'=>'>one of: link, date, html-allowed<', // this value triggers additional processing
    - 'process'=>'name of function to use to perform additional processing on this element', // see notes below for the function prototype
    - 'process-children'=>'name of function to process any child elements of this element after they have all been built', // see notes below for the function prototype
    - 'attr'=>array(
      - 'attribute name'=>array(
        
        'src' or 'val'... // the same as with elements
        
        'is'=>'<link or date>', // note: not "html-allowed"
        
        'process'... // the same as with elements
        
        'required'... // the same as with elements
        
        ),
      ),
    - 'child'=>array(
      // mappings for any child elements, with the same structure as for ['channel']['child']
      ),
item'=>array(
- 'base'... // as with 'channel'
- 'child'... // as with 'channel'

Paths to elements and attributes
Paths to source elements and attributes are specified using a subset of XPath syntax.

'base' (as a child of either 'channel' or 'item') must be the path to an element. It must begin from the document root element, but must not start with a "/".
'src' can be a path to an element. It must begin from the 'base' of the enclosing 'channel' or 'item', and need not start with a "/".
An element with a child element with a specific value may be similarly indicated like this:

'foo[bar="qwerty"]/asdf'

The preceding points to the contents of the "asdf" element which is a child of the "foo" element whose "bar" child element has the value "qwerty". The value is case sensitive and must be an exact match, except that leading and trailing space is trimmed from the actual element value before comparison.
When more than one element with the same name exists, one may be selected using a numeric index like this:

'foo[3]'

The preceding indicates the third element named "foo".
Some of the above may be combined. For example, the following selects the value of an "asdf" which is the child of a "bar" element which is the child of a "foo" element where the "bar" element's first child element named "foobar" has a "rel" child whose value is "qwerty":

'foo/bar[foobar[1]/rel="qwerty"]/asdf'
Some of the above may not be combined. For example, this syntax, where two predicates are combined (the value of the first "foo" element if it's "bar" child's value is "qwerty"), is not supported:

foo[1][bar="qwerty"]
When multiple elements are found that meet the entire specified criteria, the first one will be used.

Process and Process-Children Callback Functions
The prototype for "process" and "process-children" functions is:

function FunctionName($element_name, $source_data)

$element_name is the name of the RSS element being created. 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.