Merge pull request #591 from City-of-Helsinki/UHF-12059

UHF-12059 Subtheme theme builder

Author: khalima

public/themes/custom/hdbt_subtheme/.eslintignore

@@ -1,3 +1 @@
 node_modules/**/*
-webpack.config.js
-webpack.svgToSprite.js

public/themes/custom/hdbt_subtheme/.nvmrc

@@ -1 +1 @@
-23
+22

public/themes/custom/hdbt_subtheme/README.md

@@ -4,34 +4,40 @@
 
 HDBT Subtheme is a so called "starterkit" which you can start using by enabling it in `/admin/appearance`.
 
-Or if you don't accept the theme name, you can rename every `hdbt_subtheme` file with `your_theme_name` and renaming every `hdbt_subtheme_*` variable/reference with `your_theme_name_*`. And then enable it in `/admin/appearance`.
+HDBT Subtheme uses HDBT theme builder to compile the JS and SCSS files. Also, the SVG icons are combined in to a sprite.svg via the theme builder.
 
-Of course you have a choice to not use it at all by just deleting the whole folder.
-
-HDBT Subtheme uses webpack module bundler to compile the JS and SCSS files. Also the SVG icons are combined in to a sprite.svg via webpack.
-
-As the HDBT Subtheme is only distributed via the [HELfi Platform](https://github.com/City-of-Helsinki/drupal-helfi-platform), it doesn't have an upgrade path per se. In case there is a demand for upgradeability for existing projects then of course we will consider changing the theme to an upgradeable model.
+As the HDBT Subtheme is only distributed via the [HELfi Platform](https://github.com/City-of-Helsinki/drupal-helfi-platform),
+it doesn't have an upgrade path per se. In case there is a demand for upgrade-ability for existing projects then of
+course we will consider changing the theme to an upgradeable model.
 
 ## Requirements
 
-HDBT Subtheme requires HDBT theme as a base theme and it should be installed in `/themes/custom/hdbt`.
+Do not rename the `hdbt_subtheme` as the Platform config 3.* assumes that the sub theme name is `hdbt_subtheme`.
+
+HDBT Subtheme requires [hdbt theme](https://github.com/City-of-helsinki/drupal-hdbt) as a base theme, and it should be
+installed in `/themes/contrib/hdbt`.
 
 Requirements for developing:
-- [NodeJS ( ^ 16.10 )](https://nodejs.org/en/)
+- [NodeJS](https://nodejs.org/en/)
 - [NPM](https://npmjs.com/)
 - optional [NVM](https://github.com/nvm-sh/nvm)
 
 ## Commands
 
-| Command       | Description                                                                       |
-| ------------- | --------------------------------------------------------------------------------- |
-| nvm use       | Uses correct Node version chosen for the subtheme compiler                        |
-| npm i         | Install dependencies and link local packages.                                     |
-| npm ci        | Install a project with a clean slate. Use especially in travis like environments. |
-| npm run dev   | Compile styles for development environment and watch file changes.                |
-| npm run build | Build packages for production. Minify CSS/JS. Create icon sprite.                 |
+| Command       | Make command               | Description                                                                       |
+|---------------|----------------------------|-----------------------------------------------------------------------------------|
+| nvm use       | N/A                        | Uses correct Node version chosen for the subtheme compiler                        |
+| npm i         | make install-hdbt-subtheme | Install dependencies and link local packages.                                     |
+| npm ci        | N/A                        | Install a project with a clean slate. Use especially in travis like environments. |
+| npm run dev   | make watch-hdbt-subtheme   | Compile styles for development environment and watch file changes.                |
+| npm run build | make build-hdbt-subtheme   | Build packages for production. Minify CSS/JS. Create icon sprite.                 |
+
+Consistent Node version defined in `.nvmrc` should be used. For development, use either `nvm` to select the correct
+version or `make` commands that select the version automatically. Run `make` the commands from the table above in the
+project directory of your instance. For more information, see
+[build-assets.md](https://github.com/City-of-Helsinki/drupal-helfi-platform/blob/main/documentation/build-assets.md).
 
-Setup the developing environment by running
+Set up the developing environment with `nvm` by running
 
     nvm use
     npm i
@@ -40,6 +46,12 @@ Explanations for commands.
 - `nvm use` : Install and use the correct version of Node.
 - `npm i` : As stated above; Install dependencies and link local packages.
 
+Related files.
+- `.nvmrc` : Defines the node version used to compile the theme.
+- `package.json and package-lock.json` : Defines the node modules for compiling the theme.
+- `theme-builder/` : The theme builder tools.
+- `theme-builder.mjs` : Configuration file for the theme builder tool that is used to build the theme.
+
 Start SCSS/JS watcher by running
 
     npm run dev
@@ -50,49 +62,28 @@ Build the minified versions of CSS/JS into dist with
 
 ## Structure for files and folders
 
-```
-hdbt_subtheme
-│   README.md
-└───templates
-│   └───block
-│   └───content
-│   └───...
-└───src
-│   └───scss
-│   │   │   styles.scss
-│   │   └───base
-│   │   │   └───__index.scss
-│   │   │   └───_base.scss
-│   │   │   └───...
-│   │   └───components
-│   │   │   └───__index.scss
-│   │   │   └───...
-│   │   └───...
-│   └───js
-│   │   │   common.js
-└───dist
-    └───css
-        |   styles.min.css
-    └───js
-        |   bundle.min.js
-```
+The structure follows the same rules as in the hdbt-theme so you should read about more from the
+[hdbt documentation](https://github.com/City-of-helsinki/drupal-hdbt).
 
 ## How tos
 
 ### My javascript has unexpected errors when loading a page in Drupal.
 
-If you have compiled the code with dev-flag (`nmp run dev`), then the sourcemaps expects the JS files to be found in correct places.
-This means that JS preprocessing (minifying) should be turned off. Just add the following lines to local.settings.php.
+If you have compiled the code with dev-flag (`nmp run dev`), then the sourcemaps expects the JS files to be found in
+correct places. This means that JS preprocessing (minifying) should be turned off. Just add the following lines to
+local.settings.php.
 ```
 $config['system.performance']['css']['preprocess'] = 0;
 $config['system.performance']['js']['preprocess'] = 0;
 ```
 
 ### I need to rebuild caches every time I build the css or change the twig files. How can I automate it?
 
-You can create a `local.settings.php` and `local.services.yml` files to `/sites/default/` folder and paste the following contents in them.
+You can create a `local.settings.php` and `local.services.yml` files to `/sites/default/` folder and paste the following
+contents in them.
 
-**_Keep in mind that using the Null Cache Backend is the primary culprit for caching issues. F.e. Something works in local environment, but not in production environment._**
+**_Keep in mind that using the Null Cache Backend is the primary culprit for caching issues. F.e. Something works in
+local environment, but not in production environment._**
 
 local.services.yml:
 ```
@@ -131,7 +122,8 @@ aggregation from Drupal. Go to /admin/config/development/performance and uncheck
 site caches and you should be able to continue with your work.
 
 ### How can I add custom translations?
-Add your UI translations to ``./translations/{fi/sv}.po`` files like it is explained in Translation in Drupal 8 documentation: https://www.drupal.org/docs/understanding-drupal/translation-in-drupal-8.
+Add your UI translations to `./translations/{fi/sv}.po` files like it is explained in Translation in Drupal
+documentation: https://www.drupal.org/docs/understanding-drupal/translation-in-drupal-8.
 These translations consists of:
 
 PHP
@@ -166,6 +158,6 @@ msgstr[1] "Monikko"
 
 To see these translation changes in an instance, run in container shell:
 ```
-drush locale:check && drush locale:update
+drush locale:check && drush locale:update && drush cr
 ```
 And then flush all caches from top left drupal admin menu under "Druplicon".