CiviCRM supports CSS-based theming. You may define a theme which overrides
or supplements the main CSS files, `civicrm.css` and `bootstrap.css`.
# Architecture
or supplements a CSS file such as `civicrm.css` and `bootstrap.css`.
Most installations of CiviCRM are embedded within a CMS (such as Drupal,
Joomla, or WordPress). Customizing the look-and-feel therefore includes two
...
...
@@ -25,65 +24,124 @@ However, we cannot achieve that vision in one dramatic leap. Rather, theming
in Civi will be in transition for the foreseeable future, so we must discuss
some more nuanced concepts. The key concepts in Civi theming are:
* __Visual Look-and-Feel__ (Theme): This is the visual appearance that an end-user
will recognize. For example:
* The "__Greenwich__" theme provides a look-and-feel with beveled grey buttons.
* The "__Shoreditch__" theme provides a look-and-feel with flat blue buttons.
* __HTML Coding Convention__: This is the programmatic convention. It defines a contract
between an application-developer (who produces HTML data) and a theme-developer
(who produces CSS data). Each coding convention should have a __style-guide__ which
demonstrates the convention. For example:
* The "__civicrm.css__" coding convention encodes a button using the class `crm-button` as in `<input type="submit" class="crm-button">`.
* The "__bootstrap.css__" coding convention encodes a button using the class `btn` as in `<button class="btn btn-default">`.
* __Package__: This is the electronic deliverable that an administrator installs
when he wishes to customize the visual look-and-feel. CiviCRM supports
many package types, such as "CiviCRM extensions", "Drupal modules", and
"WordPress plugins".
* __Look-and-Feel (*Theme*)__: The visual appearance that an end-user will recognize. (*Ex: a flat, high-contrast appearance built around blue and white*)
* __Package__: The deliverable that an administrator installs/activates. (*Ex: a CiviCRM extension*)
* __Vocabulary__: The set of HTML/CSS class-names which form a contract between HTML and CSS providers. (*Ex: BootstrapCSS*)
Generally speaking, these are relevant to people acting in different roles:
* A __theme developer__ who wishes to define a new __look-and-feel__ (_theme_) should learn about the __vocabulary__
by examining its __style guide__; then, he or she can create a __package__ (e.g. CiviCRM extension) which
includes a __CSS file__ for the __vocabulary__.
* A __site administrator__ who wishes to change the __look-and-feel__ of the site should install the __package__
provided by the __theme developer__.
* An __application developer__ who wishes to provide a pleasant experience should learn about the __vocabulary__
by examining its __style guide__. He or she can create pages which load the __CSS file__ and use this __vocabulary__.
We can explore each of these concepts in greater detail.
## Quick Start
To generate an extension with a new, skeletal theme named `newyork`, use [civix](/extensions/civix.md):
```bash
$ civix generate:module org.civicrm.newyork
$ cd org.civicrm.newyork
$ civix generate:theme
Initialize theme "newyork"
Write newyork.theme.php
Write css/civicrm.css
Write css/bootstrap.css
```
Note how this provides theme metadata (`newyork.theme.php`) and two empty CSS files (`css/civicrm.css` and
`css/bootstrap.css`).
A theme-developer who wishes to define a new __look-and-feel__ (_theme_) should create
a __package__ with two CSS files:
## Themes
*`civicrm.css` defines the look-and-feel for any screens based on the __crm-*__ coding convention.
*`bootstrap.css` defines the look-and-feel for any screens based on the __Bootstrap__ coding convention.
A*theme* determines the visual appearance that an end-user will recognize. At time of writing, there are two
important themes in CiviCRM:
The remainder of this document will explore the specifics of the coding
conventions and packaging mechanics.
* __Greenwich (Village)__: This has been the standard appearance since roughly CiviCRM 3.x. Visually, you can
recognize Greenwich by the use of grey beveled buttons. Technically, it has been developed in vanilla CSS.
* __Shoreditch__: This is a newer theme developed as an extension during 4.7/5.x. Visually, you can recognize
Shoreditch by its flat design. Technically, it has been developed in the Bootstrap(S)CSS framework.
# Coding: civicrm.css
!!! note "What's in a name?"
_TODO: Discuss history of civicrm.css. Provide instructions on viewing the style-guide. Discuss
maintenance challenges._
During a planning session for Shoreditch in Fort Collins, CO, we got repeatedly confused by the lack of a distinct
name for the current and proposed themes. We started to use names that paid hommage to the original development
teams -- naming each after a neighborhood that was close to the original teams' bases of operations.
# Coding: bootstrap.css
## Vocabularies {:#vocab}
_TODO: Discuss history of bootstrap.css. Provide instructions on viewing the style-guide._
A __vocabulary__ provides a list of CSS class-names. It defines a contract between an application-developer (who
generates HTML data) and a theme-developer (who generates CSS data). The best way to learn about common
vocabularies is to install the [org.civicrm.styleguide](https://github.com/civicrm/org.civicrm.styleguide/) extension.
_TODO: Application developers may need to `addStyleFile('civicrm, 'css/bootstrap.css')`._
There are two important vocabularies which correlate to two important files:
# Mechanics
*`crm-*` (aka `civicrm.css`) defines the look-and-feel for any screens based on the __crm-*__ coding convention.
* __Strength__: This is the traditional vocabulary used on the most screens. It has some smart conventions for
identifying/selecting fields.
* __Weakness__: Developed organically. It has gone through some iterations of cleanup/improvement, but its definition
and terms are not strongly documented.
* BootstrapCSS (aka `bootstrap.css`) defines the look-and-feel for any screens based on the __Bootstrap__ coding convention.
* __Strength__: Widely used vocabulary with a larger ecosystem and support tools (e.g. BootstrapSCSS).
* __Weakness__: This is newer in the CiviCRM ecosystem. Not included with `civicrm-core` -- and there's no
Greenwich for BootstrapCSS.
CSS files are loaded in CiviCRM by calling `addStyleFile()`, e.g.
The basic purpose of a theme is to provide a copy of each CSS file.
!!! note "Shoreditch as bridge"
At time of writing, [Shoreditch](https://github.com/civicrm/org.civicrm.shoreditch) is the only theme which implements
a consistent look-and-feel in both vocabularies. It is intended to be a bridge that provides a consistent
look-and-feel while other parts of the application transition from `crm-*` to BootstrapCSS.
!!! note "Additional vocabularies"
If you need to define a new vocabulary for widgets and concepts that don't exist in `crm-*` (`civicrm.css`) or
BootstrapCSS (`bootstrap.css`), then you can simply choose another filename (`superwidgets.css`) and implement a
style-guide. The theme system will allow themes to override any CSS file.
However, this doesn't mean that *every* CSS file should be overriden. From the perspective of an application developer,
adhoc CSS often isn't intended for consumption/override by others. From the perspective of a theme developer, it
would be overwhelming to override every CSS file from every extension.
Instead, approach new vocabularies conscientiously -- a new vocabulary should represent a contract in which both
application developers and theme developers benefit from a clearer specification. Use a style-guide to document
the contract.
## Mechanics
Suppose we have a theme -- such as Greenwich or Shoreditch -- which defines a file -- such as `civicrm.css`. How
does this file get loaded on to the screen?
Somewhere within the application, there is a call to [Resources::addStyleFile()](resources.md), as in:
