Global

Methods

channel(topic, chanParams) → {Channel}

Description:

  • Initiates a new channel for the given topic

Source:
Parameters:
Name Type Description
topic string
chanParams Object

Parameters for the channel
Returns:
Type
Channel

connect(params)

Source:
Parameters:
Name Type Description
params Object

The params to send when connecting, for example {user_id: userToken}

Passing params to connect is deprecated; pass them in the Socket constructor instead: new Socket("/socket", {params: {user_id: userToken}}).

connectionState() → {string}

Source:
Returns:
Type
string

disconnect(callback, code, reason)

Description:

  • Disconnects the socket

    See https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes for valid status codes.

Source:
Parameters:
Name Type Description
callback function

Optional callback which is called after socket is disconnected.
code integer

A status code for disconnection (Optional).
reason string

A textual description of the reason to disconnect. (Optional)

endPointURL() → {string}

Description:

  • The fully qualified socket url

Source:
Returns:
Type
string

getLongPollTransport()

Description:

  • Returns the LongPoll transport reference

Source:

hasLogger()

Description:

  • Returns true if a logger has been set on this socket.

Source:

init()

Description:

  • Combo HTML

    It provides enhancements for HTML:

    • Support data-confirm="message" attributes, which shows a confirmation modal with the given message.

    • Support data-method="patch|post|put|delete" attributes, which sends the current click as a PATCH/POST/PUT/DELETE HTTP request. You will need to add data-to with the URL and data-csrf with the CSRF token value.

    • Dispatch a combo.link.click event, which provides a mechanism to customize the default behaviour above. Stopping propagation for this event will disable data-confirm. Prevent default behaviour for this event will disable data-method.

    Setup

    To use the functionality above, you must load code into your build tool:

    import html from "combo/html";

html.init();

    Customizing the default behaivour

    Customizing the data-confirm behaviour

    Intercept the combo.link.click event before it bubbling up to window and do your own custom logic.

    For example, you could replace the default behavior using window.confirm with a custom implementation based on vex:

    // Compared to window.confirm, the custom dialog does not block JavaScript
// execution. Therefore to make this work as expected we store the successful
// confirmation as an attribute and re-trigger the click event.

// On the second click, the `data-confirm-resolved` attribute is set
// and we proceed.
const RESOLVED_ATTRIBUTE = "data-confirm-resolved";

// listen on document.body, so it's executed before the default of
// html.init(), which is listening on the window object.
document.body.addEventListener(
  "combo.link.click",
  function (e) {
    // Prevent default implementation
    e.stopPropagation();

    // Introduce alternative implementation
    const message = e.target.getAttribute("data-confirm");
    if (!message) {
      return;
    }

    // Confirm is resolved execute the click event
    if (e.target?.hasAttribute(RESOLVED_ATTRIBUTE)) {
      e.target.removeAttribute(RESOLVED_ATTRIBUTE);
      return;
    }

    // Confirm is needed, preventDefault and show your modal
    e.preventDefault();
    e.target?.setAttribute(RESOLVED_ATTRIBUTE, "");

    vex.dialog.confirm({
      message: message,
      callback: function (value) {
        if (value == true) {
          // Customer confirmed, re-trigger the click event.
          e.target?.click();
        } else {
          // Customer canceled
          e.target?.removeAttribute(RESOLVED_ATTRIBUTE);
        }
      },
    });
  },
  false,
);

    Creating new custom behavior

    window.addEventListener(
  "combo.link.click",
  function (e) {
    // Introduce new behaviour
    var message = e.target.getAttribute("data-prompt");
    var answer = e.target.getAttribute("data-prompt-answer");
    if (message && answer && answer != window.prompt(message)) {
      e.preventDefault();
    }
  },
  false,
);
Source:

isConnected() → {boolean}

Source:
Returns:
Type
boolean

join(timeout) → {Push}

Description:

  • Join the channel

Source:
Parameters:
Name Type Description
timeout integer
Returns:
Type
Push

leave(timeout) → {Push}

Description:

  • Leaves the channel

    Unsubscribes from server events, and instructs channel to terminate on server

    Triggers onClose() hooks

    To receive leave acknowledgements, use the receive hook to bind to the server ack, ie:

Source:
Example
channel.leave().receive("ok", () => alert("left!") )
Parameters:
Name Type Description
timeout integer
Returns:
Type
Push

list(presences, chooser) → {Presence}

Description:

  • Returns the array of presences, with selected metadata.

Source:
Parameters:
Name Type Description
presences Object
chooser function
Returns:
Type
Presence

