DuelJS Documentation

Note

Documentation still in progress.

Welcome to the DuelJS JavaScript library documentation.

User Documentation

Getting Started

Getting started with DuelJS.

Requirements

With DuelJS you no need to any requirements - only vanilla js and modern web browser. Don’t try to use it with node.js without browser emulators.

Installing DuelJS

You can install it using bower or simple copy duel.js main file into your site or even clone git repository.

Different ways:

  • Bower package: bower install duel --save
  • Git repo: git clone https://github.com/studentIvan/dueljs.git
  • Main file: duel.min.js

Put it into your webpage: <script type="text/javascript" src="path/to/duel.min.js"></script>

So we’ve got all the set up out of the way. Let’s write some simple code.

<script type="text/javascript">
var channel = duel.channel('my_first_channel');
// now you have opened some channel, this tab is connected to it

setInterval(function () {
    if (channel.currentWindowIsMaster()) {
        // here you checking is this tab active (in focus) or not
        // you can use alternative syntax: if (window.isMaster()) { ...

        document.title = 'Master ' + duel.getWindowID();
        // duel.getWindowID returns a unique browser tab id

    } else {
        document.title = 'Slave ' + duel.getWindowID();
    }
}, 100);
</script>

Broadcasting

When your tab had some channel (e.g. my_first_channel from previous section) you can do cross-tab broadcasting.

Use simple commands:

  • channel.broadcast(‘event_name’, a,r,g,u,m,e,n,t,s...);
    • send event command to all another tabs in channel. Alias: channel.emit.
  • channel.on(‘event_name’, function (a,r,g,u,m,e,n,t,s...) { do here what you want });
    • define watcher for event_name.
  • channel.off(‘event_name’);
    • remove event_name watcher.
  • channel.once(‘event_name’, function (a,r,g,u,m,e,n,t,s...) { do here what you want });
    • define watcher for event_name, do it only one time and remove.

API:duel

duel

Main global object.

  • global
  • type: object

duel.activeChannels

Collect inside all active channels.

  • public
  • type: array
  • default: []

duel.useStorageEvent

Optional configuration. Storage event improves performance in modern browsers.

  • public
  • type: boolean
  • default: true (IE - false)

duel.isLocalStorageAvailable()

Common function for localStorage detection.

  • public
  • type: function
  • returns: boolean

duel.channel(name:string)

Creates a new channel or join to existed. Hint: a = duel.channel(‘x’) and b = duel.channel(‘x’) will be linking on ONE object.

  • public
  • type: function
  • returns: object (duel.DuelAbstractChannel inheritor)

duel.makeCurrentWindowMaster()

Take the all channels in current window and set current window as master for all of them.

  • public
  • type: function

duel.clone(obj:object)

Common function for copy objects.

  • public
  • type: function
  • returns: object
  • throws error on unsupported type

duel._generateWindowID()

Generates, sets up and returns new window/tab ID.

  • private
  • type: function
  • returns: number

duel.getWindowID()

Get unique window/tab ID.

  • public
  • type: function
  • returns: number

duel.addEvent(el:object, type:string, fn:function)

Cross-browser addEvent method.

  • public
  • type: function

duel.storageEvent(event:object)

Finds the specific channel and execute event on it. event object contains key:string and newValue:string. newValue is a JSON string, which contains channelName:string and triggerDetails:object. triggerDetails contains name:string and args:array.

  • public
  • type: function

duel.DuelAbstractChannel

Abstract class for possible duel channels. DuelJS probably will support another channels besides duel.DuelLocalStorageChannel in future.

  • abstract
  • type: function
  • returns: object

duel.DuelLocalStorageChannel

Channel class for work with localStorage.

  • abstract
  • type: function
  • returns: object

duel.DuelFakeChannel

Channel class for work without localStorage.

  • abstract
  • type: function
  • returns: object

window.isMaster()

Take first channel in current window and check is it master or not

Standard window object spreading method. Looks like syntax sugar for channelObject.currentWindowIsMaster()

  • public
  • type: function
  • returns: boolean

API:channel object interface

channel.getName()

Returns the name of this channel.

  • public
  • type: function
  • returns: string

channel.setCurrentWindowAsMaster()

Makes current window/tab as master in this channel.

  • public
  • type: function
  • returns: boolean

channel.currentWindowIsMaster()

Checks the master state of this channel.

  • public
  • type: function
  • returns: boolean

channel.broadcast(trigger:string[, arguments:arguments])

Emits broadcasting. Hint: only master can sends broadcast.

  • public
  • type: function

channel.emit(trigger:string[, arguments:arguments])

Alias of channel.broadcast

channel.executeTrigger(triggerDetails:object[, force:boolean])

Executes pointed trigger. triggerDetails contains name:string and args:array

  • public
  • type: function
  • throws error if triggerDetails is not an instance of Object

channel.on(trigger:string, callback:function)

Attaches callback to trigger event.

  • public
  • type: function

channel.once(trigger:string, callback:function)

Attaches callback to trigger event only for one time.

  • public
  • type: function

channel.off(trigger:string)

Detaches callback from trigger event (destroys trigger).

  • public
  • type: function

channel._triggers

Contains triggers of this channel.

  • private
  • type: object