billstclair / elm-geolocation / PortFunnel.Geolocation

Find out about where a user’s device is located. Geolocation API.

Location


type alias Location =
{ latitude : Basics.Float
, longitude : Basics.Float
, accuracy : Basics.Float
, altitude : Maybe Altitude
, movement : Maybe Movement
, timestamp : Time.Posix 
}

All available details of the device's current location in the world.


type alias Altitude =
{ value : Basics.Float
, accuracy : Basics.Float 
}

The altitude in meters relative to sea level is held in value. The accuracy field describes how accurate value is, also in meters.


type Movement
    = Static
    | Moving ({ speed : Basics.Float, degreesFromNorth : Basics.Float })

Describes the motion of the device. If the device is not moving, this will just be Static. If the device is moving, you will see the speed in meters per second and the degreesFromNorth in degrees.

Note: The degreesFromNorth value goes clockwise: 0° represents true north, 90° is east, 180° is south, 270° is west, etc.


type alias JSVersion =
{ v4_1 : () }

This is used to force a major version bump when the JS changes.

You'll usually not use it for anything.

Subscribe to Changes

watchChanges : Message

Enable receipt of changes as the browser device moves.

stopWatching : Message

Stop receiving changes as the browser device moves.

Get Current Location

now : Message

Return a message to send to receive a location now.


type Error
    = PermissionDenied String
    | LocationUnavailable String
    | Timeout String

The now functions may fail for a variety of reasons.

* The user may reject the request to use their location.
* It may be impossible to get a location.
* If you set a timeout in the `Options` the request may just take too long.

In each case, the browser will provide a string with additional information.

Options

nowWith : Options -> Message

Return a message to send to receive a location now with options.


type alias Options =
{ enableHighAccuracy : Basics.Bool
, timeout : Maybe Basics.Int
, maximumAge : Maybe Basics.Int 
}

There are a couple options you can mess with when requesting location data.

defaultOptions : Options

The options you will want in 99% of cases. This will get you faster results, less battery drain, no surprise failures due to timeouts, and no surprising cached results.

{ enableHighAccuracy = False
, timeout = Nothing
, maximumAge = Nothing
}

The Standard PortFunnel interface

Types


type Message

Messages sent between Elm and the port JavaScript.

Opaque type, returned by now, nowWith, changes, stopChanges.


type State

Internal module state.


type Response
    = LocationResponse Location
    | ErrorResponse Error
    | NoResponse

Responses.

LocationResponse is returned from a now or nowWith message, and for changes if you've subscriped with a changes message.

ErrorResponse is returned if there is an error.

NoResponse is sent if the processing code receives a message that is not a valid response message. Shouldn't happen.

Components of a PortFunnel.FunnelSpec

moduleName : String

The name of this module: "Geolocation".

moduleDesc : PortFunnel.ModuleDesc Message State Response

Our module descriptor.

commander : (PortFunnel.GenericMessage -> Platform.Cmd.Cmd msg) -> Response -> Platform.Cmd.Cmd msg

Responsible for sending a CmdResponse back througt the port.

Called by PortFunnel.appProcess for each response returned by process.

Always returns Cmd.none.

Initial State

initialState : State

The initial, empty state, so the application can initialize its state.

Sending a Message out the Cmd Port

send : (Json.Encode.Value -> Platform.Cmd.Cmd msg) -> Message -> Platform.Cmd.Cmd msg

Send a Message through a Cmd port.

Conversion to Strings

toString : Message -> String

Convert a Message to a nice-looking human-readable string.

toJsonString : Message -> String

Convert a Message to the same JSON string that gets sent

over the wire to the JS code.

Simulator

makeSimulatedCmdPort : (Json.Encode.Value -> msg) -> Json.Encode.Value -> Platform.Cmd.Cmd msg

Make a simulated Cmd port.

Non-standard Functions

isLoaded : State -> Basics.Bool

Returns true if a Startup message has been processed.

This is sent by the port code after it has initialized.

errorToString : Error -> String

Convert an Error to a string for simple printing.