css-lightbox 0.2.0 → 0.3.beta.0

data/README.mkdn

@@ -1,20 +1,25 @@
 Compass CSS Lightbox
 ====================
 
-CSS-only lightboxes that work in Everything But IE. Degrades gracefully, with
-no effect on IE at all, so you can set fallback styles there and/or bootstrap it
-with Javascript.
+These lightboxes work in all modern browsers with pure CSS. Additional support 
+for Internet Explorer and older browsers is made possible with a small amount 
+of JavaScript.
+
 
 Installation
 ============
 
 From the command line:
 
-    sudo gem install css-lightbox
+    (sudo) gem install css-lightbox
 
-Add to a project (rails: compass.config, other: config.rb):
+Add to a project:
 
+    // rails: compass.config, other: config.rb
     require 'css-lightbox'
+
+    // command line
+    compass install css-lightbox
     
 Or create a new project:
 
@@ -24,58 +29,163 @@ Or create a new project:
 Lightboxes
 ==========
 
-Your HTML:
-    
-    <div id="content">
-      <!-- all your normal page content, with links to lightboxes: -->
-      <a href="#about-us">a link to the about-us lightbox</a>
-    </div>
+The basic CSS-Lightbox works with a combination of internal links, z-index, 
+positioning and the css3 `:target` selector. Javascript bootstrapping simply
+interupts the link action, and applys active or inactive classes to the 
+boxes.
+
+Each lightbox contains three important elements:
 
-    <div id="lightboxes">
+    - Container
+        - Box
+        - Link to close the box (href="#")
+
+The container gives you extra positioning options, and acts as an optional 
+modal overlay for the page. You can write the HTML to your liking, but here is 
+one example:
+
+    <aside id="about-us" class="container">
+      <div class="box">
       
-      <!-- start lightbox -->
-      <aside id="about-us">
-        <div>
-          <!-- Your Lightbox Content -->
-          <a href="#" title="close the about lightbox">close</a>
-        </div>
-      </aside>
-      <!-- end lightbox... repeat as needed... -->
+        <!-- Your Lightbox Content -->
       
-    </div>
+        <a href="#" title="close the 'about' lightbox">close</a> <!-- Link to close -->
+      </div>
+    </aside>
+
+To open your lightbox, all you need is a link from somewhere else on the page
+that points at your lightbox:
 
-The important part is that you have:
+    <a href="#about-us">a link to the about-us lightbox</a>
 
-* elements with an ID linked from the content (the `aside` above)
-* an inner element in each that will act as the box itself (the `div` above)
-* a link to `#` from each box, to close it
+For a quick, pre-styled lightbox simply apply the `lightbox-with-default-styles`
+mixin to your lightbox containers. 
 
-Your Scss:
+    .container {
+      @include lightbox-with-default-styles;
+    }
+
+`lightbox-with-default-styles` takes three optional arguments, each with 
+defaults that you can override globaly for your project. 
+
+* The first argument is a (relative) selector for the box, and defaults 
+  to `"> div"`. 
+* The second is a fade-speed using CSS transitions. This defaults to `false` 
+  for no fade.
+* The third defines the JS fallback "active" selector that you are using.
+  It defaults to `.active`.
+
+Use them like so:
+
+    .container {
+      @include lightbox-with-default-styles('> div', '300ms', '.visible');
+    }
+
+
+Javascript Bootstrapping
+========================
+
+For Javascript bootstrapping in IE (using jQuery), simply link the included 
+lightbox.js and make any needed changes to the HTML-related variables that it 
+uses:
+
+    // "lightboxes" should point to the lightbox containers on your page
+    var lightboxes = $('#lightboxes aside');
+    
+    // "closeLinks" should point at the links used to close boxes
+    var closeLinks = $('#lightboxes a[title*="close"]');
     
-    // override these if you want
-    //
-    // // set to "true" for CSS3 transform fade-in/out
-    // // - bug in Chrome allows you to see fade-out on-load
-    // !lightbox-fade      ||= "false"
-    //
-    // // set to your box element
-    // // or false to set the box styles on your own (see below)
-    // !lightbox-box       ||= "> div"
-
-    // import lightboxes
-    @import "css-lightbox";
-
-    // make it happen (assuming lightbox.html markup)
-    #lightboxes aside {
-      @include css-lightbox;
-
-      // add styles for IE
-      // properties: values
-
-      // override box styles
-      // &:not(:target), &:target
-      //   > div
-      //     properties: values
+    // "showClass" is the class to use for active lightboxes
+    // "hideClass" is used for inactive lightboxes
+    var showClass = 'active'
+    var hideClass = 'hidden'
+
+The function is called simply, and the variables can be overridden on each call
+as needed:
 
