skulletor

SkulletorJS

Table of contents

• Motivation
• Installation
• How to use ?
• Key concepts
  • Shapes
  • Middlewares
  • Controls
  • Responsive
• TODO

Motivation

SkulletorJS is a Javascript library that allows you to ease your skeleton loading screen creation. It uses predefined shapes you can configure and compose to create more complex skeletons.

The created skeletons are CSS based. SkulletorJS also provides control capabilities such as end, disappear.

Simple example

This basic script produces a vanilla javascript skeleton. Easy to create, it simply uses some basic shapes and appends the result to the DOM.

const bluePrint = () => [
  {
    width: '35%',
    height: '365px',
  },
  circle({ radius: 35, left: 15, top: 15, color: { r: 255, g: 255, b: 255, a: 1 } }),
  rectangle({ height: '185px' }),
  line({ fontSize: 22, width: '180px', topGap: 20, left: 20 }),
  line({ fontSize: 22, width: '120px', topGap: 20, left: 20 }),
  line({ fontSize: 36, width: '150px', topGap: 20, left: 20 }),
]

const { Skulletor } = skulletor([bluePrint(), bluePrint()])
const dom = document.getElementById('root')
dom.appendChild(Skulletor)

The result :

Installation

npm install --save skulletor

How to use

First of all, you need to choose your adapter.

In the library you have 3 adapters available : Vanilla, React (Hooks) or React. It will define what kind of skulletor you're going to use, but the call remains similar.

Vanilla adapter :

import skulletor from 'skulletor/lib/adapter/vanilla'

// Here, 'Skeletor' is a domNode ready to be injected inside the document ...
const { Skulletor } = skulletor([bluePrint()])

dom.appendChild(Skulletor)

React Hooks adapter :

import React from 'react'
import skulletor from 'skulletor/lib/adapter/react-hooks'

// ... while here, 'Skeletor' is a React Component.
const { Skulletor } = skulletor([bluePrint()])

ReactDOM.render(
  <div>
    <Skulletor />
  </div>,
  dom,
)

React adapter :

import React from 'react'
import skulletor from 'skulletor/lib/adapter/react'

// Same as React Hooks, this Skulletor is a React Component.
const { Skulletor } = skulletor([bluePrint()])

ReactDOM.render(
  <div>
    <Skulletor />
  </div>,
  dom,
)

Key concepts

Shapes

SkulletorJS provides some basic shapes sufficient to satisfy common needs. (To implement custom shapes, please refer to chapter 'Raw CSS' or 'Going further'). Shape creation is very simple, each of them are functions with predefined and comprehensive parameters (fontSize, width etc.).

There are four basic shapes : rectangle, line, circle and square (square is equal to rectangle but use only size instead of width / height params).

import { rectangle, line, circle, square } from 'skulletor/lib/shapes'
const white = { r: 255, g: 255, b: 255, a: 1 }

const authorIcon = circle({ radius: 35, left: 15, top: 15, color: white })
const photo = rectangle({ height: '185px' })
const title = line({ fontSize: 22, width: '180px', topGap: 20, left: 20 })

const bluePrint = [authorIcon, photo, title]

The blueprint order is important :

• the stack will be displayed from first to last shape : In the following example, the whiteIcon shape will overlap the greyRectangle.

const bluePrint = [
	whiteIcon, // Will be on top if shapes should overlap.
	greyRectangle,
	...
]

• Gap handling is possible with the use of topGap and/or leftGap properties. Those values are relative to the previous object defined in the blueprint.

const bluePrint = [
	rectangle({ height: '185px' }),
	line({ fontSize: 22, topGap: 20 }), //  Will be positioned 20px after the rectangle.
	...
]

const bluePrint = [
	rectangle({ height: '185px' }),
	line({ fontSize: 22, topGap: -22, leftGap: 20 }), //  Will be positioned 20px next to the rectangle. Note the use of topGap with a negative number so the line removes its heights in the gaping 
	...
]

Middlewares

