Alchemy.Embed (alchemy v0.6.8)

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

Represents a file attached to an embed.

Represents the author of an embed.

Represents a field in an embed.

Represents an Embed footer.

Represents the image of an embed.

Represents the provider of an embed.

t()

Represents the thumnail of an embed.

Represents a video attached to an embed.

Functions

Adds author information to an embed.

Sets the color of an embed

Adds a description to an embed.

Adds a field to an embed.

Adds a footer to an embed.

Sets the main image of the embed.

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

Adds a thumbnail to an embed.

Adds a timestamp to an embed.

Adds a title to an embed.

Sets the url for an embed.

Link to this section Types

Link to this type

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

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

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.

Specs

footer() :: %Alchemy.Embed.Footer{
  icon_url: url(),
  proxy_icon_url: url(),
  text: String.t()
}

Represents an Embed footer.

  • text

    The text of the footer

  • icon_url

    The url of the image in the footer

  • proxy_icon_url

    The proxied url of the footer's icon. Setting this when sending an embed serves no purpose.

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.

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

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()
}

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

Specs

url() :: String.t()

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

Link to this function

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
Link to this function

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
Link to this function

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
Link to this function

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")
Link to this function

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
Link to this function

image(embed, url)

Specs

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

Sets the main image of the embed.

Examples

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

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
Link to this function

thumbnail(embed, url)

Specs

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

Adds a thumbnail to an embed.

Examples

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

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())

Link to this function

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
Link to this function

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