Elm is a programming language for building client-side web applications that compiles to JavaScript. Because it’s strongly-typed and pure, Elm provides a handy mechanism for interacting with the “unsafe world” that is JavaScript to help maintain boundaries between the two.
That mechanism is ports.
Why Ports?
Because Elm relies on an explicit understanding of the data it describes via the type system, it needs to make guarantees when interacting with JavaScript so developers can trust the compiler to verify accuracy in the program. Elm touts “no runtime exceptions”, and while I’ve personally found ways to break that (hint: don’t attempt to convert user input into a regular expression), I trust the compiler to help spot issues.
Because of these guarantees, ports are necessary to guard what flows into the Elm application from JavaScript, and allows developers to format data from Elm flowing outward to JavaScript. Ports act as a bridge between two different worlds, and introduce confidence that communication between the two languages is occurring correctly.
Limited Interface
Ports allow for basic primitives to flow to and from JavaScript and Elm, including JavaScript objects, arrays, boolean values, numbers, and strings. Functions cannot be passed directly, even though they’re first-class objects in JavaScript. Similarly, functions cannot be passed from Elm to JavaScript to be called afterward.
Because of this limited interface, it’s arguably easier to ensure both Elm and JavaScript are able to communicate; there’s a much smaller language with which they can speak to each other.
Forced Constraints and Forced Failure
While I’ve written at length about Elm decoders, their purpose is to parse
JSON structures into Elm-specific data structures. Elm provides a Result a b
primitive type that describes both success and failure; with this, the Elm code
will then explicitly handle when parsing JSON fails, and provide information to
the developer (and perhaps customer) that something went wrong.
Forced error handling means explicit messaging to customers; edge-cases around unexpected things happening crop up much less frequently.
Managing Side-Effects
Port interaction is handled entirely through Elm as asynchronous messages. This means all inbound port interaction is handled either with Elm subscriptions (JavaScript sending data over a port to Elm) and outbound port interaction with Elm commands (Elm sending data to JavaScript over a port).
Because of this, communication via ports is often isolated to a single file, ensuring all code with side-effects is isolated from the rest of the codebase.
-- outbound port
port initialized : List GoogleMapMarker.Model -> Cmd a
-- outbound port
port selectLatLon : GoogleMapMarker.Model -> Cmd a
-- inbound port
port clickedMapMarker : (Int -> msg) -> Sub msg
Example Application
For this article, I built an Elm application that plots thoughtbot offices on a Google Map. The data is seeded via JavaScript objects and passed into the Elm application with a flag, and once the data is decoded, it’s plotted on the map.
Elm to JavaScript
Let’s start by sending information from Elm to JavaScript. This occurs at the
top-level initial and update functions within the Elm application as a
command, and we’ll need a way to encode an Elm structure into JSON.
Sending Messages to Ports
The first port we’ll define will be used to initialize the Google Map itself; with this, we’ll provide a list of geographical coordinates (latitude and longitude) that we can iterate over to plot on the map.
Laying the foundation of the data model, let’s look at what a Google Map marker looks like:
module GoogleMapMarker
exposing
( Model
, fromOffice
)
import Json.Encode as Encode
import Office.Model as Office
import Address.Model as Address
type alias Model =
Encode.Value
fromOffice : Office.Model -> Model
fromOffice ({ id } as office) =
Encode.object
[ ( "id", encodeOfficeId id )
, ( "latLng", encodeLatLon office.address.geo )
]
To make this list of offices available to JavaScript, we’ll begin by defining a port:
port initialized : List GoogleMapMarker.Model -> Cmd a
This defines a function that takes a list of GoogleMapMarker.Model and
returns a polymorphic Cmd a; with this in place, we can call initialized
from initial (which we’ve told Elm to use when starting the application) and
provide the list of coordinates:
initial : Flags.Model -> ( Model, Cmd Msg )
initial flags =
let
initialModel =
initialModelFromFlags flags
initialLatLngs =
List.map GoogleMapMarker.fromOffice initialModel.offices
in
( initialModel, initialized initialLatLngs )
When we embed the Elm application, we’ll subscribe to the initialized port,
initialize the map, and register the coordinates. Let’s take a look at the
JavaScript necessary to do so:
const flags = {
offices: [
{
id: 1,
name: "Boston",
// ...
}
]
}
document.addEventListener("DOMContentLoaded", () => {
const app = Elm.Main.embed(document.getElementById("main"), flags);
app.ports.initialized.subscribe(latLngs => {
window.requestAnimationFrame(() => {
const map = new Map(
window.google,
document.getElementById("map")
);
map.registerLatLngs(latLngs);
});
});
});
As you can see, we’ve extracted interacting with the Google Map into a new
JavaScript class, Map. Its constructor accepts a reference to google, as
well as the element we’ll be embedding the map within. The registerLatLngs
function takes the list of coordinates, plots the markers, and updates map
boundaries so all points are displayed at the appropriate zoom level.
Of note is the use of window.requestAnimationFrame(); because we’re outside
of Elm’s rendering in the JavaScript side of this port, we wrap modification of
the Elm-controlled DOM in this callback to ensure smooth rendering.
Encoding Data Structures with Json.Encode
Looking at the type signature for initialized, we can see it expects a list
of GoogleMapMarker.Model. Ports in Elm can provide data to JavaScript in two
ways: send along only Elm primitives like String or Bool, or use the
Json.Encode.Value type to represent a JSON structure, and have the developer
define how a structure is encoded.
Let’s look at the GoogleMapMarker module to dig into encoding.
module GoogleMapMarker
exposing
( Model
, fromOffice
)
import Json.Encode as Encode
import Office.Model as Office
import Address.Model as Address
type alias Model =
Encode.Value
fromOffice : Office.Model -> Model
fromOffice ({ id } as office) =
Encode.object
[ ( "id", encodeOfficeId id )
, ( "latLng", encodeLatLon office.address.geo )
]
encodeOfficeId : Office.Id -> Encode.Value
encodeOfficeId (Office.Id id) =
Encode.int id
encodeLatLon : Address.LatLon -> Encode.Value
encodeLatLon latLon =
Encode.object
[ ( "lat", Encode.float latLon.latitude )
, ( "lng", Encode.float latLon.longitude )
]
Here, we alias Model to be Json.Encode.Value, and provide the function
fromOffice to handle encoding. The JSON generated should be straightforward:
{
"id": 1,
"latLng": {
"lat": 42.356157,
"lng": -71.061634
}
}
JavaScript Data Structures
With the JSON structure in place, let’s look quickly at the registerLatLngs
function from Map and see how the data is used in JavaScript.
export default class Map {
// ...
registerLatLngs(latLngs) {
const bounds = new this.google.maps.LatLngBounds();
latLngs.forEach(o => {
const gLatLng = o.latLng;
bounds.extend(gLatLng);
const marker = new this.google.maps.Marker({
position: gLatLng,
map: this.map
});
});
this.map.fitBounds(bounds);
}
}
Because registerLatLngs receives an array of JavaScript objects, we can
iterate over the list and build markers for Google Maps, as well as extend the
map bounds, in a single forEach. Google Maps expects a specific structure for
the coordinate, captured in latLng, so we pass it through directly.
Messages to Ports via update
With our markers rendered, the next thing we’ll cover is selecting an office in Elm, which should pan the map to the appropriate marker.
First, let’s create a new port for selecting a particular office:
port selectLatLon : GoogleMapMarker.Model -> Cmd a
In the update function, we’ll now handle the new message:
update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
case msg of
SelectOffice office ->
{ model | selectedOffice = Just office }
|> navigateMapsToOffice
-- other messages
navigateMapsToOffice : Model -> ( Model, Cmd Msg )
navigateMapsToOffice model =
let
cmd =
case model.selectedOffice of
Nothing ->
Cmd.none
Just office ->
selectLatLon <| GoogleMapMarker.fromOffice office
in
( model, cmd )
When a selected office exists, we use the selectLatLon port to notify the
JavaScript.
The underlying JavaScript needs to be updated a bit so the new port can also reference the map:
document.addEventListener("DOMContentLoaded", () => {
const app = Elm.Main.embed(document.getElementById("main"), flags);
let map; // make map available
app.ports.initialized.subscribe(latLngs => {
window.requestAnimationFrame(() => {
map = new Map(
window.google,
document.getElementById("map")
); // assign to map
map.registerLatLngs(latLngs);
});
});
app.ports.selectLatLon.subscribe(latLng => {
map.selectLatLng(latLng); // call a function on our now-available map
});
});
Within our Map, we add the function selectLatLng to handle map interaction:
export default class Map {
// ...
selectLatLng(o) {
this.map.panTo(o.latLng);
this.map.setZoom(12);
}
}
When selecting an office, the map now pans to the appropriate position!
JavaScript to Elm
With outgoing ports configured, the final step we need to take is capturing clicking on a marker to select the office Elm-side.
Subscriptions
While outgoing ports are handled as side-effects at the top-level update
function, accepting data from incoming ports is handled via subscriptions.
Let’s look at the incoming port and subscriptions functions to see how these
fit together:
subscriptions : Model -> Sub Msg
subscriptions _ =
clickedMapMarker (\id -> SelectOfficeById <| Office.Id id)
port clickedMapMarker : (Int -> a) -> Sub a
In this example, our subscriptions operate regardless of model state, and we
ingest an Int, transform it to an Office.Id, and wrap it in the
SelectOfficeById message. With this, we’ll need to wire up clicking on a
marker to send the id property, and handle this message in update.
update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
case msg of
SelectOfficeById id ->
selectOfficeById id model
|> navigateMapsToOffice
-- other messages
We’ll leverage navigateMapsToOffice again, which will ensure the map is
panned correctly.
We’ll also need to configure the callback when clicking on a marker, so let’s update the JavaScript:
document.addEventListener("DOMContentLoaded", () => {
const app = Elm.Main.embed(document.getElementById("main"), flags);
let map;
app.ports.initialized.subscribe(latLngs => {
window.requestAnimationFrame(() => {
map = new Map(
window.google,
document.getElementById("map"),
app.ports.clickedMapMarker.send // pass the inbound port function
);
map.registerLatLngs(latLngs);
});
});
app.ports.selectLatLon.subscribe(latLng => {
map.selectLatLng(latLng);
});
});
Finally, when we register the initial set of coordinates, we configure a listener on the “click” event on the marker:
export default class Map {
registerLatLngs(latLngs) {
const bounds = new this.google.maps.LatLngBounds();
latLngs.forEach(o => {
const gLatLng = o.latLng;
bounds.extend(gLatLng);
const marker = new this.google.maps.Marker({
position: gLatLng,
map: this.map
});
marker.addListener("click", () => {
this.clickedCallback(o.id); // trigger the callback with the office ID
});
});
this.map.fitBounds(bounds);
}
}
Similar to sending data out of the Elm application, it’s able to handle
decoding primitive data structures with ease. In this case, we take the
identifier (an Int) and do some simple wrapping to an Office.Id in the
subscriptions function above.
If you need to decode larger data structures, the process is largely the same, but you’ll need to build decoders for your Elm types, which you can read more about in another post.
What’s Next for Ports
Ports in Elm are a robust mechanism of sending data between the worlds of Elm and JavaScript. It supports primitive data structures out of the box, resulting in quick prototyping and validation, while allowing for the raw power of Elm’s JSON encoders and decoders when necessary.
Beyond encoding and decoding data, because data passed to Elm still flows
through the top-level update function, behavior triggered from JavaScript is
easy to reason about because it abides by the same rules as all other actions
within the application. Murphy Randle talked about a different approach to
ports at ElmConf 2017 that, while I haven’t tried, seems very appealing. I
encourage you to watch his talk.
