Last updated Mar 28, 2024

Custom content

questions

What is custom content?

Confluence provides creation and collaboration features for different types of content. Pages and blogs, for example, are content types that are supported by default, while Confluence Questions is an example of an app that introduces questions and answers as new types of content that integrate with Confluence.

The custom content pattern describes how an app can achieve a similar outcome to Confluence Questions by introducing other types of content into Confluence. Just like with the default content types, app content can be created by one user and navigated to via spaces, search, or dashboard streams by other users.

Custom content is modeled within a container-ship hierarchy. In the case of Confluence Questions, questions "contain" answers. This is similar to the behavior of the default Confluence content types, where one content type, like blogs, can contain another, like comments. Custom content can contain both default content types, as well as those created by apps. For example, questions can contain answers, as well as comments and attachments.

To fit with the theme of 'custom' content and to provide a unique look and feel to users, Atlassian Connect and Atlassian Forge enable custom content types to provide dedicated view, create, and edit experiences within Confluence.

What can I build with custom content?

Custom content can be used for several purposes, including macro attachments and forms.

Content solutions

These apps create specialized forms of content and provide dedicated view/create/edit experiences.

Examples include:

  • Confluence Questions
  • Recruiting solutions (candidates, roles, etc)
  • CRM solutions (customers, communications, etc)
  • Forms (forms, responses, etc).

Macro attachments

These apps combine custom content with the macro pattern. Instead of custom view/create/edit experiences, macros are used to view/create/edit new types of content as they are added to a page. Essentially, the macro lets users create custom content attached to a page, which they can manage through the page custom content list screen. Macros then allow references to this attached content to be embedded within the content body of a page.

Examples include:

  • Embedded diagramming apps
  • Diagramming integration (using custom content as an index that integrates with search)

How do I build custom content?

To start with, you will want to define new custom content in your Connect module descriptor, populate it via the REST API, and confirm you can search on that content.

Definition and search integration

When defining custom content you need to consider whether your use case needs space level or page level content. Content solutions typically need space level content, while custom attachments for specialized macros typically need page level content.

Custom content must represent real world content related concepts as they are displayed to users for navigation and search. Only define custom content that will be a meaningful concept to users and consider their name carefully and avoid appending technical terms such as *definition* or *configuration*.

Space custom content list view

When viewing the various types of content under a Confluence space, a default experience is provided for each custom content type in the Apps section of the side navigation. Each custom content type is shown as a separate item and displays all of the custom content contained in that space, regardless of the content's supported container type. This enables users to view all custom content in a space, including custom content whose container type is a space, page, or other custom content type.

You can override the default experience in Connect by providing a listViewComponent as part of the customContent module. For Forge, a SpaceCustomContentListView component is provided as a UI Kit component within @forge/ui.

space-custom-contents-list-screen

Page custom content list view

When viewing the various types of content under a Confluence page, a default experience is provided for custom content types within the page custom content list screen. Each custom content type is collated within separate tabs. Your app must provide a custom icon to be rendered under this view. For example, if you create a 'diagram' custom content type, all diagrams placed on a page would be viewable in the 'diagram' tab. This enables users to access the custom content on the content tool menu as well.

page-custom-contents-list-screen

Custom content view

When navigating to the blogs or pages under a space, Confluence provides users with a native experience. Unlike these native types, when introducing custom content, an app must provide a custom user interface for this view. For example, in the case of Confluence Questions, an input field is provided for asking a question above a list of questions asked earlier in the chosen space.

Custom content creation 

Using custom dialogs and the page extensions pattern, you can easily guide users through an in-context or out-of-context, full screen content creation experience. In addition to this level of UI support, Confluence Connect provides API support for important content events such as 'create', 'update', 'trash', 'restore' or 'delete'. This allows your app service to perform these actions remotely through the Confluence API.

What other patterns might be helpful?

Macros

Macros are a relevant pattern if your app is implementing a specialized attachment style of custom content. See discussion on specialized attachments above.

Let's do this!

Get going by following our Custom content tutorials:

  • Integrations
  • Content solutions

Rate this page: