Alchemy.Embed (alchemy v0.7.0)

A module containing structs and functions relative to Embeds.

Embeds allow you to format messages in a structured, and quite pretty way; much more than can be done with simple text. For a basic idea of how embeds work, check this link.

Example Usage

Cogs.def embed do
  %Embed{}
  |> title("The BEST embed")
  |> description("the best description")
  |> image("http://i.imgur.com/4AiXzf8.jpg")
  |> Embed.send
end

Note that this is equivalent to:

Cogs.def embed do
  %Embed{title: "The BEST embed",
         description: "the best description",
         image: "http://i.imgur.com/4AiXzf8.jpg"}
  |> Embed.send
end

File Attachments

The fields that take urls can also take a special "attachment" url referencing files uploaded alongside the embed.

Cogs.def foo do
  %Embed{}
  |> image("attachment://foo.png")
  |> Embed.send("", file: "foo.png")
end

Link to this section Summary

Types

attachment()

Represents a file attached to an embed.

author()

Represents the author of an embed.

field()

Represents a field in an embed.

footer()

Represents an Embed footer.

image()

Represents the image of an embed.

provider()

Represents the provider of an embed.

t()

thumbnail()

Represents the thumnail of an embed.

url()

video()

Represents a video attached to an embed.

Functions

author(embed, author)

Adds author information to an embed.

color(embed, integer)

Sets the color of an embed

description(embed, string)

Adds a description to an embed.

field(embed, name, value, options \\ [])

Adds a field to an embed.

footer(embed, footer)

Adds a footer to an embed.

image(embed, url)

Sets the main image of the embed.

send(embed, content \\ "", options \\ [])

Sends an embed to the same channel as the message triggering a command.

thumbnail(embed, url)

Adds a thumbnail to an embed.

timestamp(embed, time)

Adds a timestamp to an embed.

title(embed, string)

Adds a title to an embed.

url(embed, url)

Sets the url for an embed.

Link to this section Types

attachment()

Specs

attachment() :: %Alchemy.Attachment{
  filename: String.t(),
  height: Integer | nil,
  id: String.t(),
  proxy_url: url(),
  size: Integer,
  url: url(),
  width: Integer | nil
}

Represents a file attached to an embed.

id
The attachment id
filename
The name of the file attached
size
The size of the file attached
url
The source url of a file
proxy_url
A proxied url of a file
height
The height of the file, if it's an image
width
The width of a file, if it's an image

author()

Specs

author() :: %Alchemy.Embed.Author{
  icon_url: url(),
  name: String.t(),
  proxy_icon_url: url(),
  url: url()
}

Represents the author of an embed.

name
The name of the author
url
The author's url
icon_url
A link to the author's icon image
proxy_icon_url
A proxied url for the author's icon image

field()

Specs

field() :: %Alchemy.Embed.Field{
  inline: Boolean,
  name: String.t(),
  value: String.t()
}

Represents a field in an embed.

name
The title of the field
value
The text of the field
inline
Whether or not the field should be aligned with other inline fields.

image()

Specs

image() :: %Alchemy.Embed.Image{
  height: Integer,
  proxy_url: url(),
  url: url(),
  width: Integer
}

Represents the image of an embed.

url
A link to this image

The following parameters shouldn't be set when sending embeds:

proxy_url
A proxied url of the image
height
The height of the image.
width
The width of the image.

provider()

Specs

provider() :: %Alchemy.Embed.Provider{name: String.t(), url: url()}

Represents the provider of an embed.

This is usually comes from a linked resource (youtube video, etc.)

name
The name of the provider
url
The source of the provider

t()

Specs

t() :: %Alchemy.Embed{
  author: author(),
  color: Integer,
  description: String.t(),
  fields: [field()],
  footer: footer(),
  image: image(),
  provider: provider(),
  thumbnail: thumbnail(),
  timestamp: String.t(),
  title: String.t(),
  type: String.t(),
  url: String.t(),
  video: video()
}

thumbnail()

Specs

thumbnail() :: %Alchemy.Embed.Thumbnail{
  height: Integer,
  proxy_url: url(),
  url: url(),
  width: Integer
}

Represents the thumnail of an embed.

