Imba

Imba is the namespace for all runtime related utilities

Static Methods

Imba.await
value

Coerces a value into a promise. If value is array it will call Promise.all(value), or if it is not a promise it will wrap the value in Promise.resolve(value). Used for experimental await syntax.

Imba.clearInterval
interval

Clear interval with specified id

Imba.clearTimeout
timeout

Clear timeout with specified id

Imba.isClient

True if running in client environment.

Imba.isServer

True if running in server environment.

Imba.iterable
o

Lightweight method for making an object iterable in imbas for/in loops. If the compiler cannot say for certain that a target in a for loop is an array, it will cache the iterable version before looping.

# this is the whole method def Imba.iterable o return o ? (o:toArray ? o.toArray : o) : [] class CustomIterable def toArray [1,2,3] # will return [2,4,6] for x in CustomIterable.new x * 2
Imba.schedule
target
method
=

Global alternative to requestAnimationFrame. Schedule a target to tick every frame. You can specify which method to call on the target (defaults to tick).

Imba.setInterval
interval
block

Light wrapper around native setInterval that expects the block / function as last argument (instead of first). It also triggers an event to Imba after every interval to let schedulers update (to rerender etc) afterwards.

Imba.setTimeout
delay
block

Light wrapper around native setTimeout that expects the block / function as last argument (instead of first). It also triggers an event to Imba after the timeout to let schedulers update (to rerender etc) afterwards.

Imba.unschedule
target
method

Unschedule a previously scheduled target

Imba.Touch

Consolidates mouse and touch events. Touch objects persist across a touch, from touchstart until end/cancel. When a touch starts, it will traverse down from the innermost target, until it finds a node that responds to ontouchstart. Unless the touch is explicitly redirected, the touch will call ontouchmove and ontouchend / ontouchcancel on the responder when appropriate.

tag draggable # called when a touch starts def ontouchstart touch flag 'dragging' self # called when touch moves - same touch object def ontouchmove touch # move the node with touch css top: touch.dy, left: touch.dx # called when touch ends def ontouchend touch unflag 'dragging'

Instance Methods

touch.button

Button pressed in this touch. Native touches defaults to left-click (0)

touch.dr

The absolute distance the touch has moved from starting position

touch.dx

The distance the touch has moved horizontally

touch.dy

The distance the touch has moved vertically

touch.extend
plugin

Extend the touch with a plugin / gesture. All events (touchstart,move etc) for the touch will be triggered on the plugins in the order they are added.

touch.redirect
target

Redirect touch to specified target. ontouchstart will always be called on the new target.

touch.suppress

Suppress the default behaviour. Will call preventDefault for all native events that are part of the touch.

touch.tx

Horizontal position of touch relative to target

touch.ty

Vertical position of touch relative to target

touch.x

Horizontal position of touch

touch.x0

Initial horizontal position of touch

touch.y

Vertical position of touch

touch.y0

Initial vertical position of touch

Imba.Event

Imba handles all events in the dom through a single manager, listening at the root of your document. If Imba finds a tag that listens to a certain event, the event will be wrapped in an Imba.Event, which normalizes some of the quirks and browser differences.

Instance Methods

event.cancel

Cancel the event (if cancelable). In the case of native events it will call preventDefault on the wrapped event object.

event.halt

Prevents further propagation of the current event.

event.isPrevented

Indicates whether or not event.cancel has been called.

event.keychar

Get the normalized character for KeyboardEvent/TextEvent

event.redirect
node

Redirect the event to new target

event.responder

A reference to the object responding to the event.

event.target

A reference to the initial target of the event.

event.which

Returns a Number representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as keyCode.

For mouse-events, the returned value indicates which button was pressed on the mouse to trigger the event.

event.x

Return the x/left coordinate of the mouse / pointer for this event

event.y

Return the y/top coordinate of the mouse / pointer for this event

Imba.EventManager

Manager for listening to and delegating events in Imba. A single instance is always created by Imba (as Imba.Events), which handles and delegates all events at the very root of the document. Imba does not capture all events by default, so if you want to make sure exotic or custom DOMEvents are delegated in Imba you will need to register them in Imba.Events.register(myCustomEventName)

Instance Methods

manager.create
type
target
data
:
source
:

Create a new Imba.Event

manager.register
name
handler
=
true

Tell the current EventManager to intercept and handle event of a certain name. By default, Imba.Events will register interceptors for: keydown, keyup, keypress, textInput, input, change, submit, focusin, focusout, blur, contextmenu, dblclick, mousewheel, wheel

manager.trigger

Trigger / process an Imba.Event.

Imba.Tag

This is the baseclass that all tags in imba inherit from.

Instance Methods

node.append
item

The .append method inserts the specified content as the last child of the target node. If the content is already a child of node it will be moved to the end.

example

var root = <div.root> var item = <div.item> "This is an item" root.append item # appends item to the end of root root.prepend "some text" # append text root.prepend [<ul>,<ul>] # append array
node.appendChild
node

Append a single item (node or string) to the current node. If supplied item is a string it will automatically. This is used by Imba internally, but will practically never be used explicitly.

node.blur

Remove focus from current node

node.build

Called implicitly through Imba.Tag#end, upon creating a tag. All properties will have been set before build is called, including setContent.

node.child
i

Get the child at index

node.children
sel

Get the children of node

node.closest
sel

Get the first element matching supplied selector / filter traversing upwards, but including the node itself.

node.commit

Called implicitly through Imba.Tag#end, for tags that are part of a tag tree (that are rendered several times).

node.contains
node

Check if node contains other node

node.dataset
key
val

Method for getting and setting data-attributes. When called with zero arguments it will return the actual dataset for the tag.

