Learning Drupal 8 from Boilerplate Code

Image

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.

Assumptions

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.

1. Open a Terminal window
2. Navigate to your home directory:

   cd ~/
   

3. 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 $PATH.

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:

export PATH=/usr/local/bin:$PATH

Then run the following command to refresh your bash profile file:

source ~/.bash_profile

Now when you run the following in a Terminal window:

which drupal

...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:

site:new d8folder

New command for http://t.co/JGgIT4tutX site:new sponsored by @anexusit #drupalcr pic.twitter.com/vG5nLm6pBL

— Eduardo Garcia (@enzolutions) July 4, 2015

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:

drupal generate:theme

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 imageeffect and 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.

1. From the admin menu, go to Extend and enable your new module.
2. From the admin menu, go to Structure > Block layout
3. Locate the Place Blocks section (as of Drupal 8, beta 12, this is in the right sidebar, subject to change).
4. 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
5. Click on the name of your block (the plugin label); mine is "default_block."
6. Fill in a Title for your block.
7. In my example, I added a simple textfield with the label "Your Name" to my block, so I'll fill in that as well.
8. Choose a region to place your block. I chose the First Sidebar.
9. Click Save block.
10. Scroll down to the bottom of the Block layout page and click Save blocks.
11. From the admin menu, click Go to site.
12. 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.

Resources

• Drupal Console Documentation
• Drupal Console Website
• Drupal Console on Twitter
• DrupalCon Presentation: Speeding up Drupal 8 development using Drupal Console
• Drupalize.Me Podcast No. 58: Drupal Console