OEmbed
oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.
Usage
const { Keystone } = require('@keystonejs/keystone');
const { OEmbed } = require('@keystonejs/fields');
const { IframelyOEmbedAdapter } = require('@keystonejs/oembed-adapters');
const keystone = new Keystone(/* ... */);
const iframelyAdapter = new IframelyOEmbedAdapter({
apiKey: '...', // Get one from https://iframely.com
});
keystone.createList('User', {
fields: {
name: { type: Text },
portfolio: { type: OEmbed, adapter: iframelyAdapter },
// ..
},
});
Config
Option | Type | Default | Description |
---|---|---|---|
isRequired | Boolean | false | Does this field require a value? |
GraphQL
Will add the following to the GraphQL schema:
type OEmbedThumbnail {
# A URL to a thumbnail image
url: String!
# The width of the thumbnail
width: String!
# The height of the thumbnail
height: String!
}
type OEmbedAuthor {
# The name of the author/owner of the resource.
name: String
# A URL for the author/owner of the resource.
url: String
}
type OEmbedProvider {
# The name of the resource provider.
name: String
# The url of the resource provider.
url: String
}
interface OEmbed {
# The resource type. One of 'photo'/'video'/'link'/'rich'
type: String
# The original input URL which the oEmbed data was generated from
originalUrl: String!
# The oEmbed version number. Will be 1.0.
version: String
# A text title, describing the resource.
title: String
# The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
cacheAge: String
# The resource provider.
provider: OEmbedProvider
# The author/owner of the resource.
author: OEmbedAuthor
# An optional thumbnail image representing the resource.
thumbnail: OEmbedThumbnail
}
type OEmbedPhoto implements OEmbed {
type: String
originalUrl: String
version: String
title: String
cacheAge: String
provider: OEmbedProvider
author: OEmbedAuthor
thumbnail: OEmbedThumbnail
# OEmbedPhoto specific fields
url: String
width: String
height: String
}
type OEmbedVideo implements OEmbed {
type: String
originalUrl: String
version: String
title: String
cacheAge: String
provider: OEmbedProvider
author: OEmbedAuthor
thumbnail: OEmbedThumbnail
# OEmbedVideo specific fields
html: String
width: String
height: String
}
type OEmbedLink implements OEmbed {
type: String
originalUrl: String
version: String
title: String
cacheAge: String
provider: OEmbedProvider
author: OEmbedAuthor
thumbnail: OEmbedThumbnail
}
type OEmbedRich implements OEmbed {
type: String
originalUrl: String
version: String
title: String
cacheAge: String
provider: OEmbedProvider
author: OEmbedAuthor
thumbnail: OEmbedThumbnail
# OEmbedRich specific fields
html: String
width: String
height: String
}
input UserCreateInput {
# A URL which will be transformed into the oEmbed types above by the provider
portfolio: String
}
type User {
portfolio: OEmbed
}
type Query {
User(where: UserWhereUniqueInput!): User
}
type Mutation {
createUser(data: UserCreateInput): User
}
Create a new User with an OEmbed
type:
mutation {
createUser(data: { portfolio: "https://flickr.com/foobar" }) {
portfolio {
__typename
type
originalUrl
title
thumbnail {
url
width
height
}
provider {
name
}
... on OEmbedPhoto {
url
width
height
}
... on OEmbedVideo {
html
width
height
}
... on OEmbedRich {
html
width
height
}
# NOTE: No OEmbedLink fragment - it doesn't specify any extra fields
}
}
}
Will result in something like:
{
data: {
createUser: {
portfolio: {
__typename: "OEmbedPhoto",
type: "photo",
originalUrl: "https://flickr.com/foobar",
title: "My Glamour Shot",
thumbnail: {
url: "...",
width: "90",
height: "90",
},
provider: {
name: "Flickr",
},
// because it's a 'photo' type, we get url/width/height:
url: "...",
width: "1024",
height: "400",
}
}
}
}