Confluence content byline item

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.

Properties

i18n object

Content properties to store byline properties

Starting in Forge CLI version 12.6.1, you can control the title, icon, or tooltip properties of the confluence:contentBylineItem module using content properties. If the contentPropertyKey is provided in the manifest.yml file, Confluence attempts to retrieve the dynamic properties from the value of that content property on the initial render of the app. Read more about the content property API.

You can also use either the set method of the useContentProperty hook (in @forge/react version 11.4.0 and above) or the updateBylineProperties @forge/confluence-bridge (in @forge/confluence-bridge version 3.1.0 and above) method to programmatically refresh the associated byline module properties. For example, a confluence:backgroundScript module could be used to trigger the re-rendering of byline properties by updating the values in the content property of a page.

In your byline manifest:

1
2
confluence:contentBylineItem:
  - key: byline-app
    resource: main
    render: native
    title: Byline App
    contentPropertyKey: byline-properties-unique-key

In another module, like confluence:backgroundScript or macro, you can use:

1
2
import { useContentProperty } from '@forge/react';

const [properties, setProperties, deleteProperties] = useContentProperty('byline-properties-unique-key', { defaultValues });

const setTestContentProperty = async () => {
  const date = new Date().toTimeString();
  await setProperties({ title: `Updated title at ${date}`, icon: "new-icon-path", tooltip: `Updated tooltip at ${date}`});
}

You can also use the updateBylineProperties bridge method for Custom UI apps.

Dynamic properties

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
2
interface 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
2
interface 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
2
function handlerFunction(payload, context) {
  return {
    "title": "Updated title",
    "icon": "https://mydomain.com/my-icon.png",
    "tooltip": "Updated Tooltip"
  };
}

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.

Extension context

UI Kit and Custom UI

Use the useProductContext hook to access the extension context in UI Kit or getContext bridge method in Custom UI.