dillonkearns / elm-oembed / Oembed

Oembed Discovery

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.

Custom Providers

Explicitly looking up providers is preferrable to using Oembed Discovery because it:

  1. Gives you a Maybe type which you can check for to see if anything went wrong, and
  2. Doesn't require the extra HTTP request to do the Discovery.

Here'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")


type alias 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).