Creating a Drupal 8 theme from scratch

Transcription

1 Creating a Drupal 8 theme from scratch Devsigner 2015 (Hashtag #devsigner on the internets)

2 So you wanna build a website

3 And you want people to like it

4 Step 1: Make it pretty

5 Step 2: Don t make it ugly

6 So

7 Learn you an HTML!

8 Learn you a CSS!

9 Learn you a jquery!

10 BUT WAIT

11

12 THERE S MORE

13 You re using a CMS? Drupal, you say?

14 You need a theme

15 What is a theme?

16 What is a theme? Themes control appearance Themes don t provide functionality Usually specific to a single site Contains HTML (templates), CSS, Javascript, and a little PHP

17 What about Drupal 8?

18 Changes for Drupal 8 Drupal 8 loves abstractions Drupal 8 loves themers and front end developers Kinda Documentation is still somewhat sparse Drupal 8 is still changing

19 Setup for Drupal 8 Make sure you use newer versions of Drush, 8.x minimum Clear the cache, a lot Disable page cache, and CSS/JS aggregation, these are now enabled by default

20 Let s get started

21 Themes now go in themes directory No more sites/all/ themes

22 Add a themename.info.yml file

23 What is.yml?

24 YAML YAML Ain t Markup Language Readable by machines But also readable by humans, which is cool since most front end developers are humans

25 key: value strings: "Quoted for special characters or spaces" collection: - "Indented with spaces" - "Start with dash (-)" collections: can: "specify key" nested: items: "Work as well" another: "See?" boolean: true or: false

26 Make a directory for your theme with it s name Add a themename.info.yml file

27 demo.info.yml name: Demo type: theme description: 'A demo theme.' core: 8.x

28

29 Let s install it!

30

31 Wow, that looks like the web in like 1996

32

33 Want to remove some of Drupal s default stylesheets?

34 demo.info.yml name: Demo type: theme description: 'A demo theme.' core: 8.x libraries: - demo/global-styling stylesheets-remove: - core/assets/vendor/normalize-css/normalize.css

35 We need some CSS

36 No more drupal_add_css() or drupal_add_js()

37 Libraries

38 Drupal 8 Libraries Drupal 8 is all about abstraction and reuse, even with front end code Libraries represent external components Libraries can have CSS, Javascript, and dependencies Examples: normalize, html5shiv, jquery, modernizer, backbone, underscore, CKEditor, etc

39 Libraries are defined in themename.libraries.yml

40 demo.libraries.yml global-styling: version: 8.x-1.x css: theme: css/styles.css: {}

41 demo.info.yml name: Demo type: theme description: 'A demo theme.' core: 8.x libraries: - demo/global-styling

42 Specify additional options, such as media

43 demo.libraries.yml global-styling: version: 8.x-1.x css: theme: css/styles.css: {} css/print.css: { media: print }

44 Let s add some Javascript

45 demo.libraries.yml global-styling: version: 8.x-1.x css: theme: css/styles.css: {} css/print.css: { media: print } js: js/script.js: {} dependencies: - core/jquery - core/drupal

46 Note the dependencies, jquery is no longer included on every page by default

47 What else can you do with libraries?

48 demo.libraries.yml global-styling: version: 8.x-1.x css: theme: css/styles.css: {} landing-pages: version: 8.x-1.x css: theme: css/landing-pages.css: {}

49 How to include additional libraries? Specify globally in theme info.yml file Add in preprocess function with #attached Add via Twig function Add to render array

50 demo.info.yml name: Demo type: theme description: 'A demo theme.' core: 8.x libraries: - demo/global-styling - demo/landing-pages

51 Where do I put preprocess functions?

52 Wait, Drupal 8 still has preprocess functions????

53 Adding a themename.theme file

54 themes demo css print.css styles.css demo.info.yml demo.libraries.yml demo.theme

55 Think of.theme as a replacement for template.php

56 OH MY GOD ITS FULL OF PHP

57 demo.theme <?php /** * Contains preprocess functions for Demo theme. */ /** * Preprocess for node pages. */ function demo_preprocess_node(&$variables) { $variables['#attached']['library'][] = 'demo/landing-pages'; }

58 Don t forget to rebuild caches when changing theme files

59 Moving right along

60 Templates, what are they good for?

61 Twig

62 What s so great about Twig Flexible Easy to use Similar to other template systems (jinja2, swig, etc) SECURE

63 Twig Examples

64 {# All twig tags use braces #} {# Comment use the hash/pound #} {{ this_tag_prints_output }} {# Tags with percent signs, are control blocks #} {% if variable %} {{ variable }} {% endif %}

65 {% set variable = 'Special value.' %} {{ variable clean_class }} {# Prints 'special-value' #}

66 Example filters Part of Twig capitalize, date, escape, first, length, lower, number_format, trim, etc Drupal provided t, trans, passthrough, placeholder, drupal_escape, safe_join, without, clean_class, clean_id, render

67 {{ 'This text will be translated' t }} <title>{{ head_title safe_join(' ') }}</title> {# Prints out '<title>homepage Demo site</title>' #}

68 region.html.twig {% set classes = [ 'region', 'region-' ~ region clean_class, ] %} {% if content %} <div{{ attributes.addclass(classes) }}> {{ content }} </div> {% endif %}

69 Working with Drupal regions

70 page.html.twig {% if page.sidebar_first %} <aside class="layout-sidebar-first" role="complementary"> {{ page.sidebar_first }} </aside> {% endif %}

71

72 Templates are cached!

73 Fast websites are good, but caching sucks when you re developing

74 Disable render caching in sites/default/settings.php

75 sites/default/settings.php /** * Disable CSS and JS aggregation. */ $config['system.performance']['css']['preprocess'] = FALSE; $config['system.performance']['js']['preprocess'] = FALSE; /** * 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';

76 Disable caching in sites/default/services.yml

77 sites/default/services.yml parameters: twig.config: # Twig auto-reload: # # Automatically recompile Twig templates whenever the source code changes. # If you don't provide a value for auto_reload, it will be determined # based on the value of debug. # # Not recommended in production environments null auto_reload: null # Twig cache: # # By default, Twig templates will be compiled and stored in the filesystem # to increase performance. Disabling the Twig cache will recompile the # templates from source each time they are used. In most cases the # auto_reload setting above should be enabled rather than disabling the # Twig cache. # # Not recommended in production environments true cache: true

78

79 sites/default/services.yml parameters: twig.config: # Twig debugging: # # When debugging is enabled: # - The markup of each Twig template is surrounded by HTML comments that # contain theming information, such as template file name suggestions. # - Note that this debugging markup will cause automated tests that directly # check rendered HTML to fail. When running automated tests, 'debug' # should be set to FALSE. # - The dump() function can be used in Twig templates to output information # about template variables. # - Twig templates are automatically recompiled whenever the source code # changes (see auto_reload below). # # For more information about debugging Twig templates, see # # # Not recommended in production environments false debug: false

80 Lets try it

81 (after clearing the cache, of course)

82 <!-- THEME DEBUG --> <!-- THEME HOOK: 'menu main' --> <!-- FILE NAME SUGGESTIONS: * menu--main.html.twig x menu.html.twig --> <!-- BEGIN OUTPUT from 'core/modules/system/templates/menu.html.twig' --> <ul class="menu"> <li class="menu-item"> <a href="/" data-drupal-link-system-path="<front>">home</a> </li> </ul> <!-- END OUTPUT from 'core/modules/system/templates/menu.html.twig' -->

83

84 Debug features We can see template suggestions We can see what the default or current used template is We can also use the dump() function to inspect variables

85 themes demo css styles.css demo.info.yml demo.libraries.yml demo.theme templates region.html.twig

86 templates/region.html.twig {% set classes = [ 'region', 'region-' ~ region clean_class, ] %} {{ dump(attributes) }} {% if content %} <div{{ attributes.addclass(classes) }}> {{ content }} </div> {% endif %}

87 Guess what?

88 The existence of a template file is still cached, even with debug enabled :(

89

90

91 templates/node.html.twig <article{{ attributes }}> {{ title_prefix }} {% if not page %} <h2{{ title_attributes }}> <a href="{{ url }}" rel="bookmark">{{ label }}</a> </h2> {% endif %} {{ title_suffix }} {% if display_submitted %} <footer> {{ author_picture }} <div{{ author_attributes }}> {% trans %}Submitted by {{ author_name }} on {{ date }}{% endtrans %} {{ metadata }} </div> </footer> {% endif %} <div{{ content_attributes }}> {{ dump(content) }} {{ content }} </div> </article>

92 array (size=5) 'field_image' => array (size=2) '#cache' => array (size=3) 'contexts' => array (size=0)... 'tags' => array (size=0)... 'max-age' => int -1 '#weight' => int -1 'body' => array (size=16) '#theme' => string 'field' (length=5) '#title' => string 'Body' (length=4) '#label_display' => string 'hidden' (length=6) '#view_mode' => string 'full' (length=4) '#language' => string 'en' (length=2) '#field_name' => string 'body' (length=4) '#field_type' => string 'text_with_summary' (length=17) '#field_translatable' => boolean true '#entity_type' => string 'node' (length=4) '#bundle' => string 'article' (length=7)...

93 <div{{ content_attributes }}> <div class="for-the-tags"> {{ content.field_tags }} </div> {{ content without('field_tags') }} </div>

94 But what variables are defined?

95 {{ dump() }}

96 Other fun stuff to do with templates

97 {{ attach_library('demo/landing-pages') }}

98 {% import _self as menus %} {# We call a macro which calls itself to render the full #} {{ menus.menu_links(items, attributes, 0) }} {% macro menu_links(items, attributes, menu_level) %} {% import _self as menus %} {% if items %} {% if menu_level == 0 %} <ul{{ attributes.addclass('menu') }}> {% else %} <ul class="menu"> {% endif %} {% for item in items %} <li{{ item.attributes }}> {{ link(item.title, item.url) }} {% if item.below %} {{ menus.menu_links(item.below, attributes, menu_level + 1) }} {% endif %} </li> {% endfor %} </ul> {% endif %} {% endmacro %}

99 So you ve got a handle on templates

100 You know how to find template names, suggestions, but

101

102 <body class="layout-one-sidebar layout-sidebar-first user-logged-in path-frontpage">

103 Not included by default with Drupal 8

104

105 But what if you liked those?

106 Enter the Classy theme

107 Classy theme Provides a base theme that just adds classes for other themes to build on Literally only has about 40 lines of CSS No PHP at all But over a hundred templates! Bartik uses Classy as a base theme

108 What s with the Drupal core CSS files?

109 </style> <style url("/core/modules/filter/css/filter.admin.css?nqlozl"); </style> <style url("/core/themes/bartik/css/components/table.css?nqlozl"); </style>

110 That s a lot of CSS!

111 Drupal 8 uses SMACSS

112 Scalable and Modular CSS It s a book! By Jonathan Snook! It s also a workshop! It s a guide for organizing CSS

113 SMACSS in Drupal 8 Base CSS reset/normalize plus HTML element styling. Layout macro arrangement of a web page, including any grid systems. Component discrete, reusable UI elements. State styles that deal with client-side changes to components. Theme purely visual styling ( look-and-feel ) for a component.

114 But it s really up to you in your theme

115 What are you likely to use in your theme? Base Layouts Component overrides Theme styles

116 css base elements.css components admin.css book.css breadcrumb.css buttons.css comments.css content.css contextual.css form.css forum.css sidebar.css skip-link.css tabs.css views.css layout.css maintenance-page.css print.css

117 Standards for organizing CSS

118 Best practices for CSS architecture in Drupal 8

119 Thank you! Please evaluate this session

120 Extras (time permitting)

121 Breakpoints

122 Allows you to expose your CSS breakpoints to the Drupal admin UI

123 demo.breakpoint.yml demo.mobile: label: mobile mediaquery: '' weight: 2 multipliers: - 2x demo.narrow: label: narrow mediaquery: 'all and (min-width: 560px) and (max-width: 850px)' weight: 1 multipliers: - 2x demo.wide: label: wide mediaquery: 'all and (min-width: 851px)' weight: 0 multipliers: - 2x

124

125 <picture> <!--[if IE 9]><video style="display: none;"><![endif]--> <source srcset="styles/large/billy_mays.jpg 1x, styles/ large_960x_960_/billy_mays.jpg 2x" media="all and (min-width: 851px)" type="image/jpeg"> <source srcset="styles/medium/billy_mays.jpg 1x, styles/ medium_440x440_/billy_mays.jpg 2x" media="all and (min-width: 560px) and (max-width: 850px)" type="image/jpeg"> <source srcset="styles/thumbnail/billy_mays.jpg 1x" type="image/jpeg"> <!--[if IE 9]></video><![endif]--> <img property="schema:image" srcset="" alt="billy Mays here" typeof="foaf:image" data-pfsrcset="styles/large_960x_960_/ Billy_Mays.jpg" src="styles/large_960x_960_/billy_mays.jpg" style="" width="350"> </picture>

126 Screenshots

127 This is ugly

128 Add a screenshot Make a PNG Make it 588 x 438 Call it screenshot.png BOOM

129 But really, there are directions

130 Thank you! Please evaluate this session