Documentation

Class

Component

kiss.ui.Component(config)

The Component is the base class for all KissJS UI components.

KissJS Component derives from HTMLElement, and therefore inherits all native DOM operations.

Most UI frameworks are encapsulating DOM elements with classes. Instead of that, KissJS is directly attaching new properties and new methods to DOM elements.

Let's imagine a Panel component built with KissJS. Because a KissJS Component is a pure DOM element, you can get your Panel using native DOM operations. Then, once you have your panel, you can directly call its methods like this:

const myPanel = document.getElementById("my-panel")
myPanel.expand()
myPanel.setAnimation("shakeX")

This way, it avoids the overhead of encapsulation (= no additional layers to cross). It's also easier to keep the memory clean: when you destroy your DOM element, everything attached to it (states, events...) is flushed and can be garbage collected.

KissJS components are partly using the Custom Web Components API. They are "half" Custom Web Components in the sense they're not using shadow DOM.

They are recognizable and easy to lookup in the DOM because their tag name always starts with "a-", like: "a-field", "a-button", "a-panel", "a-menu", and so on...

The Component base class also does a few things for us:

  • id generation (all KissJS components must have ids)
  • automatically inserted at a specific location in the DOM, using the optional "target" property
  • keep the component config attached to the component, to be able to serialize it / save it / rebuild it later
  • automatically adds a base class depending on the component type (example: "a-field", "a-button", ...)
  • we can bind custom methods, using the "methods" config
  • we can bind W3C events, using the "events" config
  • we can "subscribe" the component to one ore more PubSub channels, using the "subscriptions" config
  • a "render" method is automatically attached to manage the component rendering lifecycle
  • a "load" method can be attached to manage the component's loading / re-loading (typically when the component generation relies on data)
  • we can bind the component to one or more data collections, using the "collections" config: it will automatically reload the component when one of the binded collections changes
  • a few helper methods are attached automatically (show, hide, toggle, animation, showLoading, hideLoading...)
  • we can hook custom behavior in the lifecycle by using private methods like: _afterConnected, _afterRender, _afterShow, _afterHide, _afterDisconnected

Schema overview of the instanciation and rendering:

Constructor

# new Component(config)

Parameters:
Name Type Attributes Description
config object
id string <optional>

id of the component. Will be auto-generated if not set
hidden boolean <optional>

true if the component is hidden when rendered for the 1st time
target string | HTMLElement <optional>

DOM target insertion point. Either a DOM element or a CSS selector.
methods object <optional>

Custom methods of the component
events object <optional>

W3C events handled by the component
subscriptions object <optional>

Array of functions registered in the PubSub
collections Array.<Collection> <optional>

List of collections bound to the compoent. Component will reload if a mutation occurs in one of its bound collections.
tip string | object <optional>

hover help message
animation string | object <optional>

Animation to perform when rendering for the 1st time
autoSize boolean <optional>

If true, the component will trigger its "updateLayout" method when its parent container is resized

View Source client/ui/abstract/component.js, line 60

this

Methods

# attachTip(tipConfig)

Attach a tip text to the component

TODO: At the moment, attaching a tip prevents from having other "onmouseenter" events. Don't overwrite onmouseenter event

Parameters:
Name Type Attributes Description
tipConfig object | text

Config object {text: ..., deltaX: ..., deltaY: ...}, or a simple string
text string

Tip text
textAlign string <optional>

Tip text alignment: "center", "right". Default "left"
x number <optional>

Optional static x
Y number <optional>

Optional static y
deltaX number <optional>

Shift the tip on X coordinate
deltaY number <optional>

Shift the tip on Y coordinate

View Source client/ui/abstract/component.js, line 607

this

Example
// Using a configuration object
myField.attachTip({
 text: "Please enter your name",
 deltaX: 20,
 deltaY: 20
})

// Using a simple text
myField.attachTip("Please enter your name")

# detachTip()

Detach the tip from the component (if any)

View Source client/ui/abstract/component.js, line 650

this

# getHeight() → {number}

Get the component's height

View Source client/ui/abstract/component.js, line 671

The height in pixels

number

# getWidth() → {number}

Get the component's width

View Source client/ui/abstract/component.js, line 662

The width in pixels

number

# hide()

Hide the component

View Source client/ui/abstract/component.js, line 423

this

# hideLoading()

Hide the loading spinner of the Component

View Source client/ui/abstract/component.js, line 571

this

# isHidden() → {boolean}

Test if the component is hidden

View Source client/ui/abstract/component.js, line 490

boolean

# isVisible() → {boolean}

Test if the component is visible

View Source client/ui/abstract/component.js, line 499

boolean

# moveToViewport()

Move the component inside the visible viewport. This is useful for example to re-center a component so that it's entirely visible.

View Source client/ui/abstract/component.js, line 480

this

# render(targetopt, load)

Render an Element at a specified DOM location The rendering is optimized to render only the element that are detached from the DOM.

The render() method is chainable with other Component's methods. For example:

myElement.render().showAt(100, 100).setAnimation("shakeX")
Parameters:
Name Type Attributes Default Description
target * <optional>

optional DOM target insertion point
load boolean true

true (default) to execute the component's load method after DOM insertion

View Source client/ui/abstract/component.js, line 267

this

# setAnimation(config)

Animate an HTMLElement.

  • The animation must be set before rendering the component
  • It's chainable, so it can be combined with render() and showAt()

Animation speed can be modified with the param "speed":

  • slower
  • slow
  • fast
  • faster

