Search

Wherever Gulp finds a file that should be processed, it will create a dist folder next to it. The Gulp is smart enough to rename it's files, so you never have to open up the folder to see if the names are matching.

Gulp is configured to optimise any jpg, png or gif by using a lossless compression. Lossless means that no quality is lost, so when developing, you can safely use the images found in the dist folder, while also keeping the originals.

Sourcemapping enables you to trace back from which .scss file any rule in CSS is generated by. This can be handy when you are inspecting CSS in the browser. This would also be handy if you decide to use partial .scss files within a component.

In this chapter we'll first cover the component-specific Sass, and then we will cover the theme-wide Sass.

Gulp will only compile the CSS of the component that you are working in, except for when you are changing something within _sass-essentials. When changing something in _sass-essentials, Gulp will make sure, all the CSS of each component of the theme is re-generated.

Gulp is smart enough to only compile the files that it needs to compile. This means that if you change some JS inside a component, Gulp will only compile the JS of that component and not the JS from every component of the theme. This makes the compilation process as fast as possible. Each JS file that you write in a component will generate a JS file in a sibling dist folder.

While theming a Drupal site, it happens often that in order to make your theming changes take place, you have to run the well known drush cr command. If you are not sure about the inner workings of Drupal’s caching system, Compony is here to help you out.

You can configure your Gulp to allow Browsersync to help you develop. You can enable this in local.config.js, and filling in the url of your setup in usePackages.browsersync_localhost. Hat tip: Browsersync will keep multiple browsers & devices in sync, so when you open the same url on a smartphone and a desktop, scrolling on the desktop will also scroll the mobile device. For this to work, you need to be connected to the same network.

When working with more people on the same theme, someone might remove a component and commit it in Git. When you pull changes, due to the nature of Git, the files will be removed, but the folder won't. Therefor, when running the gulp command, Compony removes empty folders. If you want a folder to stay, you could put a .gitkeep file in them.

Compony embodies the component-based approach. This means that nesting, adding or renaming components will be a common task. To accommodate you as a Frontender, we made sure that you don’t need to re-run the gulp command when refactoring components.

The .component.yml file is a hidden file, that you will only have inside components that you downloaded from compony.io. This file is automatically generated when you click the download button and contains all of the information about the component. 

Under the features key in local.config.js, you can choose what features you want to enable inside your Gulp setup,

You can choose when Gulp should produce native notifications. Setting a notification setting to false, will only prevent the notification in your operating system, but it will still show on your command line output.

When you download a JavaScript library online, you should add that library code to the component. But you don’t want Gulp to uglify, minify and lint it, as most libraries online already come with a minified version. Therefor Gulp is configured by default to ignore any .js file that ends with .min.js in the filename.

When you write a mistake in a JavaScript, the Gulp will notify you in the command line and with a native notification.

Compony is capable of handling cutting edge JavaScript. The Javascript in the dist folder will be browser-compatible to a version of JavaScript you can control.

Compony will minify the JavaScript you write in components by uglifying the JavaScript inside the dist folder.

If you don’t want Gulp to process a certain .js file, you can tell Gulp that a file is a partial JavaScript file, by starting it’s filename with an underscore _.

Components can have a [component-name].theme file, therefor Gulp has a PHP linter that detects formatting errors.

Use a linter that detects formatting errors in your component'slibraries.yml files.

Use a linter that detects formatting errors in your [component-name].html.twig files.

When you write a mistake in Sass, the watchers in Gulp will notify you in the command line and give you a native notification.

Autoprefixer is enabled by default and will prefix according to the configuration set in project.config.js.

The Gulp setup supports Sass Globbing which means within your [component-name].scss file you could write: @import "_my-partials/**/*.scss";

Inside a component, each .scss file will generate a CSS file in a sibling dist folder.  If you don’t want that for a certain file, you can tell Gulp that a certain file is a partial, by starting it’s filename with an underscore.

This part defines the path to your Drupal-theme(s) you want this Gulp setup to run on. If you leave the gulpfile.js folder in the Drupal-theme, the path-variable can be an empty string: ''.If you have multiple themes in your project, or if you want to keep your theme as clean as possible, you could drag the gulpfile.js folder out of your theme, and put it in the root of the project

Anything you change in this file will impact the generated files such as CSS and JavaScript of your components, so each change you make in this file, will need to be committed to your repository so that your colleagues also have these same settings. We have 2 sets of options here: you can choose to link your Gulp to 1 or more themes and you can also choose what features you want to enable inside Gulp.

Tree shaking is a term commonly used in the JavaScript context for dead-code elimination.

This documentation is about the Compony theme and the Compony Gulp setup.

The first and most important part is introducing a new way of theming. 80% of this documentation is repeating Drupal's best practices, and 20% is taking it to new heights. This documentation has a focus on Drupal Frontend developers from any skill-level. We start off with a bit of orientation and will from there cover all the concepts of a Compony-theme.

Documentation overview page for the theme folder structure.

A Compony-theme looks a lot like any other Drupal 8 theme, let's first cover the files that are default in a Drupal 8 theme.

If you open up the components folder, you should see a bunch of subfolders. Each subfolder is either a component, or a collection of components.

The main structure to notice is the dist folder. The files inside the dist folder will always be compiled by Gulp. The rest of the files are in the root of the component-folder.

Putting files in a folder together, doesn’t make it a component yet. We need a bit of logic to make it in to a component Drupal can understand.

In Compony, we consider everything to be a component. In this chapter we'll first cover the concept of a component, and then we'll cover each part that a component can consist off.

In this chapter we'll cover the inner structure of a component. Then we'll cover what it sticks it all together to be a functioning component. And finally we'll cover the the naming convention to follow to have a as clear as possible component-system.

In practice you could choose the name of the folders of each component yourself. You could name something: messages-thingy and that could work. But to avoid complexity and a high randomness-factor, we will follow the BEM-naming. This naming convention is used by Drupal and can be best seen in the names of the .html.twig files.

If your component contains any CSS or JS or both, you will need a libraries.yml file.

Within a Compony-theme we are not doing anything specific with .html.twig files. However, We are using a lot of good practices, that might be unfamiliar to theming in a conventional way. The main difference is that we make heavy use of extending templates from each other to prevent scalability issues.

When you have multiple template files in the same component, you can group them together for clarity. An example would be to create a templates folder within your component.

The rule of thumb is: if there is a double hyphen -- in the name of the .html.twig file of your component, you should extend. Extending is a core Twig-functionality that is often overlooked in a Drupal context. It is so powerful for consistency that we are making heavy use of it in our component-based approach.

Let’s go back to our examples of nodes of the previous chapter and let’s have a look at how node.html.twig looks like from core (simplified for readability sake)

You can think of the concept of “attaching a library” as linking assets such as CSS or JS to HTML. For Drupal, this means: If I am going to use that .html.twig file, I should also send along the assets it's attached library. In the context of aggregating CSS/JS it makes sense too: If Drupal is about to render a page, it will make a list of all the templates it needs for that page. Not only that, it will also list all the assets of each of those templates, aggregate them together, and send them along with the page.

Drupal’s backend gives you an overview for everyone to reorder the fields as they see fit. Templates, give you the flexibility of making sure no-one moves fields around, when styling or design is depending on it. It also gives you the flexibility of only hardcoding the position of the fields that need hardcoding and leave the rest intact. It’s important to note that both options are completely valid, and each have their advantages. It’s recommended to start with the backend-approach, and hardcode the parts in the templates when needed.

The traditional approach (in Drupal 7) was to copy the node-template found from core in to our theme. This has the problem that each custom template wasn't considering changes from other template-files. And it is also goes against the DRY-principle. No longer! If we have 2 different templates that both have node.html.twig as a base, then we should respect the custom things defined in the base node.html.twig.

In this chapter we'll start by talking about the different categories we have in Sass. Next we'll talk about the different locations we have in Compony where you can write Sass. We'll also cover the different conventions we are using in Compony and the most common pitffalls and anti-patterns

To understand this part of the documentation, it helps to keep in mind that browsers don’t read Sass. Sass is merely a tool to generate CSS. With that in the back of our minds, that’s also how we implement Sass in to the Compony-theme. Understanding the difference between these 2 categories of Sass is important because of where you can write Sass in the theme. There are 3 locations of where you could write Sass and each location has a different impact on your theme’s output.

The sass-essentials should only contain None-CSS-generating Sass. This means that in this folder we should define our variables. Each component will be able to use these variables. You have the flexibility of restructuring these files under the _sass-essentials folder. The only name that can’t change is sass-essentials.scss, as that is used by our Gulp to be imported in to the components.

Everyone can write Sass however they want, but in order to keep it sane for new developers joining your project. You have the option to adopt some conventions in terms of naming, but also in comments.

There is no limit to how many Sass files you can have inside a component. If the component could benefit, from splitting it up a Sass file, you have the flexibility to do so. Each Sass file you create will create its corresponding CSS file.

This section is a warning to not use certain features of Sass that you have at your disposal. Sass is only a tool to generate CSS, nothing more. However, when working in a component-based setup, there are a few things that won’t work that well anymore.

There are many toolsets online that we can extend the functionality of Sass with. Compony is still in the early process of writing implementations for the most popular ones. If you are a fan of CSS-frameworks, we currently only support the ones that are contributed from the community. Have a look in Compony's Gulp documentation to find out what is already plug-and-playable from Sass tools or other npm packages that are waiting to be used.

This chapter will cover all the files that can be found inside a component.

All images that are put in to components will automatically be optimised in a lossless format and being put in a dist folder. When you want to group your images of your components in to a folder, you have the flexibility to do so. A dist folder will be generated in the same folder where your images are placed.

In this chapter we'll cover the Compony recommendations for a component-based approach within Drupal. And we will also cover how to include JavaScript libraries and frameworks.

Compony's recommendation on jQuery usage, Drupal Behaviours and writing cutting edge JavaScript.

