adaptivecard

package
v2.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2023 License: MIT Imports: 11 Imported by: 26

Documentation

Overview

Package adaptivecard provides support for generating Microsoft Teams messages using the Adaptive Card format.

See the provided examples in this repo, the Godoc generated documentation at https://pkg.go.dev/github.com/atc0005/go-teams-notify/v2 and the following resources for more information:

https://adaptivecards.io/explorer https://docs.microsoft.com/en-us/adaptive-cards/ https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/getting-started https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model https://docs.microsoft.com/en-us/adaptive-cards/getting-started/bots https://docs.microsoft.com/en-us/adaptive-cards/resources/principles https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#mention-support-within-adaptive-cards https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/what-are-cards https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#send-adaptive-cards-using-an-incoming-webhook https://stackoverflow.com/questions/50753072/microsoft-teams-webhook-generating-400-for-adaptive-card

Index

Constants

View Source 
const (
	// TypeAdaptiveCard is the supported type value for an Adaptive Card.
	TypeAdaptiveCard string = "AdaptiveCard"

	// AdaptiveCardSchema represents the URI of the Adaptive Card schema.
	AdaptiveCardSchema string = "http://adaptivecards.io/schemas/adaptive-card.json"

	// AdaptiveCardMaxVersion represents the highest supported version of the
	// Adaptive Card schema supported in Microsoft Teams messages.
	//
	// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards
	// https://adaptivecards.io/designer
	AdaptiveCardMaxVersion  float64 = 1.5
	AdaptiveCardMinVersion  float64 = 1.0
	AdaptiveCardVersionTmpl string  = "%0.1f"
)

Card & TopLevelCard specific constants.

View Source 
const (
	// TypeMention is the type for a user mention for a Adaptive Card Message.
	TypeMention string = "mention"

	// MentionTextFormatTemplate is the expected format of the Mention.Text
	// field value.
	MentionTextFormatTemplate string = "<at>%s</at>"
)

Mention constants.

View Source 
const (

	// AttachmentContentType is the supported type value for an attached
	// Adaptive Card for a Microsoft Teams message.
	AttachmentContentType string = "application/vnd.microsoft.card.adaptive"

	AttachmentLayoutList     string = "list"
	AttachmentLayoutCarousel string = "carousel"
)

Attachment constants.

https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference https://docs.microsoft.com/en-us/dotnet/api/microsoft.bot.schema.attachmentlayouttypes https://docs.microsoft.com/en-us/javascript/api/botframework-schema/attachmentlayouttypes https://github.com/matthidinger/ContosoScubaBot/blob/master/Cards/1-Schools.JSON

View Source 
const (
	// TextBlockStyleDefault indicates that the TextBlock uses the default
	// style which provides no special styling or behavior.
	TextBlockStyleDefault string = "default"

	// TextBlockStyleHeading indicates that the TextBlock is a heading. This
	// will apply the heading styling defaults and mark the text block as a
	// heading for accessibility.
	TextBlockStyleHeading string = "heading"
)

TextBlock specific constants. https://adaptivecards.io/explorer/TextBlock.html

View Source 
const (
	// TypeColumn is the type for an Adaptive Card Column.
	TypeColumn string = "Column"

	// ColumnWidthAuto indicates that a column's width should be determined
	// automatically based on other columns in the column group.
	ColumnWidthAuto string = "auto"

	// ColumnWidthStretch indicates that a column's width should be stretched
	// to fill the enclosing column group.
	ColumnWidthStretch string = "stretch"

	// ColumnWidthPixelRegex is a regular expression pattern intended to match
	// specific pixel width values (e.g., 50px).
	ColumnWidthPixelRegex string = "^[0-9]+px$"

	// ColumnWidthPixelWidthExample is an example of a valid pixel width for a
	// Column.
	ColumnWidthPixelWidthExample string = "50px"
)

Column specific constants. https://adaptivecards.io/explorer/Column.html

View Source 
const (
	SizeSmall      string = "small"
	SizeDefault    string = "default"
	SizeMedium     string = "medium"
	SizeLarge      string = "large"
	SizeExtraLarge string = "extraLarge"
)

Text size for TextBlock or TextRun elements.

View Source 
const (
	WeightBolder  string = "bolder"
	WeightLighter string = "lighter"
	WeightDefault string = "default"
)

Text weight for TextBlock or TextRun elements.

View Source 
const (
	ColorDefault   string = "default"
	ColorDark      string = "dark"
	ColorLight     string = "light"
	ColorAccent    string = "accent"
	ColorGood      string = "good"
	ColorWarning   string = "warning"
	ColorAttention string = "attention"
)