+    $(document).ready(function(){
+      lightboxBootstrap(lightboxes, closeLinks, showClass, hideClass);
+    });
+
+
+Advanced Lightboxes
+===================
+
+But why would you use my styles when you can create your own? For simple 
+lightboxes without any styling at all, you can use the simple `lightbox` mixin:
+
+    .container {
+      @include lightbox;
     }
-    
+    
+I'll warn you, it's ugly until you add some style, but adding style isn't hard.
+By default `absolute` positioning is used on the containers to place them in
+the top left. You can override that by changing the positioning of your 
+container as you like. You'll find that each solution has advantages and 
+disadvantages.
+
+
+Available Defaults and Mixins
+=============================
+
+Defaults:
+
+    // Set this to a selector for the inner box.
+    $lightbox-box-to-style: "> div";
+
+    // Set the default fade time, or leave false for no fade
+    $lightbox-fade: false;
+
+    // Set the active selector to be used by the JS fallback
+    $lightbox-active: ".active";
+
+Mixins:
+
+* What makes a lightbox inactive
+
+    lightbox-hidden();
+
+* What makes a lightbox active
+
+    lightbox-active();
+
+* Initiallizes lightbox styles, and hides them to be revealed later
+  
+    lightbox-hide();
+
+* Shows a lightbox when it should be active
+
+  lightbox-show(
+    $active: $lightbox-active );
+
+* Set up your lightboxes by applying to each container
+
+    lightbox(
+      $active: $lightbox-active );
+
+* Set a lightbox to fade
+
+    lightbox-fade(
+      $fade-speed: $lightbox-fade or 500ms );
+
+* Apply default styles to the lightbox container
+
+    lightbox-default-container-styles(
+      $fade-speed: $lightbox-fade );
+  
+* Apply default styles to the box
+
+    lightbox-default-box-styles();
+
+* Apply default styles to the container and box in one fell swoop
+
+    lightbox-default-styles(
+      $style      : $lightbox-box-to-style, 
+      $fade-speed : $lightbox-fade );
+
+* Create and style a lightbox all at once
+
+    lightbox-with-default-styles(
+      $style      : $lightbox-box-to-style, 
+      $fade-speed : $lightbox-fade,
+      $active     : $lightbox-active );

data/stylesheets/_css-lightbox.scss

@@ -1,27 +1,22 @@
-// CSS-only Lightboxes
-// Plugin by Eric Meyer - http://www.oddbird.net/
-// Based on the work of Jenna Smith - http://growldesign.co.uk/
+// CSS-Lightboxes ------------------------------------------------------------
+// Plugin by Eric Meyer - http://eric.oddbird.net/
 
-// CSS-only lightboxes that work in Everything But IE. Degrades gracefully, with
-// no effect on IE at all, so you can set fallback styles there or bootstrap it
-// with Javascript. Probably both.
+// These lightboxes work in all modern standards-complient browsers with
+// pure CSS. Additional support for Internet Explorer and older browsers
+// is made possible with a small amount of JavaScript.
 
-// Set this to "true" to turn on CSS transitions
-// - causes Chrome to show fade-out on-load
-$lightbox-fade: false !default;
 
-// override to set your own box styles as follows:
-// FOR EXAMPLE:
-//
-// #lightboxes aside
-//   +css-lightbox
-//
-//   &:not(:target), &:target
-//     > div
-//       /* styles for your box element
+// Defaults ------------------------------------------------------------------
 
-//
-$lightbox-box: "> div" !default;
+// Every lightbox includes an outer container and an inner box
+// Set this to a selector for that box.
+$lightbox-box-to-style  : "> div"     !default;
 
-// import lightboxes
+// Set the default fade time, or leave false for no fade
+$lightbox-fade          : false       !default;
+
+// Set the active selector to be used by the JS fallback
+$lightbox-active        : ".active"   !default;
+
+// Import --------------------------------------------------------------------
 @import "css-lightbox/lightbox";

data/stylesheets/css-lightbox/_lightbox.scss