We have a controversial, but simple approach to implementing JavaScript libraries you find online. Let’s say you want to use a JavaScript library in your component. Then you want the visitor of your site to load in that JavaScript library before executing your custom JavaScript. That's all it is, so with that in mind, let’s not make it more complex than it should be.

We are looking into getting a variation of Compony out for VueJS and React. But currently we don’t have that setup yet. We do recommend using these frameworks but for now you will have to add them manually to the component you want it in. Also make sure you only add the framework to the component that will use the framework. The division under the components-folder is to split up standalone frontend-components and is not meant for code-splitting a framework implementation.

Considering everything to be a component, the global .theme file is still in our way. Whatever we write in there applies to every component, so it breaks the standalone component approach. In programming terms this means that we should write a hook_preprocess_node function inside the node component. Not in the global [themename].theme file somewhere on line 314.

We haven’t mentioned the possibility of having component specific .theme files anywhere else in the documentation. The reason is because it's not vital to your project. If you want to get in to PHP as a themer, this is the way to do it. Usually 95% of what you want to accomplish inside the theming layer is possible within Twig templates. But for that extra 5%, we have the possibility of having a component-specific .theme-file. You can see this file as a partial of the [themename].theme file. There is no added functionality you can write in here that you can’t write in the global [themename].theme file.

Inside a .theme file, there are a lot of php functions that you could use to alter the way Drupal works. However, it’s not because you can write functions inside a .theme file, that you should do it here. A lot of functions that you could write, belong in a custom Drupal module. Only functions that impact the presentational layer should be used inside a .theme file. Functions that change something in the business logic, should go in to a custom module. If you Google these concepts, you get some big words thrown at you about what the difference is between the 2 logics. Here is our stab at explaining it in a way actual humans (read: Frontenders) can understand.

Frontenders don’t like diving in to PHP, but if you do master a few PHP functions, a lot of possibilities will open up. If you already have a good understanding of the hook system, please skip to: "Extending existing principles". Trying to understand the complexity of the different functions as a themer is as endless, as it is deep. Researching it, usually ends up with a whole lot of mumbo-jumbo-backendy complex gibberish.

In the previous chapter, we brushed up on the following 4 functions: HOOK_preprocess_hook, HOOK_theme_suggestions_hook_alter, HOOK_theme and HOOK_library_info_alter. The first 2 functions, we have to replace the word hook in them to the name of the component that we want to impact. Therefor those 2 functions are theoretically component-based. The last 2 functions are not component-based, and we can only write those once per theme. (Due to a limitation in PHP, you also can’t have 2 functions with exactly the same name.) Having a function that is theme-specific, isn’t the component-way. Therefor Compony is extending these functions to become component-specific. This means you can use them from inside .theme files within components, without having to worry of duplicating functions.

If you would want to a preprocess for both node--article and node--blog, then you would need to write a my_theme_preprocess_node function in both component-folders. Due to a limitation in PHP, you can't have the same function name in both components, so let's extend this component-specific function to be template_suggestion-specific function!

We believe that creating a state-of-the-art Gulp-setup can cause baldness from excessive head-scratching. Our Gulp came to life as a set of helping tools specifically for a component-based Drupal setup. The Gulp-setup is also open-source, which means that you won’t have to worry about trying to keep it up to date, or to make updated npm-packages work together. The Gulp setup is opinionated, but customisable to the needs of your project and to the needs of a development team that operates in multiple ways. Within the same project it can handle multiple environments and operating systems.

Let's focus on the Gulp-specific files of the Compony-theme.

Gulp has been set up in a way that it is easy to finetune. This fine tuning can happen on 2 levels: project-specific and environment-specific. This separation makes it possible to work independent of how other team members, while working with the same Gulp-setup.

Inside the gulpfile.js folder, the files you should edit, are the files that end on config.js. project.config.js is the project-specific configuration. This file will be the same on each environment.The config.js file is the default environment-specific configuration. If you want to change something inside this file for your local setup, don’t. Instead, you should copy this file and name it local.config.js. The local.config.js file will be git-ignored by default, so each environment can create its own local.config.js file.

Let's cover the contents of the local.config.js file.

Let's cover the features that you can enable from within project.config.js.

The previous chapter covered the different configuration options, this chapter covers the different steps in order to get your Gulp running.

For installation you will need to have both Node and NVM installed. You could also opt to install Gulp, but that is not a requirement to install that separately.

You will need to use the correct Node version and you will also need to install the node modules either through npm or through Yarn.

There are only 2 gulp commands you need to know, and you have the option of running them with your local installed Gulp, or with the Gulp that comes installed in your node_modules.

The Gulp setup is stuffed to the brim with usefulness, all handmade for component-based Drupal theming. We are still expanding the setup to be even more helpful, and more features will become optional over time. Certain features are optional to use for either your environment, or for your project. Please note that these features are only developer-tools, and none of these features are required to make your Compony-theme work in Drupal. The Compony theme has no dependency on Gulp!