Supported colors for TextBlock or TextRun elements.

View Source 
const (
	ImageStyleDefault string = ""
	ImageStylePerson  string = ""
)

Image specific constants. https://adaptivecards.io/explorer/Image.html

View Source 
const (
	ChoiceInputStyleCompact  string = "compact"
	ChoiceInputStyleExpanded string = "expanded"
	ChoiceInputStyleFiltered string = "filtered" // Introduced in version 1.5
)

ChoiceInput specific constants.

View Source 
const (
	TextInputStyleText     string = "text"
	TextInputStyleTel      string = "tel"
	TextInputStyleURL      string = "url"
	TextInputStyleEmail    string = "email"
	TextInputStylePassword string = "password" // Introduced in version 1.5
)

TextInput specific constants.

View Source 
const (
	ContainerStyleDefault   string = "default"
	ContainerStyleEmphasis  string = "emphasis"
	ContainerStyleGood      string = "good"
	ContainerStyleAttention string = "attention"
	ContainerStyleWarning   string = "warning"
	ContainerStyleAccent    string = "accent"
)

Container specific constants.

View Source 
const (
	SpacingDefault    string = "default"
	SpacingNone       string = "none"
	SpacingSmall      string = "small"
	SpacingMedium     string = "medium"
	SpacingLarge      string = "large"
	SpacingExtraLarge string = "extraLarge"
	SpacingPadding    string = "padding"
)

Supported spacing values for FactSet, Container and other container element types.

View Source 
const (

	// TeamsActionsDisplayLimit is the observed limit on the number of visible
	// URL "buttons" in a Microsoft Teams message.
	//
	// Unlike the MessageCard format which has a clearly documented limit of 4
	// actions, testing reveals that Desktop / Web displays 6 without the
	// option to expand and see any additional defined actions. Mobile
	// displays 6 with an ellipsis to expand into a list of other Actions.
	//
	// This results in a maximum limit of 6 actions in the Actions array for a
	// Card.
	//
	// A workaround is to create multiple ActionSet elements and limit the
	// number of Actions in each set ot 6.
	//
	// https://docs.microsoft.com/en-us/outlook/actionable-messages/message-card-reference#actions
	TeamsActionsDisplayLimit int = 6

	// TypeActionExecute is an action that gathers input fields, merges with
	// optional data field, and sends an event to the client. Clients process
	// the event by sending an Invoke activity of type adaptiveCard/action to
	// the target Bot. The inputs that are gathered are those on the current
	// card, and in the case of a show card those on any parent cards. See
	// Universal Action Model documentation for more details:
	// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model
	//
	// TypeActionExecute was introduced in Adaptive Cards schema version 1.4.
	// TypeActionExecute actions may not render with earlier versions of the
	// Teams client.
	TypeActionExecute string = "Action.Execute"

	// ActionExecuteMinCardVersionRequired is the minimum version of the
	// Adaptive Card schema required to support Action.Execute.
	ActionExecuteMinCardVersionRequired float64 = 1.4

	// TypeActionSubmit is used in Adaptive Cards schema version 1.3 and
	// earlier or as a fallback for TypeActionExecute in schema version 1.4.
	// TypeActionSubmit is not supported in Incoming Webhooks.
	TypeActionSubmit string = "Action.Submit"

	// TypeActionOpenURL (when invoked) shows the given url either by
	// launching it in an external web browser or showing within an embedded
	// web browser.
	TypeActionOpenURL string = "Action.OpenUrl"

	// TypeActionShowCard defines an AdaptiveCard which is shown to the user
	// when the button or link is clicked.
	TypeActionShowCard string = "Action.ShowCard"

	// TypeActionToggleVisibility toggles the visibility of associated card
	// elements.
	TypeActionToggleVisibility string = "Action.ToggleVisibility"
)

Supported Actions

View Source 
const (
	TypeFallbackActionExecute          string = TypeActionExecute
	TypeFallbackActionOpenURL          string = TypeActionOpenURL
	TypeFallbackActionShowCard         string = TypeActionShowCard
	TypeFallbackActionSubmit           string = TypeActionSubmit
	TypeFallbackActionToggleVisibility string = TypeActionToggleVisibility

	// TypeFallbackOptionDrop causes this element to be dropped immediately
	// when unknown elements are encountered. The unknown element doesn't
	// bubble up any higher.
	TypeFallbackOptionDrop string = "drop"
)

Supported Fallback options.

