Template Suggestions

Exercise: Debugging the Hero

• In your Drupal site, visit the page you created before with the Hero

• Right-click anywhere on the hero and select Inspect or inspect element, depending on your browser. This will display the HTML that makes up the page you are currently viewing. In addition, it will display other information generated by Twig debugging. See an example of Twig debug output below (click on it to zoom in):

Template Suggestions are Green.

If you look at the image above, you will see a few things that are extremely helpful for creating the right template suggestions:

• The last line of green text BEGIN OUTPUT... shows where the template being used by Drupal to render the Hero is located and what its name is modules/contrib/paragraphs/templates/paragraph.html.twig.

• Just above that line, under FILE NAME SUGGESTIONS:, there is a list of files all of which begin with paragraph. Since we are using the Paragraphs module, for the hero, Drupal is telling us we can create a Twig template with any of the names listed above and we can customize it to our needs. This list is what we mean when we say Template suggestions.

• The file with an x next to it is the template Drupal is currently using to render the Hero.

**IMPORTANT: **The first rule of Drupal is "Don't hack core". This means you should never modify a template provided by Drupal core, or a contrib module. Instead, you create a copy of that template in your theme. This is a best practice and we are going to follow it throughout this training.

Exercise: Creating new template suggestions

We will need to store our custom templates somewhere. Some put them in the src/templates directory. I prefer to keep them in my theme, but Drupal will find them either way. Let's use the command line (feel free to do this in your code editor).

// Make the template folder
mkdir web/themes/custom/training_theme/templates

// Copy the template from Paragraphs module into theme
cp web/modules/contrib/paragraphs/templates/paragraph.html.twig web/themes/custom/training_theme/templates 

1. Copy paragraph.html.twig from modules/contrib/paragraphs/templates/

   into your project's /themes/custom/training_theme/templates/. You will likely need to create the templates folder inside your theme if it does not exist. You can use the command line or Mac's Finder/ Window's Explorer to copy this file.

2. Rename the newly copied template in your theme to paragraph--hero.html.twig. Why this name? Well, while we could have used any of the suggested names above, paragraph--hero is specific enough so that any changes we make to the template will only affect the Hero content and not other content. Now every time the Hero component is rendered, Drupal will use this new template and not the one provided by Drupal core.

3. Next clear Drupal's cache (Configuration > Development > Performance)

4. Reload the page and inspect the code one more time (Right-click on Hero and select Inspect).

Notice there is an x next to paragraph--hero.html.twig, which means Drupal is now using our custom twig template suggestion. In addition, notice the path of the template is now our own theme's template directory.

TIP: If I know I will be creating multiple template suggestions of the same kind (i.e. node), I would normally leave the unchanged copy of node.html.twig in my theme and make copies of it every time I need a new template. This way I don't have to copy the same template over and over from Drupal core or a contrib module (I'm lazy).