phollyer / elm-phoenix-websocket / Phoenix.Channel

This module can be used to talk directly to PhoenixJS without needing to add anything to your Model. You can send and receive messages to and from your Channels from anywhere in your Elm program. That is all it does and all it is intended to do.

If you want more functionality, the top level Phoenix module takes care of a lot of the low level stuff such as automatically joining to your Channels.

Joining


type alias Topic =
String

A type alias representing the Channel topic id. For example "topic:subTopic".


type alias Event =
String

A type alias representing an event sent to, or received from a Channel.


type alias Payload =
Json.Encode.Value

A type alias representing data that is sent to, or received from, a Channel.


type alias JoinConfig =
{ topic : Topic
, events : List Event
, payload : Payload
, timeout : Maybe Basics.Int 
}

A type alias representing the config for joining a Channel.

joinConfig : JoinConfig

A helper function for creating a JoinConfig.

import Phoenix.Channel exposing (joinConfig)

{ joinConfig
| topic = "topic:subTopic"
, events = [ "event1", "event2" ]
}


type alias PortOut msg =
{ msg : String
, payload : Json.Encode.Value } -> Platform.Cmd.Cmd ms
}

A type alias representing the port function required to send messages out to the accompanying JS.

You will find this port function in the Port module.

join : JoinConfig -> PortOut msg -> Platform.Cmd.Cmd msg

Join a Channel.

import Json.Encode as JE
import Phoenix.Channel as Channel
import Ports.Phoenix as Ports

Channel.join
    { topic = "topic:subtopic"
    , payload = JE.null
    , events = []
    , timeout = Nothing
    }
    Ports.phoenixSend

Leaving


type alias LeaveConfig =
{ topic : Topic
, timeout : Maybe Basics.Int 
}

A type alias representing the config for leaving a Channel.

leave : LeaveConfig -> PortOut msg -> Platform.Cmd.Cmd msg

Leave a Channel.

import Phoenix.Channel as Channel
import Ports.Phoenix as Ports

Channel.leave
    { topic = "topic:subtopic"
    , timeout = Nothing
    }
    Ports.phoenixSend

Pushing

push : { a | topic : Topic, event : Event, payload : Payload, timeout : Maybe Basics.Int, ref : Maybe String } -> PortOut msg -> Platform.Cmd.Cmd msg

Push to a Channel.

The optional ref is returned with the response to the Push so that you can use it to identify the response later on if needed.

import Json.Encode as JE
import Phoenix.Channel as Channel
import Ports.Phoenix as Port

Channel.push
    { topic = "topic:subtopic"
    , event = "new_msg"
    , payload =
        JE.object
            [("msg", JE.string "Hello World")]
    , timeout = Nothing
    , ref = Nothing
    }
    Port.pheonixSend

Receiving


type alias PortIn msg =
({ topic : Topic
, msg : String
, payload : Json.Encode.Value } -> msg) -> Platform.Sub.Sub ms
)

A type alias representing the port function required to receive a Msg from a Channel.

You will find this port function in the Port module.


type InternalError
    = DecoderError String
    | InvalidMessage Topic String Payload

An InternalError should never happen, but if it does, it is because the JS is out of sync with this package.

If you ever receive this message, please raise an issue.


type Msg
    = JoinOk Topic Payload
    | JoinError Topic Payload
    | JoinTimeout Topic Payload
    | PushOk Topic Event Payload String
    | PushError Topic Event Payload String
    | PushTimeout Topic Event Payload String
    | Message Topic Event Payload
    | Error Topic
    | LeaveOk Topic
    | Closed Topic
    | InternalError InternalError

All of the messages you can receive from the Channel.

subscriptions : (Msg -> msg) -> PortIn msg -> Platform.Sub.Sub msg

Subscribe to receive incoming Channel Msgs.

import Phoenix.Channel as Channel
import Ports.Phoenix as Port

type Msg
  = ChannelMsg Channel.Msg
  | ...


subscriptions : Model -> Sub Msg
subscriptions _ =
    Channel.subscriptions
        ChannelMsg
        Port.channelReceiver

Incoming Events

These are events that are pushed or broadcast from your Elixir Channels. It is necessary to set up the JS event listeners so that the events can be captured and sent on to Elm. These functions turn those event listeners on and off.

on : { topic : Topic, event : Event } -> PortOut msg -> Platform.Cmd.Cmd msg

Switch an incoming event on.

allOn : { topic : Topic, events : List Event } -> PortOut msg -> Platform.Cmd.Cmd msg

Switch a list of incoming events on.

off : { topic : Topic, event : Event } -> PortOut msg -> Platform.Cmd.Cmd msg

Switch an incoming event off.

allOff : { topic : Topic, events : List Event } -> PortOut msg -> Platform.Cmd.Cmd msg

Switch a list of incoming events off.