@@ -1,36 +1,106 @@
-// apply this to the container elements of each lightbox
-@mixin css-lightbox($fade: $lightbox-fade, $style: $lightbox-box) {
-  &:not(:target), &:target {
-    @include reset-box-model;
-    @include reset-font;
-    display: block;
-    z-index: -1;
-    position: fixed;
-    top: 0;
-    left: 0;
-    width: 100%;
-    @include transparent;
-    @if $fade {
-      @include transition(unquote("opacity, z-index")); 
-    }
-    @if $style {
-      #{$style} {
-        margin: 3em auto;
-        padding: 1.5em;
-        width: 32em;
-        border: 1em solid;
-        background: white;
-        text-align: left;
-        @include box-shadow(rgba(0, 0, 0, 0.9), 0, 0, 1em); 
-      } 
-    } 
-  }
-  
+//** CSS-Lightboxes **//
+
+// Lightbox Basics -----------------------------------------------------------
+
+// Sets a lightbox as hidden
+@mixin lightbox-hidden {
+  @include reset-box-model;
+  @include transparent;
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  display: block;
+  z-index: -1;
+}
+
+// Sets a lightbox as active
+@mixin lightbox-active {
+  @include opaque;
+  z-index: 999; 
+}
+
+// Initiallizes lightbox styles, and hides them to be revealed later
+@mixin lightbox-hide {
+  @include lightbox-hidden;
+}
+
+// Shows a lightbox when it should be active
+@mixin lightbox-show(
+  $active: $lightbox-active
+) {
   &:target {
-    z-index: 999;
-    @include opaque;
-    @if $fade {
-      @include transition(unquote("opacity, z-index")); 
+    @include lightbox-active; 
+  }
+  @if $active {
+    &#{$active} {
+      @include lightbox-active; 
     } 
   } 
 }
+
+// Set up your lightboxes by applying to each container
+@mixin lightbox(
+  $active: $lightbox-active
+) {
+  @include lightbox-hide;
+  @include lightbox-show($active); 
+}
+
+// Default Lightboxing ------------------------------------------------------
+
+// Set a lightbox to fade
+@mixin lightbox-fade(
+  $fade-speed: $lightbox-fade
+) {
+  @if not $fade-speed {
+    $fade-speed: 500ms;
+  }
+  @include transition(unquote("opacity, z-index"), $fade-speed); 
+}
+
+// Styles the lightbox container
+@mixin lightbox-default-container-styles(
+  $fade-speed: $lightbox-fade
+) {
+  background: rgba(#000,.125);
+  @if $fade-speed {
+    @include lightbox-fade($fade-speed);
+  }
+}
+
+// Styles the lightbox box
+@mixin lightbox-default-box-styles {
+  @include box-shadow(rgba(0, 0, 0, 0.9), 0, 0, 1em); 
+  position: relative;
+  margin: 3em auto;
+  padding: 1.5em;
+  width: 32em;
+  border: 1em solid;
+  background: white;
+  text-align: left;
+}
+
+// Style the container and box in one fell swoop
+@mixin lightbox-default-styles(
+  $style      : $lightbox-box-to-style, 
+  $fade-speed : $lightbox-fade
+) {
+  @include lightbox-default-container-styles($fade-speed);
+  @if $style {
+    #{$style} {
+      @include lightbox-default-box-styles; 
+    }
+  }
+}
+
+// Create and style a lightbox all at once
+@mixin lightbox-with-default-styles(
+  $style      : $lightbox-box-to-style, 
+  $fade-speed : $lightbox-fade,
+  $active     : $lightbox-active
+) {
+  @include lightbox($active);
+  @include lightbox-default-styles($style,$fade-speed);
+}

data/templates/project/_lightbox.scss

@@ -1,31 +1,12 @@
-// CSS LIGHTBOXES
-// CSS-only lightboxes that work in Everything But IE. Degrades gracefully, with
-// no effect on IE at all, so you can set fallback styles there or bootstrap it
-// with Javascript. Probably both.
+//** CSS-Lightboxes **//
 
-// override these if you want
-//
-// // set to "true" for CSS3 transform fade-in/out
-// // - bug in Chrome allows you to see fade-out on-load
-// !lightbox-fade      ||= "false"
-//
-// // set to your box element
-// // or false to set the box styles on your own (see below)
-// !lightbox-box       ||= "> div"
+// Import ------------------------------------------------------------------
 
-// import lightboxes
 @import "css-lightbox";
 
-// make it happen (assuming lightbox.html markup)
+/* Lightboxes --------------------------------------------------------------*/
+
+// Based on the lightbox.html template provided:
 #lightboxes aside {
-  @include css-lightbox;
-  
-  // add styles for IE
-  // properties: values
-  
-  // override box styles
-  // &:not(:target), &:target
-  //   > div
-  //     properties: values
-  
-}
+  @include lightbox-with-default-style("> div", "300ms");
+}

data/templates/project/lightbox.html

@@ -5,14 +5,23 @@
 
 <div id="lightboxes">
   
