How to incorporate Flawless into existing project?

[Zearin]

Question

Is it possible to use just Flawless’ mixins in my CSS without using the rest of the framework?

If so, how?

Reasoning

I have an existing project structure that I don't want to muck up, and I'm too far along in the project to “reboot” it starting with Flawless’ setup (even with the speed bonuses provided by Flawless).

[DominikGuzei]

Hi Zearin!

You have just discovered the main concept behind flawless ;-) Althought the whole framework is "loaded" when you develop your styles, nothing is included into your stylesheets if you didn't use it explicitly. This means if you just want to add rounded corners to some elements than you can do that - the framework will only write css styles that are needed for this specific task. All other things (grid system etc.) will not be included into your stylesheet.

i hope this helps! kind regards, Dominik

[superstructor]

Hi Zearin,

Thanks for your interest in flawless.

Dominik is absolutely correct that only what you explicitly use via mixins will be included in your static CSS.

Some technical points on the minimum required to use flawless mixins from an existing project that I hope will help:

1. Obviously you need to include the Lessjs JavaScript file on your page e.g.

   <script type="text/javascript" src="less-1.0.36.js"></script>

2. Not as obvious is you must use the customized copy of Lessjs at css/flawless/core/development/less-1.0.36.js as flawless adds custom functions to the Lessjs language.
3. After including css/flawless/core/development/less-1.0.36.js you must have have an additional script tag that calls the function flawless.initLess(); The flawless global and initLess() function is defined in less-1.0.36.js.

4. Having a manually invoked less as per 3. enables you to directly attach your own custom functions to the less.tree.functions namespace if you wish before calling flawless.initLess(); For example the following enables use of the direction function in your CSS:

   // Return the direction in degrees from the origin to the given offset co-ordinates. less.tree.functions.direction = function(x, y) { return new (less.tree.Anonymous)(Math.atan2(y.value, x.value) * (180 / Math.PI)); } flawless.initLess();

5. To include framework mixins in your actual CSS you only need .less files under css/flawless and sub-directories. See css/style_dev.less lines 1-47 for all essential framework setup you need in your CSS file. I.e. four actual code lines of include loader.less, setup_framework_path, setup_vertical_rhythm and setup_font_size. Other than the less.js file mentioned above these are the only files you need, everything else in the flawless repository can be discarded.

6. Include your own Less/Flawless-enabled CSS file like so:

   <link rel="stylesheet/less" type="text/css" href="css/style_dev.less" title="flawless_css" />

7. To get the compiled static CSS (recommended for production) you can use the below function, sorry requires jQuery but should be easy to modify this example for any JS library:

   function getCss() { var style = jQuery('#less\\:flawless_css')[0]; if (style.styleSheet) { /* IE */ return style.styleSheet.cssText; } else { return style.firstChild.nodeValue; } }

All this is setup for you if you use the provided flawless project layout but I understand it may be more convenient to integrate the above points manually into an existing project. This is an area of flawless we working to improve. Feedback is welcome.

If you have any more questions please ask!

Best regards, Isaac

[Zearin]

Ah, now I see what was confounding me! Flawless assumes the stylesheet/less usage for LESS.

Although I write in LESS, I always compile to CSS. (Yep—even for development.) I absolutely love LESS, but I after trying the stylesheet/less usage I found it distasteful. My reaction is due more to feeling than rationale, but I:

• Testing
  • Testing with CSS is “one step closer” to the final product. In other words, there’s one less step between development and release: (1) Testing site using LESS, (2) compiling CSS, (3) testing CSS, (3.5) remove stylesheet/less markup and scripts, and (4) release.
  • Using CSS, I can automatically rule out any Javascript-related issues during troubleshooting.
• Browsers have dedicated fine-tuning for CSS

Less.js has an “older brother” called SASS. SASS has a companion app called Compass, which automatically compiles SASS into CSS every time you edit the SASS file. I searched and found the equivalent companion app for LESS: Less.app.

With this, I get the benefits of the LESS syntax and the peace of mind that comes from knowing I’m still testing CSS. With the application running the background, each time I edit a *.less file, the app automatically compiles and drops the CSS in the appropriate directory.

I wonder if it would be feasible for a future version of Flawless to allow developers to use it without requiring either the stylesheet/less or compile-to-CSS flavors for working with Less?

[superstructor]

Thanks for your interesting feedback Zearin!

Indeed your rationale for preferring compiled CSS is sound and completely valid.

You can already use most of the Flawless framework with compile-to-CSS flavors. The only component that will fail is the grids as it requires the customized version of Less.js. Every other component as far as I am aware will work fine with stock Lessjs.

Dominik has made Flawless in a very modular fashion. So it should be possible just to import the components you need such as css/flawless/core/production/framework/type/install.less for typography only. You will need to take a look at the LESS CSS in those files to see what variables need to be defined or paths tweaked but other than that there are no significant dependencies. E.g. in type_externals.less you would probably need to define @setup_framework_path or change the path @setup_framework_path/core/production/framework/type/images/externals/externals.png so it can be found.

I havn't used Less.app before but I have a similar issue where I want to be able to use the lessc command line compiler, as well as the Express.js frameworks ability to compile LESS into CSS as it is serving the file to the client from the Node.js server.

Compatibility with all such modes of use is a primary goal for me for future versions of Flawless. Specifically issue #11 needs to be resolved.

It would also be great to be able to support other implementations of LESS such as lessphp. Leafo (author of lessphp) has been doing some great work recently to make that possible by resolving syntax differences: https://github.com/leafo/lessphp/issues/16

Best regards, Isaac

[Zearin]

Oh, the cruel irony! :) The most attractive part of Flawless—the one I was hoping to incorporate into my project—was Flawless’ grids.

