Difference between revisions of "Joomla LESS"

From Joomla! Documentation

(Created page with "''This page is intended for Joomla Bug Squad members.'' Joomla 3.0 is shipped with a LESS compiler to generate default template and bootstrap CSS files from LESS files. The ...")
 
m (Change URL)
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
''This page is intended for Joomla Bug Squad members.''
+
<noinclude><languages /></noinclude>
  
−
Joomla 3.0 is shipped with a LESS compiler to generate default template and bootstrap CSS files from LESS files.
+
<translate>
 +
<!--T:1-->
 +
Most of the Joomla 3.0 default template stylesheets are written using [[wikipedia:LESS_(stylesheet_language)|LESS]] and then compiled to generate the [[wikipedia:CSS|CSS]] files.
 +
</translate>
  
−
The css generation wrapper script, LESS compiler, and other similar build tools are located in the build directory.  The build directory is only available from a GitHub clone; it is not included in an official Joomla release.  
+
<translate>
 +
== Where can you find the .less stylesheets and compiler? == <!--T:2-->
 +
</translate>
  
−
To generate the CSS files you will need to execute the generation scrips as a CLI application.
+
<translate>
 +
<!--T:3-->
 +
The <code>.less</code> building blocks are located in <code>media/jui/less/</code>. The template specific <code>.less</code>files are located in <code>templates/&lt;templates&gt;/less/</code>.
 +
 
 +
<!--T:4-->
 +
The CSS generation wrapper script, LESS compiler, and other similar build tools are located in the <code>build/</code> directory of the Joomla source located on GitHub.  Refer to [[S:MyLanguage/Git_for_Coders|Git for Coders]] for more information on using GitHub.  The build directory is only available from the Joomla source, it is not included in an official Joomla release.
 +
</translate>
 +
 
 +
<translate>
 +
== How to re-generate the CSS stylesheets == <!--T:5-->
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:6-->
 +
To re-generate all the CSS files from a Joomla core distribution, you will need to execute the generation scripts as a [[wikipedia:Command-line_interface|CLI application]].
 +
 
 +
<!--T:7-->
 +
For example:
 +
</translate>
 +
 
 +
<pre>cd joomla-cms/build
 +
c:\xampp\php\php.exe generatecss.php
 +
</pre>
 +
 
 +
<translate>
 +
== Compiling your own LESS files for your template == <!--T:8-->
 +
 
 +
<!--T:9-->
 +
To compile less files for your own template, you will need to take a copy of the <code>generatecss.php</code> script and adjust it to suite your template.
 +
 
 +
<!--T:10-->
 +
Alternatively you can use a LESS Compiler plugin which compiles your .less files automatically on page reload:
 +
http://extensions.joomla.org/extensions/miscellaneous/development/22424
 +
 
 +
<!--T:11-->
 +
More alternatives and tools on a recent Joomla! Magazine article:
 +
http://magazine.joomla.org/issues/issue-may-2013/item/1289-tools-to-do-less
 +
</translate>
 +
 
 +
<translate>
 +
== Not all LESS compilers are equal == <!--T:12-->
 +
