Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/psu-libraries/psulib_base

Drupal Base Theme
https://github.com/psu-libraries/psulib_base

drupal theme

Last synced: about 2 months ago
JSON representation

Drupal Base Theme

Awesome Lists containing this project

README 

          
# 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](https://getbootstrap.com/docs/5.3/getting-started/introduction/) framework.



## Development



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 composer install;

ddev drush si --existing-config;

ddev develop-theme;

ddev theme-build;

ddev launch;

```



### Existing DDEV Environment



```bash

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](https://storybook.js.org/addons/storybook-addon-sdc) 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)](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components) 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.



```bash

ddev drush generate sdc

```



#### Applying the template



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



```twig

{% include 'psulib_base:COMPONENT' with {

  prop_name: variable,

} %}

```



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



```twig

{% 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

1. Add `replaces: psulib_base:COMPONENTNAME` to the `COMPONENTNAME.component.yml` file

1. 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](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components)

- [Using/Attaching only css/js](https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/faq-frequently-asked-questions#s-can-i-use-attach-only-the-assets-library-cssjs-of-a-component-inside-a-twig-template)

- [Radix Theme](https://git.drupalcode.org/project/radix/-/tree/6.0.x/components?ref_type=heads) - 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):



```bash

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

```



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

```



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



```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 add alias for bootstrap and exclude base theme specific components. This should look like the following.



```js

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



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

```



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



```html



```



## 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](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/)