Ore-js

A javascript-library for front-end development with a minimal API that functions mostly through configurations.

Objects

Ore has some objects you'll be using throughout development. The Ore object is the root of the library, containing a minimalist API.
Being a front-end library, you'll be provided with some ways to manipulate and create elements. These are wrapped in custom objects, called Minerals. These implement Ore's functionality, once again with a minimalist API, allowing you to build your site and make it interactive.
Ore also provides you with glimmers, which are animations.
These glimmers and minerals are interfaced with by passing configurations. These are maps / literal objects which you can just inline in your function calls.

List of objects and their API

• Ore:
  The library's variable. This contains the main functions to get you started.

  • mine( selector[string], config[Object] ):
    selector: either a css-selector refering to the element you wish to get the mineral of, or new<tagname> to create a mineral containing a new element.
    config: a configuration-object to pass to a newly created mineral.
    Returns a mineral containing a new element or one matching the passed selector.

• mineral:
  A wrapper-function around HTML-elements, allowing you to either manipulate them or retrieve data from them. Calling it with configuration allows you to manipulate the wrapped element.
  Calling without arguments, will retrieve data for you.

  • mineral( config[Object] ): Returns itself after applying your changes to the element.
  • mineral(): Returns an object containing all data of the element that is deemed useful.
    Has the following methods: * .get( path[string], prop[string] ):
    path: a string containing the type of data you want returned. Can be one of the following: [styles, attr, class].
    prop: a string containing the name of the prop you want returned. This will be the name of the css-property or attribute, depending on what the path-parameter was. Retrieving classes requires no prop-param.
    Returns the requested value.
    • .element():
      Returns the element it contains, in case you need some finer tuning.
    • .add( config[Object] ): Method that takes a configuration of functions to be added to routines.
      Routines can be called through a mineral by passing configuration.

• glimmer:
  An animation object with a similar API as minerals.

  • glimmer( config[Object] ):
    Takes a configuration and applies it to the glimmer-object.
    Returns the glimmer so that methods can be chained.

Configurations

There has been a lot of talk about configurations. These are used to interface with most API's Ore provides.
Configurations are plain maps / object literals. Ther don't require instantiation.
For now, there are 2 types of configurations. One for minerals and one for glimmers.

Mineral-configuration

The mineral configuration allows you to manipulate an element to a great extent. Before being processed, it gets mapped from whichever you pass to something the mineral can interpret.

Properties

Here you'll see a list of properties that the mineral can understand. They'll be accompanied by examples demonstrating their use and variations.

• styles[Object]:
  A key-value map containing styles to set.
  Keys being the css-property, values being their new value. The properties should be camel-cased.
  Alternatively, styles can be set in the root of the config. They'll be picked up in the default mapper if they are a recognised css-property.
• attr[Object]:
  A key-value map, containing attributes to set. Keys being the attribute to set, values being their new value.
  Alternatively, attributes be set in the root of the config. They'll be picked up by the default mapper if they are recognised as valid attributes.
• events[Object]: A key-value map containing events to add to the mineral. Keys being the event to handle, values being either a function or an array of functions to handle the event.
  Alternatively, events can be set in the root of the config. Their notation should then be changed from <eventname> to on<Eventname>
• text[string]:
  A string to set as text.
• append/prepend[Array, Mineral, Element]:
  A mineral or element or array of either to append to the mineral the configuration is passed to.

Routines

Routines are functions that are assigned to a mineral and can be easily called from labor. They can be added by calling a mineral's routine-function, which accepts an object. The object's keys should be the names of the routine you want to add, the value should be the corresponding function.
Routines can be called by using their name as a key inside of the labor-config, passing the arguments for your routine as the value, or as an array if there are more than one.

// Creating a new mineral containing a div-element
// and adding a routine, 'show', that will alter
// the div's display property based on the passed bool.
var mineral = Ore.mine('newdiv')
        .add({
          show: function (bool) {
            this({ display: bool ? 'block': 'none' });
          }
        })
        
/*...*/

// Hiding the div using the routine. This will put
// the div's display-prop on none.
mineral({
  show: false
})

Glimmer-configuration

Properties

Here, all properties the glimmer-configuration can hold will be listed. At the end, there will be some examples illustrating them.

• set[function, Array]:
  A function or array of functions to do something with the animated value.
• styles[string, Arra, Object]: A string or array of strings on which the animated value should be applied.
  Alternatively, you can pass an key-value map of which the keys are the styles and the values are functions further altering the value.
• from[number]:
  The initial value.
• to[number]:
  The value to animate towards.
• duration[number]:
  The animation's duration. This should be in miliseconds.
• delay[number]:
  The delay before the animation takes effect.
• onEnd[function]:
  A function to execute when the animation is finished.
• play[boolean]:
  A boolean indicating whether the animation should play or not.
• reverse[boolean]:
  A boolean that, if set to true, will trigger the animation to turn around.
• reset[boolean]: A boolean that, if set to true, will trigger the animation to reset.
• easing[string]:
  A string refering to an easing.

Supported Easings

This is a list of all supported easings. It's suggested to play around with them and find the best one for your use-case.
Every easing-function has a easeIn, easeOut and easeInOut variation. To use these, you'd pass easeInCubic for the cubic easing.
linear, bounceIn and bounceOut do not have these variations

• linear: has no variations - default
• bounceIn: has no variations
• bounceOut: has no variations
• quad
• cubic
• quart
• quint

Examples

Basic:

• Animating a variable:
  In this example, a variable will be animated from 0 to 200 over 500ms. The value will not be applied to a style. Only saved as a variable. The glimmer will start immediately after passing the config.

var animatedVariable,
  config = {
    from: 0,
    to: 200,
    duration: 500,
    set: function (value) { animatedVariable = value },
    play: true
  }
glimmer(config)

• Animating a style:
  Same as previous example, except for the value being applied to a style instead of being assigned to a variable.
  Don't forget to pass the mineral you wish to animate.

var config = {
    from: 0,
    to: 1,
    duration: 500,
    style: 'opacity',
    mineral: mineral,
    play: true
  }
glimmer(config)

• Animating a style with a unit:
  In this case, a function is passed to add a unit to the value.

var config = {
    from: 0,
    to: 200,
    duration: 500,
    style: {
      'top': function (value) { return value + 'px' }
    },
    mineral: mineral,
    play: true
  }
glimmer(config)

• Animating with an easing:
  Now we'll add an easing to make the animation feel more natural.

var config = {
    from: 0,
    to: 200,
    duration: 500,
    style: {
      'top': function (value) { return value + 'px' }
    },
    mineral: mineral,
    easing: 'bounceOut',
    play: true
  }
glimmer(config)

Advanced:
We can now start adding looping or interactivity.

• Looping a glimmer:
  Here, we make the onEnd-property apply a new configuration that reverses the glimmer and starts it again. For simplicity's sake, we'll do nothing with the animated value. You can of course leave out the reverse-property that's not needed in your case.

var config = {
    from: 0,
    to: 200,
    duration: 500,
    onEnd: function () {
      this({ reverse: true, play: true })
    },
    play: true
  }
glimmer(config)

• Animating multiple styles:
  We can make multiple styles animate with different values by passing an object to the styles-property that interpolates the animated value. This way, multiple styles will be assigned different values.

var config = {
    from: 0,
    to: 200,
    duration: 500,
    styles: {
      'top': function (value) { return value + 'px' },
      'opacity': function (value) { return value / 200 }
    },
    mineral: mineral,
    play: true
  }
glimmer(config)

WIP

This library, as well as this README is a work in progress. Input is always appreciated.