The LESS compiler used for the Joomla core for code style consistency is obtained from [http://leafo.net/lessphp leafo.net/lessphp]. 
 +
 
 +
<!--T:13-->
 +
If you're working on your own template you can use any compiler you like.
 +
</translate>
 +
 
 +
<translate>
 +
== Difference CSS vs LESS imports == <!--T:14-->
 +
 
 +
<!--T:15-->
 +
The main .less file and starting point e.g. in protostar is located in <pre>/templates/protostar/less/template.less</pre>
 +
If you open that file you will find many @imports in this file - imports from many different places. Unlike imports in CSS, imports in LESS get compiled to a single CSS file. This will result in fewer http requests and speed your site up.
 +
</translate>
 +
 
 +
<translate>
 +
== From existing CSS to LESS / import CSS files == <!--T:16-->
 +
 
 +
<!--T:17-->
 +
You may want to add your existing CSS files and classes to your LESS powered template or start with what you have. All CSS declarations are compatible with LESS so you can just rename your .css files to .less and you can compile and use them. You can then step by step make use of the great dynamic features LESS has to offer: variables, mixins, operations and functions. See http://www.lesscss.org
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:18-->
 +
Notice: the examples below reference the default Protostar template for clarity. Your paths may be different.
 +
Notice: If you want to customize Protostar template it is a good idea to copy the template and customize it afterwards - so that Joomla! updates do not overwrite your customizations.
 +
</translate>
 +
 
 +
<translate>
 +
=== Option 1: import your .css as .less files === <!--T:19-->
 +
(a little bit work but worth it, imho)
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:20-->
 +
Now lets assume you want to include your custom files and get them parsed by LESS compiler - you do NOT need to rewrite your .css to LESS because plain .css works as well. The only thing you have to do is to rename your .css files to .less and add an @import statement into above mentioned main /templates/protostar/less/template.less
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:21-->
 +
I assume you put your custom .css files renamed to .less into the /templates/protostar/less folder. Now you open /templates/protostar/less/template.less and at the bottom of the file you import your custom .less files so that they override existing declarations:
 +
</translate>
 +
 
 +
<pre>
 +
@import "modules.less";
 +
@import "components.less";
 +
@import "articles.less";
 +
</pre>
 +
 
 +
<translate>
 +
<!--T:22-->
 +
If you now compile your main template.less file you end up with one main template.css optimized and minified (if you wish). You also reduced your http requests and the site should load faster. Now you can start step by step in your custom.less files to use less variables and other cool stuff http://lesscss.org has to offer.
 +
</translate>
 +
 
 +
<translate>
 +
=== Option 2: just import your .css / does not work for overriding === <!--T:23-->
 +
In /templates/protostar/less/template.less just import your .css files and they will be included as imports into main template.css:
 +
</translate>
 +
 
 +
<pre>
 +
@import "../css/modules.css";
 +
@import "../css/components.css";
 +
@import "../css/articles.css";
 +
</pre>
 +
 
 +
<translate>
 +
<!--T:24-->
 +
But this way you do not get any optimization. And a big issue is that this import is always on top before other declarations - so you can't override an existing declaration.
 +
 
 +
<!--T:25-->
 +
More information: http://lesscss.org/#usage (Section Importing)
 +
</translate>
 +
 
 +
<translate>
 +
== References == <!--T:26-->
 +
 
 +
<!--T:27-->
 +
http://kyleledbetter.com/jui/less/ - Example of building your own template.less
 +
</translate>
 +
 
 +
<noinclude><translate>
 +
<!--T:28-->
 +
[[Category:New in Joomla! 3.0]]
 +
[[Category:Bug Squad]]
 +
[[Category:Template Development]]
 +
[[Category:Development]]
 +
</translate>
 +
</noinclude>

Revision as of 09:20, 16 February 2015

Other languages:
English • ‎Nederlands • ‎español • ‎français • ‎italiano • ‎中文（台灣）‎

Most of the Joomla 3.0 default template stylesheets are written using LESS and then compiled to generate the CSS files.

Where can you find the .less stylesheets and compiler?[edit]

The .less building blocks are located in media/jui/less/. The template specific .lessfiles are located in templates/<templates>/less/.

The CSS generation wrapper script, LESS compiler, and other similar build tools are located in the build/ directory of the Joomla source located on GitHub. Refer to Git for Coders for more information on using GitHub. The build directory is only available from the Joomla source, it is not included in an official Joomla release.

How to re-generate the CSS stylesheets[edit]

To re-generate all the CSS files from a Joomla core distribution, you will need to execute the generation scripts as a CLI application.

For example: 

cd joomla-cms/build
c:\xampp\php\php.exe generatecss.php

Compiling your own LESS files for your template[edit]

To compile less files for your own template, you will need to take a copy of the generatecss.php script and adjust it to suite your template.

Alternatively you can use a LESS Compiler plugin which compiles your .less files automatically on page reload: http://extensions.joomla.org/extensions/miscellaneous/development/22424

More alternatives and tools on a recent Joomla! Magazine article: http://magazine.joomla.org/issues/issue-may-2013/item/1289-tools-to-do-less

Not all LESS compilers are equal[edit]

The LESS compiler used for the Joomla core for code style consistency is obtained from leafo.net/lessphp.

If you're working on your own template you can use any compiler you like.

Difference CSS vs LESS imports[edit]

The main .less file and starting point e.g. in protostar is located in 

/templates/protostar/less/template.less

If you open that file you will find many @imports in this file - imports from many different places. Unlike imports in CSS, imports in LESS get compiled to a single CSS file. This will result in fewer http requests and speed your site up.

From existing CSS to LESS / import CSS files[edit]

You may want to add your existing CSS files and classes to your LESS powered template or start with what you have. All CSS declarations are compatible with LESS so you can just rename your .css files to .less and you can compile and use them. You can then step by step make use of the great dynamic features LESS has to offer: variables, mixins, operations and functions. See http://www.lesscss.org

Notice: the examples below reference the default Protostar template for clarity. Your paths may be different. Notice: If you want to customize Protostar template it is a good idea to copy the template and customize it afterwards - so that Joomla! updates do not overwrite your customizations.

Option 1: import your .css as .less files[edit]

(a little bit work but worth it, imho)

Now lets assume you want to include your custom files and get them parsed by LESS compiler - you do NOT need to rewrite your .css to LESS because plain .css works as well. The only thing you have to do is to rename your .css files to .less and add an @import statement into above mentioned main /templates/protostar/less/template.less

I assume you put your custom .css files renamed to .less into the /templates/protostar/less folder. Now you open /templates/protostar/less/template.less and at the bottom of the file you import your custom .less files so that they override existing declarations: 

@import "modules.less";
@import "components.less";
@import "articles.less";

If you now compile your main template.less file you end up with one main template.css optimized and minified (if you wish). You also reduced your http requests and the site should load faster. Now you can start step by step in your custom.less files to use less variables and other cool stuff http://lesscss.org has to offer.

Option 2: just import your .css / does not work for overriding[edit]

In /templates/protostar/less/template.less just import your .css files and they will be included as imports into main template.css: 

@import "../css/modules.css";
@import "../css/components.css";
@import "../css/articles.css";

But this way you do not get any optimization. And a big issue is that this import is always on top before other declarations - so you can't override an existing declaration.

More information: http://lesscss.org/#usage (Section Importing)

References[edit]

http://kyleledbetter.com/jui/less/ - Example of building your own template.less

Retrieved from "https://docs.joomla.org/index.php?title=Joomla_LESS&oldid=158958"