View Source 
const (
	TypeElementActionSet      string = "ActionSet"
	TypeElementColumnSet      string = "ColumnSet"
	TypeElementContainer      string = "Container"
	TypeElementFactSet        string = "FactSet"
	TypeElementImage          string = "Image"
	TypeElementImageSet       string = "ImageSet"
	TypeElementInputChoiceSet string = "Input.ChoiceSet"
	TypeElementInputDate      string = "Input.Date"
	TypeElementInputNumber    string = "Input.Number"
	TypeElementInputText      string = "Input.Text"
	TypeElementInputTime      string = "Input.Time"
	TypeElementInputToggle    string = "Input.Toggle"
	TypeElementMedia          string = "Media"         // Introduced in version 1.1 (TODO: Is this supported in Teams message?)
	TypeElementRichTextBlock  string = "RichTextBlock" // Introduced in version 1.2
	TypeElementTextBlock      string = "TextBlock"
	TypeElementTextRun        string = "TextRun" // Introduced in version 1.2
)

Valid types for an Adaptive Card element. Not all types are supported by Microsoft Teams.

https://adaptivecards.io/explorer/AdaptiveCard.html

TODO: Confirm whether all types are supported. NOTE: Based on current docs, version 1.4 is the latest supported at this time. https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model#schema

View Source 
const (
	MSTeamsWidthFull string = "Full"
)

Supported width values for the msteams property used in in Adaptive Card messages sent via Microsoft Teams.

View Source 
const (
	// TypeMessage is the type for an Adaptive Card Message.
	TypeMessage string = "message"
)

General constants.

Variables

View Source 
var (
	// ErrInvalidType indicates that an invalid type was specified.
	ErrInvalidType = errors.New("invalid type value")

	// ErrInvalidFieldValue indicates that an invalid value was specified.
	ErrInvalidFieldValue = errors.New("invalid field value")

	// ErrMissingValue indicates that an expected value was missing.
	ErrMissingValue = errors.New("missing expected value")

	// ErrValueNotFound indicates that a requested value was not found.
	ErrValueNotFound = errors.New("requested value not found")
)

Sentinel errors for this package.

Functions

func AddMention 

func AddMention(card *Card, textBlock *Element, prependText bool, separator string, mentions ...Mention) error

AddMention adds one or more provided user mentions to the specified Card. The Text field for the specified TextBlock element is updated with the Mention Text. If specified, the Mention Text is prepended, otherwise appended. If specified, a custom separator is used between the Mention Text and the TextBlock Text field, otherwise the default separator is used.

NOTE: This function "registers" the specified Mention values with the Card and updates the specified textBlock element, however the caller is responsible for ensuring that the specified textBlock element is added to the Card.

An error is returned if specified Mention values fail validation, or one of Card or Element pointers are null.

func ConvertBreakToEOL 

func ConvertBreakToEOL(s string) string

ConvertBreakToEOL converts <br> statements into \n\n to provide comparable spacing in Adaptive Card TextBlock elements.

This function is intended for processing text for use in an Adaptive Card TextBlock element. The goal is to provide spacing in rendered text display comparable to native display.

The primary use case of this function is to process text that was previously formatted in preparation for use in a MessageCard; the MessageCard format supports <br> statements for text spacing/formatting where the Adaptive Card format does not.

https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features

func ConvertEOL 

func ConvertEOL(s string) string

ConvertEOL converts \r\n (windows), \r (mac) and \n (unix) into \n\n.

This function is intended for processing text for use in an Adaptive Card TextBlock element. The goal is to provide spacing in rendered text display comparable to native display.

NOTE: There are known discrepancies in the way that Microsoft Teams renders text in desktop, web and mobile, so even with using this helper function some differences are to be expected.

https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#newlines-for-adaptive-cards https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features

Types

type Action 

type Action struct {

	// Type is required; specific values are supported.
	//
	// Action.Submit is not supported for Incoming Webhooks.
	//
	// Action.Execute was added in Adaptive Card schema version 1.4. which
	// Teams MAY not fully support.
	//
	// The supported actions are Action.OpenURL, Action.ShowCard,
	// Action.ToggleVisibility, and Action.Execute (see above).
	//
	// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference#support-for-adaptive-cards
	// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model#schema
	Type string `json:"type"`

	// ID is a unique identifier associated with this Action.
	ID string `json:"id,omitempty"`

	// Title is a label for the button or link that represents this action.
	Title string `json:"title,omitempty"`

	// URL to open; required for the Action.OpenUrl type, optional for other
	// action types.
	URL string `json:"url,omitempty"`

	// Fallback describes what to do when an unknown element is encountered or
	// the requirements of this or any children can't be met.
	Fallback string `json:"fallback,omitempty"`

	// Card property is used by Action.ShowCard type.
	//
	// NOTE: Based on a review of JSON content, it looks like `ActionCard` is
	// really just a `Card` type.
	//
	// refs https://github.com/matthidinger/ContosoScubaBot/blob/master/Cards/SubscriberNotification.JSON
	Card *Card `json:"card,omitempty"`
}

