<p>KUTE.js is a very flexible animation engine that allows you to extend beyond measure. In this tutorial we'll dig into what's best to do to extend/customize the functionality of KUTE.js core, plugins and features.</p>
<h3>Basic Plugin Template</h3>
<p>The best way to extend, no matter what you would like to achieve is to use a specific closure, here's an example:</p>
<pre><codeclass="language-javascript">/* KUTE.js - The Light Tweening Engine
<p>In some cases, you may want to extend with additional tween control methods, so before you do that, make sure to check <code>Tween</code> function to get the internal references notation:</p>
<pre><codeclass="language-javascript">//add a reference to _tween function
<p>For some reasons these methods aren't included into the core/plugins by default, but let you decide what you need and how to customize the animation engine for your very specific need.</p>
<p>KUTE.js core engine and plugins cover what I consider to be most essential for animation, but you may have a different opinion. In case you may want to know how to animate properties that are not currently supported, stick to this guide and you'll master it real quick, it's very easy.</p>
<li><code>KUTE.prepareStart['propertyName']</code><kbdclass="bg-red">required</kbd> a function to get the current value of the property required for the <code>.to()</code> method;</li>
<li><code>KUTE.parseProperty['propertyName']</code><kbdclass="bg-red">required</kbd> a function to process the user value / current value to have it ready to tween;</li>
<li><code>window.dom['propertyName']</code><kbdclass="bg-red">required</kbd> a <strong>domUpdate</strong> function that will update the property value into the DOM;</li>
<li><code>KUTE.crossCheck['propertyName']</code><kbdclass="bg-green">optional</kbd> a function to help you set proper values when for instance startValues unit is different than endValues unit; so far this is used for CSS3/SVG transforms and SVG Morph, but it can be extended for many properties such as box-model properties or border-radius properties;</li>
<li>also <kbdclass="bg-green">optional</kbd> additional functions that will help with value processing.</li>
<p>So let's add support for <kbdclass="bg-olive">boxShadow</kbd>! It should be a medium difficulty guide most developers can follow and the purpose of this guide is to showcase how easy it actually is to extend KUTE.js. So grab the above template and let's break it down to pieces:</p>
<p>Now we have access to the KUTE object, prototypes and it's utility functions, let's write a <code>prepareStart</code> function that will read the current <code>boxShadow</code> value:</p>
<pre><codeclass="language-javascript">// for the .to() method, you need to prepareStart the boxShadow property
// which means you need to read the current computed value
var cssBoxShadow = getCurrentStyle(element,'boxShadow'); // where getCurrentStyle() is an accurate method to read the current property value
return /^none$|^initial$|^inherit$|^inset$/.test(cssBoxShadow) ? '0px 0px 0px 0px rgb(0,0,0)' : cssBoxShadow; // if the current value is not valid, use a default one
<p>Next we'll need to write a <code>processProperty</code> function that will prepare the property value and build an Object or Array of values ready to tween. This function also registers the <code>window.dom['boxShadow']</code> function into the KUTE object, and this way we avoid filling the main object with unnecessary functions, just to keep performance tight.</p>
<p>This plugin should be compatible with IE9+ and anything that supports <code>boxShadow</code> CSS property. As you can see it can handle pretty much anything you throw at it, but it requires at least 3 values: h-shadow, v-shadow, and color because Safari doesn't work without a color. Also this plugin won't be able to handle multiple instances of <code>boxShadow</code> for same element, because the lack of support on legacy browsers, also the color cannot be RGBA, but hey, it supports both outline and inset shadows and you can fork it anyway to your liking.</p>
<p>If you liked this tutorial, feel free to write your own, a great idea would be for <code>textShadow</code>, it's very similar to the above example plugin.</p>
<h3>Utility Methods</h3>
<ul>
<li><kbdclass="bg-lime">KUTE.selector(selector,multi)</kbd> is the selector utility that uses <code>getElementById</code> or <code>querySelector</code> when <code>multi</code> argument is <strong>null</strong> or <strong>false</strong>, BUT when <strong>true</strong>, <code>querySelectorAll</code> is used and returns a HTMLCollection object.</li>
<li><kbdclass="bg-lime">KUTE.property(propertyName)</kbd> is the <strong>autoPrefix</strong> function that returns the property with the right vendor prefix, but only if required; on legacy browsers that don't support the property, the function returns <strong>undefinedPropertyName</strong> and that would be an easy way to detect support for that property on most legacy browsers: <pre><codeclass="language-javascript">if (/undefined/.test(KUTE.property('propertyName')) ) { /* legacy browsers */ } else { /* modern browsers */ }</code></pre></li>
<li><kbdclass="bg-lime">KUTE.getPrefix()</kbd> returns a vendor preffix even if the browser supports a specific preffixed property or not.</li>
<li><kbdclass="bg-lime">KUTE.getCurrentStyle(element,property)</kbd> a hybrid <code>getComputedStyle</code> function to get the current value of the property required for the <code>.to()</code> method; it actually checks in <code>element.style</code>, <code>element.currentStyle</code> and <code>window.getComputedStyle(element,null)</code> to make sure it won't miss the property value;</li>
<li><kbdclass="bg-lime">KUTE.truD(value)</kbd> a function that accepts String and Number and returns a <code>{v: 150, u: 'px'}</code> object for any box model or a single numeric value based property and make it ready to tween. When a second parameter is set to <i>true</i> it will return an object with value and unit specific for rotation angles and skews.</li>
<li><kbdclass="bg-lime">KUTE.truC(color)</kbd> a function that returns an <code>{r: 150, g: 150, b: 0}</code> color object ready to tween; if the color value is a <ahref="http://www.w3schools.com/colors/colors_names.asp"target="_blank">web safe color</a>, the IE9+ browsers will be able to return the rgb object we need.</li>
<li><kbdclass="bg-lime">KUTE.htr(hex)</kbd> a function that accepts HEX formatted colors and returns an <code>{r: 150, g: 150, b: 0}</code> color object;</li>
2016-03-17 15:54:13 +01:00
<li><kbdclass="bg-lime">KUTE.rth(r,g,b)</kbd> a function that accepts numeric values for red, blue and green and returns a HEX format <code>#006699</code> color string.</li>
<li><kbdclass="bg-lime">window._number</kbd> is most essential interpolation tool when developing plugins for various properties not supported in the core.</li>
<li><kbdclass="bg-lime">window._unit</kbd> is used mainly for box model properties, text properties, and generally anything that's a string based valued. Like <code>width: 250px</code></li>
<li><kbdclass="bg-lime">window._color</kbd> is a very fast interpolation function for colors, as used in the above example.</li>
<li><kbdclass="bg-lime">window._coords</kbd> is SVG Plugin only, but you can have a look anytime when you're out of ideas.</li>
<liclass="hidden-xs"><atarget="_blank"href="https://www.facebook.com/sharer/sharer.php?u=http://thednp.github.io/kute.js/index.html"title="Share KUTE.js on Facebook"><spanclass="ion-social-facebook-outline icon"></span></a></li>
<liclass="hidden-xs"><atarget="_blank"href="https://twitter.com/home?status=Spread the word about @kute_js animation engine by @dnp_theme and download here http://thednp.github.io/kute.js/index.html"title="Share KUTE.js on Twitter"><spanclass="icon ion-social-twitter-outline"></span></a></li>
<liclass="hidden-xs"><atarget="_blank"href="https://plus.google.com/share?url=http://thednp.github.io/kute.js/index.html"title="Share KUTE.js on Google+"><spanclass="icon ion-social-googleplus-outline"></span></a></li>