From d89afe210e26ba495e7cb1f7789f7da9210c0772 Mon Sep 17 00:00:00 2001 From: Mike Henninger Date: Wed, 17 Apr 2024 15:55:59 -0400 Subject: [PATCH 1/2] Issue #36 - Updating the README.md to use ddev for theme development. Updating how the subtheme should be used... this section is still WIP. --- README.md | 148 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 120 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1384232..afbfa35 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,38 @@ -# psulib_base +# PSU Libraries Base Theme (psulib_base) -## Developing with this theme -1.) bare clone drupal-site-config into a theme development folder -``` -git clone --bare git@github.com:psu-libraries/drupal-site-config.git ~/theme_wrapper -``` +This theme is intended to be used for PSU Branded Libraries Drupal sites. This is based on the [Bootstrap 5](https://getbootstrap.com/docs/5.3/getting-started/introduction/) framework. -2.) clone psulib_base theme into development site -``` -cd ~/theme_wrapper/web/themes/contrib -rm -rf psulib_base -cd ~/theme_wrapper/web/themes/custom -rm -rf psulib_base -git clone git@github.com:psu-libraries/psulib_base.git -``` +## Development -3.) start up theme-wrapper project +This base theme is easiest to develop using a theme generated using the [drupal-site-template](https://github.com/psu-libraries/drupal-site-template) or using the site template itself. This will use the psul-web site as an example. + +### New DDEV Environment + +```bash +gh repo clone psu-libraries/psul-web; +cd psul-web; +ddev start; +ddev drush si --existing-config; +ddev develop-theme; +ddev theme-build; +ddev launch; ``` -cd ~/theme_wrapper -ddev config --project-name=theme-wrapper -ddev config --additional-hostnames theme-wrapper -ddev start -ddev drush si --existing-config -y + +### Existing DDEV Environment + +```bash +ddev develop-theme; +ddev theme-build; +ddev launch; ``` +## Using this Theme + +The psulib_base theme can be used as a standalone theme but can also act as a base theme if custom styles are required. There are 3 ways to use this base theme, which are listed below. -## Using this Base Theme +### Installing -This base theme is intended to be a base that operates with a child theme in your site. To use this base theme, you must first add the base theme repository in your site's composer.json (either manually or with this command): +To use this base theme, you must first add the base theme repository in your site's composer.json (either manually or with this command): ```bash ddev composer config repositories.psul/theme-base github "https://github.com/psu-libraries/psulib_base.git" @@ -38,17 +43,97 @@ Then, require the actual base theme: ```bash ddev composer require psu-libraries/psulib_base ``` + and install it with Drush ```bash ddev drush theme:enable psulib_base ``` -This does not make the theme 'default' ... it just makes the theme available to the system. You then can create your child/sub-theme. +### Standalone -For more information about creating a subtheme: -- [Drupal.org - Subtheming](https://www.drupal.org/node/2165673) -- [Drupalize.me - Use a Base Theme](https://drupalize.me/tutorial/use-base-theme) +If you are using this as a standalone theme then you will need to run the following command after the theme has been installed. + +```bash +ddev drush config-set system.theme default psulib_base; +``` + +### Base Theme Extended Styles + +If you want to use all styles in the base theme BUT add additional styles for your site. You will be able to use scss `variables` and `mixins` but NOT `extends` as the + +```bash +ddev generate-subtheme SUBTHEMENAME; +``` + +Update the styles.scss with the following. + +```scss +// Include bootstrap. +@import '../../../../themes/contrib/psulib_base/scss/init'; + +// Sub theme styling. +``` + +Update `webpack.mix.js` file to exclude base theme specific components. This should look like the following. +```js +// webpack.mix.js + +let mix = require('laravel-mix'); + +// Use relative URL so fonts will work. +mix.sass('scss/style.scss', 'dist/css') + .options({ + processCssUrls: false + }); + +// Combine custom javascript into the application.js file. +mix.combine('js/base', 'dist/js/application.js'); +``` + +### Base Theme Override Styles + +If you want to override ALL styles coming from the base theme. + +```bash +ddev generate-subtheme SUBTHEMENAME; +``` + +Update the styles.scss with the following to re-build the styles in the base theme. (**THIS NEEDS WORK. The scss does not allow you to override variables.**) + +```scss +// Include bootstrap. +@import '../../../../themes/contrib/psulib_base/scss/style'; + +// Sub theme styling. +``` + +Add the following to the subtheme `*.info.yml` file to exclude the base theme library so styles are lot loaded twice: + +```yaml +libraries-override: + psulib_base/global-styling: + css: + theme: + dist/css/style.css: {} +``` + +Update `webpack.mix.js` file to exclude base theme specific components. This should look like the following. + +```js +// webpack.mix.js + +let mix = require('laravel-mix'); + +// Use relative URL so fonts will work. +mix.sass('scss/style.scss', 'dist/css') + .options({ + processCssUrls: false + }); + +// Combine custom javascript into the application.js file. +mix.combine('js/base', 'dist/js/application.js'); +``` ## Creating a subtheme @@ -60,7 +145,7 @@ git clone git@github.com:psu-libraries/drupal-site-template.git ~/drupal-site-te cp -rf ~/drupal-site-template/.ddev/commands/web/ .ddev/commands ``` -This will create 3 new ddev commands for you to create a subtheme, build the theme, and watch the theme for changes +This will create 3 new ddev commands for you to create a subtheme, build the theme, and watch the theme for changes ``` ddev generate-subtheme @@ -73,9 +158,16 @@ ddev theme-watch Since there is no current CI/CD process to build out the assets on demand, the bootrap icons are copied into the target theme on npm install. There is a postinstall script to copy fonts/icons into ./assets/bootstrap/fonts - + Once this has run you can use it as documented on https://icons.getbootstrap.com: ```html ``` + + +## Resources +For more information about creating a subtheme: +- [Drupal.org - Subtheming](https://www.drupal.org/node/2165673) +- [Drupalize.me - Use a Base Theme](https://drupalize.me/tutorial/use-base-theme) +- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.3/getting-started/introduction/) \ No newline at end of file From 22c046b67e94d48f51877bb0946c28dfda2450ed Mon Sep 17 00:00:00 2001 From: Mike Henninger Date: Wed, 17 Apr 2024 16:00:29 -0400 Subject: [PATCH 2/2] Issue #36 - Removing duplicate steps for generating the subtheme. --- README.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/README.md b/README.md index afbfa35..0a6b866 100644 --- a/README.md +++ b/README.md @@ -135,24 +135,6 @@ mix.sass('scss/style.scss', 'dist/css') mix.combine('js/base', 'dist/js/application.js'); ``` -## Creating a subtheme - -1.) Install the ddev web commands - -From your project directory -``` -git clone git@github.com:psu-libraries/drupal-site-template.git ~/drupal-site-template -cp -rf ~/drupal-site-template/.ddev/commands/web/ .ddev/commands -``` - -This will create 3 new ddev commands for you to create a subtheme, build the theme, and watch the theme for changes - -``` -ddev generate-subtheme -ddev theme-build -ddev theme-watch -``` - ## Boostrap Icons Since there is no current CI/CD process to build out the assets on demand, the bootrap icons are copied into the target theme on npm install.