var node = <div data-name='hello'> # get the whole dataset node.dataset # {name: 'hello'} # get a single value node.dataset('name') # 'hello' # set a single value node.dataset('name','newname') # self
node.empty

Remove all content inside node

node.end

A very important method that you will practically never manually. The tag syntax of Imba compiles to a chain of setters, which always ends with .end. <a.large> compiles to tag('a').flag('large').end()

You are highly adviced to not override its behaviour. The first time end is called it will mark the tag as built and call Imba.Tag#build, and call Imba.Tag#commit on subsequent calls.

node.find
sel

Get descendants of current node, optionally matching selector

node.first
sel

Get the first matching child of node

node.flag
name
toggler

Add speficied flag to current node. If a second argument is supplied, it will be coerced into a Boolean, and used to indicate whether we should remove the flag instead.

node.flags

List of flags for this node.

node.focus

Focus on current node

node.getAttribute
name

returns the value of an attribute on the tag. If the given attribute does not exist, the value returned will either be null or "" (the empty string)

node.hasFlag
name

Check whether current node has specified flag

node.html

Get inner html of node

node.html=
html

Set inner html of node

node.index

Get the index of node.

node.insertBefore
node
rel

Insert a node into the current node (self), before another. The relative node must be a child of current node.

node.last
sel

Get the last matching child of node

node.last # returns the last child of node node.last %span # returns the last span inside node node.last do |el| el.text == 'Hi' # return last node with text Hi
node.log
args

Shorthand for console.log on elements

node.matches
sel

Check if this node matches a selector

node.next
sel

Get the immediately following sibling of node.

node.orphanize

Remove node from the dom tree

node.parent

Get the parent of current node

node.parents
sel

Get ascendents of node

node.path
sel

Get node and its ascendents

node.prepend
item

The .prepend method inserts the specified content as the first child of the target node. If the content is already a child of node it will be moved to the start.

node.prepend <div.top> # prepend node node.prepend "some text" # prepend text node.prepend [<ul>,<ul>] # prepend array
node.prev
sel

Get the immediately preceeding sibling of node.

node.remove
child

Remove specified child from current node.

Method is deprecated
node.removeAttribute
name

removes an attribute from the specified tag

node.removeChild
child

Remove specified child from current node.

node.render

Empty placeholder. Override to implement custom render behaviour. Works much like the familiar render-method in React.

node.schedule
options
=

Shorthand to start scheduling a node. The method will basically proxy the arguments through to scheduler.configure, and then activate the scheduler.

node.scheduler

Get the scheduler for this node. A new scheduler will be created if it does not already exist.

node.setAttribute
name
value

Adds a new attribute or changes the value of an existing attribute on the specified tag. If the value is null or false, the attribute will be removed.

node.setChildren
nodes
type

Set the children of node. type param is optional, and should only be used by Imba when compiling tag trees.

node.setContent
content
type

Override this to provide special wrapping etc.

node.setFlag
name
value

Set/update a named flag. It remembers the previous value of the flag, and removes it before setting the new value.

node.setFlag('type','todo') node.setFlag('type','project') # todo is removed, project is added.
node.setHandler
event
handler
ctx

Method that is called by the compiled tag-chains, for binding events on tags to methods etc. <a :tap=fn> compiles to tag('a').setHandler('tap',fn,this).end() where this refers to the context in which the tag is created.

node.setRef
ref
ctx

Setting references for tags like <div@header> will compile to tag('div').setRef('header',this).end() By default it adds the reference as a className to the tag.

node.siblings
sel

Get the siblings of node

node.synced

This is called instead of Imba.Tag#end for <self> tag chains. Defaults to noop

node.text
v

Get text of node. Uses textContent behind the scenes (not innerText) https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent

node.text=
txt

Set text of node. Uses textContent behind the scenes (not innerText) https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent

node.tick

Called by the tag-scheduler (if this tag is scheduled) By default it will call this.render. Do not override unless you really understand it.

node.toggleFlag
name

Toggle specified flag on node

node.unflag
name

Remove specified flag from node

node.unschedule

Shorthand for deactivating scheduler (if tag has one).

Method is deprecated
node.up
sel

Get the closest ancestor of node that matches specified selector / matcher.

Imba.Scheduler

Instances of Imba.Scheduler manages when to call tick() on their target, at a specified framerate or when certain events occur. Root-nodes in your applications will usually have a scheduler to make sure they rerender when something changes. It is also possible to make inner components use their own schedulers to control when they render.

Instance Methods

scheduler.activate

Start the scheduler if it is not already active. While active, the scheduler will override target.commit to do nothing. By default Imba.tag#commit calls render, so that rendering is cascaded through to children when rendering a node. When a scheduler is active (for a node), Imba disables this automatic rendering.

scheduler.active

Check whether the current scheduler is active or not

scheduler.configure
fps
:
1
events
:
true

Configure the scheduler

scheduler.deactivate

Stop the scheduler if it is active.

scheduler.dt

Delta time between the two last ticks

scheduler.flush

Instantly trigger target.tick and mark scheduler as clean (not dirty/marked). This is called implicitly from tick, but can also be called manually if you really want to force a tick without waiting for the next frame.

scheduler.initialize
target

Create a new Imba.Scheduler for specified target

scheduler.mark

Mark the scheduler as dirty. This will make sure that the scheduler calls target.tick on the next frame

scheduler.tick
delta

Called automatically on every frame while the scheduler is active. It will only call target.tick if the scheduler is marked dirty, or when according to @fps setting.

If you have set up a scheduler with an fps of 1, tick will still be called every frame, but target.tick will only be called once every second, and it will make sure each target.tick happens in separate seconds according to Date. So if you have a node that renders a clock based on Date.now (or something similar), you can schedule it with 1fps, never needing to worry about two ticks happening within the same second. The same goes for 4fps, 10fps etc.