Action represents an action that a user may take on a card. Actions typically get rendered in an "action bar" at the bottom of a card.

https://adaptivecards.io/explorer/ActionSet.html https://adaptivecards.io/explorer/AdaptiveCard.html https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference

TODO: Extend with additional supported fields.

func NewActionOpenURL 

func NewActionOpenURL(url string, title string) (Action, error)

NewActionOpenURL creates a new Action.OpenURL value using the provided URL and title. An error is returned if invalid values are supplied.

func (Action) Validate 

func (a Action) Validate() error

Validate asserts that fields have valid values.

type Actions 

type Actions []Action

Actions is a collection of Action values.

func (Actions) Validate 

func (a Actions) Validate() error

Validate asserts that the collection of Action values are all valid.

type Attachment 

type Attachment struct {

	// ContentType is required; must be set to
	// "application/vnd.microsoft.card.adaptive".
	ContentType string `json:"contentType"`

	// ContentURL appears to be related to support for tabs. Most examples
	// have this value set to null.
	//
	// TODO: Update this description with confirmed details.
	ContentURL NullString `json:"contentUrl,omitempty"`

	// Content represents the content of an Adaptive Card.
	//
	// TODO: Should this be a pointer?
	Content TopLevelCard `json:"content"`
}

Attachment represents an attached Adaptive Card for a Microsoft Teams message.

func (Attachment) Validate 

func (a Attachment) Validate() error

Validate asserts that fields have valid values.

type Attachments 

type Attachments []Attachment

Attachments is a collection of Adaptive Cards for a Microsoft Teams message.

func (Attachments) Validate 

func (a Attachments) Validate() error

Validate asserts that the collection of Attachment values are all valid.

type Card 

type Card struct {

	// Type is required; must be set to "AdaptiveCard"
	Type string `json:"type"`

	// Schema represents the URI of the Adaptive Card schema.
	Schema string `json:"$schema"`

	// Version is required for top-level cards (i.e., the outer card in an
	// attachment); the schema version that the content for an Adaptive Card
	// requires.
	//
	// The TopLevelCard type is a superset of the Card type and asserts that
	// this field is properly set, whereas the validation logic for this
	// (Card) type skips that assertion.
	Version string `json:"version"`

	// FallbackText is the text shown when the client doesn't support the
	// version specified (may contain markdown).
	FallbackText string `json:"fallbackText,omitempty"`

	// Body represents the body of an Adaptive Card. The body is made up of
	// building-blocks known as elements. Elements can be composed to create
	// many types of cards. These elements are shown in the primary card
	// region.
	Body []Element `json:"body"`

	// Actions is a collection of actions to show in the card's action bar.
	// The action bar is displayed at the bottom of a Card.
	//
	// NOTE: The max display limit has been observed to be a fixed value for
	// web/desktop app and a matching value as an initial display limit for
	// mobile app with the option to expand remaining actions in a list.
	//
	// This value is recorded in this package as "TeamsActionsDisplayLimit".
	//
	// To work around this limit, create multiple ActionSets each limited to
	// the value of TeamsActionsDisplayLimit.
	Actions []Action `json:"actions,omitempty"`

	// MSTeams is a container for properties specific to Microsoft Teams
	// messages, including formatting properties and user mentions.
	//
	// NOTE: Using pointer in order to omit unused field from JSON output.
	// https://stackoverflow.com/questions/18088294/how-to-not-marshal-an-empty-struct-into-json-with-go
	// MSTeams *MSTeams `json:"msteams,omitempty"`
	//
	// TODO: Revisit this and use a pointer if remote API doesn't like
	// receiving an empty object, though brief testing doesn't show this to be
	// a problem.
	MSTeams MSTeams `json:"msteams,omitempty"`

	// MinHeight specifies the minimum height of the card.
	MinHeight string `json:"minHeight,omitempty"`

	// VerticalContentAlignment defines how the content should be aligned
	// vertically within the container. Only relevant for fixed-height cards,
	// or cards with a minHeight specified. If MinHeight field is specified,
	// this field is required.
	VerticalContentAlignment string `json:"verticalContentAlignment,omitempty"`
}

Card represents the content of an Adaptive Card. The TopLevelCard is a superset of this one, asserting that the Version field is properly set. That type is used exclusively for Message Attachments. This type is used directly for the Action.ShowCard Card field.

func NewCard 

func NewCard() Card

NewCard creates and returns an empty Card.

