Custom content
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.
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.
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.
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:
- Adding a custom content type
- Working with custom content
- Searching custom content
- Working with custom content children
Related app categories
- Integrations
- Content solutions
Related custom content pages
Rate this page: