One of the benefits of using Drupal single directory components is that Drupal automatically builds and attaches an asset library whenever it is used. Adding CSS styles and JavaScript interactivity to a single directory component (SDC) is as simple as dropping component-name.css and component-name.js files into the root directory of the component. Drupal detects these files, creates an asset library, and attaches it when the component is rendered. This means when you want to add additional CSS or JavaScript assets, you will override the asset library created for your component instead of defining a new one.
In this tutorial, we will:
- Add component-scoped CSS and JavaScript files.
- Learn how to override a component's existing asset library to add additional assets.
- Discuss how to integrate common front-end asset build tools (Gulp, Webpack, Vite, etc.) while working with Drupal single directory components.
By the end of this tutorial, you'll be able to attach CSS and JavaScript assets to an SDC and validate that they load only when the component is in use.
Drupal single directory components use Twig template files to define their HTML markup and how the values of props and slots are displayed. To discover available props and slots, read the component’s .component.yml file. When working with slots, you’ll often choose between rendering a slot as a Twig block ({% block %}) or interpolating a variable directly ({{ variable }}).
In this tutorial, you’ll:
- Add a card.twig file to an existing component directory.
- Read the associated card.component.yml schema to identify props and slots you can work with.
- Render props and slots wrapped in custom HTML markup.
By the end of this tutorial, you’ll be able to connect a Twig template to any SDC and render the props and slots passed into the component.
A Drupal single directory component (SDC) is Drupal's way of packaging the markup, metadata, styles, and behavior for a UI element in one self-contained folder inside a theme or module. This structure helps front-end developers and site builders keep all related files together for easier theming and reuse. A Drupal single directory component directory must be located in a specific place and its files named with a particular convention so that the system can discover it and use its assets.
In this tutorial, we'll:
- Show where Drupal discovers single directory components in your codebase.
- Explain the naming and organization conventions for Drupal single directory component directories and files.
- Outline key files for a component—both required and optional.
By the end of this tutorial, you'll be able to identify an SDC directory in a Drupal module or theme and know exactly what you're looking at.
Using Vite we can scaffold a stand-alone React application with modern tooling, instant dev-server startup, and hot module replacement. It's a great way to get started with React and works perfectly for decoupled apps that talk to Drupal's JSON:API. After creating the scaffold, we'll port code from previous tutorials to the new structure.
In this tutorial we'll:
- Use Vite to scaffold a new React project
- Refactor existing code into Vite's project structure
- Confirm that our code runs
By the end of this tutorial, you'll know what Vite is and how to get started using it for a decoupled React app.
Props and slots are the two ways that data can be provided to a single directory component (SDC). They are part of a component's schema definition, and are used to determine the names of variables passed to a component's template file. Props pass structured, validated data into a component, while slots allow us to inject flexible content such as HTML or nested components. Understanding when and how to use each ensures you can build reusable and adaptable components.
In this tutorial, we'll:
- Learn what props and slots are, and how they differ.
- Discuss how using one or the other impacts the developer experience and use of your components in a UI.
- Practice deciding when to use each for component design.
By the end of this tutorial, you'll know how to choose between props and slots when building components.
Overriding Single Directory Components (SDCs) allows you to safely customize the functionality and appearance of components provided by contrib modules or themes. Instead of editing the original files, copy a component into your theme, declare that it replaces the original, and then make the necessary adjustments. This approach ensures our changes are upgrade-safe and easy to maintain.
In this tutorial, we will:
- Copy an existing SDC into a theme.
- Use the
replaces:key in the component metadata to declare the override. - Modify the component Twig, CSS, or JavaScript and confirm the changes appear on our site.
By the end of this tutorial, you should be able to override SDCs safely and maintain your customizations in an upgrade-safe manner.
Converting an exisiting theme to Omega takes time and some planning, but Omega gives us plenty of options of moving things around the page all without touching a piece of code. When working with a grid layout we use Omega to set all of our content to span the proper columns all while moving our content from zone to zone so it is placed properly on the page. We will cover:
- Moving content from zone to zone
- Choosing proper zone column widths
- Splitting column amounts to create right and left columns
Once all of this is complete we are just a few steps away from getting into some CSS and really making our theme come together as an Omega sub-theme.
Additional notes:
If you want to touch code, you can edit the .info file as such (for the first part, moving branding zone):
settings[alpha_region_branding_zone] = 'header'
...
settings[alpha_region_branding_weight] = '3'
...
settings[alpha_region_header_first_weight] = '1'
...
settings[alpha_region_header_second_weight] = '2'
Responsive design is more than a just a buzzword these days but a standard practice of good web shops when building out a site. Omega provides a responsive design out of the box and gives lots of options to layout your content in the proper places and the ability to work with the break-points all with a User Interface. In this lesson we will cover:
- Omega responsive options
- Column settings for your grid layout
- Omega responsive layout settings
- Device viewports and media queries
We end the lesson getting our new sub-theme ready to handle our 960 robots theme and the 16 column setup we designed it with.
If you prefer working with code, instead of the web UI, you may configure your theme as follows to change your column settings from 12 grid columns to 16 in your theme's .info file:
Find and replace all the instances of:
_columns] = '12'
with:
_columns] = '16'
There may still be additional regions that also need to be set which weren't the full width. You can edit other regions as needed, such as:
_region_user_first_columns] = '8'
change to:
_region_user_first_columns] = '12'
Walks through the process of first adding the search block to the node template file, and then explains some of the best practices for incorporating JavaScript scripts within your theme. Walks through how to protect the dollar-sign variable, and how to use the Drupal behaviors instead of the document ready so that your JavaScript will fire not only on page loads, but also if there is any dynamic material being loaded on the page through asynchronous page loads. We'll show you how to select the jQuery selector to target the desired element, and how to conform to Drupal's best-practice coding standards when it comes to integrating JavaScript and jQuery into your theme. You can learn more about jQuery itself with the Introduction to jQuery Series.
To use Query in no conflict mode, because was not defined.
Add this line on the top: jQuery.noConflict(); more info here: http://api.jquery.com/jQuery.noConflict/
To improve how the search box looks, you need to modify the following:
currently : search-theme-form
modify to: search-block-form
and then in the property in line 321 to look like this:
/* Header quick search */
#header form#search-block-form {
top: -165px;
Additional resources
Shows how you can use the ajax framework in Drupal 7 to load additional content onto the page dynamically after clicking on a 'read more' link.
The sample code for this series is in the Downloads tab for the first video in this series: http://drupalize.me/videos/introduction-jquery-and-javascript-drupal#do…. If you're skipping around, and things aren't working, you may benefit from going back to the beginning and completing each of the videos in order.
Emma Jane Westby introduces the series. In this series, you'll learn how to transform a static design file into a whole Drupal theme. We'll work through three major steps.
- Develop a style guide based on the design patterns we see in our design files.
- Build out Drupal so that it has all of the elements we need in place.
- Work with theming files to decorate Drupal.
Additional Resources
In addition to the lessons in this series, Emma has assembled an extensive FAQ on Drupal theming.
In this lesson we'll take a tour of the theme you'll be building. The design we'll be working with was created by Betty Bisenthal. It's a fairly simple design with three columns and a banner image. It has been used as a starting point for several years by many people who are learning to theme. In this lesson we'll take a look at:
- the design we'll be working with
- variations of this design created by other students
- how Drupal was customized to accommodate our design
- the Sass used to create the layout for the site
By the end of this lesson you'll be able to describe the shape of the design used throughout this series, and identify variants of the design.
Additional resources
In this lesson we're going to learn about the front end development strategy of theming by components. This strategy relies on being able to break a design into individual components. Elsewhere on the Web this technique has been described as “atomic design” or “interface pattern pairing”. No matter what you call it, developing a pattern library of components is going to make it a lot easier to convert your design to a theme. This is an overview lesson that explains the strategy we'll be using in future lessons. More specifically, we'll look at:
- two popular pattern libraries
- an overview of how pages are built by Drupal so they can be rendered in a browser
By the end of this lesson you'll be able to identify components from a static design file by referencing a pattern library.
Additional resources
SMACSS (Scalable and Modular Architecture for CSS)
Over the last couple of years we've seen the rise of object oriented CSS. There's been a lot of work done by smart folks to categorize different types of rules that we use to style our sites. We're going to take advantage of this work and use it to create a style guide. This foundation piece will help us to map the elements in our static design to the elements that we will build, and theme, in Drupal.In this lesson we'll create a style guide from our design with:
- Base rules
- Layout rules
- Component rules
By the end of this lesson you will be able to create a text-based style guide of your design which accurately describes your site according to base rules, layout rules, and component rules. You will be able to further supplement this style guide by adding relevant images which reference the exact component the style guide is describing.
In the previous lesson you created a text-based style guide. It's now time to extract the necessary assets from our static design for use in our theme. To complete this lesson you will need a design application capable of opening a .psd file. The video demonstrates Photoshop, but I typically use Gimp. Either is fine. And if you don't have a graphics program, you can watch the video, but simply download the assets which were extracted during the lesson. By the end of this lesson you will be able to identify page-level design assets which need to be extracted from a design file for your Drupal theme.
Additional resources
In this lesson we will convert the style guide into a series of stubs which we can view in a Web browser. The design was originally created using the templates from the 960gs. We'll use this same grid framework to ensure all of our margins are automatically adopted. Grid frameworks are excellent for rapid prototyping of designs. Ultimately many front end developers choose choose to write their own for the final theme; however, if you're just getting started try to stick with a grid framework to reduce the number of things that you need to fight with.
The original theme that was created for this design used the NineSixty base theme. There are some nifty features in this theme which are great for more complex designs; however, it is not responsive, and does not use Sass. To bring the lessons up-to-date we'll be using the 960-Compass Plugin to generate our stub files and give us some sample Sass output to work with.
By the end of this lesson you will be able to convert a style guide to a series of stub files in Sass (or CSS) using SMACSS conventions and a grid framework.
Additional resources
SMACSS (Scalable and Modular Architecture for CSS)
In SMACSS there are both major and minor layout rules that need to be created. The major layout rules are often handled by a grid framework and are used to describe big areas on your site, such as your Drupal regions. The minor rules are used for the components (for example how a picture aligns next to a paragraph of text). In this lesson we'll start by review how Sass allows us to use semantic naming for our CSS layout classes. Then we'll adapt the sample Sass provided by the 960 Compass Plugin so that it uses the necessary structure for our design.
By the end of this lesson, you will be able to implement the layout rules from your style guide as a Sass file using the 960 Compass Plugin as a reference.
Additional resources
The final step before we step back into Drupal is to create a checklist for all the things we need to implement in Drupal. Using our style guide as a starting point, we'll ensure that every design decision which has been made can be implemented in Drupal. Your checklist might also include notes about which modules should be used to build each of the components from within Drupal. Creating a checklist might seem like a trivial task, but it's really important that you know exactly what you're about to build so that you don't get overwhelmed once you step into Drupal. By the end of this lesson you should be able to create a document with all the instructions, and notes you will need to apply your style guide to a Drupal site.
Technically a theme can be installed onto any Drupal site, but it never quite works this way in real life. In this lesson we'll create a playground so that we can try out our theme before deploying it to a live server. We'll start by installing Drupal and adding some “fake” content and menus with the devel generate module. For these tasks we'll use Drupal's default theme, Bartik. By the end of this lesson you will be able to install Drupal in an environment where a development version of the theme can be safely tested.
Additional resources
One of the most time consuming things a content editor can be forced to do is resize images before creating their content. Fortunately we can get Drupal to do the resizing for us. It's not perfect—it's just a plain resize, but it's enough for most basic sites. By the end of this lesson, you will be able to configure Drupal to resize images to your specification when they are uploaded using the image field type.