5.7 Theme Best Practices (and what makes a good theme)
Permalink 2 users found helpful
I am interested in getting opinions on what people think makes a good theme and potentially establishing best practices once developer documentation is released. With new features like theme presets, it opens the door to making very versatile and customizable themes. Better themes attract more people to concrete5 and provide more value to paid themes.
It would be good to get opinions from developers, designers, tech savvy users, and non-technical users.
A few things I've come up with so far.
1. full marketplace description (in addition to the basic requirements)
- browser version compatibility
- if using a framework, the name of the framework
2. well documented
- instructions for using anything custom (blocks, templates, areas, presets, etc.)
- assume that your end user has no prior knowledge of web technology or web tools beyond using a web browser (this should help reduce support ticket requests)
3. a variety of:
- page types
- page templates
- area classes
- block classes
- block templates
- custom Redactor styles
- theme presets
- style variables
- custom blocks (optional)
4. registration of all assets
5. prevent theme CSS from overriding core styles
- use appropriate CSS selector specificity (overly broad selectors risk overriding core styles)
- avoid using core selectors unless you have a specific reason to
- scope your CSS (.ccm-page is often used as a scope class)
Links to information on CSS selector specificity.
http://css-tricks.com/specifics-on-css-specificity/...
https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity...
JohntheFish wrote an excellent how-to on scoping theme CSS with a CSS preprocessor.
http://www.concrete5.org/documentation/how-tos/designers/easily-sco...
Here is a neat tool for analyzing the specificity of your styles.
http://jonassebastianohlsson.com/specificity-graph/...
http://csswizardry.com/2014/10/the-specificity-graph/...
Sass and Less
The theme presets are written in a CSS Preprocessor called Less. Less allows for creating variables needed for all the different dynamic preset properties.
http://lesscss.org/
In case you don't know what theme presets are, please check them out.
http://www.concrete5.org/documentation/using-concrete5-7/in-page-ed...
For those who use Sass, Sass files can be manually and automatically converted to Less. Be warned in advance that Less supports a few things that Sass does not and Sass supports a lot of things that Less does not. You will need to take this into consideration when writing your Sass if you intend to convert.
Some Sass users are using grid systems and sass features that cannot be converted to Less. In these situations, another possibility is using Sass @import to separate your files. You would create a file(s) with all the settings that would be available in a theme preset - fonts, typography styles, background, etc. These theme preset specific files could be converted to Less. Your non-theme preset specific files (like your grid), which do not require Less variables, could be compiled and put into a Less file.
Automated conversion using a grunt task:
- this looks like it does a good job of converting plain Sass files
https://github.com/jonschlinkert/grunt-refactor...
A few articles about manually converting Sass to Less:
http://nicoespeon.com/en/2013/06/convert-sass-project-into-less/...
http://mstrutt.co.uk/blog/2013/08/converting-from-less-to-sass/...
Area naming conventions
- to be determined
http://www.concrete5.org/community/forums/5-7-discussion/page-type-...
https://github.com/concrete5/concrete5-5.7.0/issues/195...
Olsgreen made a theme boilerplate that includes all the basics to start making a theme. He also made a screencast tutorial on how to use it.
http://codeblog.co.uk/theme-development-concrete-5-7-html5-boilerpl...
https://github.com/olsgreen/concrete_theme_package...
It would be good to get opinions from developers, designers, tech savvy users, and non-technical users.
A few things I've come up with so far.
1. full marketplace description (in addition to the basic requirements)
- browser version compatibility
- if using a framework, the name of the framework
2. well documented
- instructions for using anything custom (blocks, templates, areas, presets, etc.)
- assume that your end user has no prior knowledge of web technology or web tools beyond using a web browser (this should help reduce support ticket requests)
3. a variety of:
- page types
- page templates
- area classes
- block classes
- block templates
- custom Redactor styles
- theme presets
- style variables
- custom blocks (optional)
4. registration of all assets
5. prevent theme CSS from overriding core styles
- use appropriate CSS selector specificity (overly broad selectors risk overriding core styles)
- avoid using core selectors unless you have a specific reason to
- scope your CSS (.ccm-page is often used as a scope class)
Links to information on CSS selector specificity.
http://css-tricks.com/specifics-on-css-specificity/...
https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity...
JohntheFish wrote an excellent how-to on scoping theme CSS with a CSS preprocessor.
http://www.concrete5.org/documentation/how-tos/designers/easily-sco...
Here is a neat tool for analyzing the specificity of your styles.
http://jonassebastianohlsson.com/specificity-graph/...
http://csswizardry.com/2014/10/the-specificity-graph/...
Sass and Less
The theme presets are written in a CSS Preprocessor called Less. Less allows for creating variables needed for all the different dynamic preset properties.
http://lesscss.org/
In case you don't know what theme presets are, please check them out.
http://www.concrete5.org/documentation/using-concrete5-7/in-page-ed...
For those who use Sass, Sass files can be manually and automatically converted to Less. Be warned in advance that Less supports a few things that Sass does not and Sass supports a lot of things that Less does not. You will need to take this into consideration when writing your Sass if you intend to convert.
Some Sass users are using grid systems and sass features that cannot be converted to Less. In these situations, another possibility is using Sass @import to separate your files. You would create a file(s) with all the settings that would be available in a theme preset - fonts, typography styles, background, etc. These theme preset specific files could be converted to Less. Your non-theme preset specific files (like your grid), which do not require Less variables, could be compiled and put into a Less file.
Automated conversion using a grunt task:
- this looks like it does a good job of converting plain Sass files
https://github.com/jonschlinkert/grunt-refactor...
A few articles about manually converting Sass to Less:
http://nicoespeon.com/en/2013/06/convert-sass-project-into-less/...
http://mstrutt.co.uk/blog/2013/08/converting-from-less-to-sass/...
Area naming conventions
- to be determined
http://www.concrete5.org/community/forums/5-7-discussion/page-type-...
https://github.com/concrete5/concrete5-5.7.0/issues/195...
Olsgreen made a theme boilerplate that includes all the basics to start making a theme. He also made a screencast tutorial on how to use it.
http://codeblog.co.uk/theme-development-concrete-5-7-html5-boilerpl...
https://github.com/olsgreen/concrete_theme_package...
Relating to folder or file structure here are some suggestions.
First lets define basic structure. The ThemeName is required as the initial folder. That folder will be called the root directory or folder if you prefer. Subdirectories will have names like css, images, and js.
Specific names are your preference. Styles or css are common folder names in themes. What is important is that a subdirectory contains the appropriate css or script files.
This is one one suggestion for the files in the root folder:
description.txt
default.php
full.php (even if it is the same code as default.php there should be one additional template file)
page_theme.php
thumbnail.png
It's really that simple.
The subdirectories or folders are simple too:
elements (which is a C5 standard)
css
js
images
Since vendor tools, SASS or LESS and frameworks have their own folder standards you would follow their standards and just integrate those into your theme. Concrete5 appears to support LESS so maybe we should include that in best practices. Please comment on that particular exception.
-------
The file page_theme.php is a major file. Maybe it should be added to Item 3 in the discussion. The class PageTheme and method registerAssets() is extremely important if not essential. The Urbanic tutorial has a great example of how Concrete core assets can conflict with your theme assets. That should be enough to place page_theme.php as an essential part of every theme. Of course, there are other methods that are important to your theme so let's consider discussing this file under best practices.
-------
Finally, C5 core css and your theme css is integrated. After converting a theme from a previous version their css stepped all over the Concrete5 admin toolbar and the admin dropdown sidebars. With this integrated css it is necessary to define elements specifically to classes and id's. This is not just an issue between C5 core and your theme but other third party applications and tools. Should the best practices discussion include a section on coding standards?
First lets define basic structure. The ThemeName is required as the initial folder. That folder will be called the root directory or folder if you prefer. Subdirectories will have names like css, images, and js.
Specific names are your preference. Styles or css are common folder names in themes. What is important is that a subdirectory contains the appropriate css or script files.
This is one one suggestion for the files in the root folder:
description.txt
default.php
full.php (even if it is the same code as default.php there should be one additional template file)
page_theme.php
thumbnail.png
It's really that simple.
The subdirectories or folders are simple too:
elements (which is a C5 standard)
css
js
images
Since vendor tools, SASS or LESS and frameworks have their own folder standards you would follow their standards and just integrate those into your theme. Concrete5 appears to support LESS so maybe we should include that in best practices. Please comment on that particular exception.
-------
The file page_theme.php is a major file. Maybe it should be added to Item 3 in the discussion. The class PageTheme and method registerAssets() is extremely important if not essential. The Urbanic tutorial has a great example of how Concrete core assets can conflict with your theme assets. That should be enough to place page_theme.php as an essential part of every theme. Of course, there are other methods that are important to your theme so let's consider discussing this file under best practices.
-------
Finally, C5 core css and your theme css is integrated. After converting a theme from a previous version their css stepped all over the Concrete5 admin toolbar and the admin dropdown sidebars. With this integrated css it is necessary to define elements specifically to classes and id's. This is not just an issue between C5 core and your theme but other third party applications and tools. Should the best practices discussion include a section on coding standards?
"Since vendor tools, SASS or LESS and frameworks have their own folder standards you would follow their standards and just integrate those into your theme. Concrete5 appears to support LESS so maybe we should include that in best practices. Please comment on that particular exception."
What makes Sass and Less flexible is they don't have folder standards. You can structure your files and folders however you like. This has allowed for a variety of approaches to writing and organizing CSS (i.e. BEM, OOCSS, and SMACSS).
The reason why I bring up converting partial and full Sass files is for using Sass specific tools. An example is the Susy grid system. Susy uses a lot of math functions and control structures not available in Less.
http://susy.oddbird.net/
What makes Sass and Less flexible is they don't have folder standards. You can structure your files and folders however you like. This has allowed for a variety of approaches to writing and organizing CSS (i.e. BEM, OOCSS, and SMACSS).
The reason why I bring up converting partial and full Sass files is for using Sass specific tools. An example is the Susy grid system. Susy uses a lot of math functions and control structures not available in Less.
http://susy.oddbird.net/
Theme presets it's very important, more complete, more easy to us or our clients to give some personalization. Maybe one day Concrete5 have the same capacity of Editing the CSS files directly, like Jo***.