Learn how to create your own style without changing the theme’s core files so you can take advantage of future updates.
Make sure you have the followed the steps from the Build tools page. You should have already installed the following:
- Gulp or Laravel Mix
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.
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:
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
Every Sass variable in Bootstrap 4 and MRGi 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
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
$primaryvariable and copy it
- open the
custom/_variables.scssand paste the variable with its value
- replace the value and remove the
- 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 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 MRGi 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
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-*. Basically, you will need to follow the naming convention Bootstrap and MRGi use:
nameis the component name corresponding to the given class name (e.g .alert)
stateis the pseudo-class used to define a special state of an element (e.g: hover, active, checked etc)
propertyis the given CSS property in order to achieve the results you need (e.g: color, background, display)
modifieris 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:
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.
You will find in MRGi 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:
- 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
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 MRGi will be constantly updated.
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.