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.
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.
- 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:
|ahah_example||Using AHAH forms||x|
|ajax_example||Using AJAX forms||x|
|batch_example||Using the batch API||x||x||x|
|cache_example||Using cache APIs in Drupal||x||x|
|cron_example||hook_cron() and family demonstration||x||x|
|dbtng_example||Database examples (DBTNG)||-||-||x||x|
|entity_example||Custom entities in Drupal||x||x|
|field_example||Defining fields in the Field API||-||-||x||x|
|filter_example||Defining an input filter||x||x||x|
|form_example||Fom API: multistep, states, elements||x||x||x||x|
|image_example||Image example (styles and effects)||x||x|
|menu_example||Creating and altering menu entries||x||x||x||x|
|node_access_example||Defining custom access rules||x||x||x|
|node_example||Creating custom node types (with fields)||x||x||x||x|
|nodeapi_example||modifying existing node types||x||x||x|
|page_example||How to create static pages||x||x||x||x|
|pager_example||Using pagers in Drupal||x||x||x||x|
|queue_example||Using the queue API||x||x|
|rdf_example||Using RDF hooks||x||x|
|render_example||Using Drupal_render's capabilities||-||-||x||x|
|simpletest_example||How to write tests for your modules||x||x||x||x|
|theming_example||Demonstrating the module-developer theming hooks||x||x||x|
|token_example||Using and creating tokens||x||x||x||x|
|trigger_example||Implementing triggers and actions||x||x||x|
|vertical_tabs_example||Using vertical tabs in your forms||x||x|
|xmlrpc_example||XMLRCP server and client example||x||x||x||x|
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.
(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!
- davereid did the Token example and has contributed in dozens of other ways.