Puzzler

Puzzler makes it easy to insert bits and pieces of Wikipedia content into Drupal. It retrieves updated information as Wikipedia’s editors improve the source articles, avoiding the need to maintain copied-and-pasted excerpts.

Use tokens or a field formatter to display an article’s introduction, filtered article text, links or images with credit. Content can be selected using a Wikipedia article URL or title, or the label of a node or taxonomy term supplied to the token. Puzzler respects the selected language and follows Wikipedia redirects.

The modern 2.x series supports Drupal 10.3+, 11 and 12 and is currently in beta. Earlier 7.x releases are for Drupal 7.

Installation and requirements

Install Puzzler through Composer, then enable it:

composer require 'drupal/puzzler:^2.0@beta'

No additional contributed module is required. The site needs outbound HTTPS access to Wikipedia and Wikimedia Commons, and regular Drupal cron runs.

Recommended modules

• Token provides additional token browsing tools.
• Token Filter allows tokens in text formats configured to use its filter.

Settings and dashboard

Visit admin/config/services/puzzler to configure the cache period, fallback language and an API user agent identifying your site. The dashboard at admin/config/services/puzzler/dashboard lists available tokens and cached API items.

How to use

For new setups, add a Puzzler Wikipedia content field to taxonomy terms or other fieldable content. Each field item keeps one Wikipedia article, its selected images and their alternative text together. The field can contain multiple articles, and each article can contain multiple images. On Manage display, select the Puzzler Wikipedia content formatter and choose Images and introduction, introductions, article text, article links or images with credit. The formatter also works in Views.

Editors can enter either a Wikipedia article title or its URL. They can load the images used by the article, choose no image, use the automatic representative image, or enter any Wikimedia file title. Puzzler checks selected images and shows a preview, credit and alternative text while editing. It preserves source alternative text where available, permits an editor to revise it, and keeps previous custom text available to restore when a different image is checked. Encoded file titles, spaces and underscores are accepted, including existing saved values.

The Images and introduction display keeps each article’s images with its introduction. A Show introduction checkbox is enabled by default for each article and can hide an introduction, for example when an image is useful but the article is in another language. Images, article links and full article HTML remain available independently.

Puzzler recognises image files from non-English Wikipedia projects, including their translated file namespaces. It checks public-domain, CC0 and other declared free-licence information, including information available from a Wikimedia Commons file page when the API metadata is incomplete. A missing Artist value does not by itself exclude an explicitly public-domain or CC0 image. Public-domain and CC0 captions are shown by default but can be suppressed when the extra source and rights text is not wanted. Image attribution links open in a new tab by default. Global licensing, caption, unavailable-content and new-tab link settings can be overridden by individual formatters. Review licence requirements for each image and provide any required credit.

When Wikipedia or Wikimedia cannot provide information, Puzzler can show a specific notice instead of failing silently. This includes temporary API failures such as replication lag, missing articles or files, licensing restrictions and incomplete attribution. Existing plain-text setups, image-choice widgets, formatters and token names continue to work; conversion to the new field is optional.

A field configured separately in Views has its own formatter settings and does not inherit them from Manage display. A View that renders an entity in a selected view mode uses that view mode’s display settings.

The original tokens remain available:

• [puzzler:wikipedia-matching-url] — article URL.
• [puzzler:wikipedia-matching-url-html] — article link.
• [puzzler:wikipedia-matching-title] — resolved article title.
• [puzzler:wikipedia-matching-html] — filtered article text with credit.
• [puzzler:wikipedia-matching-intro] — introduction with credit.
• [puzzler:wikipedia-matching-image-url] — representative image URL.
• [puzzler:wikipedia-matching-image-html] — representative image with credit.
• [puzzler:wikipedia-matching-attribution] — Wikipedia text attribution.

Append an explicit article title when needed. For example, [puzzler:wikipedia-matching-intro:Richard Feynman] retrieves that article’s introduction independently of your Drupal content’s title. Tokens need a component such as Token Filter to expand them; ordinary text fields do not expand tokens automatically.

See the README for configuration and developer examples. Vacilando’s original Puzzler page provides background and earlier examples.

FAQ

Is a Wikipedia API account needed?

No account or API key is needed. Use a reasonable cache period to avoid unnecessary requests.

What about licensing?

Wikipedia text is generally available under CC BY-SA 4.0. Images have their own licences. Puzzler can include source and licence information; review the source for any additional credit requirements.

Must content be saved again to refresh it?

No. Puzzler retrieves fresh information when its cached responses expire. Drupal page caching also affects when visitors see an update, so keep cron running regularly.

Roadmap

• Future Wikimedia media integration: explore a separate importer that could map Wikimedia file metadata into Drupal Media entities, including sites using Media Remote Image. Serving local copies, either directly or as a fallback when Wikimedia fails, is not part of Puzzler 2.0.0-beta2.
• Further tokens and possible Wikidata integration remain ideas for future development.

Collaboration

Let's make this module better together! Suggestions, testing and contributions are welcome in the issue queue.

Puzzler was originally developed by Vacilando. Early integrations included the Encyclopedia of World Problems and Human Potential and Kinpedia. The modern Drupal version builds on that original work.

The 2.x update was developed with assistance from OpenAI Codex for implementation, testing and documentation.