func NewMentionCard 

func NewMentionCard(displayName string, id string, msgText string) (Card, error)

NewMentionCard creates a new Card with user Mention using the given displayName, ID and message text. An error is returned if provided values are insufficient to create the user mention.

func NewTextBlockCard 

func NewTextBlockCard(text string, title string, wrap bool) (Card, error)

NewTextBlockCard creates a new Card using the specified text and optional title. If specified, the TextBlock has text wrapping enabled.

func (*Card) AddAction 

func (c *Card) AddAction(prepend bool, actions ...Action) error

AddAction adds one or more provided Actions to the associated Card. If specified, the Action values are prepended to the Card (as a collection retaining current order), otherwise appended.

NOTE: The max display limit for a Card's actions array has been observed to be a fixed value for web/desktop app and a matching value as an initial display limit for mobile app with the option to expand remaining actions in a list.

This value is recorded in this package as "TeamsActionsDisplayLimit".

Consider adding Action values to one or more ActionSet elements as needed and include within the Card.Body directly or within a Container to workaround this limit.

An error is returned if specified Action values fail validation.

func (*Card) AddContainer 

func (c *Card) AddContainer(prepend bool, container Container) error

AddContainer adds the given Container Element to the collection of Element values for the Card. If specified, the Container Element is inserted at the beginning of the collection, otherwise appended to the end.

func (*Card) AddElement 

func (c *Card) AddElement(prepend bool, elements ...Element) error

AddElement adds one or more provided Elements to the Body of the associated Card. If specified, the Element values are prepended to the Card Body (as a contiguous set retaining current order), otherwise appended to the Card Body.

An error is returned if specified Element values fail validation.

func (*Card) AddFactSet 

func (c *Card) AddFactSet(prepend bool, factsets ...FactSet) error

AddFactSet adds one or more provided FactSet elements to the Body of the associated Card. If specified, the FactSet values are prepended to the Card Body (as a contiguous set retaining current order), otherwise appended to the Card Body.

An error is returned if specified FactSet values fail validation.

TODO: Is this needed? Should we even have a separate FactSet type that is so difficult to work with?

func (*Card) AddMention 

func (c *Card) AddMention(prepend bool, mentions ...Mention) error

AddMention adds one or more provided user mentions to the associated Card along with a new TextBlock element. The Text field for the new TextBlock element is updated with the Mention Text.

If specified, the new TextBlock element is inserted as the first element in the Card body. This effectively creates a dedicated TextBlock that acts as a "lead-in" or "announcement block" for other elements in the Card. If false, the newly created TextBlock is appended to the Card, effectively creating a "CC" list commonly found at the end of an email message.

An error is returned if specified Mention values fail validation.

func (*Card) GetElement 

func (c *Card) GetElement(id string) (*Element, error)

GetElement searches all Element values attached to the Card for the specified ID (case sensitive). If found, a pointer to the Element is returned, otherwise an error is returned.

func (*Card) Mention 

func (c *Card) Mention(displayName string, id string, msgText string, prependElement bool) error

Mention uses the given display name, ID and message text to add a new user Mention and TextBlock element to the Card. If specified, the new TextBlock element is added as the first element of the Card, otherwise it is added last. An error is returned if provided values are insufficient to create the user mention.

func (*Card) SetFullWidth 

func (c *Card) SetFullWidth()

SetFullWidth enables full width display for the Card.

func (Card) Validate 

func (c Card) Validate() error

Validate asserts that fields have valid values.

type Column 

type Column struct {

	// Type is required; must be set to "Column".
	Type string `json:"type"`

	// ID is a unique identifier associated with this Column.
	ID string `json:"id,omitempty"`

	// Width represents the width of a column in the column group. Valid
	// values consist of fixed strings OR a number representing the relative
	// width.
	//
	// "auto", "stretch", a number representing relative width of the column
	// in the column group, or in version 1.1 and higher, a specific pixel
	// width, like "50px".
	Width interface{} `json:"width,omitempty"`

	// Items are the card elements that should be rendered inside of the
	// column.
	Items []*Element `json:"items,omitempty"`

	// SelectAction is an action that will be invoked when the Column is
	// tapped or selected. Action.ShowCard is not supported.
	SelectAction *ISelectAction `json:"selectAction,omitempty"`
}

Column is a container used by a ColumnSet element type. Each container may contain one or more elements.

https://adaptivecards.io/explorer/Column.html

func (Column) Validate 

func (c Column) Validate() error

Validate asserts that fields have valid values.

type ColumnItems 

type ColumnItems []*Element

ColumnItems is a collection of card elements that should be rendered inside of the column.