-  <!-- start lightbox -->
-  <!-- You need this structure, but can use whatever tags/classes/IDs you like-->
-  <aside id="about-us">
-    <div>
+  <!-- start lightbox 
+    You need this structure for each lightbox:
+
+      * Container
+        * Lightbox
+        * Link to close the lightbox
+      
+    But you can use whatever tags/classes/IDs you like
+  -->
+  
+  <aside id="about-us"><!-- Container -->
+    <div><!-- Lightbox -->
       <!-- Your Lightbox Content -->
-      <a href="#" title="close the about lightbox">close</a>
+      <a href="#" title="close the 'about' lightbox">close</a><!-- Link to close -->
     </div>
   </aside>
-  <!-- end lightbox... repeat as needed... -->
+  
+  <!-- repeat as needed -->
   
 </div>

data/templates/project/lightbox.js

@@ -0,0 +1,45 @@
+//** CSS-Lightboxes **//
+
+// Settings ------------------------------------------------------------------
+// Edit these settings to match your lightbox HTML code. These will act as
+// defaults, which you can override per application as needed:
+
+var lightboxes = $('#lightboxes aside');
+var closeLinks = $('#lightboxes a[title*="close"]');
+var showClass = 'active'
+var hideClass = 'hidden'
+
+// Function ------------------------------------------------------------------
+// Call this function to implement lightbox bootstrapping 
+// on any given lightboxes:
+
+function lightboxBootstrap(boxes, close, sClass, hClass) {
+
+    $(boxes).not('.' + sClass).addClass(hClass);
+
+    function lightboxClose(lightbox) {
+        $(lightbox).removeClass(sClass).addClass(hClass);
+    }
+
+    function lightboxOpen(lightbox) {
+        $(boxes).removeClass(sClass).addClass(hClass);
+        $(lightbox).removeClass(hClass).addClass(sClass);
+    }
+
+    boxes.each(function() {
+        $('a[href="#' + $(this).attr('id') + '"]').click(function() {
+            lightboxOpen($(this).attr('href'));
+            return false;
+        });
+    });
+
+    closeLinks.click(function() {
+        lightboxClose($(this).parents(boxes));
+        return false;
+    });
+}
+
+// Application ---------------------------------------------------------------
+$(document).ready(function(){
+  lightboxBootstrap(lightboxes, closeLinks, showClass, hideClass);
+});

data/templates/project/manifest.rb

@@ -1,16 +1,19 @@
 # Make sure you list all the project template files here in the manifest.
 stylesheet '_lightbox.scss', :media => 'screen, projection'
 html 'lightbox.html'
+javascript 'lightbox.js'
 
-description "css-only lightboxes"
+description "css-only lightboxes with optional javascript bootstrapping."
 
 help %Q{
-Installs some html and a stylesheet that you can use directly
-or refer to as an example.
+Installs some html, a stylesheet partial, and javascript bootstrapping that 
+you can use directly or refer to as an example.
 }
 
 welcome_message %Q{
-Please refer to the lightbox.html file to see how the markup should be structured.
-And to the lightbox stylesheet partial to see how to use the library and apply it to your markup.
+Please refer to the lightbox.html file to see how the markup should be 
+structured, the lightbox stylesheet partial to see how to use the library and 
+apply it to your markup, and the lightbox.js script to see how 
+bootstrapping works.
 }
 

metadata

@@ -1,12 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: css-lightbox
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  hash: 62196299
+  prerelease: 4
   segments: 
   - 0
-  - 2
+  - 3
+  - beta
   - 0
-  version: 0.2.0
+  version: 0.3.beta.0
 platform: ruby
 authors: 
 - Eric Meyer
@@ -14,22 +16,24 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-20 00:00:00 -06:00
+date: 2011-03-18 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: compass
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 62196237
         segments: 
         - 0
-        - 10
-        - 0
-        - rc3
-        version: 0.10.0.rc3
+        - 11
+        - beta
+        - 3
+        version: 0.11.beta.3
   type: :runtime
   version_requirements: *id001
 description: a css-only lightbox implementation for compass
@@ -42,11 +46,11 @@ extra_rdoc_files: []
 
 files: 
 - README.mkdn
-- lib/css-lightbox.rb
 - stylesheets/_css-lightbox.scss
 - stylesheets/css-lightbox/_lightbox.scss
 - templates/project/_lightbox.scss
 - templates/project/lightbox.html
+- templates/project/lightbox.js
 - templates/project/manifest.rb
 has_rdoc: true
 homepage: http://www.oddbird.net/
@@ -58,23 +62,29 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
+      hash: 25
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
 summary: a css-only lightbox implementation for compass

data/lib/css-lightbox.rb

@@ -1 +0,0 @@
-Compass::Frameworks.register("css-lightbox", :path => "#{File.dirname(__FILE__)}/..")