The confluence:contentBylineItem
module adds an entry to the content byline section,
which is the part of the content under the title that includes metadata about contributors and more.
The title
, icon
, and tooltip
of the module render together as a list item.
For UI Kit 1, see the ContentBylineItem component documentation for an example.
On apps that use Custom UI, module content is displayed inside a special Forge iframe which has the sandbox attribute configured. This means that HTML links (for example, <a href="https://domain.tld/path">...</a>
) in this iframe won't be clickable. To make them clickable, use the router.navigate API from the @forge/bridge
package.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
resource | string | If using Custom UI or modern versions of UI Kit | The key of a static resources entry that your module will display. See resources for more details. |
render | 'native' | If using modern versions of UI Kit | Indicates the module uses UI Kit. |
function | string | Deprecated Required if using UI Kit 1 | The key of a function module that returns a UI Kit 1 component. |
resolver | { function: string } or{ endpoint: string } |
Set the Set the | |
viewportSize | 'small' , 'medium' or 'large' | The display size of resource . Can only be set if the module is using the resource property. Remove this property to enable automatic resizing of the module. | |
title | string or i18n object | Yes |
The title of the content byline item, which is displayed as a list item. The |
icon | string |
The icon displayed next to the For custom UI and UI Kit apps, the If no icon is provided, or if there's an issue preventing the icon from loading, a generic app icon will be displayed. | |
tooltip | string or i18n object |
The tooltip of the content byline item, which is displayed on hover. The | |
description | string or i18n object |
The description of the content byline item. The | |
displayConditions | object | The object that defines whether or not a module is displayed in the UI of the app. See display conditions. | |
dynamicProperties | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . See Dynamic properties for more details.
| |
keyboardShortcut | object | The object that defines a keyboard shortcut to trigger this module. See keyboard shortcuts. |
Internationalization (i18n) for Forge apps is now available through Forge's Early Access Program (EAP). For details on how to sign up for the EAP, see the changelog announcement.
EAPs are offered to selected users for testing and feedback purposes. APIs and features under EAP are unsupported and subject to change without notice. APIs and features under EAP are not recommended for use in production environments.
For more details, see Forge EAP, Preview, and GA.
Key | Type | Required | Description |
---|---|---|---|
i18n | string | Yes | A key referencing a translated string in the translation files. For more details, see Translations. |
Dynamic properties are used to dynamically update the title
, icon
, or tooltip
properties of the
confluence:contentBylineItem
module. If provided in the manifest.yml
file, Confluence attempts
to retrieve the dynamic properties on the initial render of the app. To do this, the dynamicProperties
handler function of the app is called. When the content byline item is clicked, the app renders in a
dialog, where it can perform business logic updates. After the dialog is closed, the handler function
is again called to retrieve updates, and then update the title
, icon
, or tooltip
.
The app's handler function is passed two arguments: payload
and context
. The payload
object has the following structure:
1 2interface Payload { // The cloudId for your site cloudId: string; // A unique id for this instance of this component in the content localId: string; extension: { // The module type included in the manifest.yml file. // In this case, it is the "confluence:contentBylineItem" module. type: string; content: { // The unique identifier of the Confluence content id: string; // The type of Confluence content on which the invocation has occurred type: 'page' | 'blogpost' | 'space'; }; space: { // The id of the originating invocation space id: string; // The key of the originating invocation space key: string; } }; }
The context
object has the following structure:
1 2interface Context { principal: { accountId: string; }; installContext: string; }
The handler function should return (or resolve with) a plain old JavaScript object with a title
,
icon
, and tooltip
as keys. These optional keys are only sent if their
respective values require updating. Failure to provide a key would default to the last used value
or the original values defined within the manifest.yml
file.
Below is an example of a handler function returning a returned object:
1 2function handlerFunction(contextPayload) { return { "title": "Updated title", "icon": "https://mydomain.com/my-icon.png", "tooltip": "Updated Tooltip" }; }
When you use an icon
in your dynamic properties, its source URL is subject to a permission check.
For an example of adding source URL permissions for your icon
property, see External Permissions.
Bundled resources in the following formats are allowed by default:
resource:<resource key>;<relative path to resource>
data:image
URIsSee Icons for more information about bundling icons as a resource.
When the source URL does not have the appropriate permissions, the dynamic properties are not loaded. The default configuration is used instead.
Check out the Page approver app as an example of
an app that updates the title and tooltip on change, and prepopulates a default icon that's missing
from the manifest.yml
file.
Use the useProductContext hook to access the extension context in UI Kit or getContext bridge method in custom UI.
Property | Type | Description |
---|---|---|
type | string | The type of the module. |
content.id | string | A string that represents the unique identifier of the `content` object |
content.type | string | A string that represents the unique key of the `content` object |
space.id | string | A string that represents the unique identifier of the `space` object. |
space.key | string | A string that represents the unique key of the `space` object. |
Property | Type | Description |
---|---|---|
type | string | The type of the module. |
Rate this page: