#####    ###     ##  ### ########              ###     ##  ###    ###TM
   #######  #######   ####### ########            #######   #######  #######
  ###      ###   ###  ###         ###            ###   ###  ###     ###   ##
  ###      ###   ###  ##       ###               ###   ###  ##      ###   ##
   #######  #######   ##      ########    ###     #######   ##       #######
     #####    ###     ##      ########    ###       ###     ##           ###
                                                                      #####

    CSS Modules..

    /inc/css/modules/

    These are style "modules", CSS programming that gets re-used in different
    scripts. Most of the style sheets the browser sees are just a collection of
    modules, pulled together and spat out in one minified, gzipped gob of data.

    To use a module, simply include it in your CSS, like so..

    @@my-module@@

    That's it!

    Modules allows us to keep single style sheet size unconfusingly small and
    enables us to make all-at-once changes to global elements with trivial ease.

    Having everything in logical modules makes editing and crucially, finding
    which style to edit, a breeze. This cuts down on potential differences
    occurring between elements on-site, and keeps everything uniform, as well as
    other benefits, not least of which the ability to leave loads of notes and
    experimental styles lying around without fear of them hitting a user's page.
    Oh yes, gzipped, minified output is standard!

    The corresponding module for the above example include would be..

        css/modules/my-module.css

    You don't need to use the ".css" part of the file name in your include
    statement, but it doesn't break anything if you do.

    Just like the main sheets, these modules can contain dynamic %%tokens%%.
    More information about tokens here: http://corz.org/blog/about-blog#notes

    Also, like the main style sheets, these are parsed by the php engine, so
    everything must go inside valid <?php ?> tags.

    Most of the main style sheets (that are seen by browsers) are simply scripts
    that call these modules, sometimes many modules.

    You can build a set of page styles entirely with modules, then spit out a
    sheet specific to a particular page or better yet, section in one single
    HTTP request. Highly nifty.

    Here is a COMPLETE style sheet with everything you need for a regular page..

        <?php include 'css-init.php';
        echo <<<CSS

        @@base-styles@@

        CSS;
        output_CSS(); ?>


    Done!

        Note: modules can contain /other/ modules! Oh Yes! Though note, no
        module can be imported more than once into a single style sheet, which
        would be pointless anyway.

        If you want to import blocks of repeating CSS code (i.e. vendor-specific
        code), use "snippets" (more details in the snippets folder).


    @media query blocks..

        You can place your modules inside @media query blocks, as well as put
        @media query blocks inside the modules themselves, and so on. Just go
        with the flow!



    Sending %%tokens%%:

        As well as plain values, you can send %%tokens%%!

        This enables you to do funky stuff like..

            .foot-gradient {
                height: 2rem;
            @@gradient(start=%%bg_color%%,end=%%footer_bg_color%%)@@
            }

        And Wham! An instant top-down gradient, starting at your current
        background color, and ending at your curent footer background color.
        The /generated/ code would look something like this (at least before
        minification)..

.foot-gradient {
    height: 2rem;
    /* simple top-down gradient - send it start and end values) */
    background-image: -moz-linear-gradient(top, #fff7d1 0%, #403826 100%);
    background-image: -ms-linear-gradient(top, #fff7d1 0%, #403826 100%);
    background-image: -o-linear-gradient(top, #fff7d1 0%, #403826 100%);
    background-image: -webkit-linear-gradient(top, #fff7d1 0%, #403826 100%);
    background-image: linear-gradient(to bottom, #fff7d1 0%, #403826 100%);
}


        Again, insanely powerful stuff, shaving oodles off CSS coding and
        debugging time.



    Sending Values:

        You can send values with your module and snippet statements, which can
        then be accessed in your style sheets as regular %%tokens%%. For
        example..

            .some-button {
                @@semi-opaque(o=50)@@
            }

        This imports the "semi-opaque" snippet and sets the values of the "o"
        token to '50'..

            opacity: 0.%%o%%;    >>    opacity: 0.50;

        You can send multiple values, separating them with commas, like so..

            .some-div {
                @@rotate(angle=-90,float=none)@@
            }

        And so long as there are %%angle%% and %%float%% tokens waiting to be
        transformed inside the snippet/module, it all works like magic. Which,
        indeed it is.

        You can override any already-set values this way, too. So long as the
        value exists in the module/snippet as a %%token%%, it will be set to the
        new value, even if you send a blank value.

        This is some incredibly useful functionality, but also a big fat gotcha!
        for the unaware.


        With this facility in place, you can, of course, create whatever
        *value* variables you need on-the-fly, but perhaps not so obviously,
        *any* part of your CSS can be tokenized, for example, if you had a
        snippet (e.g. "css/snippets/throbber.css") like this..

            .throbber, .throbber h1, %%my_div%% {
                <-- a crap-load of CSS here -->
            }

        You could then do something like this in your style sheet..

            @@throbber(my_div=#MyThrobbingDiv)@@


        A bit back-to-front but quite handy!



    Simple Math (okay, Arithmetic!):

        That's right! Continuing with the same (braces) convention we use for
        sending values, we can also do some basic arithmetic, e.g..

            top: %%top_space(+2)%%;

        This will set the value to the current value of %%top_space%%, plus two.

        You can add (+), subtract (-), multiply (*) and divide (/).

        For example, if %%top_space%% is set to "4rem" (in your scheme / prefs /
        etc), the final value will be "6rem". Obvious, right?

        The original unit setting is always used for the calculation. If the
        initial value was "10px" and you did (+2), you get "12px".

        You can send decimal fractions. "4rem" (+1.5) would give us "5.5rem",
        "10rem" (-.25) would give us "9.75rem", "5rem" (*.25) gives us
        "1.25rem", "6rem" (/.5) gives us "12rem", and so on.

        Finally, you can also send percentage values. For example..

            top: %%top_space(+25%)%%;

        If %%top_space%% was originally "4rem", it would now be set to 4rem+25%,
        which would output "top: 5rem;".

        Results are rounded to three decimal places, e.g. "3.142rem".

        Aside from this, no limit is placed on the numbers sent, or the results
        obtained. Go nuts!

        The usefulness of all this should be immediately apparent! Many sizes
        have a "base", from which other sizes are calculated. Unfortunately, 90%
        in CSS isn't always what one expects. Using simple math is an extremely
        reliable way to set, for example, font size across browsers.

        It means you can avoid font-size % in CSS, instead using %%size(*1.25)%%
        (125%, absolutely) so that styles can go inside styles without cascading
        the sizes.

        It's also highly useful for setting sizes for @media query adjusted
        content. A %%top_space%% that changes depending on the current menu
        style is one obvious use. Or a section that has a sub-menu, etc..

        Set relative sizes with absolute certainty! *grin*



    Gotchas!..

        If you comment out a module command..

            /*@@my-module@@*/

        ..it will probably not work as you expect, but additionally putting a
        space between the @ symbols will do the job..

            /*@ @my-module@ @*/

    Tips:

        If your text editor/IDE allows you to add more comment types, you can
        use %% and @@ as comment start/end markers and color up the tokens and
        module include lines all pretty for even-more-easy finding and editing.


    Weeeh! CSS is fun again!

    En-Joy!!

    ;o)


    (c) 2003->tomorrow! cor + corz.org ;o)