DocumentBuilder - Documentation

Constructor

new DocumentBuilder(inputopt, parentopt)

Source:

builder.js, line 76

Example

const doc = new DocumentBuilder()
    .setTitle("Check this out!")
    .setSubtitle("Example Service")
    .setLogo("https://cdn.service.example/logo.png", 1)
    .addFields(
        {"name": "Name", "value": "Lady Sampleton", "inline": true},
        {"name": "Age", "value": "42", "inline": true}
    )
    .addGallery(
        "https://cdn.service.example/images/1",
        "https://cdn.service.example/images/2",
    );

Parameters:

Name	Type	Attributes	Description
`input`	RichToken \| Array.<RichToken>	<optional>	A rich token document to initialize this builder with.
`parent`	DocumentBuilder	<optional>	A parent `DocumentBuilder` to this builder, for convenience.

Methods

add(token) → {DocumentBuilder}

Source:

builder.js, line 527

Add a token to the end of the document.

Parameters:

Name	Type	Description
`token`	RichToken	The token to be added.

Returns:

this

Type: DocumentBuilder

addConditional(mediaopt, nsfwopt, contentopt, alternativeopt) → {DocumentBuilder}

Source:

builder.js, line 597

Add a new conditional to the end of the document.

Parameters:

Name	Type	Attributes	Description
`media`	Boolean	<optional>	Whether or not media is required to be true or false for this conditional. Media is ignored if this is null-ish.
`nsfw`	Boolean	<optional>	Whether or not NSFW is required to be true or false for this conditional. NSFW is ignored if this is null-ish.
`content`	String \| Array.<RichToken> \| DocumentBuilder	<optional>	Content to include when the condition passes.
`alternative`	String \| Array.<RichToken> \| DocumentBuilder	<optional>	Content to include when the condition fails.

Returns:

this

Type: DocumentBuilder

addField(name, value, inlineopt) → {DocumentBuilder}

Source:

builder.js, line 576

Add a single field to the end of the document.

See DocumentBuilder#addFields for more details.

Parameters:

Name	Type	Attributes	Default	Description
`name`	String \| Array.<RichToken>			The name to display for the field.
`value`	String \| Array.<RichToken>			The value to display for the field.
`inline`	Boolean	<optional>	`false`	Whether or not the field should display in-line.

Returns:

this

Type: DocumentBuilder

addFields(…fields) → {DocumentBuilder}

Source:

builder.js, line 547

Add fields to the end of the document, using the fieldset token.

If the last token in the document is a fieldset, these fields will be added to that token. Otherwise, a new fieldset token will be added to the end of the document.

Parameters:

Name	Type	Attributes	Description
`fields`	Field	<repeatable>	The fields to be added.

Returns:

this

Type: DocumentBuilder

addHeader(titleopt, subtitleopt, imageopt, optsopt) → {DocumentBuilder}

Source:

builder.js, line 655

Add a new header to the end of the document.

See the header token in {@template responses} for more information. The header must have at least one of an image, title, or subtitle.

Parameters:

Name Type Attributes Description

title

String | Array.<RichToken>

The title for the header.

subtitle

String | Array.<RichToken>

The subtitle for the header.

image

String | URL | RichToken

The image for the header.

opts

Object

Options for the header token.

Properties

Name	Type	Attributes	Description
`compact`	Boolean	<optional>	Whether or not this should be displayed as a compact header. Compact headers are displayed on a single line to save space.
`image_attach`	String	<optional>	Either `"left"` or `"right"`.
`height`	Number	<optional>	If set, the header will be this tall rather than automatically determining its height.

Returns:

this

Type: DocumentBuilder

build(recurseopt) → {Array.<Object>}

Source:

builder.js, line 142

Return an object representing the content of this builder. May be an array of tokens, a single token, or null.

If this builder is the child of another builder, this method will instead return an object representing the content of that builder. Calling build() on any part of a nested structure of DocumentBuilders returns the entire structure, unless you set recurse to false here.

