NCIDS Transitional Theme Front‐End Layout - NCIOCPL/cgov-digital-platform GitHub Wiki

This is the front-end stuff to build the new front-end. Where possible we reference as much from cgov_site/themes/custom/cgov as possible.

**NOTE: If adding packages DO NOT add to the dependencies list unless it is reference in the front-end code. Anything related to tooling should be placed in devDependencies **

**NOTE: We are moving to Typescript. Anything new MUST be a .ts file. **

1. Go into your container
2. Change into docroot/profiles/custom/cgov_site/themes/custom/ncids_trans/front-end
3. Run npm pack <package> --pack-destination=./local_packages where <package> is a valid package name and optional version. Run it like you would npm install <package>.
   • Example: npm pack @nciocpl/[email protected] --pack-destination=./local_packages
4. Find the file name of the downloaded tarball. For example @nciocpl/[email protected] becomes [email protected], so we can't give you a specific renaming rule.
5. Run npm install ./local_packages/<tarball> or npm install --save-dev ./local_packages/<tarball>
6. Remove the old tarball.

We have a large amount of unspecific css selectors in our SASS files, e.g., form button, that bleed into the NCIDS. Additionally, and more problematic, is that we use foundation's types partial, and based on testing cannot easily remove it for this release. The types partial defines things like H1, H2, UL, etc. So we must prefix all the legacy CSS with a selector (e.g., .cgdpl) and add a container that wraps the node's contents. (The node's contents meaning the H1 tag down to the footer, excluding the side nav) The reason this is being pointed out is that there are special things that need to be done!

(This work will already have been done for the new ncids-common entrypoint)

1. Ensure the page-<whatever>.html.twig file has the legacy wrapper. By the time you read this, the default page template will already have it.
2. Create a <entrypoint>-legacy.scss file next to the existing <entrypoint>.scss
3. In your <entrypoint>.ts file add a import './<entrypoint>-legacy.scss'; statement on the line after import "./<entrypoint>.scss";
4. Move whatever you need to from the <entrypoint>.scss to <entrypoint>-legacy.scss.

1. We first named the legacy wrapper class .cgdp-legacy. When we changed it to .cgdpl we saved about 15K, which demonstates the large number of selectors we have. That is about 2.5K per character, so we may end up changing this in the future just to save more.
2. Because of number 1, there are some partials that have class definitions with a high level of specificity, e.g., jqueryui. For those items we did not wrap them with the legacy selector. (This also saved about 3K) We also moved some of the base Foundation outside of the selector, which saved about 5k.
   • The moral of this bullet point is that you should think about the contents to determine if it needs to be wrapped in the legacy wrapper or not.
3. Because of how some of our rules are implemented, prefixing the legacy is not as simple as .cgdpl { @import 'somepartial' }. The parent selector (&) includes the wrapper and if you have something like div.foo { .bar &.someclass } then things break because & no longer means div.foo, but .cgdpl div.foo. So we have to use postcss to handle the prefixing, which in hindsight it probably more efficient, and thus file naming really matters.

Firstly, don't. If you do, you must update the files listed below. NOTE: the configurations differ accross the file, so DO NOT COPY/PASTE!!!!

• tsconfig.json
• jest.config.js
• webpack.alias.js

To use an NCIDS component in the platform, do the following: TBD

• clean:dist - this cleans up the dist folder (../dist) that webpack publishes to. This is where the theme's libraries file points to.
• clean:legacy-sprite - cleans up any of the files generated by the sprite builder
• clean:all - cleans everything up
• prebuild:dev - Runs before build:dev, which cleans out dist.
• build:dev - builds sprites and runs a dev webpack build
• prebuild:prod - Runs before build:prod, which cleans out dist.
• build:prod - builds sprites and runs a prod webpack build
• prewatch - Runs before watch, which cleans out dist.
• watch - builds sprites and does a webpack watch build. NOTE: this does not watch the sprites.
• prebuild:legacy-sprite - runs before build:legacy-sprite, which cleans out the sprites
• build:legacy-sprite - builds the legacy sprites image/map

• src
  • entrypoints - this is a copy of the entrypoints config from the legacy theme (cgov_common) If someone changes something in common they probably have to change it here.
    • global - this is where the common css & js live that go on every page.
    • <entrypoint> - There is a folder for each entrypoint that contains a <entrypoint>.scss, <entrypoint>-legacy.scss and <entrypoint>.ts
  • legacy - when we cannot just use a partial or class from the cgov folder, but need to keep the legacy styling with modifications, they are copied and modified here. This should mimick the source folder structure.
    • styles - these are overrides from cgov/src/styles
    • transition-hacks - these are, well, hacks that are not copies, but should die when then migration is done. For example we cannot generate the foundation _types.scss classes since they are for things like <p> tags. So we generate those we can in ncids-common.scss and then in ncids-common-legacy.scss we generate the types classes, which is prefixed with .cgdpl.
  • styles - this is junk to support the legacy sprites. If this can be moved to legacy without breaking we will.
  • lib - This is the code and styles for new stuff. ncids-js and ncids-css should carry over most of the styles, but this is for cgdp overrides, implementation specific js (e.g. analytics) and other stuff.
    • core - this is for general utility type functions/libraries. I don't think any styles would go in here.
    • components - There should be a component folder for each NCIDS component we are using. This will include any analytics JavaScript or other things needed. See Consuming a NCIDS Component NOTE: Custom CGDP components which would not be globally usable for NCIDS should also be placed in this folder. These should be pretty rare, but could happen.
      • wysiwyg - Contains all styles and analytics related to the WYSIWYG editors. Is separated by a common embedded entities folder and the text editor stylesheets themselves.
        • common - Holds common/shared styles and analytics for WYSIWYG embed buttons.

• WYSIWYG
  • For embedded media and nodes used within the WYSIWYG editor, we aim to import only the minimal css necessary for that specific embed. To ensure clarity, styles related to these embeds should be placed in folders with the following naming convention: cgdp-embed-<media-type or node-type>
    • Current examples - cgdp-embed-image, cgdp-embed-video, cgdp-embed-infographic
• Node field
  • In the cases that a node's field requires additional styles not already found within the node's entrypoint or ncids-minal (for non-legacy pages), those styles should be placed in a folder with the following naming convention: cgdp-<field-name
    • Current examples - cgdp-field-image-article
• Entity Embed Container
  • The twig suggestions to override the default twig template for embedded entities is entity-embed-container--media.<view_mode>.html.twig. This twig suggestion doesn't follow our standard naming convention for twig templates so we've added a hook_theme_suggestions_HOOK_alter() to add in the suggested name of our choice. As we can have embedded images, infographic, videos, and feature cards, we can create templates with the following naming convention: entity-embed-container--media--<media_bundle>.html.twig
    • Current examples - entity-embed-container--media--cgov-image.html.twig

• babel.config.json - this is the config for babel builds. It currently uses @babel/preset-env, which will use the browserslist in package.json.
• legacy-sprites.config.json - this is the config for svg-sprite and is used to generate the legacy sprite from the legacy sass
• package.json - you know the deal. This does have the browserslist config in it.
• jest.config.js - this is the configuration for jest.
• postcss.config.js - this is the config for postcss. Mostly now it is autoprefixing and adding .cgdpl to legacy classes.
• tsconfig.json - This is the typescript config. Anything new in this theme should be done in typescript, but we will support .js for all the legacy junk.
• webpack.alias.js - this is for our aliases. Most of this is for referencing the legacy code.
• webpack.config.js - the normal webpack config.
• webpack.entries.js - this is the config for the entry points for this theme's front-end code.

• Webpack 5.66 - Build tool
  • Babel Loader 8.2 - This supports Typescript now, so it is the loader for TS
  • Sass Loader 12.4
  • CSS Loader 6.5
  • Postcss Loader 6.2 + Autoprefixer 10.4
  • Webpack bundle analyzer 4.5
  • Mini CSS Extract Plugin 2.5 - This extracts .css files from the webpack .js modules.
  • CSS Minimizer Webpack Plugin - 3.4
• Typescript 4.5
• Node Sass 7.0 - Sass transpiler
• Jest 27 - Test framework
• Rimraf - tool for cleaning up dirs
• Svg Sprite - legacy sprite building tool