3W CMS Documentation

Frontend development

This document describes the basic information to work on frontend development with CMS 5.0

Setup

Open project in Visual Studio Code. Open framework directory of the same project in Visual Studio Code.

`<project_name>`/vendor/w3media/framework

Step-by-step guide

  1. Check variables: vendor-variables > website-variables
  2. Override component styling

1 - Check variables

In the project we have 2 variables .scss files of which one is located on project level and one on framework level. The variables on the framework level shouldn’t be modified and only contain default values. On project level you can customize/override these values (or add new variables).

When you start a new project you should start with checking the vendor-variables first, then the website-variables.

vendor-variables

The variables defined in vendor-variables are overrides of third-party libraries like bootstrap. If you don’t override these variables, the defaults variable values of bootstrap are used.

You can view the default variables and their values in the following file (don’t modify this file):

`<project_name>`/node_modules/bootstrap/scss/_variables.scss

The vendor-variables on project level can be found in:

`<project_name>`/assets/_themes/default/0_config/_vendor-variables.scss

This file will be empty for a new project. So it is adviced to copy the contents of the vendor-variables of the framework to the vendor-variables on project level, because there are a number of variables that are used and overridden a lot for our websites. When a change on framework level happens, the project won’t be influenced by it.

All variables that are not used can be removed. Variables that don’t exist but are specific to third-party libraries like Bootstrap can be added here. For example $font-weight-medium

The vendor-variables of the framework are located here:

`<project_name>`/vendor/w3media/framework/assets/scss/Dev/0_config/_vendor-variables.scss

website-variables

The website-variables contain our own custom variables, not specific to any third-party library. For example: custom classes, blocks, elements, … These variables are set to fixed values, variables of vendor-variables or previously defined website-variables.

The website-variables of the project are located here:

`<project_name>`/assets/_themes/default/0_config/_website-variables.scss

This file will also be empty for a new project. So it is advised to check all framework website-variables, those that you want to override should be copied to the project level website-variables.

The website-variables of the framework are located here:

`<project_name>`/vendor/w3media/framework/assets/scss/Dev/0_config/_website-variables.scss

2 - Custom component / element styling

Apart from the variables there are other .scss files with the actual website styling. These files are seperated into 7 area’s:

  • 0_config
  • 1_vendor
  • 2_layout
  • 3_components
  • 4_page_block
  • 5_utilities
  • 6_theme
  • 7_hacks

The directories with all default .scss files are located in the framework here:

`<project_name>`/vendor/w3media/framework/assets/scss/Dev

In a new project there will only be a 0_config directory, located here:

`<project_name>`/assets/_themes/default

If you want to customize the styling on project level for a specific part, follow these steps:

  1. Copy the .scss file from where you want to make changes, for example header.scss.
  2. Paste this file on project level in the same subdirectory as it was on vendor (in this case 2_layout). If the directory doesn’t exist yet, create it.
  3. The file needs to be included now, therefore open theme.scss on project level and add an include within body.default {} (no need to append file extension .scss in the import statement)
@import './<directory>/<file>';

In this example:

@import './2_layout/header';

Now you can empty the contents of this file, since this is already loaded on framework level. In this empty file you can add custom styling. you can also use variables defined in vendor-variables or website-variables in this stylesheet.

SCSS directory structure

The bold directories are the most important / most used, the other ones shouldn’t be used in most cases.

Directory Explanation
0_config Variable files _vendor-variables.scss and _website-variables.scss are located here
1_vendor Third party libraries like bootstrap are located here. No changes should be made here, but new files can be added.
2_layout Large and unique section styling like header and footer are located here. In the content.scss the content section styling is located, but also all kinds of headlines/texts that are located within.
3_components Specific component styling like parts of modules like lists, forms, cards. Cards is an important one, these are used a lot to simplify generic styling.
4_page_block Large or small block styling that can occur within sections.
5_utilities Small styling modifications like buttons, hovers, animations, …
6_theme Specific page or module overrides like a home template or accommodation overview.
7_hacks Fixes or bugs, not important