SkulletorJS uses a simple middleware system to improve itself.

Some of them are adapter-specific like applyFadeOut while others are generic.

N.B. : The base skulletor function uses 3 middlewares, but you can change this by calling the skulletorFactory function used to generate your own "skulletor" function.

import { skulletorFactory, applyFadeOut } from 'skulletor/lib/adapter/vanilla'
import { applyBaseCSS, applyAnimation } from 'skulletor/lib/middlewares'

// Generate your own skulletor function with some middlewares.
const mySkulletor = skulletorFactory([applyBaseCSS(), applyAnimation(), applyFadeOut()])
const { Skulletor } = mySkulletor([bluePrint()])

When applying the middleware applyAnimation, the laser ray style animation is applied on our skeleton :

It's possible to provide your own middlewares (refer to "going further" section).

N.B. : Middlewares are functions that will be handlded by the middlewareHandler. Provided middlewares are generators so you can custom them as follows.

// Custom fadeOut duration and timing function
const mySkulletor = skulletorFactory([applyBaseCSS(), applyAnimation(), applyFadeOut({ time: '0.8s', timingFunction: 'ease-out' })])

Controls

SkulletorJS provides control capabilites which can differ greatly between the Vanilla and the React adapter. This chapter focuses on the Vanilla version (the React version will be explained in the next chapter with a full example).

import skulletor from 'skulletor/lib/adapter/vanilla'

const { Skulletor, end } = skulletor([bluePrint()])

const dom = document.getElementById('root')
dom.appendChild(Skulletor)

// The skeleton will end after 2 seconds, and when it disapears, display a text.
setTimeout(() => {
  end().then(() => {
    dom.innerText = 'Loading finish !'
  })
}, 2000)

Be careful, end and disapear are two different concepts. When end is called, the skeletor is asked to finish, but the promise will only be resolved when all middlewares release. For instance, with applyFadeOut middleware, the skeleton loader could end but will disapear only when fadeout is terminated.

Example with React adapter

import React, { Fragment, Component } from 'react'
import ReactDOM from 'react-dom'

import skulletor from 'skulletor/lib/adapter/react'
import { rectangle, line, circle } from 'skulletor/lib/shapes'

const bluePrint = () => [
  {
    width: [35, '%'],
    height: [365, 'px'],
  },
  circle({ radius: 35, left: 15, top: 15, color: { r: 255, g: 255, b: 255, a: 1 } }),
  rectangle({ height: [185, 'px'] }),
  line({ fontSize: 22, width: [180, 'px'], topGap: 20, left: 20 }),
  line({ fontSize: 22, width: [120, 'px'], topGap: 20, left: 20 }),
  line({ fontSize: 36, width: [150, 'px'], topGap: 20, left: 20 }),
]

const { Skulletor } = skulletor([bluePrint()])

class App extends Component {
  state = {
    isLoading: true,
    displayFinishMessage: false,
  }

  componentDidMount() {
    setTimeout(() => this.setState({ isLoading: false }), 2000)
  }

  render() {
    const { isLoading, displayFinishMessage } = this.state
    return (
      <Fragment>
        <Skulletor end={!isLoading} onDisapear={() => this.setState({ displayFinishMessage: true })} />
        {displayFinishMessage && 'Loading finish !'}
      </Fragment>
    )
  }
}

ReactDOM.render(<App />, document.getElementById('root'))

Responsive

You can provide media queries in order to handle responsive skeletons :

const bluePrintSmall = () => [ ... ]
const bluePrintLarge = () => [ ... ]

const { Skulletor } = skulletor({
  'max-width: 639px': [bluePrintSmall(), bluePrintSmall()],
  'min-width: 640px': [bluePrintLarge(), bluePrintLarge()],
})

TODO

• Create a basic documentation.
• Improve documentation and add following titles :
  • API
  • Raw CSS
  • Going further
    • Create new shapes
    • Create middlewares
    • Adapter system for compatibility
• Add unit tests
• Configure CI
• Provide an umd builded lib file