Extend documentation

[havenchyk]

Hi. Can you please explain more clear what this plugin do? Plugin added variables before compiling .less files e.g.? What is the difference between @import with another less file? Thanks.

[tsalzinger]

I think the readme already describes pretty detailed what this plugin does and how it can be used.
The point you seem to miss is that regular @import statements will always be present in your packaged less files while this plugin enables you to configure what is 'imported' via config values which will be loaded when your server starts up. In addition the @import statments use relative paths while with the plugin you can 'import' any resource. In addition if you use the plugin instead of @import to include for example all your variables and mixins in every single less file you get rid of all the duplicate import statements at the beginning. But I agree that the prepend feature isn't the most valuable for less files - the main advantage this plugin provides for less files is the append functionality which I already described in the readme (https://github.com/tscheinecker/grails-augmented-resources#usage-example).

Do you have any further questions?

[havenchyk]

Thanks for answering so quickly, may be it is my problem, but I still can't understand, how plugin do what you describe in documentation. I know that lesscss-resources plugin provide compiling of .less to .css, also it supports @import directive, so I can use my own file with variables like @main-color e.g., but I can't understand, how does plugin work. Less file should be compiled to css, does plugin add my _mixin.less to begining of the result.less and invoke recompile? Why should I restart server after adding _mixin.less?

Thanks.

[tsalzinger]

This plugin works before the compiling of the less files happens, it copies all the content of external resources either to the beginning (prepend) or end (append) of a configured file. The plugin supports live reloading as well, restarting is only necessary in production mode and, at the moment also for less files because of an issue with the lesscss-resources plugin (paulfairless/grails-lesscss-resources#49).

Let me try to explain the plugins features again:

Imagine you have a project where you have several less files.
You developed it in a clean manner and extracted a _variables.less and a _mixins.less which you placed in a directory less/imports.

in all your other files you include these two files.

My plugin would allow you to get rid of the @import statements for all files by specifying

grails.resources.mappers.augment.lesscsscompatibility = true
grails.resources.mappers.augment.augment = [
    'less/*.less' : [
            prepend: ['less/imports/_variables.less', 'less/imports/_mixins.less']
    ]
]

But as mentioned several times already, this is only a possibility and nothing you would do in a real project.

What is much more likely is that you use the append feature to modify some of your variables you defined in your _variables.less file.

Imagine you have deployed your application on a tomcat for a customer. The customer isn't satisfied with the colors used by your application because they don't match the colors of his coporate identity.
You could now change all the color derfinitions in your _variables.less and deploy a new version, but this approach will get you in trouble as soons as you have more then one customer. This is where this plugin comes in:

In your config just specify

grails.resources.mappers.augment.lesscsscompatibility = true
grails.resources.mappers.augment.augment = [
    'less/*.less' : [
            append: "file:${System.properties['catalina.base']}/ci/ci_colors.less"
    ]
]

This way your application will maintain it's default styling unless you provide the configured ci_colors.less file within the tomcat directory of your deployed application.
The contents of this file then will be copied to the end of every configured file (in our case 'less/*.less') and therefore effectively overrides all variables which already have been defined before. This step takes place before the less file is actually compiled and therefor you changed the look and feel of your application without having to touch the code.

[havenchyk]

Ok, now pretty clear. Thanks for explaining in detail.

[tsalzinger]

Your welcome, glad i could help