Less JavaScript Style Templates (JSST) in the Rails asset pipeline or as Tilt template. It's like a JavaScript template, but for generating dynamic CSS styles instead of HTML.
If you just want to render your Less stylesheets in the Rails backend and deliver the CSS through the asset pipeline, have a look at Less Rails.
Tested on MRI Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest version of JRuby.
Why a Style template?
Why would you like to have JavaScript Style Templates? If you have a lot of domain models that describes a UI, you can convert them dynamically to CSS and have nice style logic in the template instead of code that manipulates the DOM style attributes.
I also wrote a JavaScript Style Template for Stylus, see Stylus_Assets.
Installation
The simplest way to install Less Assets is to use Bundler.
Add less_assets
to your Gemfile
:
group :assets do
gem 'less_assets'
end
And require the less
and less_assets
in your app/assets/javascripts/application.js.coffee
:
#= require less
#= require less_assets
This provides the less.js parser to parse your stylesheets in the browser and the LessAssets renderer for adding the variables at render time.
Please have a look at the CHANGELOG when upgrading to a newer Less Assets version.
Usage
You can place all your Less templates in the app/assets/javascripts/styles
directory and include them from your
app/assets/javascripts/application.js.coffee
:
#= require_tree ./styles
Because Less Assets provides a default template name filter, the styles/
, stylesheet/
and templates/
prefix will
be automatically removed.
Configuration
Sprockets will cache your templates after compiling and will only recompile them when the content of the template has changed, thus if you change to your configuration, the new settings will not be applied to templates already compiled. You can clear the Sprockets cache with:
rake assets:clean
Template namespace
By default all Less templates are registered under the JSST
namespace, which stands for JavaScript style template.
If you prefer another namespace, you can set it in an initializer:
LessAssets::LessTemplate.namespace = `window.Styles`
Template name
The name under which the template can be addressed in the namespace depends not only from the filename, but also on the directory name by default.
The following examples assumes a configured namespace window.JSST
and the asset template directory
app/assets/javascripts/styles
:
-
app/assets/javascripts/styles/document.lesst
will becomeJSST['document']
-
app/assets/javascripts/styles/editor/zone.lesst
will becomeJSST['editor/zone']
-
app/assets/javascripts/styles/shared/general/headers.lesst
will becomeJSST['shared/general/headers']
Template name filter
If you wish to put the templates in a different location, you may want to modify name_filter
in an initializer.
LessAssets::LessTemplate.name_filter = lambda { |n| n.sub /^(templates|styles|stylesheets)\//, '' }
By default, name_filter
strips the leading templates/
, stylesheets/
and styles/
directory off of the name.
Render
When you have a template named header
with the given content:
.header (@r) {
padding: @r * 2;
border-radius: @r;
}
.header (@r) when (@r > 10) {
margin-top: 3 * @r;
}
#header {
.header(@radius);
}
You can render the style template and pass the variables to be used:
JSST['header']({ radius: '10px' })
which will return in the following CSS
#header {
margin: 20px;
border-radius: 10px;
}
whereas rendering
JSST['header']({ radius: '20px' })
will result in
#header {
padding: 40px;
border-radius: 20px;
margin-top: 60px;
}
Default variables
You do not need to define the variables in the less stylesheet, as they will be created before compilation, but you may want to have them added to provide default variables.
Given the following style template named box
@box-margin: 10px;
@box-padding: 10px;
.box {
margin: @box-margin;
padding: @box-padding;
}
Rendered with only some of the variables passed to the template
JSST['box']({ 'box-margin': '20px' })
will use the default values that results in
.box {
margin: 20px;
padding: 10px;
}
Applying the styles to a document
You can let Less Assets to manage the styles on a HTML document by passing the document to the style template.
Given the following Less style template named divider
:
div {
margin-top: @m;
}
that is compiled with
JSST['divider']({ m: '20px' }, document)
will create a new style tag in the head of the document:
<style id="less_asset_divider">
div {
margin-top: 20px;
}
</style>
Re-render the same style template again with other variables will replace the existing styles with the new ones.
Author
Developed by Michael Kessler, mksoft.ch.
If you like Less Assets, you can watch the repository at GitHub and follow @netzpirat on Twitter for project updates.
Development
- Issues and feature request hosted at GitHub Issues.
- Documentation hosted at RubyDoc.
- Source hosted at GitHub.
Pull requests are very welcome! Please try to follow these simple rules if applicable:
- Please create a topic branch for every separate change you make.
- Make sure your patches are well tested. All specs must pass.
- Update the Yard documentation.
- Update the README.
- Update the CHANGELOG for noteworthy changes.
- Please do not change the version number.
Contributors
See the CHANGELOG and the GitHub list of contributors.
Acknowledgement
- Alexis Sellier for creating Less, the dynamic stylesheet language.
License
(The MIT License)
Copyright (c) 2012 Michael Kessler
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.