Toolbox flexible grid (tfg)

Table of Contents

• About
• Getting Started
• Install local dev environment for tfg
• Dependencies
• Toolbox grid Settings
• [Toolbox Grid settings per breakpoint](#breakpoint toolbox-grid-settings-per-breakpoint)
• Usage
• todo
• Acknowledgments

About

A customizable grid system, that aims to set every parameter for your grid system individually by breakpoint. Being as flexible as possible while being as lightweight as possible. The Toolbox grid is based on the CSS flexbox model.

Getting Started

You can install tfg via npm:

npm i @familieredlich/fr-toolbox-flexible-grid --save-dev

Now you import the scss file into your workflow.

the pure grid, no css reset, no testpage styles.

@import '~@familieredlich/fr-toolbox-flexible-grid/src/styles/main';

some extra styling for the testpage, also for the Grid overlay.

@import '~@familieredlich/fr-toolbox-flexible-grid/src/styles/dev';

To show a grid overlay in your dev enviroment, you need to import the js.

import '@familieredlich/fr-toolbox-flexible-grid';

now you can hit 'g' to show an overlay to make shure everything is aligned.

Since the whole package is also a local enviroment (see next chapter), and work with the css/js files in the dist folder.

Install local dev environment for tfg

• Install dependencies

yarn

• Run development server

yarn dev

Will open your default browser to http://localhost:8080/public

Webpack will watch for changes in the ./src directory and output the bundled assets to ./public/assets. In parellel, the development server will watch for changes in the ./public directory and live reload the browser.

• Build production bundles

yarn build

Will compile, minify and auto-prefix Sass to CSS. Will Minify and uglify JavaScript and output the bundled assets to ./public/assets.

After building for production you can take the ./public directory and deploy it.

Dependencies

tgf is meant as an addition to fr-toolbox, but doesn't rely on it. So there are no dependencies.

How to use toolbox flexible Grid in conjunction with fr-toolbox

if you already use fr-toolbox, you should make shure to load tgf afterwards, and comment out the following sass-map and variable in your custom _settings.grid.scss

$toolbox-breakpoints: (
    'xs': 500px,
    'sm': 700px,
    'md': 900px,
    'lg': 1100px,
    'xl': 1300px,
    'xxl': 1700px
);

Toolbox grid Settings

Variable                                                            Type            Default                 Description
===============================================================================================================================================================================
$$toolbox-breakpoints                                               scss map        'xs': 500px,            define your breakpoints
                                                                                    'sm': 700px, 
                                                                                    'md': 900px, 
                                                                                    'lg': 1100px,
                                                                                    'xl': 1300px,
                                                                                    'xxl': 1700px
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-enabled                                               boolean         true                    enables or disables the grid css output completely
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-fluid-enabled                                         boolean         true                    enables or disables the fluid grid completely
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-fluid-breakpoint-aware-enabled                        boolean         true                    enables or disables the fluid grid by breakpoint
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-horizontal-enabled                      boolean         true                    enable / disable horizontal alignment
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-horizontal                              scss map        'start': flex-start,    setting, the possible horizontal alignment options.
                                                                                    'center': center,       The Key like 'start, center' is used for the modifier
                                                                                    'end': flex-end,        the value, represents the css justify-content value
                                                                                    'around': space-around, 
                                                                                    'between': space-between                                                        
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-horizontal-breakpoint-aware-enabled     boolean         true                    enable / disable horizontal alignment by breakpoint
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-vertical-enabled                        boolean         true                    enable / disable vertical alignment
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-vertical-enabled                        boolean         true                    enable / disable vertical alignment
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-vertical                                scss map        'top': flex-start       setting, the possible vertical alignment options.              
                                                                                    'middle': center,       The Key like 'top, middle' is used for the modifier 
                                                                                    'bottom': flex-en       the value, represents the css align-items value   
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-row-alignment-vertical-breakpoint-aware-enabled       boolean         true                    enable / disable vertical alignment by breakpoint
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-offset-enabled                                        boolean         true                    enable / disable offset
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-offset-breakpoint-aware-enabled                       boolean         true                    enable / disable offset by breakpoint
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-offset-breakpoint-aware-enabled                       boolean         true                    enable / disable offset by breakpoint
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-cols                                                  number          12                      default number of columns
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-gutter-default                                        number          12                      default grid gutter
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 
$toolbox-grid-default-columns                                       scss map        1, 2, 3, 4, 5, 6,       default number of columns that are selectable via css.
                                                                                    7, 8, 9, 10, 11, 12     e.g. o-grid__col:4
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 
$toolbox-grid-default-offsets                                       scss map        1, 2, 3, 4, 5, 6,       default number of offsets that are selectable via css.
                                                                                    7, 8, 9, 10, 11, 12     e.g. `o-grid__col--offset:4`
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-grid-cols-by-bp-enabled                                    boolean         true                    enable / disable columns by breakpoint e.g. `o-grid__col:4@sm`
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$toolbox-offset-by-bp-enabled                                       boolean         true                    enable / disable offset by breakpoint 
                                                                                                            e.g. `o-grid__col--offset:4@sm`
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                

Toolbox Grid settings per breakpoint

You can also set up various grid options per breakpoint. You just have to alter the $toolbox-config map

The default is:

$toolbox-config: (
    'toolbox-grid-cols-by-bp' : (
        'xs': (
            'grid-width': 100%,
            'cols': (1, 6, 12),
            'offset': (1, 6, 12),
            'total-grid-cols': $toolbox-grid-cols, // required, default value is set in var $toolbox-grid-gutter-default
            'custom-grid-gutter': $toolbox-grid-gutter-default,
            'custom-grid-row-alignment-vertical': $toolbox-grid-row-alignment-vertical,
            'custom-grid-row-alignment-horizontal': $toolbox-grid-row-alignment-horizontal,
        ),
        'sm': (
            'grid-width': 100%,
            'cols': (1, 4, 6, 12),
            'offset': (1, 6, 12),
            'total-grid-cols': $toolbox-grid-cols,
            'custom-grid-gutter': $toolbox-grid-gutter-default,
            'custom-grid-row-alignment-vertical': false,
            'custom-grid-row-alignment-horizontal': $toolbox-grid-row-alignment-horizontal,
        ),
        'md': (
            'grid-width': 100%,
            'cols': (1, 3, 4, 6, 8, 12),
            'offset': (1, 3, 6, 12),
            'total-grid-cols': 12,
            'custom-grid-gutter': $toolbox-grid-gutter-default,
            'custom-grid-row-alignment-vertical': (
                'top': flex-start,
                'bottom': flex-end
            ),
            'custom-grid-row-alignment-horizontal': $toolbox-grid-row-alignment-horizontal,
        ),
        'lg': (
            'grid-width': map-get($toolbox-breakpoints, 'lg')-100px,
            'cols': $toolbox-grid-default-columns,
            'offset': $toolbox-grid-default-offsets,
            'total-grid-cols': $toolbox-grid-cols,
            'custom-grid-gutter': $toolbox-grid-gutter-default,
            'custom-grid-row-alignment-vertical': $toolbox-grid-row-alignment-vertical,
            'custom-grid-row-alignment-horizontal': $toolbox-grid-row-alignment-horizontal,
        ),
        'xl': (
            'grid-width': map-get($toolbox-breakpoints, 'xl')-100px,
            'cols' : $toolbox-grid-default-columns,
            'offset': $toolbox-grid-default-offsets,
            'total-grid-cols': $toolbox-grid-cols,
            'custom-grid-gutter': $toolbox-grid-gutter-default,
            'custom-grid-row-alignment-vertical': $toolbox-grid-row-alignment-vertical,
            'custom-grid-row-alignment-horizontal': $toolbox-grid-row-alignment-horizontal,
        ),
        'xxl': (
            'grid-width': map-get($toolbox-breakpoints, 'xxl')-100px,
            'cols': $toolbox-grid-default-columns,
            'offset': $toolbox-grid-default-offsets,
            'total-grid-cols': $toolbox-grid-cols,
            'custom-grid-gutter': $toolbox-grid-gutter-default,
            'custom-grid-row-alignment-vertical': $toolbox-grid-row-alignment-vertical,
            'custom-grid-row-alignment-horizontal': $toolbox-grid-row-alignment-horizontal,
        )
    ),
    'cols-first-mobile': (1, 6, 12),
    'offsets-first-mobile': (1, 6, 12),
    'total-grid-cols-first-mobile': $toolbox-grid-cols,
    'grid-gutter-first-mobile': $toolbox-grid-gutter-default,
    'alignment-vertical-first-mobile': $toolbox-grid-row-alignment-vertical,
    'alignment-horizontal-first-mobile': $toolbox-grid-row-alignment-horizontal,

)

Option                                      Description                         
===============================================================================================================================================================================
grid-width                                  the max-width of the o-grid class, can be in % or in pixels also some calculations are possible.                                                    
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
cols                                        the column classes for this breakpoint. E.g. o-grid__col:6@md. There should be always be a `1` if you use the grid-overlay-helper.                                               
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
offset                                      the offset modifier classes for this breakpoint. E.g. o-grid__col__offset:6@md.                                    
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
total-grid-cols                             You can have for example an 4 column grid, for mobile devices and a 24 column grid for Desktop devices, if you like.                                                            
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
custom-grid-gutter                          If you like, you can have a different grid gutter on every Breakpoint.                                  
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
custom-grid-row-alignment-vertical          Here you can define the vertical alignment per breakpoint.                                  
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
custom-grid-row-alignment-horizontal        Here you can define the vertical alignment per breakpoint.                                  
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
OPTIONS FOR THE INITIAL FIRST VIEW
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
cols-first-mobile                           the column classes for the inital view (mobile first) E.g. o-grid__col:6. 
                                            There should always be a `1` if you use the grid-overlay-helper.                              
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
offsets-first-mobile                        the offset modifier classes for the initial view (mobile first). E.g. o-grid__col__offset:6.                                  
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
total-grid-cols-first-mobile                the offset modifier classes for the initial view (mobile first). E.g. o-grid__col__offset:6.                                  
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
grid-gutter-first-mobile                    the grid gutter for the initial view (mobile first). E.g. o-grid__col__offset:6.                                  
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
alignment-vertical-first-mobile             the vertical alignment grid row modifier for the initial view (mobile first). E.g. o-grid__row--top                         
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
alignment-horizontal-first-mobile           the vertical alignment grid row modifier for the initial view (mobile first). E.g. o-grid__row--between                     
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Grid Class

.o-grid

This is the main grid class which creates the basic grid wrapper.

Usage

Simply create a <div> element with the .o-grid class. By default the grid wrapper has a fixed width, which is defined in the configuration variable $toolbox-grid-fixed-widths.

<div class="o-grid">
    <!-- Grid Row's goes here... -->
</div>

Options/Modifiers

.o-grid--fluid

To disable the default fixed width

Usage

Simply add the .o-grid--fluid modifier class. This unsets the max-width property of the o-grid class. (The Grid spans over the full width).

<div class="o-grid o-grid--fluid">
    <!-- Grid Row's goes here... -->
</div>

If $toolbox-grid-fluid-breakpoint-aware-enabled is set to true, you can add the modifier class per break point, example:

<div class="o-grid o-grid--fluid@sm">
    <!-- Grid Row's goes here... -->
</div>

.o-grid__row

This class defines each row in the grid system and has to be the wrapper for all .o-grid__col classes.

Usage

Create a <div> element with the .o-grid__row class inside the .o-grid container. It is also possible to nest the grid by putting this class inside a .o-grid__col element. Keep in mind, if you nest a grid each grid column is now calculated on the base of the parent grid-column. That means, for example, a o-grid__col:6 container is just the half width, of the parent column container e.g. an o-grid__col:6 container.

<div class="o-grid">
    <div class="o-grid__row">
        <!-- Grid Col's goes here... -->
    </div>
</div>

Options/Modifiers

There are two modifier groups for the rows. Horizontal and vertical positioning. Each modifier overwrites the other modifiers in its group, so only one horizontal and one vertical modifier class can be used together on the same breakpoint.

Horizontal alignment

$toolbox-grid-row-alignment-horizontal-enabled has to be set to true.

.o-grid__row--start

Default value. Cols are positioned at the beginning of the row (justify-content: flex-start;).

<div class="o-grid__row o-grid__row--start">
    <!-- Grid Col's goes here... -->
</div>

.o-grid__row--center

Cols are positioned at the center of the row (justify-content: center;).

<div class="o-grid__row o-grid__row--center">
    <!-- Grid Col's goes here... -->
</div>

.o-grid__row--end

Cols are positioned at the end of the row (justify-content: flex-end;).

<div class="o-grid__row o-grid__row--end">
    <!-- Grid Col's goes here... -->
</div>

.o-grid__row--around

Cols are positioned with space before, between, and after (justify-content: space-around;).

<div class="o-grid__row o-grid__row--around">
    <!-- Grid Col's goes here... -->
</div>

.o-grid__row--between

Cols are positioned with space between (justify-content: space-between;).

<div class="o-grid__row o-grid__row--between">
    <!-- Grid Col's goes here... -->
</div>

Vertical alignment

$toolbox-grid-row-alignment-vertical-enabled has to be set to true.

.o-grid__row--top

Cols are positioned at the vertical beginning of the row (align-items: flex-start;).

<div class="o-grid__row o-grid__row--top">
    <!-- Grid Col's goes here... -->
</div>

.o-grid__row--middle

Cols are positioned at the vertical center of the row (align-items: center;).

<div class="o-grid__row o-grid__row--middle">
    <!-- Grid Col's goes here... -->
</div>

.o-grid__row--bottom

Cols are positioned at the vertical end of the row (align-items: flex-end;).

<div class="o-grid__row o-grid__row--bottom">
    <!-- Grid Col's goes here... -->
</div>

Vertical alignment per breakpoint

$toolbox-grid-row-alignment-vertical-breakpoint-aware-enabled has to be set to true.

.o-grid__row--*@<breakpoint>

Applies the modifier only after the specified breakpoint, overrides previous styles on each breakpoint. $toolbox-grid-row-alignment-horizontal-breakpoint-aware-enabled has to be set to true.

<div class="o-grid__row o-grid__row--start o-grid__row--center@xl">
    <!-- Grid Col's goes here... -->
</div>

Cols are aligned left and aligned center after the xl breakpoint.

.o-grid__col

This is the main grid col, where the content can be placed.

Usage

Place one or more <div> element(s) with the .o-grid__col in the .o-grid__row wrapper.

<div class="o-grid">
    <div class="o-grid__row">
        <div class="o-grid__col">
            <!-- Content Element goes here... -->
        </div>
    </div>
</div>

Options/Modifiers

.o-grid__col--first

Col is positioned as first element in the row. It can be used with the @<breakpoint> notation.

<div class="o-grid">
    <div class="o-grid__row">
        <div class="o-grid__col o-grid__col--first@m">
            <!-- Content Element goes here... -->
        </div>
    </div>
</div>

.o-grid__col--last

Col is positioned as last element in the row. It can be used with the @<breakpoint> notation.

<div class="o-grid">
    <div class="o-grid__row">
        <div class="o-grid__col o-grid__col--last@m">
            <!-- Content Element goes here... -->
        </div>
    </div>
</div>

.o-grid__col--offset:<size>

Offset from the left side of the col (value from 1 to the defined number of cols in $fw-grid-cols).

<div class="o-grid">
    <div class="o-grid__row">
        <div class="o-grid__col o-grid__col--offset:4">
            <!-- Content Element goes here... -->
        </div>
    </div>
</div>

.o-grid__col:<size>

Size of the col (value from 1 to the defined number of cols in $fw-grid-cols).

<div class="o-grid">
    <div class="o-grid__row">
        <div class="o-grid__col o-grid__col:6">
            <!-- Content Element goes here... -->
        </div>
    </div>
</div>

.o-grid__col*@<breakpoint>

Applies the modifier only after the specified breakpoint, overrides previous styles on each breakpoint.

<div class="o-grid">
    <div class="o-grid__row">
        <div class="o-grid__col o-grid__col:6 o-grid__col:4@l">
            <!-- Content Element goes here... -->
        </div>
    </div>
</div>

Col is 6 cols wide and 4 cols wide after the l breakpoint.

Todo

there are still things to do, like:

• adding source map to the local dev env
• adding a linter to the local dev env

Acknowledgments

The Grid System is based on the cps-it scss-framework by Niels Waldowski https://github.com/CPS-IT/scss-framework TGF is meant as an addition to the fr-toolbox by Kurt Gierke https://www.npmjs.com/package/@familieredlich/fr-toolbox The local environment is based on Esau Silvas live-reload-vanilla-website-template https://github.com/esausilva/live-reload-vanilla-website-template.git