Drupal 8 represents a lot of changes and a steep learning curve for many Drupal developers and themers. While many of these changes are exciting, there are many things to learn just to get started. One way to learn about the code involved with Drupal 8 modules and themes is to take a look at core's modules and themes for examples to follow. Another is to use a code-scaffolding tool like Drupal Console to generate boilerplate code and comments that you can learn from and then customize.
Note: Both Drupal 8 and the Drupal Console are under heavy development. The examples in this blog post are subject to change.
The following tutorial assumes that you have a local development environment up and running and you are able to follow the steps to install Drupal 8 on your machine.
Installing Drupal Console
Drupal Console is a command line utility that you use in Terminal or other command-line interface (CLI). It is an application that uses the Symfony Console component as well as other libraries. To install it, follow the instructions below, taken from the Using the Drupal Console Installer documentation page.
- Open a Terminal window
- Navigate to your home directory:
- Use the curl utility to download the installer:
curl -LSs http://drupalconsole.com/installer | php
This installs the console.phar file in your home directory.
To access the program from anywhere on your system, move console.phar to /usr/local/bin/drupal and ensure that this location has been added to your
For example, to move console.phar from your home directory to /usr/local/bin/drupal. In a Terminal prompt, type:
mv console.phar /usr/local/bin/drupal
If you are using bash as a shell, add the following to your ~/.bash_profile:
Then run the following command to refresh your bash profile file:
Now when you run the following in a Terminal window:
...it should say /usr/local/bin/drupal.
You may now run the Drupal Console from within any Drupal 8 site on your system by just using using the alias "drupal." For more details, see the documentation page: Using the Drupal Console Installer.
Install Drupal 8
For instructions on how to install Drupal 8, see the Drupal 8 INSTALL.txt.
Or you can try this brand new command from Drupal Console, where "d8folder" is the name you want for your Drupal directory name:
Generate Code for a Drupal 8 Theme
Let's start with generating code scaffolding for a Drupal 8 theme using Drupal Console.
In a Terminal window, navigate to your Drupal 8 local development environment.
Enter the following command:
You will be prompted with several questions about your theme. The default answer is in square brackets. If you want to use the default answer, simply hit the return key.
Here is the interactive console in action, generating a new theme:
Welcome to the Drupal theme generator Enter the new theme name: My New Theme Enter the module machine name [my_new_theme]: Enter the theme Path [/themes/custom]: Enter theme description [My Awesome Theme]: My New Theme Enter package name [Other]: Enter Drupal Core version [8.x]: Base theme (i.e. classy, seven): classy Do you confirm generation [yes]? Generated or updated files Site path: /Library/WebServer/Documents/d8beta12 1 - themes/custom/my_new_theme/my_new_theme.info.yml 2 - themes/custom/my_new_theme/my_new_theme.theme
Navigate to your newly-generated theme and explore the .yml (YAML) file and .theme file. The YAML file is ready-to-go and even includes a comment with more information about the Classy theme, if you chose that as a base theme. Make sure to check it out anyway to see how the values you entered mapped to the values in the YAML file. The .theme file (which is a PHP file) is chock full of example functions with extensive comments and example code that you can use to customize your Drupal 8 site.
Generate Code for a Drupal Module
Now let's generate code that will get us started with Drupal 8 module development. The questions here might be a bit unfamiliar. My advice is to choose "yes" if you don't know what something is, and read through the generated code and comments to learn more.
When I choose "yes" for all the options, here are the files that are generated for a module I called "My New Module."
Welcome to the Drupal module generator Enter the new module name: My New Module Enter the module machine name [my_new_module]: Enter the module Path [/modules/custom]: Enter module description [My Awesome Module]: Enter package name [Other]: Enter Drupal Core version [8.x]: Do you want to generate a default Controller [no]? yes Do you want to add a composer.json file to your module [no]? yes Would you like to add module depencencies [yes]? no Do you want to generate a unit test class [yes]? yes Do you confirm generation [yes]? yes Generated or updated files Site path: /Library/WebServer/Documents/d8beta12 1 - modules/custom/my_new_module/my_new_module.info.yml 2 - modules/custom/my_new_module/my_new_module.module 3 - modules/custom/my_new_module/composer.json 4 - modules/custom/my_new_module/src/Controller/DefaultController.php 5 - modules/custom/my_new_module/my_new_module.routing.yml 6 - modules/custom/my_new_module/Tests/Controller/DefaultControllerTest.php
Generate Code for a Block Plugin
Finally, let's generate code for block plugin. Maybe you’ve watched my colleague Joe Shindelar's DrupalCon presentation, "An Overview of the Drupal 8 Plugin System" and you want to dive in and make a plugin yourself.
Since we've already got a module generated, we'll use that module "my_new_module" to house our block plugin.
There are several types of plugins Drupal Console will generate code for, including
rest:resource, but for this example, let's make a custom block that we can place using the block administrative UI. See the Drupal Console documentation for a list of all "generate" commands.
Welcome to the Drupal Plugin Block generator Enter the module name: my_new_module Plugin class name [DefaultBlock]: Plugin label [default_block]: Plugin id [default_block]: Do you want to load services from the container [no]? You can add input fields to create special configurations in the block. This is optional, press enter to continue Do you want to generate a form structure [yes]? Input label: Your Name Input machine name [your_name]: Type [textfield]: Description: Input label: Do you confirm generation [yes]? Generated or updated files Site path: /Library/WebServer/Documents/d8beta12 1 - modules/custom/my_new_module/src/Plugin/Block/DefaultBlock.php
Now, let's see it in action! Open your local Drupal 8 site in a browser.
- From the admin menu, go to Extend and enable your new module.
- From the admin menu, go to Structure > Block layout
- Locate the Place Blocks section (as of Drupal 8, beta 12, this is in the right sidebar, subject to change).
- Under the name of your module, in my case "My New Module" is the name of the newly generated block. If you don't see your module listed, clear the cache: from the admin menu go to Performance > Clear all caches
- Click on the name of your block (the plugin label); mine is "default_block."
- Fill in a Title for your block.
- In my example, I added a simple textfield with the label "Your Name" to my block, so I'll fill in that as well.
- Choose a region to place your block. I chose the First Sidebar.
- Click Save block.
- Scroll down to the bottom of the Block layout page and click Save blocks.
- From the admin menu, click Go to site.
- Observe your new block in action!
As you can see, Drupal Console's generate commands can get you up and running with working code, complete with comments. This can give you a head start with module and theme development and help you get familiar with the new conventions now being used in Drupal 8.
This was just a small sampling of what Drupal Console provides. To learn more about Drupal Console, check out the Drupal Console Documentation. Drupal Console is in heavy development so new features are being added regularly. To learn about the handy new tools being added all the time, follow @drupalconsole on Twitter.