= Styles 'n Scripts Extension

The Styles 'n Scripts extension was an extension requested by John Long
as a means of separating javascripts & stylesheets from other site content
stored in pages.



CONTENTS
========
In this README you'll find:
  1. Usage
  2. Why Change Things?
  3. Installation
  4. To Do



USAGE
=====
Using this extension is rather painless.  If you can use the rest of Radiant,
these additions will seem obvious.  There are a couple of things to take note
of, however.

  * The CSS and JS tabs are where you create, edit, and delete stylesheets and
    javascripts.  But you need Administrator or Developer permissions to see
    these tabs.
    
  * If you want to reference or otherwise use your script or stylesheet in one
    of your pages, there are <r:stylesheet> and <r:javascript> tags.  These tags
    can be used to inject your CSS or JS code into the page or just render a
    link to the file itself. (See the 'available tags' link on the Page edit
    form to learn more about options for these tags).
    
  * If you want to cut down on server requests for CSS and JS files, you can
    also create a master CSS or JS file for each and use the appropriate 
    <r:stylesheet> or <r:javascript> tags to incorporate other files of the same
    type.  Viola, now Radiant offers asset packaging just like Rails!
    

That's it.  Everything else is either too obvious to bother with here or
automagical and too top secret to disclose.



WHY CHANGE THINGS?
==================
As John sees it, the pages tab is for storing the main content. (Think of the
tree view as the list of available destinations for your users). Sure, they need
stylesheets and javascripts but those are supporting files (much like images).
They augment your pages.

There are a number of interesting benefits gained by this approach:

  * CSS and JS files now get designer-level permissions -- not user-level.

  * These files are now cached differently.  Rather than the 5-minute expiration
    on pages, these files can now report to the browser the true LAST-MODIFIED
    date so we don't have to serve up these files constantly.  We can put the
    user's browser caching to work.

  * This properly separates the concerns of Pages and Text Assets. (I mean, do 
    javascripts really need a layout or stylesheets a breadcrumb?).  Easier to 
    understand for the user and easier to develop for.
    
  * Allows extensions to deal better interact with pages.  For example, a search
    extension can now safely parse all the pages without terms like "background"
    yielding all your stylesheets.

  * Declutter the pages tree view so that it truly only shows what your clients
    see -- the things they'd aim their browser at (see John's point above).

  * This opens the door for validation, minification and obfuscation of scripts
    and stylesheets (I'm thinking that these belong in a separate extension but
    they're *much* easier to build now that CSS and JS are a distinct type of
    object).

  * This lays a conceptual foundation for other, non-text assets like images,
    flash, and the like.



INSTALLATION
============
1.  Copy this extension into your existing Radiant project (place it at:
      [your project location]/vendor/extensions/styles_n_scripts

2.  Incorporate the database migrations into your existing database using:
      rake db:migrate:extensions

    Or, if you prefer to be more specific to this extension:
      rake radiant:extensions:styles_n_scripts:migrate

3.  Copy the needed images into Radiant's /public/images directory using:
      rake radiant:extensions:styles_n_scripts:update

4.  (Optional) Configure your stylesheet and javascript directories.  By default
    The Styles 'n Scripts serves your stylesheets and javascripts out of the
    /css and /js folders respectively.  You can change these locations via the
    custom_settings.rb file if you wish (just make sure you aren't competing
    with Radiant's /public files or your own pages.

5.  (Optional) Configure your stylesheet and javascript content (MIME) types.
    Again there are defaults but you can change them via the custom_settings.rb
    file.



TO-DO
=====
Create a way for users to upload stylesheets and javascripts (maybe even upload 
many via a zipped file) and unpack them into the db.

Improve caching.  I'd like to see a scenario where files are cached-on-save.
Rails page caching might be a great choice.  (Maintaining the cache -- sweepers,
etc. -- wouldn't be all that hard for these items.).

Add file minification to strip out comments and whitespace (and maybe obfuscate)
javascripts and stylesheets. (I already have this started).

Figure out what the core team needs to get this puppy baked into Radiant!