Front end and theming

This page is out of date and needs reviewing.

Who is this guide for?

This guide is for developers, maintainers and designers looking to work on a theme or the front end of an existing web site set up in Lando.

Introduction to Gulp

In most of the themes we support and create we use a task runner to compile Sass into CSS. In almost every case this is Gulp. The Lando stack provides the tools you need to run the commands that trigger the task runner to do it's various tasks.

Previously we needed to maintain various versions of NodeJS and a globally installed Gulp on our computer. This is no longer the case as we provide a Docker container with all the tools needed.

Prerequisites

You should have already installed Lando. If you haven't yet done that, please head back to the introduction page of these docs and follow the install notes in the How do I install Lando section.
You should already have a working 'Landoified' site. If not please ask a developer to set it up. Then follow the Using Lando guide to get a working Drupal site up.

Understanding these steps

Don't just copy paste each of the commands! You will need to edit some lines before hitting return. You will also need to open an editor (vim, nano etc) to modify lines in files.

Initial theme set up (once per site)

On every computer where you set up a Lando site and you want to do some front end work, you will need to ensure the theme's node modules are installed and that a set up task has been completed.

Make sure your containers are running (run from git root):

lando start

Now change to the theme's directory (Drupal 8+ example):

cd web/themes/custom/site_theme

Check that Lando has installed the node modules:

lando npm install

Generally Lando will have already installed the node modules the first time it starts up. If something did not complete successfully you may need to install them manually with the above command.

If you are running the current site_theme on Drupal 8+ then you'll also need to set up Pattern Lab with:

lando npm run setup

How to compile Sass

Make sure Lando is running (run from git root):

lando start

Now change to the theme's directory (Drupal 8+ example):

cd web/themes/custom/site_theme

From here you can run the commands needed to compile Sass. This depends on the type of theme:

Our current site_theme (modern D8 sites):
```
lando npm start
```
Older Omega based themes (most D7 sites):
```
lando gulp
```

Simple right? Basically just prefix the command you want to issue with lando and the command will run inside the container, making use of the tools installed inside.

How to view the site (or Pattern Lab) through browsersync

Make sure Lando is running (run from git root):

lando start

Modern D8 themes provide the Pattern Lab environment for developers and themers to work in. This is served by browsersync on port 3050 normally. Unfortunately we can't access it using http://localhost:3050 due to browsersync running inside the container. So instead we specify a (randomly generated) port in the .lando.yml file.

To discover the port number you have two options:

Run the following command from the git root:

sed -n 's/^.*ports: \[\(.*\):.*/\1/p' .lando.yml

Open the .lando.yml file in your editor and look for a line like:
```
        ports: [44032:44032]
```

Note the port number, in this example it is 44032

If your port number is 3050 then the developer that set this up missed some steps! They need to fix this so please locate them and ask them to update it.

If you haven't already, you can can start watching for file changes and serving Pattern Lab by changing directory to your theme:

cd web/themes/custom/site_theme

Check you set up Pattern Lab properly in the Initial theme set up part of this guide.

Depending on whether this is a modern Pattern Lab based theme or an older Omega based theme you can run one of the following commands:

Our current site_theme (modern D8 sites):
```
lando npm start
```
Older Omega based themes (most D7 sites):
```
lando gulp
```

You should now be able to view Pattern Lab (or your site through browsersync) by visiting localhost with the port number you made a note of earlier. In the example it would be:

http://localhost:44032

How to swap between Drupal and Pattern Lab through Browsersync

When you visit localhost with the port number you noted you will see either Pattern Lab or Drupal, depending on a line of config in gulpconfig.js. You can edit this file and comment out a line to swap between Drupal and Pattern Lab.

I want to see Pattern Lab but I see Drupal on localhost

If you don't see Pattern Lab (or a link to it) when you view localhost with your port number and instead see your Drupal site you will need to comment out a line of configuration in gulpconfig.js in your theme directory.

Edit gulpconfig.js and look around line 181 for a line that states the domain, like domain: 'appserver',

Comment it out so it looks like this:

browserSync: {
    enabled: true,
    port: 44032, // This port number will be different
    watchFiles: [],
    // enable when full CMS is set up
    // domain: 'appserver',
    baseDir: './',
    startPath: 'pattern-lab/public/',

Stop the task runner if it is currently running with control + c then start it again with:

lando npm start

Now when you view localhost with your port number you should see Pattern Lab instead of Drupal.

I want to see Drupal but I see Pattern Lab on localhost

If you want to see Drupal rather than Pattern Lab then edit gulpconfig.js again and uncomment the domain line. Restart the task runner (control + c then lando npm start). You should then see Drupal served on localhost and your port number.

I don't see anything on localhost:3050

Thats because you didn't read all of this document! Go back to 'How to view Pattern Lab' and read carefully. Hint: 3050 is not the port you are looking for.

Troubleshooting

If browsersync connects but you don't see updates getting pushed it is most likely one or a combination of these things:

Aggregation is currently turned on. Solution: Turn it off, either in the UI or by adding a line to settings.php or settings.local.php
link_css module is not enabled (D7). On D7 sites the link_css module must be enabled. Browsersync only works with css files added by the <link> method, not Drupal's default @import method.

Last updated: 3:09pm, 16th August 2023