Best practices: Manage assets in resource packages

Once you choose a frontend framework to use for your website, you can start to write CSS files in the package folder of the respective framework. The following best practices give you recommendations of how to manage your frontend assets in resource packages. For more information, see GitHub repository.

1. Open the ~/ResourcePackages/[Name-Of-Package] folder.
2. Open a console and perform npm install. This command installs all dependencies from the package.json file.
3. Open the ~/ResourcePackages/[Name-Of-Package]/assets/src/project folder.
   You place your assets in this folder.
4. In the sass folder place your SASS files and import them in the main.scss file. 
5. Open the ~/ResourcePackages/[Name-Of-Package] folder.
   
6. Open a console and run grunt.
   This command executes all grunt tasks from the gruntfile.js. This compiles and minifies the SCSS file and produces a main.min.css file in the ~/ResourcePackages/[Name-Of-Package]/assets/dist/css/.

   NOTE: If you are using Bootstrap or Minimal packages, this file is already referenced in the default.cshtml layout file, located in ~/ResourcePackages /[Name-Of-Package /MVC/Views/Layouts folder. In case you are using another package, make sure to add a reference to the main.min.css file in your layout files. This way all pages and templates, based on those layout files, load main.min.css.
   

In case you want to store custom widget templates or you do not want to use resource packages, you place the templates in the templates in the /MVC/Views folder in the root SitefinityWebApp folder of your project. If you want to share grid widget templates among resource packages, move these templates to the /GridSystem/Templates folder, located in the root SitefinityWebApp folder of the project. For more information, see Priorities for resolving views.

You generally store all your project-specific frontend assets, such as .SCSS files, images, scripts, and fonts in the assets/src/project folder. When the default Grunt task is run, all source files are processed and moved to the assets/dist folder, from where there are used in the project.

SCSS files

• sass 
  • settings
    • _colors.scss
    • _typography.scss
      ...
      
  • base
    • _link.scss
    • _typography.scss
      ...

Next, you import them in the main.scss file. For example:

When you run Grunt, all .SCSS files are imported in the assets/src/project/sass/main.scss file and then processed in the assets/dist/css/main.css file.

If you do not want to include Sitefinity or Bootstrap CSS files or you want to use another Bootstrap version, in the assets/src/project/sass/main.scss file and change one of the import rules:

• @import "../../sitefinity/sass/sitefinity.scss";
• @import "../../../../node_modules/bootstrap-sass/assets/stylesheets/bootstrap.scss";

Images

Place all images in the assets/src/project/images folder. When you run Grunt, all images from this folder are compressed and moved to the assets/dist/images folder.

JavaScript files

Place all your JavaScript files in the assets/src/project/js folder. It is always best to load one JavaScript file at a time to reduce requests to the server and speed up your site. To do this, you can concatenate and uglify all of the project's JavaScript files into one file. In the jsfiles.json file, define the order, in which the JavaScript files are to be concatenated, for example:

After you run Grunt, all JavaScript files listed in jsfiles.json file are processed and output to assets/dist/js/project.min.js.

To load the project.min.js file, open the Project's Razor layout file default.cshtml, located in the MVC/Views/Layouts/ folder. Add a reference:

@Html.Script(Url.Content("~/ResourcePackages/Bootstrap/assets/dist/js/project.min.js"), "bottom")

Icons

Place all .SVG files that you want to use as icons via an icon font in the assets/src/project/icons folder. After you run Grunt for the first time, the icon font is created. If you add new .SVG files, you need to run the Grunt task manually (grunt webfont) or rerun the default Grunt task. After that, two new CSS classes are generated for each icon. For example, if the name of the .SVG file is logo.svg, the names of the generated CSS classes are:

• icon-logo
  The icon is displayed before the Company name: <span class="icon-logo">Company name</span>
• icon-item-logo
  The icon is displayed after the Company name: <span class="icon-item-logo">Company name</span>

Once you import the source files of a frontend framework, you can change the variables the framework exposes and, thus, customize their predefined values. For example, the Bootstrap framework has variables that define the breakpoints for the responsive design features. Breakpoints depend on the website design and are not universal, so Sitefinity CMS enables you to redefine these variables according to your design requirements.

You can find the Bootstrap breakpoint variables in folder \node_modules\bootstra-sass\assets\stylesheets\bootstrap in file _variables.sass. You can locate breakpoint variables by searching for //== Media queries breakpoints. Each variable is defined with a !default tag. If,  in your SASS files, you define a variable with the same name as a predefined Bootstrap framework variable, your new variable overrides the Bootstrap default variable value.

NOTE: You can also override variables of custom frameworks you use.