We are going to deploy the new yiiframework.com website on March 23, 2018 from 8:00 to 12:00 UTC.
Website and Yii documentation will not be available in this time frame. Check the news for more details.

Difference between #6 and #5 of CSS Naming Conventions

CSS Naming Conventions
CSS, naming conventions
In this article, we introduce a set of CSS naming conventions that we have
applied in several big projects and achieved success. The goal of these naming
conventions is to eliminate the possibility of naming conflicts, facilitate
debugging and maintenance, and to simplify the naming process.

> Info: The naming conventions we introduce here may not be optimal to
> However, we believe that compared with the huge advantage it brings, its 
> performance impact is negligible. 

## CSS Class and File Name

Use lower-case letters to name all CSS classes and files. And use dash
characters to separate words in the name. For example, we may use names like
`widget-latest-comments`, `post.css`.

## Organizing CSS Files

Divide CSS styles into separate files to facilitate team work and future
maintenance. The CSS files may be named according to the following rules:

- `global.css`: this file contains global CSS styles that may be reused in
different places.

- `layout.css`: this file contains CSS styles used by layout views.

- `ControllerID.css`: here `ControllerID` refers to any controller ID in the
application. This means each controller may have its own CSS file named after
its ID. For example, `PostController` may have a CSS file named `post.css`.

- `widget-WidgetClass.css`: here `WidgetClass` refers to the class name of a
widget that requires CSS styles. For example, `LatestComments` may use the name

- `FeatureName.css`: big features may have their own CSS files named after the
feature names. For example, the Markdown content format may use the CSS file

- Other needed CSS files, such as CSS frameworks.

## Naming CSS Classes

In general, we should use CSS classes instead of IDs to style HTML elements.
This is because the same ID cannot appear twice in the same XHTML page.

The naming conventions for CSS classes are as follows:

- CSS classes that are meant to be shared should be prefixed with `g-`. For
example, we can have names like `g-submit-button`, `g-link-button`. The
declaration of the corresponding styles should be put in the aforementioned
`global.css` file, and can use the simple syntax like the following:

.g-link-button {

- Each action view file must have a root container that contains all its view
content. The root container must declare a class named as the view path. For
example, the `post/index.php` view file should content like the following:

<div class="post-index">
   ...view content here...

- Declaration of the CSS styles of an action view should be put into the
corresponding controller CSS file. Each declaration must be prefixed by the root
container class. For example, to declare the CSS styles for an item element in
the `post/index` view, we should put the following CSS styles in the `post.css`

/* in post.css file */
.post-index .item {

- CSS class naming and style declaration for a widget view follow the similar
rules for action views. For example, the `LatestComments` widget should use root
CSS class name as `widget-latest-comments`, and declare its comment styles in
the `widget-latest-comments.css` file like the following:

/* in widget-latest-comment.css file */
.widget-latest-comment.widget-latest-comments .comment {

- A layout view file should also have a root container named after the layout
name with prefix `layout-`. For example, the `main` layout should use CSS class
named as `layout-main` for its root container. To avoid naming conflict with the
inserted view content, the CSS class of container elements in the layout may be
prefixed with the root container class name. For example, the header section may
use the name `layout-main-header`; the content section may use

## Including CSS Files

In development mode (when `YII_DEBUG` is true), every CSS file should be
included in the main layout file.

In production mode, all CSS files should be merged and compressed into a single
file. The file name should contain a timestamp (e.g. `styles-201010221550.css`).

By doing so, we can let the browser to cache the merged CSS file and thus
eliminate the necessity of downloading CSS file each time.

### Combining and Compressing CSS Files

Here we introduce a strategy on how to achieve the above goal.

First, we declare all CSS file names as an array in the [application
parameters](http://www.yiiframework.com/doc/api/1.1/CModule#params-detail) in
the application configuration.

Second, write a console command to combine and compress the CSS files. The [YUI
coompressor](http://developer.yahoo.com/yui/compressor/css.html) may be used for
this purpose. The command will read the CSS file names from the application
parameters, concatenate all file contents into a single file, and call YUI
compressor to minify the CSS styles. The generated file should be named with a
timestamp on it.

Third, modify the application main layout view by inserting the following code
in the HTML head section:

    <?php if(Yii::app()->params['css.files.compressed']): ?>
    <link rel="stylesheet" type="text/css" 
          href="<?php echo Yii::app()->baseUrl.'/css/'
              . Yii::app()->params['css.files.compressed']; ?>" />
    <?php else: ?>
    <?php foreach(Yii::app()->params['css.files'] as $css): ?>
    <link rel="stylesheet" type="text/css" 
          href="<?php echo Yii::app()->baseUrl.'/css/'.$css);
?>" />
    <?php endforeach ?>
    <?php endif ?>

Note that in the above, we assume the CSS files are listed in the `css.files`
application parameter. And if the files are combined and compressed, the
resulting file name should be put in the `css.files.compressed` application
parameter. The console command should modify the application configuration file
to update the `css.files.compressed` parameter after it generates the combined
and compressed CSS file.

## Conventions for Naming jQuery Selectors

We can use the above CSS naming conventions in jQuery selectors in the
application's javascript code. In particular, when selecting one or several
elements using jQuery selectors, we should follow the similar rule for declaring
CSS styles. For example, if we want to attach `click` handlers to all hyperlinks
within news item blocks, we should use the following jQuery selectors:

$('.news-index .item a').click(function(){ 

That is, a selector should be prefixed with the root container CSS class name
(`news-index` in the above).