Basic agreements

  • Frontend dependencies are managed via NPM.
  • This means, that all dependencies are declared inside the package.json inside of this extension. Libraries like jQuery have to be pulled in via NPM. Third party code must not be managed manually.
  • The Frontend Build Process is handled by the SGC
  • The build process produces exactly one CSS and one JS file that gets included by the TypoScript configuration. It is possible to produce additional CSS files for areas of the website that differ heavily from the rest. This could be a separate area that is only visible for certain users, or simply legacy pages that have to silently remain.
  • The build process produces a .min version with compressed content which shall be included in production and one regular file that is used during development. The scriptmerger extension is only used for concatenating files (e.g. inline JS that is produced by extensions like df_tabs, JS files that are produced by extensions but can not be included via CommonJS).
  • All Styles are written in SCSS, following our Styleguide. Note that Sass is also used to import external stylesheets.
  • All JavaScript is written in CommonJS modules, following our Styleguide.

Critical Path CSS

The build process will also create an additional CSS file which will be inlined into the rendered HTML. The purpose of those inline styles is, to already provide styles for the content that is initially visible when visiting the website, before all assets are completely loaded. This area is also known as "above the fold", a term that has its origin in paper press. It originally meant the content that remains visible when the newspaper is folded.

It is up to the developer to decide which styles have to be included in this file. It is however not a replacement for the styles inside the main.css file. This is a known and wanted redundancy! Also note, that this file is not meant to contain actual CSS directives, rather than imports of other .scss files. The redundancy should be in the compiled CSS, not the actual code.

Components

A component is a reusable part of the website, such as buttons, modal windows, or other logical blocks of content and functionality. A component can be just a single .scss file that contains styles which define a certain look, as well as a whole NPM module that also offers JavaScript and other website parts.

The JavaScript of a component should offer an interface (in this case a CommonJS module) that exports an API which can be required and used in the main.js bundle.

The CSS part of a component should offer Sass files that can be imported in the websites Sass code. If possible, those files only contain mixins that can be used by sets. Mixins, as well as classes that are offered by the component, are prefixed with the component name.

Sets

A set is a collection of components that fit visually together. Every set offers prefixed classes that can be applied to the websites markup.

E.g. a button component can offer a button-standard mixin that can be used by a set named 'default', to create a class like 'default-button-standard'. Additionally, there could be a second set that creates an additional version of the same button, that looks completely different, while it still serves the same purpose. This can be very useful if the website is composed of sections that follow different styles.

Examples: pages that use legacy designs (step by step update of a project), or logically different sections, like a login-area.