scramblejs
v1.0.5
Published
text animation library for browsers
Readme
A funky text animation library. Unleash your inner nerd!
Demo
Usage
Scramble.select('h1')
.wait(1000)
.setText('this is scramble')
.descramble();Installation
using npm
npm install scramblejsmanually
git clone https://github.com/turtleDev/scramblejs
cd scramblejs
npm install
npm run buildscramblejs can be used via script tags, CommonJS require or AMD define.
/* browser */
<script src="/path/to/scramble.js"></script>
<script>
Scramble.select('h1');
</script>
/* CommonJS systems (webpack) */
var Scramble = require('scramblejs');
/* AMD */
define(['scramblejs'], function(scramble) {});Docs
Tutorial
Ready to blow some brains? lets start off with a basic demo
<!doctype html>
<head>
<script src="scramble.js"></script>
</head>
<body>
<h1></h1>
</body>
<script>
Scramble.select('h1')
.setText('hello, world!')
.descramble();
</script>So here's what happening:
Scramble.selectselects a dom element identified by the dom selector 'h1'setTextupdates the internal buffer to it's argument but doesn't actually apply any animationdescrambleis where the magic happens. To put it in simple (yet confusing) terms, it applies and removes scramble animation. The resultant element contains the text that was perviously passed tosetText
The basic workflow in scramble revoles around selecting an element, and then sequencing a series of command that animate that element. Don't worry if you're not familar with [method-chaining][mc], you'll get used to it.
It is also possible to sequence animation for multiple elements. behold:
<!doctype html>
<head>
<script src="scramble.js"></script>
</head>
<body>
<h1 class="first"></h1>
<h1 class="second"></h1>
</body>
<script>
Scramble.select('h1.first')
.setText('I am the first!')
.descramble()
.select('h1.second')
.setText('and I am the second!')
.descramble();
</script>That's pretty much (not) it! Take a look at the examples to get a feel of what else you can do with scramble.
API Docs
Scramble.select(el:string|object) -> Grinder
self-explainatory. el must either be a string, in which case it should be a DOM Selector, or a native Element object.
returns an instance of Grinder
Scramble.setConfigGlobal(config:config)
This is the module level animation parameters. see Grinder#setConfig.
Scramble.align.*
Alignment utilites used by Grinder#setText
class Grinder()
Grinder object encapsulates the selected DOM element, along with it's corresponding config. Every grinder method returns a new Grinder object (except .then and .catch). A Grinder object is returned by Scramble.select, and you will never directly instantiate this class.
Grinder#createEmpty(length:number, padding:string)
Create a new empty buffer. Note that it clears out any previous content. The created buffer is filled with padding chars.
by default, by .
Grinder#setText(text:string, align:function)
Set the internal buffer to text. align function is used to align the contents of the text within the buffer (in case the buffer is larger than the text). By default, the text is left aligned, but you can also have it right, or center aligned.
Scramble.select('h1')
.setText('this will be left aligned', Scramble.align.left) // the second parameter can be omitted here
.setText('right-align', Scramble.align.right)
.setText('center', Scramble.align.center)In case the buffer is too small, it is expanded in order to make space for the text. However, it will not be shrinked in case text-length is less than the
buffer length. To resize a buffer, use Grinder#createEmpty
Grinder#setConfig(config:object)
This method lets you configure the animation parameters for the currently selected item.
config must be an object with the following properties:
- delay - inital delay(in ms)
- interval - time between character switches(in ms)
- flip - the number of character switches
each field can either have a number as a value, or an object containing a min and max property.
for example:
/**
* this is just for demonstration purposes
* configurations are not `queued`.
*/
Scramble.select('h1')
.setConfig({delay: 20});
.setConfig({flip: {min: 5, max: 10}});
.setConfig({delay: 1, flip: 1, interval: 1});Grinder#enscramble()
applies the scramble animation. text is mangled with random characters and becomes un-legible.
Grinder#descramble()
applies the scramble animation, but the end text is the same as the internal buffer set by setText.
Grinder#select(el:string|object)
Analogous to Scramble.select, this method lets you select another element in a sequence chain.
Grinder#wait(delay:number)
lets you delay the next action. delay is the wait period in ms.
Grinder#then(successHandler:function, errorHandler:function)
This method behaves exactly like Promise.prototype.then. This method lets you schedule other tasks at the end of an animation sequence. The resolved value is the DOM element that was being animated.
Grinder#catch(errorHandler:function)
equivalent to Grinder#then(null, errorHandler)
Tip
use monospace fonts for the best effect
License
MIT
Dependencies
Scramblejs has no runtime dependencies, however, it does require the Promise API. If you're targetting browsers that don't support Promises, I recommed you use a polyfill like [bluebird][bb].
Credits
The entities.json was taken from whatwg's HTML specification. from here to be exact.
[mc]: https://en.wikipedia.org/wiki/Method_chaining
[bb]: https://github.com/petkaantonov/bluebird