func (ColumnItems) Validate 

func (ci ColumnItems) Validate() error

Validate asserts that the Items collection field for a column contains valid values. Special handling is applied since the collection could contain nil values.

type Columns 

type Columns []Column

Columns is a collection of Column values.

func (Columns) Validate 

func (c Columns) Validate() error

Validate asserts that the collection of Column values are all valid.

type Container 

type Container Element

Container is an Element type that allows grouping items together.

func NewContainer 

func NewContainer() Container

NewContainer creates an empty Container.

func (*Container) AddAction 

func (c *Container) AddAction(prepend bool, actions ...Action) error

AddAction adds one or more provided Action values to the associated Container as one or more new ActionSets. The number of actions in each newly created ActionSet is limited to the number specified by TeamsActionsDisplayLimit.

If specified, the newly created ActionSets are inserted before other Elements in the Container, otherwise appended.

An error is returned if specified Action values fail validation.

func (*Container) AddElement 

func (c *Container) AddElement(prepend bool, element Element) error

AddElement adds the given Element to the collection of Element values in the container. If specified, the Element is inserted at the beginning of the collection, otherwise appended to the end.

type Element 

type Element struct {

	// Type is required and indicates the type of the element used in the body
	// of an Adaptive Card.
	// https://adaptivecards.io/explorer/AdaptiveCard.html
	Type string `json:"type"`

	// ID is a unique identifier associated with this Element.
	ID string `json:"id,omitempty"`

	// Text is required by the TextBlock and TextRun element types. Text is
	// used to display text. A subset of markdown is supported for text used
	// in TextBlock elements, but no formatting is permitted in text used in
	// TextRun elements.
	//
	// https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/text-features
	// https://adaptivecards.io/explorer/TextBlock.html
	// https://adaptivecards.io/explorer/TextRun.html
	Text string `json:"text,omitempty"`

	// URL is required for the Image element type. URL is the URL to an Image
	// in an ImageSet element type.
	//
	// https://adaptivecards.io/explorer/Image.html
	// https://adaptivecards.io/explorer/ImageSet.html
	URL string `json:"url,omitempty"`

	// Size controls the size of text within a TextBlock element.
	Size string `json:"size,omitempty"`

	// Weight controls the weight of text in TextBlock or TextRun elements.
	Weight string `json:"weight,omitempty"`

	// Color controls the color of TextBlock elements or text used in TextRun
	// elements.
	Color string `json:"color,omitempty"`

	// Spacing controls the amount of spacing between this element and the
	// preceding element.
	Spacing string `json:"spacing,omitempty"`

	// The style of the element for accessibility purposes. Valid values
	// differ based on the element type. For example, a TextBlock element
	// supports the "heading" style, whereas the Column element supports the
	// "attention" style (TextBlock does not).
	Style string `json:"style,omitempty"`

	// Items is required for the Container element type. Items is a collection
	// of card elements to render inside the Container.
	Items []Element `json:"items,omitempty"`

	// Columns is a collection of Columns used to divide a region. This field
	// is used by a ColumnSet element type.
	Columns []Column `json:"columns,omitempty"`

	// Actions is required for the ActionSet element type. Actions is a
	// collection of Actions to show for an ActionSet element type.
	//
	// TODO: Should this be a pointer?
	Actions []Action `json:"actions,omitempty"`

	// Facts is required for the FactSet element type. Actions is a collection
	// of Fact values that are part of a FactSet element type. Each Fact value
	// is a key/value pair displayed in tabular form.
	//
	// TODO: Should this be a pointer?
	Facts []Fact `json:"facts,omitempty"`

	// Wrap controls whether text is allowed to wrap or is clipped for
	// TextBlock elements.
	Wrap bool `json:"wrap,omitempty"`

	// Separator, when true, indicates that a separating line shown should
	// drawn at the top of the element.
	Separator bool `json:"separator,omitempty"`
}

Element is a "building block" for an Adaptive Card. Elements are shown within the primary card region (aka, "body"), columns and other container types. Not all fields of this Go struct type are supported by all Adaptive Card element types.

func NewActionSet 

func NewActionSet() Element

NewActionSet creates an empty ActionSet.

TODO: Should we create a type alias for ActionSet, or keep it as a "base" Element type?

func NewActionSetsFromActions 

func NewActionSetsFromActions(actions ...Action) ([]Element, error)

NewActionSetsFromActions creates a new ActionSet for every TeamsActionsDisplayLimit count of Actions given. An error is returned if the specified Actions do not pass validation.

func NewTextBlock 

func NewTextBlock(text string, wrap bool) Element

NewTextBlock creates a new TextBlock element using the optional user specified Text. If specified, text wrapping is enabled.

