Puzzler

Wikipedia: a key puzzle piece to complete the big picture

Puzzler makes it easy to insert bits and pieces of Wikipedia content into Drupal, keeping the information fresh as improvements are done by the community of Wikipedia editors.

Puzzler allows you to use tokens to quickly include the URL, lead image, introduction, or even full text from the Wikipedia article that matches your node title, or any title you specify. And short PHP snippets make it possible to retrieve even more data elements via the Wikipedia API. Puzzler takes into account the language of your page, and it follows Wikipedia redirects so that the match is found even if the title string is not precisely the same (differences in lower-/uppercase, singular/plural, etc.)

This gives Drupal editors as well as developers a simple and precise method to include Wikipedia content in fields (text, textarea, even Display Suite), and in views, panels, blocks, templates, etc.

Crucially, information inserted using Puzzler does not age. Depending on the caching period you specify, the included pieces of data will always get updated with fresh versions as they are edited by the Wikipedians. Gone are the times of copied-and-pasted texts dating from way back when!

Content augmentation based on Wikipedia and other data sources is becoming widely used by many sites, small and large. Google, for one, shows the same data prominently on many of their search result pages. For example, try searching for Tarsier. The information you are likely to see highlighted in the box on the right comes from Wikipedia. And you can now easily build a section like that on your Drupal site using the Puzzler module. Embedding Wikipedia snippets and images are an ideal way to enrich and complete Drupal content, and to contribute to the general trend towards reuse instead of duplication of information.

Installation^#

Token is the only additional module required.
Download Puzzler and enable it like any other module.

Recommended^#

Token Filter — you will be able to use Puzzler tokens in WYSIWYG and other long text format fields
HTTPRL — Puzzler will automatically replace drupal_http_request() calls by the more performant HTTPRL requests

Settings^#

The configuration page at admin/config/services/puzzler provides some optional settings, such as the default cache period (before a fresh version of the data is fetched from Wikipedia), fallback language, etc.

Dashboard^#

Puzzler's dashboard page at admin/config/services/puzzler/dashboard provides relevant additional data from the module, such as the number of currently cached Wikipedia API items (call them puzzles!), the list of currently available tokens, etc.

How to use^#

Tokens currently provided by Puzzler (this list is also always provided on the dashboard of the module):

[puzzler:wikipedia-matching-url] => URL of the Wikipedia article whose title matches the title of the given node.
[puzzler:wikipedia-matching-url-html] => HTML link to the Wikipedia article whose title matches the title of the given node.
[puzzler:wikipedia-matching-title] => Title of the Wikipedia article whose title matches the title of the given node.
[puzzler:wikipedia-matching-html] => HTML of the Wikipedia article whose title matches the title of the given node.
[puzzler:wikipedia-matching-intro] => Introductory text of the Wikipedia article whose title matches the title of the given node.
[puzzler:wikipedia-matching-image-url] => URL of the first image of the Wikipedia article whose title matches the title of the given node.
[puzzler:wikipedia-matching-image-html] => HTML code to show the first image of the Wikipedia article whose title matches the title of the given node.

So for example if your website has an entry with title "Solar Panels", you can enrich it with a link to Wikipedia using the token [puzzler:wikipedia-matching-url]. Puzzler will search the Wikipedia API, find out that the relevant Wikipedia entry is actually named slightly differently ("Solar panel"), and return the URL to you: https://en.wikipedia.org/wiki/Solar_panel If your node has a different language, Puzzler will recognize that, too. The same token in your Spanish-language article "Velas solares" will retrieve: https://es.wikipedia.org/wiki/Vela_solar

Any of the above tokens can be extended by one more parameter — a custom title. Depending on use case, sometimes you will want to show Wikipedia information from a particular entry that is not (exactly) matching the title of your page. All you need to do is to add another colon and set the requested title manually. E.g. [puzzler:wikipedia-matching-intro:Richard Feynman] will retrieve the introduction section of the Wikipedia article on Richard Feynman regardless the title of your Drupal page.

And if you need an illustration, say for your article on the Easter Island statues, combine the various tokens in your HTML code, such as:

<a
  href="[puzzler:wikipedia-matching-url:Moai]"
  title="Visit the Wikipedia entry on [puzzler:wikipedia-matching-title:Moai]"
>
  [puzzler:wikipedia-matching-image-html:Moai]
</a>

If the existing tokens don't get you what you need, definitely consider suggesting new ones via the issue queue — or use PHP to use Puzzler module functions directly. E.g. if you wish to retrieve the introduction to the French-language Wikipedia article on Socrates and cache it for a week, use:

<?php
$puzzler_options = array(
  'wppage' => 'Socrate',
  'wplang' => 'fr',
  'wpprop' => 'extracts',
  'wpexintro' => 1,
  'todo' => 'wikipedia-matching-intro',
  'timetocache' => 7\*84600
);
echo puzzler_wikipedia($puzzler_options);
?>

For less complex cases you can simply use the token directly, wrapped in token_replace():

<?php
echo token_replace('[puzzler:wikipedia-matching-image-url:Paganism]');
?>

A popular use case is to provide relevant content for (temporarily) empty fields by using Puzzler tokens in the default values of fields. (For tokens to work in default field values you will need module Field Default Token.)

For more documentation and live examples, see the demo page.

FAQ^#

Q: Do I need to have a Wikipedia API account to retrieve data?
A: Wikipedia API is free to use. Perceived abuse (e.g. too frequent calls) may be punished, so make sure you do not set the caching period too low.

Q: What are the licensing conditions for embedded Wikipedia content?
A: Wikipedia content is available under Creative Commons license CC-BY-SA 3.0. In short: you have to mention Wikipedia as the information source, and if you modify anything, redistribution must happen under the same or compatible license.

Q: Do I need to edit and save an article to make it fetch a fresh version of data from Wikipedia?
A: No. Tokens as well as PHP resolve information from Puzzler — either from cache (for the duration you have set), or fresh from Wikipedia.

Q: My page shows text/image older than the cache period I set.
A: Your page caching period may be longer or overlapping with that of Puzzler.

Future^#

We will be adding new tokens to this module over time. If you see yourself having to extract a particular kind of Wikipedia data over and over via PHP, make a suggestion for a new Puzzler token in the issue queue. It may be accepted much faster if you provide a patch as well!

We are also actively working on using the Wikidata API in addition to the Wikipedia API. Other data APIs (non-Wikimedia) may be included as well in the future.

This module also needs to be ported to Drupal 8. Help welcome!

Known major integrators^#

Encyclopedia of World Problems and Human Potential
Kinpedia
Contact the maintainer to propose your site for this list!

Embed introduction from the Wikipedia article on Richard Feynman:

[puzzler:wikipedia-matching-title:Richard Feynman]

Fetch the introduction to the French-language Wikipedia article on Socrates and cache it for a week:

<?php
if (module_exists('puzzler')){
  $puzzler_options = array(
    'api_endpoint' => 'http://@wplang.wikipedia.org/w/api.php', // For the purpose of this demonstration we set a slightly different API endpoint (http instead of the default https)
    'wppage' => 'Socrate', // Force looking up this Wikipedia title
    'wplang' => 'fr', // Force looking up in this language version of Wikipedia
    'wpprop' => 'extracts', // Specific for fetching introductions
    'wpexintro' => 1, // Specific for fetching introductions
    'todo' => 'wikipedia-matching-intro', // Instructs Puzzler to fetch an introduction from the given Wikipedia article
    'timetocache' => 7*84600, // Caching time in seconds
  );
  echo puzzler_wikipedia($puzzler_options);
}
?>