beast

provides a timer'd loop with hooks producing various animated effects

npm install beast
4 downloads in the last week
8 downloads in the last month
<html><head><meta content="text/html; charset=utf-8" http-equiv="Content-Type"><meta charset="utf-8"></head><body><h1>beast</h1>
<p><strong>(c)<a href="http://www.bumblehead.com" title="bumblehead">Bumblehead</a>, 2013</strong> <a href="#license">MIT-license</a></p>
<h3>Overview:</h3>
<p>provides a timer&#39;d loop with hooks producing various animated effects. it is optimised for simple animated effects on elements.</p>
<p>two things beast does to improve efficiency:</p>
<ol>
<li><strong>performs multiple animated trasitions with one loop</strong><ul>
<li>allows tight synchronization of animated effects</li>
<li>one timer for several effects is better than several timers</li>
</ul>
</li>
<li><strong>pre-processes to obtain loop values</strong><ul>
<li>values that modify target elements at each frame are generated first</li>
<li>values are generated when animation starts</li>
</ul>
</li>
</ol>
<p>animations are performed with plugins -4 plugins are provided by default:</p>
<ol>
<li><a href="#plugin-fade"><em>fade</em></a> an element&#39;s opacity</li>
<li><a href="#plugin-color"><em>color</em></a> transition an element to another color</li>
<li><a href="#plugin-move"><em>move</em></a> an element to an absolute position</li>
<li><a href="#plugin-shape"><em>shape</em></a> an element&#39;s height or width</li>
</ol>
<hr>
<h4><a id="install"></a>Install:</h4>
<p>beast may be downloaded directly or installed through <code>npm</code>.</p>
<ul>
<li><p><strong>npm</strong>   </p>
<pre><code class="lang-bash">$ npm install beast</code></pre>
</li>
<li><p><strong>Direct Download</strong></p>
<pre><code class="lang-bash">$ git clone https://github.com/iambumblehead/beast.git</code></pre>
</li>
</ul>
<p>Beast is meant to be npm-installed and deployed with <a href="https://github.com/iambumblehead/scroungejs" title="scroungejs">scroungejs</a>. Alternatively, this repository contains two ready-to-use files, <a href="http://github.com/iambumblehead/beast/raw/master/beast.min.js">beast.min.js</a> and <a href="http://github.com/iambumblehead/beast/raw/master/beast.unmin.js">beast.unmin.js</a>.</p>
<p>Run <code>npm start</code> to build a sample beast page and to see an advanced component constructed around beast as an example.</p>
<hr>
<h4><a id="test"></a>Test:</h4>
<p> to run tests, use <code>npm test</code> from a shell.</p>
<pre><code class="lang-bash"> $ npm test</code></pre>
<hr>
<h4><a id="get-started">GET STARTED:</h4>
<ul>
<li><p><strong>fade element out</strong></p>
<pre><code class="lang-javascript">beast({ 
  frames : 30 
}).fade({ 
  elem : elem, 
  opend : 0
}).init();</code></pre>
</li>
<li><p><strong>fade element in</strong></p>
<pre><code class="lang-javascript">beast({ 
  frames : 30 
}).fade({ 
  elem : elem, 
  opend : 100
}).init();</code></pre>
</li>
<li><p><strong>shape and fade element simultanaeously</strong></p>
<pre><code class="lang-javascript">beast({ 
  frames : 30 
}).fade({ 
  elem : elem, 
  opend : 0
}).shape({ 
  elem : elem, 
  whend : [300, 200]     
}).init();</code></pre>
</li>
<li><p><strong>shape, fade and color element simultanaeously</strong></p>
<pre><code class="lang-javascript">beast({ 
  frames : 30 
}).fade({ 
  elem : elem, 
  opend : 0
}).shape({ 
   elem : elem, 
  whend : [300, 200]     
}).color({ 
  elem : elem, 
  bgnColor : &#39;#fff&#39;,
  endColor : &#39;#259c14&#39;,
  bgnBackgroundColor : &#39;rgb(255, 0, 0)&#39;,
  endBackgroundColor : &#39;rgb(0, 0, 0)&#39;    
}).init();</code></pre>
</li>
<li><p><strong>shape two elements simultanaeously, control the timing</strong></p>
<pre><code class="lang-javascript">beast({ 
  frames : 30 
}).shape({ 
  elem : elem, 
  ease : &#39;end&#39;,
  whend : [300, 200]     
}).shape({ 
  elem : elem2, 
  ease : &#39;bgn&#39;,
  whend : [300, 200]     
}).init();</code></pre>
</li>
<li><p><strong>use classnames during animation</strong></p>
<p>An element receives a className during animation. The className is  &#39;st-:name-beast-animating&#39;, where :name becomes the name of the module. This element would get the className &#39;st-move-beast-animating&#39;.</p>
<pre><code class="lang-css">.st-move-beast-animating {
  position:absolute;
}</code></pre>
<pre><code class="lang-javascript">beast({ 
  frames : 30 
}).move({ 
  elem : elem, 
  ltend : [300, 200] 
}).init();</code></pre>
</li>
<li><p><strong>use classnames after animation</strong></p>
<p>plugins remove styles added to elem when animation finishes. Use <code>classNameEnd</code> to add a className to elem when the animation is complete. To prevent a plugin from removing styles, define <code>isclean</code> as <code>false</code>.</p>
<pre><code class="lang-css">.st-vis-hide {
  opacity:0;
}</code></pre>
<pre><code class="lang-javascript">beast({
  frames : 6
}).fade({
  classNameEnd : &#39;vis-hide&#39;,
  isclean : false,
  elem : elem, 
  endop : 0
}).init();</code></pre>
</li>
<li><p><strong>shape, then fade an element</strong></p>
<pre><code class="lang-javascript">beast({
  frames : 6
}).shape({
  elem : elem,
  whbgn : [2000, 2000],
  classNameFin : &#39;show-open&#39;
}).init(function () {
  that.fade = beast({
      frames : 6
  }).fade({
      classNameEnd : &#39;vis-hide&#39;,
      elem : elem, 
      endop : 0
  }).init();
});</code></pre>
</li>
<li><p><strong>subscribe functons to events</strong></p>
<p>The &#39;init&#39; method passes a function to one of beast object&#39;s hook methods. Access the hooks directly.</p>
<pre><code class="lang-javascript">beast({
  frames : 6
}).shape({
  elem : elem,
  whbgn : [0, 300]
}).onBegin(function () {
  console.log(&#39;animation is starting&#39;);
}).onKill(function () {
  console.log(&#39;animation was killed!&#39;);    
}).onComplete(function () {
  console.log(&#39;animation is complete&#39;);        
}).init();</code></pre>
</li>
<li><p><strong>kill initialized animation</strong></p>
<pre><code class="lang-javascript">var mybeast = beast({
  frames : 6000
}).shape({
  elem : elem,
  whbgn : [0, 300]
}).init();

setTimeout(function () { mybeast.kill(); }, 10000);</code></pre>
</li>
</ul>
<hr>
<h4><a id="more">More:</h4>
<ul>
<li><p><strong>beast</strong></p>
<p>Two properties are useful for the beast constructor.</p>
<pre><code class="lang-javascript">beast({
  frames : 300,
  fps : 30 // frames per second
})</code></pre>
</li>
<li><p><strong>beast.proto</strong></p>
<p>proto is not a method but a property defined on beast the namespace. the prototype is used by beast to construct objects it returns. proto may be accessed to redefine its default properties.</p>
</li>
<li><p><strong>beast.proto.onBegin( <em>fn</em> )</strong></p>
<p>add subscriber function to the onBegin event.</p>
</li>
<li><p><strong>beast.proto.onKill( <em>fn</em> )</strong></p>
<p>add subscriber function to the onKill event.</p>
</li>
<li><p><strong>beast.proto.onComplete( <em>fn</em> )</strong></p>
<p>add subscriber function to the onComplete event. </p>
</li>
<li><p><strong>beast.proto.init( <em>fnopt</em> )</strong></p>
<p>begins animation loop and publishes onBegin.</p>
</li>
<li><p><strong>beast.proto.kill()</strong> </p>
<p>stops animation loop and publishes onKill. </p>
</li>
<li><p><strong>beast.proto.reinit()</strong>  </p>
<p><code>kill</code> followed by <code>init</code>. Publishes onKill and onBegin.</p>
</li>
<li><p><strong>beast.proto.complete()</strong>  </p>
<p>stops animation loop and publishes onComplete.  </p>
</li>
<li><p><strong>beast.proto.st= <em>number</em></strong></p>
<p>property holds the state of a beast object <code>1</code> (<em>continue</em>), <code>2</code> (<em>sleep</em>), <code>3</code> (<em>killed</em>) or <code>4</code> (<em>completed</em>). definition of st affects the animation loop.</p>
</li>
</ul>
<hr>
<h4><a id="plugins">plugins</h4>
<ol>
<li><a href="#plugin-fade"><em>fade</em></a></li>
<li><a href="#plugin-color"><em>color</em></a></li>
<li><a href="#plugin-move"><em>move</em></a></li>
<li><a href="#plugin-shape"><em>shape</em></a></li>
</ol>
<p><em>ex</em></p>
<pre><code class="lang-javascript">beast({ frames : 30 }).fade({ 
    classNameEnd : &#39;vis-hide&#39;,
    isclean : false,
    elem : elem, 
    ease : &#39;bgn&#39;,
    opend : 0
}).init();</code></pre>
<p>Plugins provide an implementation and interface for animated actions. All provided plugins support these properties:</p>
<ul>
<li><p><strong>elem= <em>documentElement</em></strong> <em>default: null</em><br>target element for the animation</p>
</li>
<li><p><strong>ease= <em>str</em></strong> <em>default: &#39;end&#39;</em><br>slow the &#39;bgn&#39; or &#39;end&#39; of the animation</p>
</li>
<li><p><strong>isclean= <em>bool</em></strong> <em>default: true</em><br>remove elem.style definitions made by beast when animation is finished?</p>
</li>
<li><p><strong>classNameEnd= <em>str</em></strong> <em>default: &#39;&#39;</em><br>className added to elem at end of animation</p>
</li>
</ul>
<p>Plugins are optimised. functions and data are cached where possible. Little error-handling is provided -given elements must exist in the document, numeric properties must be numeric, etc.    </p>
<p>ClassNames are added/removed with <a href="https://github.com/iambumblehead/elemst" title="elemst">elemst</a>. As a result, all classNames added/removed with beast are prefixed with &#39;st-&#39;. For example, classNameEnd &#39;box-shut&#39; would be found in the className of an element as &#39;st-box-shut&#39;.</p>
<ul>
<li><p><a href="#plugin-fade" id="plugin-fade"><strong>plugin-fade</strong></a></p>
<p><em>ex</em></p>
<pre><code class="lang-javascript">beast({ frames : 30 }).fade({ 
    elem : elem, 
    ease : &#39;bgn&#39;,
    opend : 0
}).init();</code></pre>
<ul>
<li><strong>opend= <em>num</em></strong>, <em>default: &#39;100&#39;</em><br>opacity end value, a number 0-100</li>
</ul>
<p>Starting opacity value is obtained from the element with the cascade being relevant. opacity is handled with <a href="https://github.com/iambumblehead/domopacity" title="domopacity">domopacity</a>.</p>
<p><em>by default</em>, <code>isclean</code> removes &#39;opacity&#39; styles at end of animation, recommendation is to use <code>classNameEnd</code> to preserve position.</p>
</li>
<li><p><a href="#plugin-color" id="plugin-color"><strong>plugin-color</strong></a></p>
<p><em>ex</em></p>
<pre><code class="lang-javascript">beast({ frames : 30 }).color({ 
    elem : elem, 
    ease : &#39;bgn&#39; 
    bgnColor : &#39;#aaf&#39;,
    endColor : &#39;#aafaaf&#39;,
    endBackgroundColor : &#39;rgb(&quot;255&quot;, &quot;255&quot;, &quot;255&quot;)&#39;
}).init();</code></pre>
<ul>
<li><p><strong>bgnColor= <em>str</em></strong>, <em>default: elem current &#39;color&#39;</em><br>elem start animation &#39;color&#39;</p>
</li>
<li><p><strong>endColor= <em>str</em></strong>, <em>default: elem current &#39;color&#39;</em><br>elem end animation &#39;color&#39;   </p>
</li>
<li><p><strong>bgnBackgroundColor= <em>str</em></strong>, <em>default: elem current &#39;background-color&#39;</em><br>elem start animation &#39;backround-color&#39;   </p>
</li>
<li><p><strong>bgnBackgroundColor= <em>str</em></strong>, <em>default: elem current &#39;background-color&#39;</em><br>elem start animation &#39;backround-color&#39;      </p>
</li>
</ul>
<p>where color properties are undefined, existing color properties of elem are used. The &#39;a&#39; in rgba is ignored, only non-transparent colors are animated. colors may be defined with hex code or rgba format. plugin uses browser-provided <code>getComputedStyle</code> -you will need a polyfill for it in some browser environments, such as IE8.</p>
<p><em>by default</em>, <code>isclean</code> removes &#39;color&#39; and &#39;backgroundColor&#39; styles at end of animation, recommendation is to use <code>classNameEnd</code> to preserve position.</p>
</li>
<li><p><a href="#plugin-move" id="plugin-move"><strong>plugin-move</strong></a></p>
<p><em>ex</em></p>
<pre><code class="lang-javascript">beast({ frames : 30 }).move({ 
    elem : elem, 
    ltend : [300, 200] 
}).init();</code></pre>
<ul>
<li><p><strong>ltbgn= <em>numarr</em></strong>, <em>default: [elem current &#39;left&#39;, elem current &#39;top&#39;]</em><br>elem start animation [left, top]</p>
</li>
<li><p><strong>ltend= <em>numarr</em></strong>, <em>default: [elem current &#39;left&#39;, elem current &#39;top&#39;]</em><br>elem end animation [left, top]   </p>
</li>
</ul>
<p><em>by default</em>, <code>isclean</code> removes &#39;top&#39; and &#39;left&#39; styles at end of animation, recommendation is to use <code>classNameEnd</code> to preserve position.</p>
</li>
<li><p><a href="#plugin-shape" id="plugin-shape"><strong>plugin-shape</strong></a></p>
<p><em>ex</em></p>
<pre><code class="lang-javascript">beast({ frames : 30 }).shape({ 
    elem : elem, 
    ease : &#39;bgn&#39;,
    whend : [300, 200]         
}).init();</code></pre>
<ul>
<li><p><strong>whbgn= <em>numarr</em></strong>, <em>default: [elem current &#39;width&#39;, elem current &#39;height&#39;]</em><br>elem start animation [width, height]</p>
</li>
<li><p><strong>whend= <em>numarr</em></strong>, <em>default: [elem current &#39;width&#39;, elem current &#39;height&#39;]</em><br>elem end animation [width, height]</p>
</li>
</ul>
<p><em>by default</em>, <code>isclean</code> removes &#39;width&#39; and &#39;height&#39; styles at end of animation, recommendation is to use <code>classNameEnd</code> to preserve shape.</p>
</li>
</ul>
<hr>
<h4><a id="thought">Thought:</h4>
<p>Scripted animations, why? Not all browsers support styled animations. Not all animated effects are found with styled animations. Styled animations aren&#39;t flexible as scripted ones.</p>
<p>For tablets, phones and older IE browsers... in many use-cases beast performs with no observable &#39;choppiness&#39;. If choppiness is experienced try more conservative frames and fps values.</p>
<hr>
<h4><a id="license">License:</h4>
<p> <img src="http://github.com/iambumblehead/scroungejs/raw/master/img/hand.png" alt="scrounge"> </p>
<p>(The MIT License)</p>
<p>Copyright (c) 2013 <a href="http://www.bumblehead.com" title="bumblehead">Bumblehead</a> <a href="&#x6d;&#97;&#105;&#x6c;&#116;&#111;&#x3a;&#99;&#x68;&#x72;&#105;&#x73;&#64;&#x62;&#x75;&#x6d;&#x62;&#x6c;&#101;&#x68;&#101;&#x61;&#x64;&#46;&#99;&#x6f;&#109;">&#99;&#x68;&#x72;&#105;&#x73;&#64;&#x62;&#x75;&#x6d;&#x62;&#x6c;&#101;&#x68;&#101;&#x61;&#x64;&#46;&#99;&#x6f;&#109;</a></p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &#39;Software&#39;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED &#39;AS IS&#39;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
</body></html>
npm loves you