silverstripe-framework/docs/en/topics/css.md

CSS

Introduction

SilverStripe strives to keep out of a template designer's way as much as possible - this also extends to how you want to write your CSS.

Adding CSS to your template

You are free to add <style> and <link> tags to your template (typically themes/yourtheme/templates/Page.ss).

SilverStripe provides a management layer for javascript and CSS files on top of that with the Requirements class, by adding some simple PHP calls to your controller or template. Some files are automatically included, depending on what functionality you are using (e.g. SilverStripe forms automatically include sapphire/css/Form.css).

In your controller (e.g. mysite/code/Page.php):

:::php
class Page_Controller {
	function init() {
		// either specify the css file manually
		Requirements::css("mymodule/css/my.css", "screen,projection");
		// or mention the css filename and SilverStripe will get the file from the current theme and add it to the template
		Requirements::themedCSS('print', 'print'); 
	}
}

Or in your template (e.g. themes/yourtheme/templates/Page.ss):

:::ss
<% require css(mymodule/css/my.css) %>

Management through the Requirements class has the advantage that modules can include their own CSS files without modifying your template. On the other hand, you as a template developer can "block" or change certain CSS files that are included from thirdparty code.

WYSIWYG editor: typography.css and editor.css

This stylesheet is used to "namespace" rules which just apply in a rendered site and the WYSIWYG-editor of the CMS. This is needed to get custom styles in the editor without affecting the remaining CMS-styles.

An example of a good location to use class="typography" is the container element to your WYSIWYG-editor field. The $Content WYSIWYG editor field already comes with SilverStripe out-of-the-box:

:::html
<!--
   This is a good way, you're only applying class="typography"
   to where the WYSIWYG editor is, and not the entire layout.
-->
`<div id="Main">`
   `<div id="LeftContent">`
      `<p>`We have a lot of content to go here.`</p>`
   `</div>`

   `<div id="Content" class="typography">`
      $Content
   `</div>`
`</div>`

The typography.css file should contain only styling for these elements (related to the WYSIWYG editor):

• Headers (h1 - h6)
• Text (p, blockquote, pre)
• Lists (ul, li)
• CSS alignment (img.left, .left, .right etc)
• Tables
• Miscellaneous (hr etc)

The advantages are that it's fully styled, as a default starting point which you can easily tweak. It also doesn't affect the CMS styling at all (except for the WYSIWYG), which is what we want.

It's also separated from the rest of the layout. If you wanted to change typography only, for where you usually edit the content you don't need to go wading through other CSS files related to the actual layout.

To get these styles working in the CMS. Eg you use a font you want in the CMS area you need to create an editor.css file. Then with this file you can define styles for the CMS or just import the styles from typography. Unlike typography.css, editor.css is NOT included in the front end site. So this is themes/your_theme/css/editor.css

:::css
/* Import the common styles from typography like link colors. */
@import 'typography.css';

/* We want the backend editor to have a bigger font as well though */
.typography * { font-size: 200% }

See typography for more information.

Writing good stylesheets for the CMS

• Use the id attribute sparingly. Remember that it "closes off" the structure to code reuse, as HTML elements require unique id attributes. Code reuse can happen both in CSS and JavaScript behaviour.
• Separate presentation from structure in class names, e.g. left-menu is encoding the component position (which might change later on). A more structural name could be cms-menu (or cms-tools-menu for a more specific version)
• Class naming: Use the cms- class prefix for major components in the cms interface, and the ss-ui- prefix for extensions to jQuery UI. Don't use the ui- class prefix, its reserved for jQuery UI built-in styles.
• Use jQuery UI's built-in styles where possible, e.g. ui-widget for a generic container, or ui-state-highlight to highlight a specific component. See the jQuery UI Theming API for a full list.

Related

• javascript
• "Compass" module: Allows writing CSS in SASS/LESS syntax, with better code management through mixins, includes and variables