title: Space.js
url: http://www.slashie.org/articles/space.js/
hash_url: 6545585160a15ef6eef8b7e9319a5cf3

<p>Creating content on the Internet is not just about the contents. It’s about reaching out with a message, telling a story, trying to translate an emotion into bits and communicating them to the user, efficiently.</p>
<p>I wanted the end user to feel a stronger connection to my content. I feel that the <em>medium</em> is often overlooked, sure - the message is the <em>core</em>, but what’s wrong with silver platters? I love mediums that help narrate the experience. The way an old mechanical Polaroid cameras printed picture feels in your hands, or perhaps the note produced from the purposeful humming sounds of a typewriter. Imagine holding an old hardcover book, it doesn’t present you information, it tells you its story, it tells you it’s secrets. Medium is important.</p>
<p><img src="http://www.slashie.org/articles/space.js/img/camera1.jpg" alt="Both"/></p>
<p>We generally use web pages as our canvases and paint content on the x– and y-axises. This is our tangible abstraction of reality. Here we are going to explore what happens when we introduce z-axis to content presentation. Instead of stripping down reality to a plane, we are going to simplify it, keeping our three physical dimensions but only their minimal essence.</p>
<p><img src="http://www.slashie.org/articles/space.js/img/axisinformation.png" alt=""/></p>
<p>For our messages to communicate across <strong>efficiently</strong>, <em>we need to create a powerful connection between the user and our medium</em>. Today we are going to explore a new way of presenting stories on the web. And for this I’ve created an open-source and free to use JavaScript library i call <em>space.js</em>. It’s basically parallax technologies used for narration. Think of it as a bicycle for content presentation.</p>
<p><img src="http://www.slashie.org/articles/space.js/img/spacejs.png" alt=""/></p>
<p>Now would be a great time to head over to <a href="http://www.slashie.org/space.js"><strong>the demos</strong></a> to try it out for yourself!</p>
<p><a href="http://www.slashie.org/space.js"><img src="http://www.slashie.org/articles/space.js/img/demosthumb.jpg" alt=""/></a></p>
<h2 id="using-the-library">Using the library</h2>
<p>The library is <span class="caps">HTML</span>-driven, which means that you don’t need to write a single line of JavaScript to use it on your site and still have a lot of flexibility!</p>
<p>The core of the library is to divide our <span class="caps">HTML</span> into frames, or <em>space-frames</em> as we call them her (to not conflict the common class name “frame”).</p>
<h3 id="creating-a-frame">Creating a frame</h3>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span>&gt;</span>[contents]<span class="tag">&lt;/<span class="title">div</span>&gt;</span>
</code></pre>
<p>I would also <strong>strongly</strong> recommend using an inner-frame inside the space-frame, which provides some helpful <span class="caps">CSS</span> to make things centered both vertically and horizontally inside the frame.</p>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span>&gt;</span>
    <span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-inner-frame"</span>&gt;</span>
        [contents]
    <span class="tag">&lt;/<span class="title">section</span>&gt;</span>
