====== yql Plugin ======

---- plugin ----
description: A plugin for embedding results of the Yahoo! YQL query API in a page
author     : Michael Hamann 
email      : michael@content-space.de 
type       : syntax
lastupdate : 2016-01-16
compatible : Anteater, Rincewind, Angua, Adora Belle, Weatherwax
depends    : 
conflicts  : 
similar    : 
tags       : yahoo, data

downloadurl: https://github.com/Michitux/dokuwiki-plugin-yql/zipball/master
bugtracker : https://github.com/Michitux/dokuwiki-plugin-yql/issues
sourcerepo : https://github.com/Michitux/dokuwiki-plugin-yql/
donationurl: 
----

This plugin allows to embed results from the [[http://developer.yahoo.com/yql/|YQL (Yahoo! Query Language)]] API of Yahoo! in a wiki page. The plugin only works for certain queries and certain query fields and has mainly been created because I needed to embed a certain query result. The plugin does not support queries that need authorization or return one single result (and not a list of results). It is recommended that you try out your query in the [[http://developer.yahoo.com/yql/console/|YQL Console]] in order to find the necessary parameters for the plugin.
To learn if accessing a table requires authentication, execute [[http://developer.yahoo.com/yql/console/?q=show%20tables|SHOW TABLES]] and note that tables with security=ANY do not require [[https://developer.yahoo.com/yql/guide/yql-opentables-security.html|YQL Authentication]], whereas the others do.

The results of the query are displayed as list, the individual list items can be formatted using a simple format string and support text items and links.

The plugin does also works with different renderers (like [[plugin:odt|odt]] or [[plugin:dokutexit|LaTeX]]) as it uses standard renderer functions for displaying the list of items.

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

A simple query to combine two RSS feeds:
  
  <YQL>
  select title,link,pubDate from rss
    where url in (
       'http://feeds.feedburner.com/dokuwiki',
       'http://feeds.feedburner.com/PlanetDokuwiki'
    ) | sort(field='pubDate',descending='true')|truncate(count=10)
  </YQL>

And another query, displaying a list of Sushi restaurants in San Francisco using a custom display format:

  <YQL format="%%Url|Title%% in %%MapUrl|Address%% (phone: %%Phone%%)" item_name="Result" refresh="28800">
  select * from local.search where query="sushi" and location="san francisco, ca"
  </YQL>

Here a screenshot of the output of the two examples:
  
{{https://github.com/michitux/dokuwiki-plugin-yql/raw/master/example_usage.png}}
  
===== Syntax =====

The basic syntax is:
  
  <YQL>
  your_query
  </YQL>

where your_query is the query you want to execute. Within the <YQL>-tag further options can be specified in the form option="value":
   * **format**: The format is a combination of a simple string combined with the names of the result values that shall be displayed enclosed in "%%" as in the example. As in normal DokuWiki links you can create a link by separating the name of the url field and the title field by "|".
   * **item_name**: Inside the results, the actual results items are in many cases inside a special field. The default is "item" which is also the output from the rss "table", but in other cases it can also be "Result" as shown in the example or "event" for events.
   * **refresh**: The time for which the page should be cached in seconds, the default is as for rss feeds 4 hours (14400 seconds).

===== Development =====

There are many features that are currently missing, but everything I currently need works so most probably I won't put too much work into improving it. But if you have a special use case feel free to submit feature requests, bug reports or submit even patches or pull requests on GitHub.

=== Change Log ===

{{rss>https://github.com/michitux/dokuwiki-plugin-yql/commits/master.atom date}}

=== Known Bugs and Issues ===

The plugin currently only supports certain YQL results and doesn't output any information when an error occurs.

===== Discussion =====

:!: Please don't report any bugs or feature wishes here but use the [[https://github.com/Michitux/dokuwiki-plugin-yql/issues|issue tracker]] at GitHub.