func NewTitleTextBlock 

func NewTitleTextBlock(title string, wrap bool) Element

NewTitleTextBlock uses the specified text to create a new TextBlock formatted as a "header" or "title" element. If specified, the TextBlock has text wrapping enabled. The effect is meant to emulate the visual effects of setting a MessageCard.Title field.

func (Element) HasMentionText 

func (e Element) HasMentionText(m Mention) bool

HasMentionText asserts that a supported Element type contains the required Mention text string necessary to link a user mention to a specific Element.

func (Element) Validate 

func (e Element) Validate() error

Validate asserts that fields have valid values.

type Elements 

type Elements []Element

Elements is a collection of Element values.

func (Elements) Validate 

func (e Elements) Validate() error

Validate asserts that the collection of Element values are all valid.

type Fact 

type Fact struct {
	// Title is required; the title of the fact.
	Title string `json:"title"`

	// Value is required; the value of the fact.
	Value string `json:"value"`
}

Fact represents a Fact in a FactSet as a key/value pair.

func (Fact) Validate 

func (f Fact) Validate() error

Validate asserts that fields have valid values.

type FactSet 

type FactSet Element

FactSet is an Element type that groups and displays a series of facts (i.e. name/value pairs) in a tabular form.

func NewFactSet 

func NewFactSet() FactSet

NewFactSet creates an empty FactSet.

func (*FactSet) AddFact 

func (fs *FactSet) AddFact(facts ...Fact) error

AddFact adds one or many Fact values to a FactSet. An error is returned if the Fact fails validation or if AddFact is called on an unsupported Element type.

type Facts 

type Facts []Fact

Facts is a collection of Fact values.

func (Facts) Validate 

func (f Facts) Validate() error

Validate asserts that the collection of Fact values are all valid.

type ISelectAction 

type ISelectAction struct {

	// Type is required; specific values are supported.
	//
	// The supported actions are Action.Execute, Action.OpenUrl,
	// Action.ToggleVisibility.
	//
	// See also https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference
	Type string `json:"type"`

	// ID is a unique identifier associated with this ISelectAction.
	ID string `json:"id,omitempty"`

	// Title is a label for the button or link that represents this action.
	Title string `json:"title,omitempty"`

	// URL is required for the Action.OpenUrl type, optional for other action
	// types.
	URL string `json:"url,omitempty"`

	// Fallback describes what to do when an unknown element is encountered or
	// the requirements of this or any children can't be met.
	Fallback string `json:"fallback,omitempty"`
}

ISelectAction represents an Action that will be invoked when a container type (e.g., Column, ColumnSet, Container) is tapped or selected. Action.ShowCard is not supported.

https://adaptivecards.io/explorer/Container.html https://adaptivecards.io/explorer/ColumnSet.html https://adaptivecards.io/explorer/Column.html

TODO: Extend with additional supported fields.

func (ISelectAction) Validate 

func (i ISelectAction) Validate() error

Validate asserts that fields have valid values.

type MSTeams 

type MSTeams struct {

	// Width controls the width of Adaptive Cards within a Microsoft Teams
	// messages.
	// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#full-width-adaptive-card
	Width string `json:"width,omitempty"`

	// AllowExpand controls whether images can be displayed in stage view
	// selectively.
	//
	// https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format#stage-view-for-images-in-adaptive-cards
	AllowExpand bool `json:"allowExpand,omitempty"`

	// Entities is a collection of user mentions.
	// TODO: Should this be a slice of pointers?
	Entities []Mention `json:"entities,omitempty"`
}

MSTeams represents a container for properties specific to Microsoft Teams messages, including formatting properties and user mentions.

func (MSTeams) Validate 

func (m MSTeams) Validate() error

Validate asserts that fields have valid values.

type Mention 

type Mention struct {
	// Type is required; must be set to "mention".
	Type string `json:"type"`

	// Text must match a portion of the message text field. If it does not,
	// the mention is ignored.
	//
	// Brief testing indicates that this needs to wrap a name/value in <at>NAME
	// HERE</at> tags.
	Text string `json:"text"`

	// Mentioned represents a user that is mentioned.
	Mentioned Mentioned `json:"mentioned"`
}

Mention represents a mention in the message for a specific user.

func NewMention 

func NewMention(displayName string, id string) (Mention, error)

NewMention uses the given display name and ID to create a user Mention value for inclusion in a Card. An error is returned if provided values are insufficient to create the user mention.

func (Mention) Validate 

func (m Mention) Validate() error

Validate asserts that fields have valid values.

Element.Validate() asserts that required Mention.Text content is found for each recorded user mention the Card..

