When you initially run fin init to get up and running with this project, that
command will spawn a sub-command to install NPMs. However, if you ever need to
make updates and re-run the front-end build install, you can run
fin init-theme.
Thereafter you can run fin gulp to watch for changes for Sass and JS which
in turn will compile the CSS. Sass and JS sources are in the ./src folder
and compiled assets land in the ./dist folder. You'll always want to use
Fin's version of gulp rather than a local version and fin init-theme takes
care of that and sets the correct version.
Note, you can run all these commands from the root of the project as the
commands CD into the custom theme folder,
/ucsf8/docroot/sites/dermatology.ucsf.edu/themes/custom/toland.
This theme uses core's Stable as a base theme.
For this project, we are taking a granular approach via individual CSS files being output and then compartmentalized into various libraries loaded from specific templates. This aligns with Drupal core but gives us the ability to boost performance as well.
This project uses Sass linting to help us write better code. When you run
fin gulp, you will see a list of errors and warnings print out in terminal
if there are any issues. An error will stop gulp so you can fix it and a
warning will still continue to compile. If you need to adjust the linting
settings, you can look in sass-lint.yml.
This project converts any ES6 / 2015 code to ES5 in the dist folder so that
Internet Explorer 11 can understand it. Your modern JS stays intact in the
src folder.
There are a whole host of mixins that can be utilized located in the abstract
folder, ./scss/abstract/.... Be sure to review these file for existing mixins
that will come in handy for theming.
Use Sass extends sparingly only to extend page headings (h1-h6 tags).
Ideally, just for headings when you need to change a heading's font size
but it might not be ideal to change the heading tag itself because of
accessibility.
For example, you have an h2 that follows and h1 tag but the h2 needs to be
sized like an h3. Note, when extending a heading, use its class,
@extend .h3; rather than @extend h3;
.page-title__lede h2 {
@extend .h3;
}For font sizes use the rem mixin. e.g. @include rem(font-size, 48px); which
compiles as font-size: 3rem;. For anything else, use pixels.
There are a number of utility classes.
There are three mixins to utilize SVG icons that take arguments, some of them optional.
@mixin icon-before()@mixin icon-after()@mixin icon()These take various arguments, the null ones being optional:
$icon,
$width,
$height,
$rotate: null,
$position: null,
$top: null,
$right: null,
$bottom: null,
$left: null,
$opacity: null,
$background-position: null,
$translate_y: null@include icon-before(icon-letters, 35px, 35px, $position: absolute);./icon/raw run fin gulp svg to regenerate HTML.fin gulp - (default) watches for JS and Sass changes, compiles the CSS.
Live injects new css if you have BrowserSync enabled. See "BrowserSync
and live CSS injection" below for more information.fin gulp build - Compiles all the thingsfin gulp svg - Builds icon preview page and copies icons to the dist
folder. You can preview the icons at http://local.dermatology.ucsf.edu/sites/dermatology.ucsf.edu/themes/custom/toland/dist/icon/icons.htmlfin gulp combine - combines any css in /dist/css/global for use in
ckeditor.We are using Sass MQ for media queries as it's very versatile. They have great documentation here: https://github.com/sass-mq/sass-mq
@include mq($from: large) {@include mq($from: large, $until: wide) {@include mq($until: large) {Note, write media queries in small chunks within individual selectors rather than encompassing many selectors with one giant media query. For example:
.header-no-lede {
@include mq($from: large) {
// CSS here.
}
}
.header-has-link {
@include mq($from: large) {
// CSS here.
}The gulpfile is set to reload pages upon save using BrowserSync and refresh
CSS while theming using fin gulp. As you make changes to Sass, your CSS
will get injected without a page reload for a more seamless and rapid theming
process. To make this work, you will need to add
$config['toland.settings']['browsersync'] = 1; to your local
settings file.
Drupal.behaviors.tolandMenu = {
attach: function (context, settings) {...fin gulp will compile the source JS located
in /ucsf8/docroot/sites/dermatology.ucsf.edu/themes/custom/toland/src/js
into the dist folderYou can target ie11 in Sass by using the IE11 mixin, e.g. @include ie11 {...
fin drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));"Once you discover your plugin id, you can render it right in the template like this:
{{ drupal_block('simple_gse_search_block') }}Twig field value - Allows you to get partial data from field render arrays. It gives you more control over the output without drilling deep into the render array or using preprocess functions.
Link attributes - This lets you add custom attributes to menu items in the Drupal menu UI, the best use case being custom classes.
Twig template debugging - This comes in handy to use Xdebug within Twig
templates. Add {{ drupal_breakpoint() }} to your template and start
debugging. You'll need the devel module enabled and Xdebug turned on in
Docksal, see more info below under Coding tips.
It would be ideal to use BEM style CSS syntax in combination with Twig Field Value. For example:
<div class = "column">
{% if content.field_iconcard_title | render %}
<div class="column__card-title">
{{ content.field_iconcard_title | field_value }}
</div>
{% endif %}
</div>It would be ideal to setup PHPCS / Drupal coder for this project.
Generously comment your code.
Use a docksal-local.env file to enable Xdebug. > XDEBUG_ENABLED=1 You can find a docksal-local.example.env as an example in the /.docksal folder.
You can generate a new TOC for this readme file here if needed: https://ecotrust-canada.github.io/markdown-toc/ Note, remove h1 tag in the TOC UI first before you generate.