url
A link to the thumbnail image.
proxy_url
A proxied link to the thumbnail image
height
The height of the thumbnail
width
The width of the thumbnail

url()

Specs

url() :: String.t()

video()

Specs

video() :: %Alchemy.Embed.Video{height: Integer, url: url(), width: Integer}

Represents a video attached to an embed.

Users can't set this themselves.

url
The source of the video
height
The height of the video
width
The width of the video

Link to this section Functions

author(embed, author)

Specs

author(
  t(),
  [name: String.t(), url: url(), icon_url: url()] | Alchemy.Embed.Author.t()
) :: t()

Adds author information to an embed.

Note that the proxy_icon_url, height, and width fields have no effect, when using a pre-made Author struct.

Options

name
The name of the author.
url
The url of the author.
icon_url
The url of the icon to display.

Examples

Cogs.def embed do
  %Embed{}
  |> author(name: "John",
            url: "https://discord.com/developers"
            icon_url: "http://i.imgur.com/3nuwWCB.jpg")
  |> Embed.send
end

color(embed, integer)

Specs

color(t(), Integer) :: t()

Sets the color of an embed

Color should be 3 byte integer, with each byte representing a single color component; i.e. 0xRrGgBb

Examples

Cogs.def embed do
  {:ok, message} =
    %Embed{description: "the best embed"}
    |> color(0xc13261)
    |> Embed.send
  Process.sleep(2000)
  Client.edit_embed(message, embed |> color(0x5aa4d4))
end

description(embed, string)

Specs

description(t(), String.t()) :: t()

Adds a description to an embed.

Cogs.def embed(description) do
  %Embed{}
  |> title("generic title")
  |> description(description)
  |> Embed.send
end

field(embed, name, value, options \\ [])

Adds a field to an embed.

Fields are appended when using this method, so the order you pipe them in, is the order they'll end up when sent. The name and value must be non empty strings. You can have a maximum of 25 fields.

Parameters

name
The title of the embed.
value
The text of the field

Options

inline
When setting this to true, up to 3 fields can appear side by side, given they are all inlined.

Examples

%Embed{}
|> field("Field1", "the best field!")
|> field("Inline1", "look a field ->")
|> field("Inline2", "<- look a field")

footer(embed, footer)

Specs

footer(t(), [text: String.t(), icon_url: url()] | Alchemy.Embed.Footer.t()) ::
  t()

Adds a footer to an embed.

Note that the proxy_icon_url field has no effect, when using a pre-made Footer struct.

Options

text
The content of the footer.
icon_url
The icon the footer should have

Examples

Cogs.def you do
  %Embed{}
  |> footer(text: "<- this is you",
            icon_url: message.author |> User.avatar_url)
  |> Embed.send
end

image(embed, url)

Specs

image(t(), url()) :: t()

Sets the main image of the embed.

Examples

%Embed{}
|> image("http://i.imgur.com/4AiXzf8.jpg")

send(embed, content \\ "", options \\ [])

(macro)

Sends an embed to the same channel as the message triggering a command.

This macro can't be used outside of Alchemy.Cogs commands.

See Alchemy.Client.send_message/3 for a list of options that can be passed to this macro.

Examples

Cogs.def blue do
  %Embed{}
  |> color(0x1d3ad1)
  |> description("Hello!")
  |> Embed.send("Here's an embed, and a file", file: "foo.txt")
end

thumbnail(embed, url)

Specs

thumbnail(t(), url()) :: t()

Adds a thumbnail to an embed.

Examples

%Embed{}
|> thumbnail("http://i.imgur.com/4AiXzf8.jpg")

timestamp(embed, time)

Specs

timestamp(t(), DateTime.t()) :: DateTime.t()

Adds a timestamp to an embed.

Note that the Datetime object will get converted to an iso8601 formatted string.

Examples

%Embed{} |> timestamp(DateTime.utc_now())

title(embed, string)

Specs

title(t(), String.t()) :: t()

Adds a title to an embed.

Examples

Cogs.def title(string) do
  %Embed{}
  |> title(string)
  |> Embed.send
end

url(embed, url)

Specs

url(t(), url()) :: t()

Sets the url for an embed.

Examples

Cogs.def embed(url) do
  %Embed{}
  |> url(url)
  |> Embed.send
end