<span class="tag">&lt;/<span class="title">div</span>&gt;</span>
</code></pre>
<h3 id="customize-duration">Customize Duration</h3>
<p>If we want we can provide a custom duration for our frames with the data-duration attribute, which multiplies the default duration of the transition.</p>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span> <span class="attribute">data-duration</span>=<span class="value">"1.4"</span>&gt;</span>...<span class="tag">&lt;/<span class="title">section</span>&gt;</span>
<span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span> <span class="attribute">data-duration</span>=<span class="value">"0.6"</span>&gt;</span>...<span class="tag">&lt;/<span class="title">section</span>&gt;</span>
</code></pre>
<h3 id="customize-transition">Customize transition</h3>
<p>Space.js has a default default transition - which is to enter by fading in and exit by scaling up and fading out. We can also provide a custom transition override to the library from predefined transitions. (We can also create our own transitions from scratch, but we’ll get to that later.)</p>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span> <span class="attribute">data-transition</span>=<span class="value">"rotate360"</span>&gt;</span>...<span class="tag">&lt;/<span class="title">section</span>&gt;</span>
</code></pre>
<p>Multiple values are supported!</p>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span> <span class="attribute">data-transition</span>=<span class="value">"rotate360 fadeOut slideInLeft"</span>&gt;</span>...<span class="tag">&lt;/<span class="title">section</span>&gt;</span>
</code></pre>
<h3 id="custom-entry-and-exit">Custom entry and exit</h3>
<p>If we really want to get into detail, we can provide how we wish the frame to enter (first half of the frame duration) and exit (second half).</p>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span> <span class="attribute">data-enter</span>=<span class="value">"fadeIn"</span> <span class="attribute">data-exit</span>=<span class="value">"fadeOut zoomOut"</span>&gt;</span>...<span class="tag">&lt;/<span class="title">section</span>&gt;</span>
</code></pre>
<h2 id="what-a-complete-frame-could-look-like">What a complete frame could look like</h2>
<pre><code class="lang-html"><span class="tag">&lt;<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"space-frame"</span> <span class="attribute">data-enter</span>=<span class="value">"fadeIn"</span> <span class="attribute">data-exit</span>=<span class="value">"zoomOut fadeOut"</span> <span class="attribute">data-duration</span>=<span class="value">"1.3"</span>&gt;</span>
    <span class="tag">&lt;<span class="title">section</span> <span class="attribute">class</span>=<span class="value">"space-inner-frame"</span>&gt;</span>
        <span class="tag">&lt;<span class="title">div</span> <span class="attribute">style</span>=<span class="value">"background-image:url(img/splash.png); padding:150px 200px;"</span> <span class="attribute">class</span>=<span class="value">"bg"</span>&gt;</span>
            <span class="tag">&lt;<span class="title">section</span>&gt;</span>
                <span class="tag">&lt;<span class="title">p</span>&gt;</span>Demo 1<span class="tag">&lt;/<span class="title">p</span>&gt;</span>
                <span class="tag">&lt;<span class="title">h1</span>&gt;</span>The Gallery<span class="tag">&lt;/<span class="title">h1</span>&gt;</span>
            <span class="tag">&lt;/<span class="title">section</span>&gt;</span>
        <span class="tag">&lt;/<span class="title">div</span>&gt;</span>
    <span class="tag">&lt;/<span class="title">section</span>&gt;</span>