Parameters:

Name	Type	Attributes	Default	Description
`recurse`	Boolean	<optional>	`true`	Whether or not to return the entire document and not just this specific DocumentBuilder.

Returns:

Rich Token Document

Type: Array.<Object>

content(attropt) → {DocumentBuilder}

Source:

builder.js, line 188

Drop into the content of the last token added to the builder.

Example

const data = new DocumentBuilder()
    .addConditional(true)
    .content()
        .addImage(my_image)
    .end()
    .content('alternative)
        .add('There was an image here, but you don\'t see those.')
    .end()
    .build();

Parameters:

Name	Type	Attributes	Default	Description
`attr`	String	<optional>	`'content'`	The name of the attribute to drop into. By default this is just `content`, but you can use a custom attribute to edit other sub-documents.

Returns:

A builder representing the content of the token.

Type: DocumentBuilder

done() → {DocumentBuilder}

Source:

builder.js, line 155

Return to the top level DocumentBuilder.

Returns:

The top level of this builder tree.

Type: DocumentBuilder

end() → {DocumentBuilder}

Source:

builder.js, line 165

Return to the parent DocumentBuilder. For use with content.

Returns:

The parent builder

Type: DocumentBuilder

setBackground(background) → {DocumentBuilder}

Source:

builder.js, line 273

Set the background of this document's primary header. If no primary header exists, one will be created with this background.

See DocumentBuilder#setBackground for more details.

Parameters:

Name	Type	Description
`background`	String \| RichToken	The background to set. This should be an image.

Returns:

this

Type: DocumentBuilder

setCompactHeader(compactopt) → {DocumentBuilder}

Source:

builder.js, line 296

Set the compact flag of this document's primary header. If no primary header exists, one will be created with this flag.

See DocumentBuilder#setHeader for more details.

Parameters:

Name	Type	Attributes	Default	Description
`compact`	Boolean	<optional>	`true`	Whether or not the header should be compact.

Returns:

this

Type: DocumentBuilder

setExtra(extra) → {DocumentBuilder}

Source:

builder.js, line 252

Set the extra of this document's primary header. If no primary header exists, one will be created with this extra.

See DocumentBuilder#setHeader for more details.

Parameters:

Name	Type	Description
`extra`	String \| RichToken \| Array.<RichToken>	The extra to set. Can be made of rich tokens.

Returns:

this

Type: DocumentBuilder

setFooter(titleopt, subtitleopt, imageopt, optsopt) → {DocumentBuilder}

Source:

builder.js, line 488

Set the document's primary footer.

The primary footer is always the last token output from a builder, no matter what other content is added to the builder. The footer is a header token. See the header token in {@template responses} for more information.

The footer must have at least one of an image, title, or subtitle.

Parameters:

Name Type Attributes Description

title

String | Array.<RichToken>

The title for the header.

subtitle

String | Array.<RichToken>

The subtitle for the header.

image

String | URL | RichToken

The image for the header.

opts

Object

Options for the header token.

Properties

Name	Type	Attributes	Default	Description
`sfw_image`	String \| URL \| RichToken	<optional>		The SFW image for the header, to be displayed if the default image is not SFW and the user is filtering to avoid NSFW content.
`compact`	Boolean	<optional>	`true`	Whether or not this should be displayed as a compact header. Compact headers are displayed on a single line to save space.
`image_attach`	String	<optional>		Either `"left"` or `"right"`.
`height`	Number	<optional>		If set, the header will be this tall rather than automatically determining its height.

Returns:

this

Type: DocumentBuilder

setHeader(titleopt, subtitleopt, imageopt, optsopt) → {DocumentBuilder}

Source:

builder.js, line 434

Set the document's primary header.

The primary header is always the first token output from a builder, no matter what other content is added to the builder. The header is a header token. See the header token in {@template responses} for more information.

The header must have at least one of an image, title, or subtitle.

Parameters:

Name Type Attributes Description

title

String | Array.<RichToken>

The title for the header.

subtitle

String | Array.<RichToken>

The subtitle for the header.

image

String | URL | RichToken

The image for the header.

opts

Object

Options for the header token.

Properties

Name	Type	Attributes	Description
`sfw_image`	String \| URL \| RichToken	<optional>	The SFW image for the header, to be displayed if the default image is not SFW and the user is filtering to avoid NSFW content.
`extra`	String \| Array.<RichToken>	<optional>	The extra for the header.
`compact`	Boolean	<optional>	Whether or not this should be displayed as a compact header. Compact headers are displayed on a single line to save space.
`image_attach`	String	<optional>	Either `"left"` or `"right"`.
`height`	Number	<optional>	If set, the header will be this tall rather than automatically determining its height.

Returns:

this

Type: DocumentBuilder

setLogo(url, optsopt) → {DocumentBuilder}

Source:

builder.js, line 327

Set the logo of this document's primary header. If no primary header exists, one will be created with this logo.

Logos are 48px tall for standard headers, and 24px tall for compact headers.

See DocumentBuilder#setHeader for more details. See the responses tutorial's section on Image Tokens for more.

Parameters:

Name Type Attributes Description

url

String | Object

The image to use for a logo. This can be an image token, a pair of {light: String, dark: String} URLs, or a single URL string. If this is an image token, all other arguments will be ignored.

opts

Object

Options for the token.

Properties

Name	Type	Attributes	Default	Description
`title`	String	<optional>		An optional title to use for alt text with the image.
`aspect`	Number	<optional>		An optional aspect ratio to use when presenting the image. If this is not set, images in headers default to 16:9.
`sfw`	Boolean	<optional>	`true`	Whether or not the image is Safe for Work. This is assumed to be true by default for logos.
`rounding`	Number	<optional>		How the image should be rounded.

Returns:

this

Type: DocumentBuilder

setSFWLogo(url, optsopt) → {DocumentBuilder}

Source:

builder.js, line 381

Set the SFW logo of this document's primary header. If no primary header exists, one will be created with this SFW logo.

Logos are 48px tall for standard headers, and 24px tall for compact headers.

See DocumentBuilder#setHeader for more details. See the responses tutorial's section on Image Tokens for more.

Parameters:

Name Type Attributes Description

url

String | Object

The image to use for a logo. This can be an image token, a pair of {light: String, dark: String} URLs, or a single URL string. If this is an image token, all other arguments will be ignored.

opts

Object

Options for the token.

Properties

Name	Type	Attributes	Default	Description
`title`	String	<optional>		An optional title to use for alt text with the image.
`aspect`	Number	<optional>		An optional aspect ratio to use when presenting the image. If this is not set, images in headers default to 16:9.
`sfw`	Boolean	<optional>	`true`	Backup logos MUST be sfw.
`rounding`	Number	<optional>		How the image should be rounded.

Returns:

this

Type: DocumentBuilder

setSubtitle(subtitle) → {DocumentBuilder}

Source:

builder.js, line 231

Set the subtitle of this document's primary header. If no primary header exists, one will be created with this subtitle.

See DocumentBuilder#setHeader for more details.

Parameters:

Name	Type	Description
`subtitle`	String \| RichToken \| Array.<RichToken>	The subtitle to set. Can be made of rich tokens.

Returns:

this

Type: DocumentBuilder

setTitle(title) → {DocumentBuilder}

Source:

builder.js, line 210

Set the title of this document's primary header. If no primary header exists, one will be created with this title.

See DocumentBuilder#setHeader for more details.

Parameters:

Name	Type	Description
`title`	String \| RichToken \| Array.<RichToken>	The title to set. Can be made of rich tokens.

Returns:

this

Type: DocumentBuilder