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.
We offer workshops, training, consultancy, support & sponsor visibility.
We want to promote the companies and organisations that are using this platform to deliver the most enhanced Frontend on your Drupal sites. But we also need some financial backing to keep the platform running and improving. Therefor we can help each other: we give your organisation the publicity you deserve for using cutting-edge technology. While we keep improving the tech and support the Compony-community as much as possible. We are looking for 1 official supporter per country. This means that for each country, we will accept only one supporter.
So how do we make a component self-independent so they are usable by others, or by yourself in future projects.
An opinionated kickstart-theme, Gulp setup and community-driven platform for Drupal.
Components are built by and for the community. How do we handle security within components?
We have loads of ways to get in contact with us! Slack, Twitter, Instagram, Linkedin, Facebook & Dev.to.
How do your rename a Compony theme, and use multiple themes with the same Gulp-setup?
The answer to the question of updatability for Compony components is not a simple one to give.
Therefor we will first explain the principle around which we built this solution. Next, will cover some good and some bad solutions around this principle. And finally we talk about how the current implementation of updatability of Compony looks like.
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.
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
The theme skeleton is compatible with every version of Drupal 8. However, in our transition towards Drupal 9, we will loose some backwards compatibility with earlier version of Drupal 8. In order to give you the option to use Compony on older projects we will track here which version of the theme skeleton has which compatibility with Drupal versions.
Compony comes in 3 layers: the theme, the gulp & the platform
If you want to understand how to start with using these 3 layers, then this blogpost is for you!
There are loads of ways of how you could link components together, but the way how you do this can bring issues or complexity with it. So let's go over what your options are.
Someone asked us recently if there was something that Compony couldn't fix.
We thought long and hard about it... and it turns out that no, there is nothing Compony couldn't help fix.
Caution this article might contain minor traces of satire and irony.
This page explains what the trademarks are, who has ownership of copyright and how we handle third party libraries. Compony.io is a platform that accommodates the spreading of components. The platform also accommodates collections, but those are a mere wrapper around components. Components are in turn always hosted on Gitlab.com. The platform accommodates both public and private components. Both type of components are licensed under the GPL2 license.
Compony is a fun, welcoming, challenging, and fair place to play. This Code of Conduct (CoC) states our shared ideals with respect to conduct. are the coding standards for people within our community. It is a way to communicate our existing values to the entire community.
Compony is an opinionated solution to introduce cutting edge standards to the Frontend of Drupal 8. As an open source project, built by and for the Drupal Frontend community, we are aligned with the Drupal project in terms of licensing, trademarks and copyrights.
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone
Mathieu Spillebeen is currently the contact for the Code of Conduct (CoC) and can be reached by all means you find appropriate on his website. Mathieu is currently the diversity lead of Frontend United and has received training in matters of conduct.
This blogpost labels the nuances, downsides, limitations and side-effects around different processes of updatability. This blogpost has the intention of clarifying the complex landscape of updating software, in a push for a good approach by Compony.
If we talk about Drupal theming, then we mostly get in contact with 2 package managers: Composer and NPM. This blogpost provides both an explication and a deep dive in to how they got build conceptually, so that we can learn from them.
Updatability of software relies on many different mechanisms and comes in many different forms each holding their own limitations. Lately, we have gotten the question a lot around how we could update components of Compony. This blogpost is intended to explain some different concepts of updatability in the wild. Having the explication of these different concepts under our belts will be needed to take this a step further as a community.
An open source project built by and for the Drupal Frontend community. Supporting collaboration around separated, functional, fully independent, cutting-edge, Drupal Frontend components. Download the kickstart-theme, and then pick your components you want to plug in to your theme.
This blogpost is a living source of tricks for Drupal Front-end developers that find themselves clearing cache manually over and over again.
The value of a community is the sum of the energy of everyone involved. You organise a conference, which brings all of this energy together in to a momentum where the community can thrive. Compony does the same thing, we bring people together by facilitating collaboration.
This page contains our design styleguide.
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.
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!