<span class="tag">&lt;/<span class="title">div</span>&gt;</span>
</code></pre>
<p><a href="https://github.com/gopatrik/space.js">Full <span class="caps">API</span> on GitHub</a></p>
<h2 id="behind-the-scenes-">Behind the scenes.</h2>
<p>The process of the library is pretty straight forward. When we have divided our <span class="caps">HTML</span> into frames, we assume each frame to initially cover the height and width of the window, which is equivalent to <code>data-duration="1"</code>. Each frame is set to have the same scroll-duration as it would have if we would’ve normally scrolled past it. So we measure how high the view port of the users browser window is let’s say 800px, then we count the number of frames there are in the <span class="caps">HTML</span>, let’s say 20. To simulate a proper scrolling mechanism the body-height is set to #frames <em> their height, in this case 800px </em> 20 frames = 16000px.</p>
<p>We then hide all frames. Because of superior performance advantages when animating a <code>position: fixed;</code> object, we need to keep them fixed, which means we have to hide all frames that should not be showing at a particular height in the document.</p>
<p>The function scrollTop() tells us how far we are from the top of the page. We can use it to check what frame should be active and at what stage that frames transition is in. Instead of scrolling past an element we change its <em><span class="caps">CSS</span></em> according to when it <em>should be visible</em>, calculated from the value we get from scrollTop().</p>
<p>We then create a listener for the for the scroll event on the document using the <code>ScrollController</code> provided in the library. Which accepts a method as an argument, and when we receive the scroll event it keeps running that method. In this case the <em>method</em> is our animate(), which animates our frames. The ScrollController will then run the animation method at an interval of something around 60 fps while we are scrolling to not overload client. It’s also of <strong>most importance</strong> that we use <code>requestAnimationFrame(...)</code> to make sure our renderings are synced up with the clients browser, otherwise we might lose a lot of performance, which is of essence here.</p>
<p>The <code>animate()</code> method does <strong>two things</strong>.</p>
<ol>
<li>Calculate and set the <em>current frame</em> through a simple comparison of how far we have scrolled (<code>scrollTop()</code>) and which frame should be showing at that particular time.</li>
<li>See how far we have scrolled into the <em>current frame</em>, and calculate all delta values of the transition based on that. E.g. if we fade something in; <code>'opacity':{from:0, to:1}</code> and have scrolled 36% into of that element, it would be given the opacity 0.36.</li>
</ol>
<p>The framework uses a <strong>linear easing</strong> algorithm for the transition, as per much experimentation, this is what feels most natural when the user <em>controls</em> the whole transition speed with his or her fingers. After all, why should the content move at different speeds when your motion remains constant?</p>
<h3 id="transitions">Transitions</h3>
<p>I love being able to construct as much as possible through the <span class="caps">HTML</span>. That’s why I made sure there are pre-defined transitions in the library, so that they can be accessed as keys from the <code>data-transition</code>, <code>data-enter</code> and <code>data-exit</code> attributes in the <span class="caps">HTML</span>. It seems the most efficient properties to transition on are <strong>opacity</strong>, <strong>scale</strong>, <strong>translate3d</strong> and <strong>rotation</strong>.</p>
<p>Basically they look like this:</p>
<pre><code class="lang-javascript">zoomOut:{
    <span class="string">'scale'</span>: {from: <span class="number">1</span>, to: <span class="number">0</span>}
},
slideInBottom: {
    <span class="string">'translate3d'</span>:{
        from:{y:<span class="number">700</span>},
        to: {y:<span class="number">0</span>}
    }
},
slideOutDown: {
    <span class="string">'translate3d'</span>:{
        from:{y:<span class="number">0</span>},
        to: {y:<span class="number">700</span>}
    }
},
rotate3dOut: {
    <span class="string">'rotate3d'</span>:{
        from:{x:<span class="number">0</span>, y:<span class="number">0</span>, z:<span class="number">0</span>, angle:<span class="number">0</span>},
        to: {x:<span class="number">1</span>, y:-<span class="number">1</span>,z:<span class="number">0</span>, angle:<span class="number">90</span>}
    }
}
</code></pre>
<p>You can add your own transitions with the <code>`addTransitions</code> method. Make sure it is done after the library is loaded.</p>
<pre><code class="lang-javascript">&lt;script src=<span class="string">"space.js"</span>&gt;<span class="xml"><span class="tag">&lt;/<span class="title">script</span>&gt;</span>

<span class="tag">&lt;<span class="title">script</span> <span class="attribute">type</span>=<span class="value">"text/javascript"</span>&gt;</span><span class="javascript">
    <span class="keyword">var</span> transitions = {
        rotate720: {
            <span class="string">'rotate'</span>:{from:<span class="number">0</span>, to:<span class="number">720</span>}
        },
        fadeOutHalf: {
            <span class="string">'opacity'</span>:{from:<span class="number">1</span>, to:<span class="number">0.5</span>}
        }
    };
    Space.addTransitions(transitions);
</span><span class="tag">&lt;/<span class="title">script</span>&gt;</span></span>
</code></pre>
<p>Check out the full <a href="https://github.com/gopatrik/space.js">source code</a> for more details!</p>
<h2 id="demos">Demos</h2>
<p><a href="http://www.slashie.org/space.js"><img src="http://www.slashie.org/articles/space.js/img/demosthumb.jpg" alt=""/></a></p>
<h2 id="last-words">Last words</h2>
<p>Note that this is not intended to be used everywhere. Every type of content has a preferred medium. I mainly wanted to inspire you to not feel conformed to the two-dimensional world of the Internet.</p>
<p>Hope you’re feeling inspired! Now tell us your story!</p>
<p><strong>Thanks for reading!</strong> Let me know if you want me to elaborate on something!</p>