Before I go further, I would like to thank you for these kind words:

Indeed your rationale for preferring compiled CSS is sound and completely valid.

I really appreciate that. Thanks. :) It’s always a nervous exercise bringing up my preferences for working with code, as programmers (in general) tend to have strong opinions on workflows, coding styles, etc. (Which is totally natural, and I'm okay with it for the most part. Just nervous when I open myself up to criticism. :)

…

I made a quick-and-dirty attempt at writing some grid mixins using Less.js and Less Framework 4 myself. The problem is…although I strongly believe in and tried my best to write human-friendly, modular code, I kept running into problems and got stuck in debugging hell. Sometimes LESS had compiling issues that were difficult to track down (despite error messages), and sometimes what I initially thought was a good way to modularize my code turned out to be problematic.

When I discovered Flawless, I thought to myself, “Look! Someone already had your idea—and published it as a project! You should totally use it instead. I bet he’s already solved all the problems you’re running into, and then some…”

Well, I was right! It’s an extremely well-crafted piece of work. Only…its №1 best feature, IMO, requires a stylesheet/less workflow. :(

…

Well, if I read you correctly, allowing developers to use the Flawless’ grids in their projects without requiring the custom JS is a goal for the project, right?

If I have that correct, then I’d like to ask…

• What are the added functions provided by Flawless’ custom Less.js?
• What parts of Flawless’ grid module require the custom Less.js?

[superstructor]

As with everything Compass/SASS, Nib/Stylus and Flawless/LESS all have corresponding strengths and weaknesses.

I like LESS because of its extreme efficiency and ability to run in browsers with zero dependency on server-side compilation. I like SASS because its mature with associated functionality easily available as Ruby gems and is already in use in some projects I use like Extjs. I like Stylus because of its elegance and mind-blowing power.

In general I have found the LESS code written by Dominik in Flawless to be of exceptional quality, especially the grid and typography modules have no equivalent in the other mentioned frameworks yet as far as I am aware. To be fair Nib was only released today, and has great promise as the Stylus language backing it is the most powerful by far.

Support for a wider range of workflows and a clearer project layout are areas of Flawless that I believe could be improved a lot. Some work has been done already towards this but I hit a wall with the one custom function that is quite essential for the grid component. I have come to the conclusion the only reasonable way to resolve the issue would be to have the function expressed in LESS instead of JavaScript, something the language is not capable of at this time.

Therefor recently I have been working on attempts to add in-language functions à la Stylus to LESS. When/if that is resolved enabling developers to use the entirety of Flawless without requiring the custom JS will be trivial and is most certainly a goal I am aiming for.

So why am I persisting with LESS ? As much as I have time for I will try to do what little I can to support all three major stylesheet language camps. I already personally use all of them for different use cases and projects. I believe for something as relatively recent as stylesheet languages diversity fosters innovation. Further I believe sometime in the future it should be possible to decouple the languages from the frameworks and interchange as you wish.

In answer to your two final questions there is a single function provided by Flawless custom Less.js in css/flawless/core/development/flawless-less-0.1.js that is used for column width calculations (including positioning):

    tree.functions.fl_columnswidth = function(count, width, columns) {
        if(width.unit == '%' || width.unit == 'em') {
            return new(tree.Dimension)(100 / columns.value * count.value, '%'); 
        } else {
            return new(tree.Dimension)((width.value / columns.value) * count.value, width.unit);    
        }
    }

Mixins such as .grid_span, .grid_shift, .grid_unshift, .grid_append and .grid_prepend require the above function.

Finally I agree programmers tend to have strong opinions. We can only move forward through positivity and open constructive debate. Unfortunately all too often that falls by the wayside in preference for protectionism and personal criticism. Opening up to criticism is a good thing because important ideas get out and dialogue ensures. Ignore those who are negativity critical and let them expose themselves as not helping technical progression.

[Zearin]

Short on time! Quicky response:

Interesting!

• Other frameworks. I haven’t heard of those other frameworks (apart from SASS). I’ll look around but I didn’t manage to find them with a quick Google. Could you possibly link me to them?
• Mindsets. I love your enthusiasm for advancing the web-dev/design ecosystem using all possible channels. :)
• Flawless JS function. Hmm, it looks like the key decision point in that function is whether the styles are using relative or absolute units for the grid. Is that correct? (If so, a non-JS variant could offer relative- and absolute-unit variants of the grid mixins. It’s inelegant and definitely something that would demand refinement in the future, but it would at least make it possible to use grid mixins sans-JS.)

[superstructor]

Re other frameworks https://github.com/visionmedia/nib is the Stylus one mentioned released yesterday. Its early days so not as feature complete as Compass or even Flawless but very promising esp with a person like TJ behind it.

Re your dual-mixin idea you are correct that might work. It is inelegant in that it requires the framework user to manually select a mixin based on units, but due to LESS lacking any conditionals or in-language function support the only better way is to hack LESS. I must say it is, in a way, also an elegant solution because it will work with current LESS versions and tooling, and will not break existing projects using Flawless.

[superstructor]

Your idea to use multiple mixins was cleaver Zearin but I found it required duplicating many user-visible mixins based on relative vs absolute units.

Instead I have fixed this with an awfully ugly piece of repeated inline JS that is localized to several "private" mixins that are not "user visible". I.e. users of the framework only invoke these mixins indirectly through other grid mixins.

It should not break anything for existing projects using Flawless.

This code works with the lessc command line compiler, Connect middleware and in all the browsers I tested. I expect it should also work with Less.app. I doubt it will work in lessphp due to the inline JS, but always open to improving this in the future. One step forward at a time ;-)