Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/akvo/akvo-json-data-plugin

Repository for the Akvo JSON Data Plugin for WordPress
https://github.com/akvo/akvo-json-data-plugin

Last synced: 5 months ago
JSON representation

Repository for the Akvo JSON Data Plugin for WordPress

Awesome Lists containing this project

README 

          
The Akvo JSON Data Feed Plugin for WordPress.

=============================================



The data feed plugin provides an API and a Wordpress shortcode for

fetching items from a JSON formatted datafeed and caching them for a

specified interval.  If Curl is used as backend, also XML formatted

feeds are supported.



Data items are cached for a duration of twice the configured refetch

interval for the feed.  If the current item is older than the refetch

interval a refetch is attempted.  On failure the old item is returned.

The refetching frequency on failure is restricted to one attempt per

30s, unless the url changes on the feed.



Shortcode data_feed

-------------------



The shortcode can be used to extract, convert to a string and escape a value from the current data item in the feed.



        [data_feed name="my-example-data-feed" url="http://example.com/json-feed" interval="360" query="fieldname->subfield"]



The shortcode will be substituted with the selected value in the item, or an error message surrounded by tags `...`.



### Parameters



* **name** is mandatory and specifies an identifier for the feed.

* **url** is optional if a feed with the specified name already have been declared and the feed handle exists in the database.  This is the url of the feed.  ** Note: **  due to a bug in Wordpress it is not possible to include ampersand characters encoded as `&` in the url.  It should work to use `&` though.

* **interval** is optional and specifies the caching interval in seconds.  If the current item have expired, a new item will be fetched on demand.  Defaults to the saved interval if the feed handle exists in the database, or to 24h if the handle doesn't exist.

* **query** is optional and can be used to select a particular field of the item.  The syntax is a list of fieldname or array indicies separated with the delimiter '->'.  Fieldnames are used verbatim, (i.e., spaces and other characters are included in the field name.).

* **pagination_policy** is optional and can be used to set the pagination policy on the feed.  (See below.)



Plugin architecture

-------------------



The plugin consists of three basic components:



* **feed cache** A chain of caches, with a network backend for fetching and caching items.

* **feed store** A persistant storage for *feed handles*.

* **object query language** A language for fetching data from a feed item.



Also there is an administrative interface for editing (overriding url and interval) and deleting feed handles.  (Not yet completed.)



Pagination support and the merging feed cache

---------------------------------------------



A feed can have its items divided into *pages* where each page is fetched from a separate *sub feed* which have its own URL.



The merging feed supports transparently fetching pages and merging them into one item.  The merging feed cache is enabled by specifying a *pagination policy*.



The merging feed cache uses the following components:



* **Page url resolver** is a component that generates the URL to the

    next page, given the previous page, the URL of the main feed, and

    the page number.  The default implementation - 'next' - obtains

    the URL from a field with the name 'next' in each page.  The field

    name is configurable via the pagination policy.  Currently

    available implementations: 'next', 'null'.

* **Page update checker** is a component that determines which pages

    have been updated recently and needs to be refetched.  The default

    implementation - 'version-array' - obtains an array of *versions*

    from the first page in the item.  The field is by default named

    'page_versions' and is configurable via the pagination policy.

    Currently available implementations: 'version-array', 'null'.

* **Object merger** is a component that is used to merge the pages

    into one page.  This is currently not configurable as the default

    implementation is expected to cover most use cases.



### Pagination policy



The pagination policy is specified using the following syntax:



    page-url=[:]&page-update-check=[:][&limit=]



For example it can be passed as a parameter to the short code:



    [data_feed name="my-example-data-feed" url="http://example.com/json-feed" interval="360"

               pagination_policy="page-url=next:next-page-url&page-update-check=null&limit=20"]



In this example the page url resolver is set to 'next' with the field

name 'next-page-url' and the page update checker is set to 'null'

which always indicates that all pages are updated.



The page URL of the first page is taken from the 'url' parameter and

of subsequent pages the page url is taken from the field

'next-page-url' of the preceeding page.  The last page is the page

where 'next-page-url' is missing or is empty.  An exception will be

thrown if the page URL's form a loop.



The 'null' page update checker always indicates that all pages have

been updated, which effectively forces a refetch of all pages every

time the main item is refetched.



The limit parameter sets a limit on the number of pages that will be

fetched and merged.



The pagination policy can be overridden in the administration

interface.



PHP functions \DataFeed\DataFeed::item and \DataFeed\DataFeed::handle.

---------------------------------------------------------------------



The plugin API functions can be used to fetch feed items in skins and other templates.



	/**

	 * @param string $name     The name of the feed.

	 * @param string $url      The url of the feed.  If the feed handle already exists, the default will be whatever is stored in the database.

	 * @param int    $interval The fetch interval in seconds.  The default interval is 24h.

	 *

	 * @return FeedHandle which can be used to fetch the current item of the feed using the method getCurrentItem().

	 *

	 * @throws DataFeed\NonexistingFeedException if the url is omitted and the feed doesn't already exist.

	 */

	public static function handle( $name, $url = null, $interval = 86400, $pagination_policy = null )



	/**

	 * @param string $name     The name of the feed.

	 * @param string $url      The url of the feed.  If the feed handle already exists, the default will be whatever is stored in the database.

	 * @param int    $interval The fetch interval in seconds.  The default interval is 24h.

	 *

	 * @return object The current item of the feed as an object.

	 * WARNING: the contents of the item is untrusted data, no

	 * validation or escaping has been made on the fields by the data

	 * feed plugin.

	 *

	 * @throws DataFeed\NonexistingFeedException if the url is omitted and the feed doesn't already exist.

	 */

	public static function item( $name, $url = null, $interval = 86400, $pagination_policy = null )



Widget

------



The plugin bundles a widget which can be used for presenting data feed

items from which title, time, text, link url and thumbnail image url

can be extracted from.  See the widget configuration under appearance

in the Wordpress administration dashboard.



Upgrade

-------



Inactivate the plugin before upgrading, to allow database schema updates to take effect.