If you use Oembed.view
, you get back a Maybe
value because it is looking up
a list of provider schemes (like https://youtube.com/watch/abc123
would
find a youtube scheme) and returning Nothing
if it doesn't find one. This is nice because you can fail your build if there are
any issues.
But some services may not be registered in the official list of providers.
These sites may instead use <link rel="alternate">
tags in their HTML <head>
tags to become discoverable.
That is to say, it will contain the information needed to get an API call to get the oembed content given a particular HTML page.
This is handy, but it means that this information is not conveniently accessible in Elm. So it's preferrable to
use Oembed.view
, but Oembed.discover
is provided to explicitly.
Also note that it requires an additional HTTP request to fetch the HTML page and process before it makes
the Oembed API request based on that page's <head>
tags.
view : List Provider -> Maybe { maxWidth : Basics.Int, maxHeight : Basics.Int } -> String -> Maybe (Html msg)
Lookup a way to handle the passed in url using the hardcoded list
of oembed provider schemes. If none is found, it will return Nothing
. Otherwise,
you will have correctly rendered Oembed content (assuming no unexpected errors occur).
viewOrDiscover : List Provider -> Maybe { maxWidth : Basics.Int, maxHeight : Basics.Int } -> String -> Html msg
Look for an oembed provider in the hardcoded list. If none is found,
fallback to trying to discover the oembed url. Note
that discovery will fail if the url passed in doesn't not link to a page
that contains the <link>
tag in the format used for discovery. So even
though those doesn't return Maybe (Html msg)
, it may fail to render oembed content.
Explicitly looking up providers is preferrable to using Oembed Discovery because it:
Maybe
type which you can check for to see if anything went wrong, andHere's an example of supplying a custom provider.
import Html
import Oembed exposing (Provider)
import Regex
customProviders : List Provider
customProviders =
[ { url = "https://ellie-app.com/oembed/"
, schemes =
[ Regex.fromString "https://ellie-app\\.com/.*" |> Maybe.withDefault Regex.never ]
}
]
ellieView =
Oembed.view customProviders Nothing "https://ellie-app.com/4Xt4jdgtnZ2a1"
|> Maybe.withDefault (Html.text "Couldn't find oembed provider")
{ schemes : List Regex
, url : String
}
elm-oembed
has a default list of providers from the official list.
You can add custom ones (see the above section in this docs page).