log(kind, msg, data)

Description:

  • Logs the message. Override this.logger for specialized logging. noops by default

Source:
Parameters:
Name Type Description
kind string
msg string
data Object

makeRef() → {string}

Description:

  • Return the next message ref, accounting for overflows

Source:
Returns:
Type
string

off(event, ref)

Description:

  • Unsubscribes off of channel events

    Use the ref returned from a channel.on() to unsubscribe one handler, or pass nothing for the ref to unsubscribe all handlers for the given event.

Source:
Example
// Unsubscribe the do_stuff handler
const ref1 = channel.on("event", do_stuff)
channel.off("event", ref1)

// Unsubscribe all handlers from event
channel.off("event")
Parameters:
Name Type Description
event string
ref integer

off(refs)

Description:

  • Removes onOpen, onClose, onError, and onMessage registrations.

Source:
Parameters:
Name Type Description
refs refs

list of refs returned by calls to onOpen, onClose, onError, and onMessage

on(event, callback) → {integer}

Description:

  • Subscribes on channel events

    Subscription returns a ref counter, which can be used later to unsubscribe the exact event listener

Source:
Example
const ref1 = channel.on("event", do_stuff)
const ref2 = channel.on("event", do_other_stuff)
channel.off("event", ref1)
// Since unsubscription, do_stuff won't fire,
// while do_other_stuff will keep firing on the "event"
Parameters:
Name Type Description
event string
callback function
Returns:

ref

Type
integer

onClose(callback)

Description:

  • Hook into channel close

Source:
Parameters:
Name Type Description
callback function

onClose(callback)

Description:

  • Registers callbacks for connection close events

Source:
Parameters:
Name Type Description
callback function

onError(callback)

Description:

  • Hook into channel errors

Source:
Parameters:
Name Type Description
callback function

onError(callback)

Description:

  • Registers callbacks for connection error events

Source:
Example
socket.onError(function(error){ alert("An error occurred") })
Parameters:
Name Type Description
callback function

onMessage(event, payload, ref) → {Object}

Description:

  • Overridable message hook

    Receives all events for specialized message handling before dispatching to the channel callbacks.

    Must return the payload, modified or unmodified

Source:
Parameters:
Name Type Description
event string
payload Object
ref integer
Returns:
Type
Object

onMessage(callback)

Description:

  • Registers callbacks for connection message events

Source:
Parameters:
Name Type Description
callback function

onOpen(callback)

Description:

  • Registers callbacks for connection open events

Source:
Example
socket.onOpen(function(){ console.info("the socket was opened") })
Parameters:
Name Type Description
callback function

ping(callback)

Description:

  • Pings the server and invokes the callback with the RTT in milliseconds

Source:
Parameters:
Name Type Description
callback function

Returns true if the ping was pushed or false if unable to be pushed.

protocol() → {string}

Description:

  • Returns the socket protocol

Source:
Returns:
Type
string

push(event, payload, timeoutopt) → {Push}

Description:

  • Sends a message event to server with the payload payload. Server receives this in the handle_in(event, payload, socket) function. if server replies or it times out (default 10000ms), then optionally the reply can be received.

Source:
Example
channel.push("event")
  .receive("ok", payload => console.log("server replied:", payload))
  .receive("error", err => console.log("server errored", err))
  .receive("timeout", () => console.log("timed out pushing"))
Parameters:
Name Type Attributes Description
event string
payload Object
timeout number <optional>
Returns:
Type
Push

push(data)

Source:
Parameters:
Name Type Description
data Object

receive(status, callback)

Source:
Parameters:
Name Type Description
status *
callback *

replaceTransport(newTransport)

Description:

  • Disconnects and replaces the active transport

Source:
Parameters:
Name Type Description
newTransport function

The new transport class to instantiate

resend(timeout)

Source:
Parameters:
Name Type Description
timeout number

scheduleTimeout()

Description:

  • Cancels any previous scheduleTimeout and schedules callback

Source:

send()

Source:

syncDiff() → {Presence}

Description:

  • Used to sync a diff of presence join and leave events from the server, as they happen. Like syncState, syncDiff accepts optional onJoin and onLeave callbacks to react to a user joining or leaving from a device.

Source:
Returns:
Type
Presence

syncState() → {Presence}

Description:

  • Used to sync the list of presences on the server with the client's state. An optional onJoin and onLeave callback can be provided to react to changes in the client's local presences across disconnects and reconnects with the server.

Source:
Returns:
Type
Presence