Animation repetition can be adjusted with the param "repeat":

  • repeat-1
  • repeat-2
  • repeat-3
  • infinite

Available animation names are:

  • bounce
  • flash
  • pulse
  • rubberBand
  • shakeX
  • shakeY
  • headShake
  • swing
  • tada
  • wobble
  • jello
  • heartBeat
  • hinge
  • jackInTheBox
  • rollIn
  • rollOut
  • flipInX
  • flipInY
  • flipOutX
  • flipOutY
  • backInDown
  • backInLeft
  • backInRight
  • backInUp
  • backOutDown
  • backOutLeft
  • backOutRight
  • backOutUp
  • bounceIn
  • bounceInDown
  • bounceInLeft
  • bounceInRight
  • bounceInUp
  • bounceOut
  • bounceOutDown
  • bounceOutLeft
  • bounceOutRight
  • bounceOutUp
  • fadeIn
  • fadeInDown
  • fadeInDownBig
  • fadeInLeft
  • fadeInLeftBig
  • fadeInRight
  • fadeInRightBig
  • fadeInUp
  • fadeInUpBig
  • fadeInTopLeft
  • fadeInTopRight
  • fadeInBottomLeft
  • fadeInBottomRight
  • fadeOut
  • fadeOutDown
  • fadeOutDownBig
  • fadeOutLeft
  • fadeOutLeftBig
  • fadeOutRight
  • fadeOutRightBig
  • fadeOutUp
  • fadeOutUpBig
  • fadeOutTopLeft
  • fadeOutTopRight
  • fadeOutBottomLeft
  • fadeOutBottomRight
  • lightSpeedInRight
  • lightSpeedInLeft
  • lightSpeedOutRight
  • lightSpeedOutLeft
  • rotateIn
  • rotateInDownLeft
  • rotateInDownRight
  • rotateInUpLeft
  • rotateInUpRight
  • rotateOut
  • rotateOutDownLeft
  • rotateOutDownRight
  • rotateOutUpLeft
  • rotateOutUpRight
  • zoomIn
  • zoomInDown
  • zoomInLeft
  • zoomInRight
  • zoomInUp
  • zoomOut
  • zoomOutDown
  • zoomOutLeft
  • zoomOutRight
  • zoomOutUp
  • slideInDown
  • slideInLeft
  • slideInRight
  • slideInUp
  • slideOutDown
  • slideOutLeft
  • slideOutRight
  • slideOutUp
Parameters:
Name Type Attributes Description
config string | object

If the param is a string, it must be the animation name. Otherwise, it's a config like: {name: "zoomIn", speed: "fast", repeat: "repeat-3", callback: function() {...}}. Set the animation to false to remove the animation.
name string

Animation name
speed string <optional>

"slower" | "slow" | "fast" | "faster"
repeat string <optional>

"repeat-1" | "repeat-2" | "repeat-3" | "infinite"
callback function <optional>

Function to execute when the animation ends

View Source client/ui/abstract/component.js, line 1122

this - The component

Example
// Using only the animation name:
myComponent.setAnimation("fadeIn").render().showAt(100,100)

// Using a config object:
myComponent.setAnimation({
     name: "tada",
     speed: "fast",
     repeat: "repeat-1",
     callback: function() {
         this.hide()
     }
})

// Remove the animation
myComponent.setAnimation(false)

# setSize()

Set the component's size

Parameters:
Name Type Attributes Description
config.width object <optional>

Any CSS valid size, or a number (will be converted to pixels)
config.height object <optional>

Any CSS valid size, or a number (will be converted to pixels)

View Source client/ui/abstract/component.js, line 820

this

Example
myComponent.setSize({width: "10vw"})
myComponent.setSize({height: "100px"})
myComponent.setSize({width: 300, height: "20%"})

# show(modeopt)

Display the component

Parameters:
Name Type Attributes Description
mode string <optional>

Force a display mode. Ex: block, flex, inline, inline-block, inline-flex

View Source client/ui/abstract/component.js, line 442

this

# showAt(x, y, animationTimeInSecondsopt)

Show the component at a specified (x, y) position on the screen. If the component leaks outside the viewport, it's re-centered to fit in.

Parameters:
Name Type Attributes Description
x number

Coord x in pixels
y number

Coord y in pixels
animationTimeInSeconds number <optional>

Optional parameter to animate the translation of the Element

View Source client/ui/abstract/component.js, line 466

this

Example
// It wil take 2 seconds to translate to position 500,500:
myElement.showAt(500, 500, 2)

# showLoading(config)

Show a loading spinner over the Component. By default, the overlay has the size of the element.

Parameters:
Name Type Description
config object
fullscreen boolean

If true, the loading mask cover the full screen
mask boolean

Set to false to hide the background overlay
spinnerSize number

Size of the spinning symbol, in pixels

View Source client/ui/abstract/component.js, line 530

this

Example
myPanel.showLoading({spinnerSize: 32})

# toggle()

Show / hide alternatively the Component

View Source client/ui/abstract/component.js, line 508

this

# translate()

Translate the localized elements of a Component on the fly TODO: handle external values merged into the translated strings

View Source client/ui/abstract/component.js, line 245

# update(newConfigopt) → {object}

Update a component with a new config

  • Internally, destroys the component and re-render it from its config.
  • If the component was inside a parent container, it re-render it at the same position
  • Attention: if the component received extra properties/methods/events outside it's default config, they will be lost
Parameters:
Name Type Attributes Description
newConfig object <optional>

View Source client/ui/abstract/component.js, line 325

The new KissJS component

object