Cutomization

Learn how to create your own style without changing the theme’s core files so you can take advantage of future updates.

Prerequisites

Make sure you have the followed the steps from the Build tools page. You should have already installed the following:

  • Node.js
  • Gulp or Laravel Mix

SASS

Sass is the most mature, stable, and powerful professional grade CSS extension language in the world. To learn more click here to see the official documentation.

File structure

The Sass structure is built from two main folders:

  • purpose, which contains the extended components based on Bootstrap and also the custom built ones
  • skins, which contains folders with different custom variables that allow you to change the theme’s appearance with ease.
  • custom, which contains a basic structure made from a style, a font and a variable files in order to get you started with the customization process nice and easy

Heads up! Bootstrap is automatically loaded from the node_modules folder in the purpose.scss file. It is installed via npm install and compiled using the build tools.

Remember, you are not limited to use the structure we have included in the resources/scss/user folder. If you have a more complex project you can choose to follow the directory structure we have made for Purpose. This will help you create modular components easily extendable and re-usable.

Below is the main structure you will be able to see inside the main SCSS folder:

purpose-application-ui-kit/
├── resources/
└── ├── scss/
    │   ├── purpose/
    │   ├── ├── animations/
    │   ├── ├── components/
    │   ├── ├── mixins/
    │   ├── ├── utilities/
    │   ├── ├── libs/
    │   │   ├── _animations.scss
    │   │   ├── _components.scss
    │   │   ├── _functions.scss
    │   │   ├── _mixins.scss
    │   │   ├── _reboot.scss
    │   │   ├── _utilities.scss
    │   │   ├── _libs.scss
    │   │   └── _variables.scss
    ├── ├── skins/
    │   │   ├── default/
    │   │   ├── blue/
    │   │   ├── red/
    │   │   ├── vibrant/
    └── └── user/
    │   │   ├── _styles.scss
    │   │   └── _variables.scss
    └── └── purpose.scss

Important! We highly recommend to not make changes to the purpose folder. It includes core files and components that can be updated in the future. If you want to take advantage of future updates you may want to have a more Bootstrap-ish approach, meaning you should create new styles or components to override styles, extend or add new components in the custom folder.

Variable defaults

Every Sass variable in Bootstrap 4 and Purpose includes the !default flag allowing you to override the variable’s default value in your own Sass without modifying Purpose’s source code. Copy and paste variables as needed, modify their values, and remove the !default flag. If a variable has already been assigned, then it won’t be re-assigned by the default values in Bootstrap.

You will find the complete list of Purpose’s variables in resources/scss/purpose/_variables.scss.

Changing variables

In order to make Sass features modular and re-usable each component has its own styles and its own set of variables. Variables should follow the $component-state-property-size formula for consistent naming.

Ex: $nav-link-disabled-color and $modal-content-box-shadow-xs.

Let’s say you need to change the primary color with the one you use for you brand. All you have to do is to:

  • open the purpose/_variables.scss, look for the $primary variable and copy it
  • open the custom/_variables.scss and paste the variable with its value
  • replace the value and remove the !default flag
  • make sure you are running Gulp or Laravel Mix watch tasks described in the build tools page

Try following the same variable succession order. Especially, colors, typography and other fundamental variables need to be declared at the beginning of the file so they can be accessible to the components that may follow afterwards.

Creating components

Creating components is easy. It is even easier if you follow the guidelines we are suggesting. This we’ll keep make your code look clean and be easy to read and to work with. Also you will make sure you have results at the same level of quality as Purpose or Bootstrap.

There are a few steps:

First, determine which component are you going to develop next. Even though it already exists, let’s say you want to create an alert component. Determining exactly the component and its purpose you help you to find a name very easily.

So, in this case the class name for alert will be .alert. Other variations or modifier classes will begin with .alert-* (e.g: .alert-danger, which will change the background and text color accordingly).

Also, all variables associated to the class .alert will begin with $alert, $alert-*. Basically, you will need to follow the naming convention Bootstrap and Purpose use: $name-state-property-modifier, where:

  • name is the component name corresponding to the given class name (e.g .alert)
  • state is the pseudo-class used to define a special state of an element (e.g: hover, active, checked etc)
  • property is the given CSS property in order to achieve the results you need (e.g: color, background, display)
  • modifier is used to define additional information for the current property, like sizes, axis (e.g alert-sm, alert-padding-y)

To wrap it up, you should have in the end something like this:

In custom/_variables.scss

$alert-padding-y:   1rem;
$alert-padding-x:   1.5rem;
$alert-color:       #FFF;
$alert-bg:          #000;
$alert-hover-bg:    lighten($alert-bg, 10%);

In custom/_styles.scss

.alert {
    padding: $alert-padding-y $alert-padding-x;
    color: $alert-color;
    background-color: $alert-bg;

    &:hover {
        background-color: $alert-hover-bg;
    }
}

Remember! You can modify the structure inside the user’s folder. You can make separate files for each newly created component and import them one by one in the _styles.scss file. They will be automatically loaded and compiled in the main Sass file.

JS

File structure

You will find in Purpose a special structure for the JS files. We did this to sort each script by its scope. In the resources/js folder you will find the following file structure:

purpose-application-ui-kit/
├── resources/
└── ├── js/
    │   ├── components/
    │   │   ├── charts/
    │   │   ├── custom/
    │   │   ├── init/
    │   │   ├── maps/
    │   │   ├── libs/
  • custom contains all the custom scripts made by us for Purpose
  • init contains all the scripts needed to initialize the Purpose’s components or third-party plugins
  • maps contains map scripts needed to customize the default Google Map style or other map library
  • libs contains all the scripts needed to initialize third-party plugins
  • layout.js is a file where we put the code needed to develop global layout actions

Making changes

Most of the JS files are just a starting point in order to make the components function properly. This means that you will need to change them accordingly, add options, create more functions and so on. All the plugins are well documented and each one has the link that will point you to the official documentations.

Also, when starting a new project you can install only the plugins you need.

Note! When starting modifying JS files make sure you keep an eye on those you edited, because Purpose will be constantly updated.

Compiling

Wether you chose to use Gulp or Laravel Mix, the mechanism behind gets the same result. All JS resources will be bundled in a single file. For the watch commands, each time you make a change, the file will be automatically regenerated and injected in the browser. Learn more about the build tools.

Summary