type Mentioned 

type Mentioned struct {
	// ID is the unique identifier for a user that is mentioned. This value
	// can be an object ID (e.g., 5e8b0f4d-2cd4-4e17-9467-b0f6a5c0c4d0) or a
	// UserPrincipalName (e.g., NewUser@contoso.onmicrosoft.com).
	ID string `json:"id"`

	// Name is the DisplayName of the user mentioned.
	Name string `json:"name"`
}

Mentioned represents the user id and name of a user that is mentioned.

func (Mentioned) Validate 

func (m Mentioned) Validate() error

Validate asserts that fields have valid values.

type Mentions 

type Mentions []Mention

Mentions is a collection of Mention values.

func (Mentions) Validate 

func (m Mentions) Validate() error

Validate asserts that the collection of Mention values are all valid.

type Message 

type Message struct {
	// Type is required; must be set to "message".
	Type string `json:"type"`

	// Attachments is a collection of one or more Adaptive Cards.
	//
	// NOTE: Including multiple attachment *without* AttachmentLayout set to
	// "carousel" hides cards after the first. Not sure if this is a bug, or
	// if it's intentional.
	Attachments []Attachment `json:"attachments"`

	// AttachmentLayout controls the layout for Adaptive Cards in the
	// Attachments collection.
	AttachmentLayout string `json:"attachmentLayout,omitempty"`

	// ValidateFunc is an optional user-specified validation function that is
	// responsible for validating a Message. If not specified, default
	// validation is performed.
	ValidateFunc func() error `json:"-"`
	// contains filtered or unexported fields
}

Message represents a Microsoft Teams message containing one or more Adaptive Cards.

func NewMentionMessage 

func NewMentionMessage(displayName string, id string, msgText string) (*Message, error)

NewMentionMessage creates a new simple Message. Using the given message text, displayName and ID, a user Mention is also created and added to the new Message. An error is returned if provided values are insufficient to create the user mention.

func NewMessage 

func NewMessage() *Message

NewMessage creates a new Message with required fields predefined.

func NewMessageFromCard 

func NewMessageFromCard(card Card) (*Message, error)

NewMessageFromCard is a helper function for creating a new Message based off of an existing Card value.

func NewSimpleMessage 

func NewSimpleMessage(text string, title string, wrap bool) (*Message, error)

NewSimpleMessage creates a new simple Message using the specified text and optional title. If specified, text wrapping is enabled. An error is returned if an empty text string is specified.

func (*Message) Attach 

func (m *Message) Attach(cards ...Card) error

Attach receives and adds one or more Card values to the Attachments collection for a Microsoft Teams message.

NOTE: Including multiple cards in the attachments collection *without* attachmentLayout set to "carousel" hides cards after the first. Not sure if this is a bug, or if it's intentional.

func (*Message) Carousel 

func (m *Message) Carousel() *Message

Carousel sets the Message Attachment layout to Carousel display mode.

func (*Message) Mention 

func (m *Message) Mention(prependElement bool, displayName string, id string, msgText string) error

Mention uses the provided display name, ID and text values to add a new user Mention and TextBlock element to the first Card in the Message.

If no Cards are yet attached to the Message, a new card is created using the Mention and TextBlock element. If specified, the new TextBlock element is added as the first element of the Card, otherwise it is added last. An error is returned if insufficient values are provided.

func (*Message) Payload 

func (m *Message) Payload() io.Reader

Payload returns the prepared Message payload. The caller should call Prepare() prior to calling this method, results are undefined otherwise.

func (*Message) Prepare 

func (m *Message) Prepare() error

Prepare handles tasks needed to construct a payload from a Message for delivery to an endpoint.

func (*Message) PrettyPrint 

func (m *Message) PrettyPrint() string

PrettyPrint returns a formatted JSON payload of the Message if the Prepare() method has been called, or an empty string otherwise.

func (Message) Validate 

func (m Message) Validate() error

Validate performs validation for Message using ValidateFunc if defined, otherwise applying default validation.

type NullString 

type NullString string

NullString represents a string value used in component fields that may potentially be null in the input JSON feed.

func (NullString) MarshalJSON 

func (ns NullString) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface. This compliments the custom Unmarshaler implementation to handle potentially null component description field value.

func (*NullString) UnmarshalJSON 

func (ns *NullString) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface to handle potentially null component description field value.

type TopLevelCard 

type TopLevelCard struct {
	Card
}

TopLevelCard represents the outer or top-level Card for a Microsoft Teams Message attachment.

func (TopLevelCard) Validate 

func (tc TopLevelCard) Validate() error

Validate asserts that fields have valid values.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.