Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Building a Custom Theme in Drupal 8

6,364 views

Published on

Little documentation and few base themes with 8.x branches - what's a front end developer to do? I'll show you what's changing in Drupal theming between D7 and D8 and how to create a custom theme based on the Classy base theme, step by step. We'll go over Twig basics and Twig debugging.

Published in: Internet
  • Be the first to comment

Building a Custom Theme in Drupal 8

  1. 1. BUILDING A CUSTOM THEME IN DRUPAL 8 BASED ON THE CLASSY BASE THEME Presentation by Anne Tomasevich
  2. 2. INTRODUCTION This is the part where I talk about myself Photo by Jessie Gladdek savaslabs.com @Savas_Labs
  3. 3. AGENDA What's changing? Let's make a theme Twig basics and debugging
  4. 4. LET'S START FROM THE VERY BEGINNING WHAT IS THEMING? Themes allow you to change the look and feel of your Drupal site. - Someone who's good at being very general
  5. 5. WHY WOULD YOU USE DRUPAL 8 NOW?! And when is it coming out?
  6. 6. WHAT'S CHANGING? ...and how do I, a person who probably doesn't like change, cope with these changes...
  7. 7. WHAT'S NEW IN DRUPAL 8? Twig, a template engine by SensioLabs Classy, a new base theme template.phpbecomes [theme-name].theme. (Dear Drupal gods, can we please have theme.php?)
  8. 8. WHAT'S NEW IN DRUPAL 8? Responsive design elements are included by default Breakpoints can be set and used across modules and themes
  9. 9. WHAT'S NEW IN DRUPAL 8? LOOK AT ALL THE PRETTY THINGS WE GET TO USE NOW!! HTML5 CSS3 Modern jQuery libraries SMACSS BEM Standardized breakpoints
  10. 10. WHAT'S NEW IN DRUPAL 8? Support for IE8 and below is dropped meaning the use of jQuery 2.0, HTML5, and CSS3 (including pseudo selectors) are now supported CSS: Far fewer IDs are used CSS file structure now uses Default class names follow the format CSS and JS files are attached to pages differently SMACSS BEM
  11. 11. WHAT'S NEW IN DRUPAL 8? For a more comprehensive list, visit Drupal's change log.
  12. 12. WHY ALL THE CHANGES? ACCESSIBILITY TO NON-DRUPALERS Fewer Drupal-specific conventions and more popular, well- documented frameworks (such as Twig), meaning non- Drupalers can jump in much more quickly. D8 themers don’t need to know PHP to whip up a theme.* * I mean kinda ¯_(ツ)_/¯
  13. 13. WHY ALL THE CHANGES? SECURITY Text is automatically escaped in Twig, meaning a lower chance of XSS attacks. Template files are more secure since they no longer contain PHP code. <?php db_query('DROP TABLE {users}'); ?> Scary example courtesy of sqndr at d8.sqndr.com.
  14. 14. WHY ALL THE CHANGES? CURRENT FRAMEWORKS AND TOOLS Separation of logic from appearance = more modular (reusable) code More semantic CSS class names = leaner CSS and a more readable DOM A general trend towards more extendable, modular, well- organized, better-performing code
  15. 15. ANY DISADVANTAGES? 1. Many contributed themes and modules don't having their 8.x branches ready. A fun note on the 8.x branch of a popular contrib theme: This is a development branch. Please note that this branch is probably severely broken. It is strongly recommended to wait before using this branch or even creating issues regarding it.
  16. 16. ANY DISADVANTAGES? 2. Serious lack of documentation online Of the documentation that DOES exist, much of it is: Outdated, and marked as such. Outdated, and NOT marked as such.
  17. 17. LET'S BUILD THIS THING
  18. 18. WHAT AM I TOTALLY GLOSSING OVER? template.php *.theme Grid framework and CSS architecture Probably a lot of other things
  19. 19. CREATE A THEME FOLDER Drupal core now resides in its own folder. Contributed and custom modules and themes are in the modulesand themes folders, respectively. Don't forget to create a customfolder for your custom theme!
  20. 20. CREATE A .INFO.YML FILE # mappy.info.yml name: Mappy type: theme description: 'D8 Theme for a basic leaflet site.' core: 8.x base theme: classy libraries: - mappy/global-styling - mappy/leaflet regions: navbar: 'Top Navigation Bar' content: Content # required! sidebar: 'Sidebar' footer: 'Footer' [theme-name].infobecomes [theme-name].info.yml
  21. 21. DOT INFO DOT WHAT? YAML is a data serialization language. Key-value pairs. Check out on YAML syntax before getting started. And mind your whitespace! Symfony's excellent writeup
  22. 22. CREATE A .INFO.YML FILE # mappy.info.yml name: Mappy type: theme description: 'D8 Theme for a basic leaflet site.' core: 8.x regions: navbar: 'Top Navigation Bar' content: Content # required! sidebar: 'Sidebar' footer: 'Footer' This looks familiar, right?
  23. 23. CLASSY, A NEW BASE THEME # mappy.info.yml base theme: classy In D8, default classes are stripped from Drupal core and moved into the base theme Classy. To avoid these default classes, simply don't base your theme on Classy. But we want them because BEM is awesome! Check out this awesome introduction.
  24. 24. LIBRARIES # mappy.info.yml libraries: - mappy/global-styling - mappy/leaflet In D8, assets can be added in a few different ways: globally, per-template, per-page, and more. All libraries must be defined in your *.libraries.ymlfile.
  25. 25. CREATE A .LIBRARIES.YML FILE # mappy.libraries.yml global-styling: css: theme: css/styles.css: {} leaflet: css: theme: css/leaflet.css: {} js: js/leaflet.js: {} js/map.js: {} dependencies: - core/jquery Note that jQuery is listed as a dependency of the Leaflet library. Since jQuery is no longer loaded automatically on every page, it must be explicitly required.
  26. 26. ADDING ASSETS TO YOUR SITE # mappy.info.yml libraries: - mappy/global-styling - mappy/leaflet Since this is a small site and we need our libraries on every page, we're adding them globally. Visit for more information on methods for adding assets. drupal.org
  27. 27. CREATE A .BREAKPOINTS.YML FILE # mappy.breakpoints.yml mappy.mobile: label: mobile mediaQuery: '(min-width: 0px)' weight: 2 multipliers: - 1x mappy.narrow: label: narrow mediaQuery: 'all and (min-width: 560px) and (max-width: 850px)' weight: 1 multipliers: - 1x mappy.wide: label: wide mediaQuery: 'all and (min-width: 851px)' weight: 0 multipliers: Ours is stolen adapted from the Bartik theme.
  28. 28. BREAKPOINTS Once you add a .breakpoints.ymlfile (and uninstall and reinstall your theme), the breakpoints you've set will be exposed in the admin UI. These breakpoints can be used across various modules.
  29. 29. WITH THESE FILES SET UP, WE NOW HAVE A WORKING CUSTOM THEME!
  30. 30. TEMPLATE FILES In our theme's current state, we're using Classy's default template files. If we want to override them, it's time to learn some Twig. If one more person makes a "Gettin' Twiggy with it" joke...
  31. 31. INTRO TO TWIG is a template engine with syntax similar to Django, Jinja, and Liquid. It simplifies template creation with clean syntax and useful built-in filters, functions, and tags. In a Drupal template file (now with the extention .html.twig), anything between curly braces is Twig. Twig
  32. 32. TWIG DELIMITERS {{ These }}are for printing content, either explicitly or via functions {% These %}are for executing statements {# These #}are for comments
  33. 33. PRINTING VARIABLES AND REGIONS In D7 we render content like so: <?php print render($page['sidebar']); ?> Printing variables in D8 is as easy as including them inside double curly braces: {# In page--front.html.twig #} {# Print the sidebar region. #} {{ page.sidebar }}
  34. 34. PRINTING VARIABLES WITH SPECIAL CHARACTERS If a variable name contains special characters, use Twig's subscript syntax (which will look familiar to seasoned Drupalers). {# In page--front.html.twig #} {# Print the page type. #} {{ page['#type'] }} This will come in handy more during debugging.
  35. 35. FILTERS Twig comes with many that variables are passed to via the pipe character. built-in filters Here's the date filter: {# Format the post date. #} {{ post.published|date("Y-m-d") }}
  36. 36. DRUPAL-SPECIFIC FILTERS Check them out here. Remember our old friend t()? {# Run an ARIA label through t() #} <nav class="tabs" role="navigation" aria-label="{{ 'Tabs'|t }}">
  37. 37. FUNCTIONS Twig also comes with various that can be used in double curly braces. functions Here's the cycle function doing some very important work: {% set fruits = ['apple', 'orange', 'banana'] %} {% for i in 0..10 %} {{ cycle(fruits, i) }} {% endfor %}
  38. 38. TAGS Used for control flow and other fun things. {# From Bartik's page.html.twig #} {# If there are tabs, output them. #} {% if tabs %} <nav class="tabs" role="navigation" aria-label="{{ 'Tabs'|t }}"> {{ tabs }} </nav> {% endif %} In template files, we’ll use the ifstatement quite often.
  39. 39. GET PSYCHED Make sure you check out the Twig coding standards!
  40. 40. TWIG DEBUGGING To enable debug mode and turn off caching, we need to do 3 things: 1. Turn on Twig’s debug mode 2. Turn on Twig auto reload, meaning that Twig templates are automatically recompiled when the source code is changed 3. Disable Drupal’s render cache You do NOT need turn off Twig caching - turning on auto reload is enough.
  41. 41. USE SETTINGS.LOCAL.PHP 1. Copy sites/example.settings.local.phpto sites/defaultand rename to settings.local.php. Fill out your local database settings. 2. Uncomment the following at the bottom of sites/default/settings.php: if (file_exists(__DIR__ . '/settings.local.php')) { include __DIR__ . '/settings.local.php'; }
  42. 42. TURN ON DEBUG MODE AND AUTO RELOAD Check out settings.local.php // In settings.local.php /** * Enable local development services. */ $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml'; This tells us to head over to development.services.yml. // In sites/development.services.yml parameters: twig.config: debug: true auto-reload: true
  43. 43. TURN OFF DRUPAL'S RENDER CACHE Just kidding, you already did. // In settings.local.php /** * Disable the render cache (this includes the page cache). * * This setting disables the render cache by using the Null cache back-end * defined by the development.services.yml file above. * * Do not use this setting until after the site is installed. */ $settings['cache']['bins']['render'] = 'cache.backend.null';
  44. 44. DEBUG AWAY Now you can: View HTML comments in your browser’s code inspector with lots of helpful info: Which theme hook is being implemented Theme hook suggestions (i.e. how to override the current theme hook) Which template file is being output. Make changes to your source code and simply refresh the page to see your changes rather than constantly rebuilding the cache.
  45. 45. DUMP( ) With Twig debugging turned on, we can use the Twig function dump(). {# In a template file #} {# Print out all variables on the page. #} {{ dump() }} {# Print the page's base path. #} {{ dump(base_path) }}
  46. 46. EVEN BETTER: KINT( ) Install the Devel and Devel Kint modules to use kint()in the same way, but with a pretty, expandable array instead. {# In a template file #} {# Print out all variables on the page. #} {{ kint() }}
  47. 47. RESOURCES AND FURTHER READING A brilliant blog post about D8 theming (Savas) D8 theming guide (Sander) YAML formatting (Symfony) Intro to BEM (CSS Wizardry) Adding assets to pages (drupal.org) Twig documentation (Sensiolabs) Drupal-specific Twig filters (drupal.org) Twig coding standards (drupal.org) Twig debugging and devel (drupalize.me)
  48. 48. QUESTIONS? @Savas_Labs savaslabs.com

×