Pre-requisites
None.
Projects (modules, themes and profiles) are the basis of extending Drupal
Drupal can be extended in many different ways; these extensions are usually packaged up inside projects, which can be one of three types:
- Profiles
- Manage the installation of a brand-new Drupal website, and permit radically different starting points: Drupal as a CRM, or Drupal as a shop.
- Themes
- Encapsulate the entire display layer of a Drupal website, containing (in theory) no business logic and interchangeable for another theme at a later date.
- Modules
- Modify and extend the way Drupal behaves with new functionality, logic, structure, content, behaviours etc.
For the purposes of these tutorials, the most straightforward way to extend Drupal is with a module, and we focus on those. Almost all of the code examples will be in the same module.
In D8, the minimum structure of a module is very simple indeed; you just need:
- A folder in the right place
- Containing a metadata file
In Drupal 8, modules, themes and profiles all standardize on the suffix .info.yml for the filename, and structure the contents of the file according to the YAML specification.
Folder: what to call it; where to put it
What do you call your module folder? Well, Drupal has a longstanding (but slightly ambiguous) concept of a "machine name": in practice, it usually means any number of word or words, made from lowercase a–z and the numbers 0–9, with the whitespace between them replaced by underscores, and not containing any other punctuation except (sometimes, but not for module names) hyphens and (sometimes, but not for module names) dots.
So hello_world_123 is a good example, but hello world! is not. In addition, to avoid possible conflicts later owing to Drupal's concept of hooks (not in the scope of this blogpost) you might also want to reduce the machine name to a single word, without any underscores: helloworld123.
Once you've decided on a provisional machine name, you should also make sure it doesn't already exist as a contributed extension you might want to use in the future: in this example, try visiting http://drupal.org/project/helloworld123. It doesn't exist, so we could go with this as our machine name. That's a bit of a weird name, though, so for the sake of the rest of this blogpost we'll use the machine name d8api.
You can create a folder with this machine name in one of the following directories, relative to the Drupal root:
modules/(Drupal 8 preferred)sites/all/modules/(Drupal 6/7 legacy location)sites/default/modules/(Drupal 8, for use on only the default site)
(These locations are determined by the ExtensionDiscovery service.)
Your particular site folder should be sites/default as above, as you probably don't want to use multisite. For now, let's assume you've created the folder sites/default/modules/d8api.
File: what to call it; what to put in it
The name of the file which contains your module's metadata should be the machine name, followed by .info.yml, and go in the top-level folder of your module. So, assuming the machine name above: sites/default/modules/d8api/d8api.info.yml.
Aside: you can use a different machine name for this metadata file, from the folder name. Don't do it! Keep the machine names the same. For a long time in Drupal 7 there was a module called googleanalytics where all of its files' names began google_analytics.*—or maybe it was the other way round. That's the point, in fact: it was always difficult to remember the difference, and there was no benefit from them being different. Keep the same machine name, kids.
This metadata file should contain, as a minimum, the following entries:
name: Tutorial description: Example module created for the tutorial. type: module core: 8.x
This tells Drupal, in turn:
- The (human-readable) name of the extension.
- A short (human-readable) description providing further information.
- That this extension is of type "module" and not "theme" or "profile".
- That it's compatible with Drupal core 8.x (basically any Drupal 8 core.)
You might add a package: ... line to help the Extend page (see below) put your module with others that provide related functionality. If you're interested, you can also read more about the possible contents of this metadata info file.
Other, optional contents of the module
That's all you need for a module. As we proceed with future tutorials, you'll find we'll add many other files; for example:
*.yml- Module-level configuration, for settings, routes, menu items etc.
src/**/*.php- Object-oriented class files, in subdirectories which sometimes have important meanings (see the later tutorial on plugins.)
MODULENAME.module- Non-objectoriented code, especially hooks (see the later tutorial on events.)
However, here we've only covered the bare minimum to begin your module, and you should already be all set.
What you should see
Open up a web browser, log into your site as an administrator, and navigate to the "Extend" tab. When you search for your module's name, it should filter down to a shorter list that includes your module:
You can then enable this module. It doesn't do anything yet, but: congratulations! You've just created the bare minimum of a Drupal module.
