SiteGenesis and CSS

Salesforce B2C Commerce storefront pages are created using ISML templates, CSS, and B2C Commerce forms, resulting in HTML that is rendered on the browser. Use these technologies to customize the look and feel of your storefront, as follows:

Technology	Use for...
Templates	Formatting live data within regular HTML code
Cascading Style Sheets (CSS)	Web page layout and definition and page element styling
Forms	Data read, write and validation.

Note: See the SiteGenesis wireframes to understand how the SiteGenesis application works.

Working with Templates

The SiteGenesis application uses ISML files (templates) to define a framework for different page layouts, thus acting as the template that defines the basic structural page. The page/template structure consists of CSS containers and structural elements.

Containers: set the width, margin and padding. They form the structural base for a specific page layout.
Structural elements: define the main wireframe layout of the page.

Page type Structure

The SiteGenesis page type structure enables you to dynamically load CSS. Each set of page type files have the following naming convention:

pt_[page_type].isml

For example, pt_giftregistry_UI.isml, pt_giftregistry_VARS.isml, and pt_giftregistry.isml.

The pt_[page_type]_UI.isml and pt_[page_type]_VARS.ism templates in the SiteGenesis Storefront Core cartridge are intentionally empty. They act as place holders for a template with the same name (pt_[page_type].isml) at a parent level in the cartridge path.

pt_xxx_UI.isml is injected into pt_xxx.isml, in the <head> element, to enable custom cartridges to add script and css dependencies.
pt_xxx_VARS.isml is injected into pt_xxx.isml, after the footer element (within the <body> element, but near the end), for adding <script> elements that are loaded after the markup is loaded.

For example, compare pt_giftregistry_VARS.isml in the SiteGenesis Storefront Core cartridge against the completed file in the SiteGenesis Storefront cartridge.

To see how SiteGenesis uses custom CSS files in searches, see the following templates, located within the core cartridge/templates/default/search:

pt_contentsearchresult_UI.isml
pt_contentsearchresult_VARS.isml
pt_productsearchresult_UI.isml
pt_productsearchresult_VARS.isml

Working with CSS

These are the standard SiteGenesis application CSS files, located in the Storefront Core cartridge (static/default/css):

normalize.css: overall page element styling, for font size and margins, for example.
print.css: styling for print output using normalize.css and style.css
style.css: specific page styling of UI elements for standard PC browser pages.
style-responsive.css: specific page styling of UI elements for responsive design pages.

To work with B2C Commerce CSS, you will need:

The storefront running with Business Manager
UX Studio connected to a server instance, with the SiteGenesis application and the APIs downloaded.
A SCSS tool such as Gulp or Grunt
A CSS editing tool

Stylesheets

SiteGenesis stylesheets are written in SCSS, a syntax that is a superset of CSS. Existing CSS is valid SCSS.

SCSS authoring is meant to be used with a build tool, such as gulp. When compiled, the SCSS is output as CSS in the static/default/css folder.

Note: SCSS (Sassy CSS) is a syntax used for Sass (Syntactically Awesome StyleSheets), a CSS extension. See http://sass-lang.com/guide

SCSS Variables

Using SCSS variables, SiteGenesis styles such as color, font size, and font family are parameterized according to the style guide shown when executing the command:

gulp styleguide

The CSS variable files are located in the app_storefront_core/cartridge/scss folder as scss files.

CSS Design Best Practices

Consider these CSS design best practices:

Include as little browser specific code as possible. If browser-specific code is required, avoid CSS hacks and use the specific browser's best practice for addressing any issues. See components/browsertoolscheck.isml, which is used in every page to render warning messages if certain functionality that is necessary to use the website (such as cookies and JavaScript) is disabled in the client browser.
Separate the CSS that controls page structure (header, footer) from the CSS that controls the styling of page elements (cart, products, forms). This makes it easier to change page design.
The first step in a new implementation is typically to change the page structure.

Third party script Libraries

B2C Commerce supports separate skinning for third party script libraries (such as jQuery) and visual features such as carousels, accordions, and tabs. B2C Commerce CSS supports the reusable component model of the SiteGenesis application. For example, page styling elements can appear in multiple places across a site, providing an easy way to override only those areas you want to change.

CSS Inheritance

CSS inheritance is a key concept used in B2C Commerce, whereby style sheet definitions along a linear processing path overwrite some or all of the previous definitions. For example, a general style sheet defines page layout and styling for a generic page. These styles are overwritten for specific portions of the page as data is entered and processed.

Note: B2C Commerce supports the standard CSS specifications, which are maintained by the World Wide Web Consortium (W3C).

The CSS style sheets used in the SiteGenesis application provide a good starting point for storefront customization and can help you understand how CSS works within the B2C Commerce environment. CSS files be specified in two places: in Business Manager and within the application cartridge.

CSS called from Business Manager

In Business Manager, you can configure custom CSS files for library folders, content assets, categories, and products. These CSS files are dynamically loaded when a storefront visitor searches either for content assets or products; they are not loaded outside of the context of a search result. When a product is found in a search, the CSS files for all of its ancestor categories (if any) are loaded, in addition to the CSS file specified for the product (if any). Similarly, when a content asset is found in a search, the CSS files for all of its ancestor library folders (if any) are loaded, in addition to the CSS file specified for the content asset (if any).

This approach gives you flexibility in deciding where in the hierarchy you want to configure your custom CSS files. For example, if you know that all content assets in a library folder should be rendered using the same custom CSS file, then you can specify the CSS file at the library folder level, instead of at the content asset level. Dynamically loaded CSS files are loaded in parent-to-child order, with the child loaded last. This means that all of the category CSS files are loaded before the product CSS file, and all of the library folder CSS files are loaded before the content asset CSS file.

CSS Called from the Cartridge

In Studio, start by looking at the CSS files located in the SiteGenesis Application cartridge. All CSS files not managed with Business Manager are referenced within the htmlhead.isml, an ISML code snippet that is included within the header of a SiteGenesis application page type rendering template.

Note: htmlhead.isml is located at templates/default/components/header within the SiteGenesis Storefront Core cartridge.

CSS Modularization

SIteGenesis uses SASS to organize CSS, in part because the syntax for SASS supports variables (which we wanted for parameratizing our colors, font collections, etc) and nesting. There is a new directory to hold all the *.scss files in the app_storefront/cartridge/default directory (app_storefront_core/cartridge/default in versions before 15.7) We use the SCSS file format but the SASS pre-processing tools - this can be slightly confusing if you're looking for *.sass files (which we don't support). If you look in app_storefront/cartridge directory, you'll also see scss support for additonal locales (French, Italian, Chinese, and Japanese). These directories are intended to hold any locale-specific modifications that you need to override the default stying. The names of the files generally correspond to the names of the pages or modules that they support and it should be fairly intuitive to find what you're looking for. _breadcrumbs.scss supports the breadcrumb styling in all the pages, _minicart.scss contains all the styling information related to the minicart. In addition to the module-specific styling, there are some global parameters, such as colors, that are stored in _variables.scss. One of the goals of the modularization effort was to remove any hard-coded values in the style files and centralize them in _variables.scss.

Other CSS Benefits - the SiteGenesis Styleguide

The SiteGenesis Styleguide is created with the goal of helping designers and developers in defining and understanding a common visual language used for their ecommerce application. It includes design elements such as colors, typography and icons as well as more complex UI components such as the product tile or navigation menu. In order to generate the styleguide for your application, go to the command line and run: % grunt styleguide. This will set up a static web server (by default at http://localhost:8000) that shows the living styleguide. This styleguide imports the Sass styles in app_storefront. This way, any update to the application's style will be reflected in the styleguide. The SiteGenesis Styleguide is written using ampersand (http://ampersandjs.com/) and handlebars (http://handlebarsjs.com/) for those users who want to extend it or see how it was constructed.