Merge pull request #6 from joshmcrty/drop-legacy-browser-support

Drop legacy browser support, use modern techniques for better performance

README.md

@@ -1,51 +1,83 @@
-Flurry
-======
+# Flurry
 
-Flurry is an easy-to-use animated snow plugin for jQuery inspired by jSnow. It uses bullet characters as snowflakes, with no dependencies on images or CSS files.
+Flurry is an easy-to-use animated snow plugin for jQuery. It takes advantage of CSS transforms, CSS transitions and requestAnimationFrame to provide smooth animation for modern browsers. It uses unicode characters as snowflakes, with no dependencies on images or CSS files. Polyfills are automatically provided for requestAnimationFrame and CSS transitions (falling back to setInterval and jQuery's .animate() feature respectively). Each flake is added to the DOM and then removed when it is finished animating, so please keep in mind the performance implications if you have too many flakes on the screen at once.
 
-Usage
------
+Tested in Chrome 54, Firefox 49, IE 11, and Edge 38.
+
+## Usage
 
 To use the default settings:
 
-    $( document ).ready( function() {
-        $('body').flurry();
-    });
+``` javascript
+$( document ).ready( function() {
+    $( 'body' ).flurry();
+});
+```
 
 To specify your own settings:
 
-    $( document ).ready( function() {
-        $().flurry({
-            height: 200,
-            speed: 2400,
-            wind: 100,
-            variance: 80
-        });
+``` javascript
+$( document ).ready( function() {
+    $( 'body' ).flurry({
+        character: "❄",
+        color: "white",
+        height: 400,
+        frequency: 80,
+        speed: 4000,
+        small: 8,
+        large: 48,
+        wind: 60,
+        windVariance: 20,
+        rotation: 0,
+        rotationVariance: 90
     });
+});
+```
+
+To destroy an instance after it's been created:
+
+``` javascript
+$('body').flurry('destroy');
+```
+
+## Options
+
+`character` (string) determines the character or html entity to be replicated as a snowflake. Default is `"❄"`. If you set this to a string of several unicode characters Flurry will randomize which flakes use each character (e.g. `"❄❅❆"`).
+
+`color` (string) determines the color of the snowflake. Default is `"white"`. You may use any valid [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
+
+`height` (number) controls how far down the page the flakes will fall in pixels. Default is `200` or the height of the `container`, whichever is smaller.
+
+`frequency` (number) controls how frequently new flakes are generated in milliseconds; lower creates more flakes at a time. Default is `100`.
+
+`speed` (number) controls how long it takes each flake to fall in milliseconds; lower is faster. Default is `3000`.
+
+`small` (number) determines the font size of the smallest flakes in pixels. Default is `8`.
+
+`large` (number) determines the font size of the largest flakes in pixels. Default is `28`.
 
-Options
--------
+`wind` (number) controls how far to the left each flake will drift in pixels. Default is `40`. Use a negative number to make flakes drift to the right.
 
-`height` controls how far down the page the flakes will fall in pixels. Default is `150` or the height of the container, whichever is smaller.
+`windVariance` (number) controls how much each flake will drift in pixels using the `wind` as a base; lower creates less random drift. Default is `20`.
 
-`density` controls how frequently new flakes are generated in milliseconds; lower is more dense. Default is `100`.
+`rotation` (number) controls how much each flake will rotate in degrees while it falls; lower is less rotation. Default is `90`.
 
-`speed` controls how fast the flakes fall; lower is faster. Default is `3000`.
+`rotationVariance` (number) controls how much each flake's `rotation` will be randomized by in degrees; lower creates less random rotation. Default is `180`.
 
-`small` determines the font size of the smallest flakes in pixels. Default is `12`.
+`startOpacity` (number) controls how much opacity the snowflakes have when they start to fall. Default is `1` which is fully opaque. You may use any valid [CSS opacity value](https://developer.mozilla.org/en-US/docs/Web/CSS/opacity).
 
-`large` determines the font size of the largest flakes in pixels. Default is `20`.
+`endOpacity` (number) controls how much opacity the snowflakes have when they finish falling and are removed from the DOM. Default is `0` which is fully transparent. You may use any valid [CSS opacity value](https://developer.mozilla.org/en-US/docs/Web/CSS/opacity).
 
-`wind` controls how far to the left the flakes will drift in pixels. Default is `40`. Use a negative number to make flakes drift to the right.
+`opacityEasing` (string) controls the easing function used to transition the flakes from their `startOpacity` to their `endOpacity`. Default is `"cubic-bezier(1,.3,.6,.74)"`. You may use any valid [CSS transition-timing-function value](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function).
 
-`variance` controls how much each flake will randomly drift in pixels using the `wind` as a base.
+`overflow` (string) sets the `overflow` CSS property for the selected element (e.g. the `body` element in the examples above). Default is `hidden`.
 
-`preventScroll` determines whether `overflow: hidden` is applied to the selected element to prevent horizontal scrolling. Default is `true`.
+`useRelative` (boolean) determines whether `position: relative` is applied to the selected element so flakes are generated within it (useful for generating flakes for only a specific part of the page). Default is `true` for all elements except the `body` element which is `false`.
 
-`useRelative` determines whether `position: relative` is applied to the selected element so flakes are generated within it (useful for generating flakes for a specific part of the page). Default is `true`.
+`zIndex` (number) sets the `z-index` CSS property for the snowflakes. Default is `9999`.
 
-`useTransitions` determines whether CSS transitions are used to animate the flakes instead of jQuery `animate()`. Checks for browser support and falls back to `.animate()` if necessary. Default is `true`.
+**Note:** Many of the options available are randomized slightly for each flake to make the overall effect appear more natural.
 
-`character` determines the character or html entity to be replicated as a snowflake. Default is `•`.
+## Methods
 
-`transparency` determines the alpha value of color of the character. Default is `1`.
+`destroy` Call `$('your-element').flurry('destroy');` to destroy the snow after you've start flurry on an element(s) on the page. With this you can easily build a toggle on/off capability for the snow.

flurry.jquery.json

@@ -6,7 +6,7 @@
         "snow",
         "animation"
     ],
-    "version": "0.4.0",
+    "version": "1.0.0",
     "author": {
         "name": "Josh McCarty",
         "email": "[email protected]",
@@ -30,6 +30,6 @@
     "docs": "https://github.com/joshmcrty/Flurry",
     "download": "https://github.com/joshmcrty/Flurry",
     "dependencies": {
-        "jquery": ">=1.0"
+        "jquery": ">=1.4.3"
     }
 }

index.html

@@ -1,40 +1,48 @@
 <html>
-    <head>
-        <style>
-            body{
-                background: darkblue;
-            }
-            main {
-              margin: 0 auto;
-              max-width: 80%;
-            }
-            .flurry-container {
-              min-height: 600px;
-            }
-        </style>
-        <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
-        <script src="jquery.flurry.js"></script>
-        <script>
-            $( document ).ready( function() {
-                $('body').flurry({
-                    height: 500,
-                    speed: 3000,
-                    wind: 400,
-                    variance: 100,
-                    large: 75,
-                    small: 25,
-                    density: 100,
-                    transparency: 0.4
-                });
-            });
-        </script>
-    </head>
-    <body>
-        <main>
-          <h1>Flurry Example</h1>
-          <div class="flurry-container">
-            <p>Let it snow!</p>
-          </div>
-        </main>
-    </body>
+  <head>
+    <meta charset="utf-8">
+    <title>Flurry Example</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <style>
+      body{
+        background: darkblue;
+        color: white;
+        font-family: sans-serif;
+      }
+      main {
+        margin: 0 auto;
+        max-width: 80%;
+      }
+      .flurry-container {
+        min-height: 600px;
+      }
+    </style>
+    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="jquery.flurry.js"></script>
+    <script>
+      $( document ).ready( function() {
+
+        $('body').flurry();
+
+        $('.toggle-snow').on('click', function(event) {
+
+          event.preventDefault();
+
+          try {
+            $('body').flurry('destroy');
+          }
+          catch(err) {
+            $('body').flurry();
+          }
+        });
+      });
+    </script>
+  </head>
+  <body>
+    <main>
+      <h1>Flurry Example</h1>
+      <p>Let it snow!</p>
+      <p><button class="toggle-snow">Toggle Snow</button></p>
+    </main>
+  </body>
 </html>