Customizing the Site Skin

A site skin essentially governs the elements that drive the visual appearance of a site. The Ed-Fi Dashboards have a robust mechanism for customizing the site skin. While the skinning techniques used in the Ed-Fi Dashboards are meant to be intuitive and are likely to be familiar to experienced UI designers, this section may be a useful guide to the particulars. This documentation discusses the basic CSS structure, frameworks, guidelines, and tools used in its implementation as well as provides instruction on how to extended or override the style of the application.

Frameworks, Guidelines, and Tools

The implementation approach is based heavily on the SMACSS guidelines which can be accessed here http://smacss.com/.

The three basic tools used in this implementation are:

1. Cassette: an asset bundler for the .NET framework.
2. SASS: An extension to CSS that helps split and organize CSS.
3. Mindscape Web Workbench: A tool that compiles the SCSS into CSS for highlighting development and debugging purposes.

Cassette (http://getcassette.net/) is an asset bundler used to manage client side code and assets. It automatically sorts, concatenates, minifies, caches and versions all JavaScript, CSS, Sass and HTML templates. It is also used in this implementation as a performance enhancement tool to reduce the number of requests for assets to the web server. One of the features of Cassette is the plugin library that can be leveraged to perform preprocessing/compiling of the Sass or SCSS files into browser-readable CSS.

Sass (http://sass-lang.com/) is an extension of CSS3 that adds additional features and structure. The features provided by Sass that are used in the Ed-Fi Dashboards include variables for color definition, hierarchical and nested CSS, mixins (CSS functions), and selector inheritance.

A few noteworthy examples of these are:

The Visual Studio plugin “Mindscape Web Workbench” (http://www.mindscapehq.com/products/web-workbench) is also used in the Ed-Fi Dashboards implementation. This tool provides the ability to process Sass files into CSS for development and debugging purposes. An additional benefit of the plugin is that it enables IntelliSense and code highlighting for Sass's SCSS files in Visual Studio. This tool can be installed from within Visual Studio Tools > Extensions and Updates… and selecting Online, searching for "Mindscape Web Workbench," and installing.

CSS structure

The base Dashboard-project-provided CSS files are located in the EdFi.Dashboards.Presentation.Core\Content\StyleSheets directory. This folder contains all the CSS and SCSS source files that are used throughout the project. The CSS is divided into two main files called 1-base.scss and 2-appearance.scss. An overview of each follows:

• 1-base.scss. This file groups the partial “_” SCSS files that provide the base style for the dashboards. Important components like _shared, _layout and _ed-fi-grid are included in the header so they can be compiled into a single 1-base.css that can be interpreted by the browser. The file _shared.scss contains all the variable definitions for colors and mixins that can be reused throughout the other SCSS files. The _layout.scss file contains all the style definitions for layout like width, height, position, floats and distribution of the application. The _ed-fi-grid.scss contains all the styles specific to the Ed-Fi grid and is a separate file due to the high level of complexity.

• 2-appearance.scss. This file only includes the _shared.scss partial so that it can access the color variables and mixins. The main purpose of 2-appearance.scss is to specify “appearance styles” which include font types, font sizes, border and background color specifications, gradients, and everything else related to the Dashboard’s visual appearance.
   

Overriding and Extending Existing Styles

The Dashboards leverage the base functionality of CSS. The Dashboard CSS is overridden using the following approaches and concepts:

1. Last style in wins. If you include two or more style sheets in the header of a HTML document that include settings for the same class style, they are processed in the order listed and the last setting overrides any styles set in previous style sheets.

2. Specificity. The more specifically defined style takes priority over less specific definitions.

The appearance.scss is built upon the above concepts and gets precompiled into an appearance.css file. This file is located in the presentation Web project in the EdFi.Dashboards.Presentation.Web\Content\StyleSheets\ path. This appearance.css will get bundled and included in the HTML document after the base CSS files giving it a higher priority. Any changes to look and feel that you desire can be made by overriding styles in the appearance.css file.

More Flexibility

If more customization is desired, such as overriding the underlying HTML structure of the whole site while still leveraging the information and MVC view models of the dashboards, there is a mechanism in place to address this. The as-shipped code includes an empty EdFi.Dashboards.Presentation.Web project. This project has the same structure as the EdFi.Dashboards.Presentation.Core and provides the ability to override the MVC views by supplying custom ones. There is flexibility to partial or child views, and developers may even even replace the whole structure with a custom _SiteLayout.cshtm and child views. Compliance with the routing and MVC definition of the views is still required.