Examples for Developers

This project aims to provide high-quality, well-documented API examples for a broad range of Drupal core functionality.

The Examples project contains many modules which hopefully illustrate best practices for implementing various Drupal APIs. These modules can be enabled individually, and will typically add menu items to your site, which should guide you through their features. You can then look through the code to see what they are doing.

Developers can learn how to use a particular API quickly by experimenting with the examples, and adapt them for their own use.

You can also browse through the documentation and code on the Drupal API site, here: Examples Project. You can also browse the file tree on drupalcode.org/project/examples.git.

Note also that these modules demonstrate internals for Drupal development in PHP (and some JavaScript). Not all Drupal users will need these examples. There are many contributed modules which will do the majority of what a Drupal site-builder could need. For instance, you could use the Entity Construction Kit module, rather than spend time with the entity API example.

Core Only

This project covers only core Drupal APIs. Many other APIs exist, and have their own example code. You can find them by following this link: Non-core Drupal examples.

Where are the Drupal 8 examples?

Currently there is nothing in the 8.x-1.x-dev release; it was removed in #1518272: Remove/archive 8.x-1.x and start over, bringing in only newly ported or created modules. It would be too hard to keep up with 8.x-1.x through its many iterations. Note that maintainers will be needed for 8.x examples. Also see the proposal in #1532612: Move Examples Project into Drupal core. If you think Examples should move into core, please comment there.

News

• 2 June 2012: Removed the 8.x-1.x-dev contents. It was broken and unmaintainable. See #1518272: Remove/archive 8.x-1.x and start over, bringing in only newly ported or created modules
• 25 May 2012: Autocomplete example added to the AJAX Example
• 17 May 2012: Tabledrag, Entity, and RDF Examples added
• 23 Nov 2011: Cache Example
• 19 Nov 2011: Cron Example added.
• 5 Sep 2011: Theming Example added
• 17 Aug 2011: Pager Example
• 13 Dec 2010: Action Example added to D7 Examples
• 14 Oct 2010: An extensible multistep form example added to D7 Form Example
• 14 Oct 2010: A Drupal 6 Token Example
• 2 Oct 2010: Major rework and improvement of XMLRPC Example
• 26 Sept 2010: Added a Render Example showing how the D7 Render subsystem works
• 5 Sept 2010: Element Example improved (new examples), moved into Form Example, and tests added
• 11 Aug 2010: New File Example (D7) shows File API and streamwrapper implementation.
• 28 July 2010: Improved page example to show render array return
• 28 July 2010: Reworked D7 Batch Example
• 28 July 2010: More depth in the #states example in the Form Example
• 20 July 2010: AHAH Validation example added to D6 AHAH Example

Example Module Status:

How can you help? I'm glad you asked:

• Most of all, we need you to file an issue every time you find an error or ambiguity or something that could be presented better.
• We need additional examples.
• We need reviews, corrections, and improvements to existing modules.
• We need improvements in the doxygen comments.
• We need help figuring out how to organize this growing mass of examples better, and how to improve the doxygen output on api.drupal.org.
• Please feel free to help out in the issue queue.

Additional To-Do Wishlist of Examples:

• Core field widget example
• User API example
• Update/Upgrade system example
• Overlay example for Form example (D7)

What examples do you need as a developer? Create an issue in the queue if you think there's a need.

Submission guidelines for patches and new modules

New example modules are welcome, and if you're willing to maintain them, ask for maintainer privileges

All changes and submissions should be done first as a patch, whether or not you have commit privileges. This module is now being tested by the bot, so in order not to break things, it's important to post the patch first and make sure it passes.

• Post as a patch before committing, to make sure your example passes.
• The module must demonstrate a core feature.
• Drupal coding standards must be maintained. Run Coder module on your module before submitting.
• Each module must have at least one menu entry, which leads to a page demonstrating the module. The menu entry should be 'examples/whatever'.
• In general, do not require any permissions to use your module.
• Remember that your example should be brain-dead simple. It's only job is to educate, certainly not to show off. Help the developer to understand the concept at hand.
• Provide hook_help() to give some hints to the user.
• Provide links to appropriate external documentation (including handbook pages, external pages, etc.) so that people can find where to go for more help.
• api.drupal.org presents this code to all searchers, so please sure that you have quality phpDoc.
• Our intent is that every module should have tests. Not only will the test keep the module maintained, but the test itself is also a great resource for developers.

We need specific maintainers of the various modules, as core does, so if you're willing to "adopt" a module, please volunteer in the issue queue.

Honor Roll

(Ping rfay if you or someone else should be here and they're not!)

• Ralf has been cleaning up messes all over the project
• cyberswat created the Node Example for D7 and has defended it against a multitude of core changes
• coltrane created the Queue example for D7
• ilo has done an enormous amount of work, more than anybody else. He wrote nearly all the tests, and has added a number of modules. Thanks!
• katbailey has done all of the javascript stuff and has added to the AJAX modules. Thanks!
• davereid did the Token example and has contributed in dozens of other ways.

Downloads