PSU Libraries Base Theme (psulib_base)

This theme is intended to be used for PSU Branded Libraries Drupal sites. This is based on the Bootstrap 5 framework.

Development

This base theme is easiest to develop using a theme generated using the drupal-site-template or using the site template itself. This will use the psul-web site as an example.

New DDEV Environment

gh repo clone psu-libraries/psul-web;
cd psul-web;
ddev start;
ddev composer install;
ddev drush si --existing-config;
ddev develop-theme;
ddev theme-build;
ddev launch;

Existing DDEV Environment

ddev develop-theme;
ddev theme-build;
ddev launch;

Global SCSS

SCSS used to generate styles that will be used everywhere are defined in the ./scss directory. Styles cannot or should be associated with a single components will live here. These can be organized in to separate files in the ./scss/base directory.

To compile the theme you will need install the node dependencies npm install.

• npx mix watch to compile the scss/js and watch for addition changes (standalone)
• ddev theme-watch psulib_base to compile the scss/js and watch for additional changes. This can only be used within a PSU Libraries Drupal site.

Storybook

This theme also includes the ability to stand up an instance of Storybook. This is using the Storybook SDC Addon to pull the stories directly from the single directory components. Run npm run storybook to stand up a development version of storybook. This will also npm mix watch concurrently to update any scss or js changes live.

Known issues with twig.js

The implementation of twig.js does not 100% match PHP Twig. There are few issues with the twig.js that need to be worked around.

• |merge will only work if you merge a array literal into a array variable. You also need to ensure that utility class array exists before merging.
• trans is not defined.
• macros need to be defined before they are used.
• attribute.removeClass() remove the attribute entirely and cannot be used.

Links

• https://storybook.js.org/
• https://storybook.js.org/addons/storybook-addon-sdc
• https://github.com/iberdinsky-skilld/sdc-addon

Single Directory Components (SDC)

The theme has a number of Single Directory Components (SDC) defined in the ./components directory. We should use SDC where appropriate. This allows for easier development and code reusability.

Creating a template

To add a new components you will need to do the following. This will create a SDC component for you to start with.

ddev drush generate sdc

Applying the template

If your component is only using props then you can use an include:

{% include 'psulib_base:COMPONENT' with {
  prop_name: variable,
} %}

If your component is using slots then you will need to use an embed:

{% embed 'psulib_base:header' with {
    prop_name: variable,
  }
%}
  {% block slot %}
    {{ page.region }}
  {% endblock %}

{% endembed %}

Replace a SDC in a Sub Theme

If you want to completely override a SDC in a subtheme you can do with the following steps:

1. Copy the component from the base theme to the subtheme
2. Add replaces: psulib_base:COMPONENTNAME to the COMPONENTNAME.component.yml file
3. Update templates, css, twig, e&c.

Note you should NOT change the props or slots because that will cause issues.

Replace SCSS for a SDC

If you only need to change the styles for a SDC you can remove the SDC css file and build the desired styles in your subtheme SCSS. There is an open ticket to implement a better way of handling this so we should probably avoid doing this for the time being.

1. Update your subtheme.info.yml file to override the component stylesheet.

libraries-override:
  core/components.psulib_base--COMPONENTNAME:
    css:
      component:
        ../../../themes/custom/psulib_base/components/COMPONENTNAME/COMPONENTNAME.css: {}

1. Add styles to your subtheme style sheet.

Links

• SDC Documentation
• Using/Attaching only css/js
• Radix Theme - This theme has large number of components that can be used as inspiration.

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.

Installing

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):

ddev composer config repositories.psul/theme-base github "https://github.com/psu-libraries/psulib_base.git"

Then, require the actual base theme:

ddev composer require psu-libraries/psulib_base

and install it with Drush

ddev drush theme:enable psulib_base

Standalone

If you are using this as a standalone theme then you will need to run the following command after the theme has been installed.

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

ddev generate-subtheme SUBTHEMENAME;

Update the styles.scss with the following.

// Include bootstrap.
@import '../../../../themes/contrib/psulib_base/scss/init';

// Sub theme styling.

Update webpack.mix.js file to add alias for bootstrap and exclude base theme specific components. This should look like the following.

// webpack.mix.js

let mix = require('laravel-mix');
const path = require('path');

mix.alias({
  'bootstrap': path.join(__dirname, 'node_modules/bootstrap')
});

// 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.

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.)

// 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:

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.

// 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');

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.

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:

<i class="bi-alarm" style="font-size: 2rem; color: cornflowerblue;"></i>

Material Icons

Material Icons can be used. These are saved as SVGs in the theme.

Usage

• TBD.

Adding Icons

• Go to https://fonts.google.com/icons?icon.style=Rounded&selected=Material+Symbols+Rounded:group:FILL@0;wght@400;GRAD@0;opsz@24&icon.size=24&icon.color=%23005FA9&icon.query=group&icon.set=Material+Symbols
• Find and download the desired icon svg
• Rename the svg to something simple (the file name is used to find the icon)
• Add the file to assets/icons
• Update components/icon/icon.component.yml to update
• Update stories/icon-usage.stories.js with details about how the icon shoudl be used withing the libraries site

Peripheral

The theme can be used to generate assets that can be used on peripheral applications. This requires that the application in question supports bootstrap.

• Run ddev theme-build
• Copy the dist/peripheral directory into the src/psulib_base/dist directory in the psu-libraries/assets project.
• Copy the dist/bootstrap-icons directory into the src/psulib_base directory in the psu-libraries/assets project.
• Copy the assets directory into the src/psulib_base directory in the psu-libraries/assets project.

Resources

For more information about creating a subtheme:

• Drupal.org - Subtheming
• Drupalize.me - Use a Base Theme
• Bootstrap 5 Documentation