Hi developer community,
We are planning to introduce a new type of macro in Confluence Cloud. Please take some time to read our Request for Comment (RFC) and provide feedback on what you think about it. We would like to understand better how this new macro type can help you build solutions for content formatting, what challenges you may have, and what will help you overcome them.
RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea, not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Summary of Project:
With this project, we are introducing a new Connect macro type in Confluence Cloud that will allow you to store multiple rich-text bodies within a macro. Marketplace partners will have the ability to manipulate these bodies in their apps by adding, removing, and displaying them. Confluence users will be able to add any available Confluence elements to the bodies, including other macros. The rendering and editing of multi-bodied macros will provide a WYSIWYG experience for end users.
While multi-bodied macros offer many opportunities for content formatting, we will focus on the Tabs use case for the first release.
- Publish: 27 Oct, 2023
- Discuss: 27 Oct, 2023 - 10 Nov, 2023
- Resolve: 17 Nov, 2023
Problem
Tabs are one of the most commonly used ways to format content. Users often use tabs on both Confluence Cloud and Confluence Server. The number of tab-related apps on the marketplace proves the popularity and demand for such functionality. On cloud alone, the 13 most popular apps are installed on 21K instances, with more than 10.2M users using them.
On Confluence server, most apps use nested-bodied macros to configure tabs. The outer macro represents the tab group, and the inner macros are tabs.
This approach has several issues:
- Nested-bodied macros are not supported by the new editor. Partners have to create workaround solutions to implement tabs. Additionally, when users convert their pages to the new editor, any nested content can no longer be edited.
- Users have different experiences with the user interface (UI) in the editor and renderer.
- Marketplace partners are responsible for rendering the content of the body. They use a few approaches to do that, but none of them are ideal, and the result is far from what the editor natively renders.
- Using nested-bodied macros as a layout for tabs creates confusion for users. It’s not obvious how to set up tabs, nor is it clear how tabs will be rendered. For large documents, it’s not easy to change focus from one tab to another.
Atlassian’s goal is to help our customers transition to the cloud and the new editor. The solution outlined in this RFC is crucial because it provides a more user-friendly and efficient way to build Tabs macros (as well as other content formatting macros) on the new editor. By enabling Tabs macros based on this solution, we (Atlassian) with you (Marketplace partners) can encourage customers to migrate from server to cloud, from the legacy editor to the new editor, and from old macros to the new ones.
Proposed Solution
In the proposed solution, we are going to build a new type of macro in Connect that Marketplace partners can use to create Tabs. For our initial release, we are planning to include the following scope:
- a new
multiBodiedExtensionADF node - a new macro type with
bodyType = multi-rich-text - a new UX for the editor and the renderer
- new AC JS functions to control bodies of the macro
New ADF Node
The nature of tabs is a multi-bodied container, where each tab’s content is represented and stored as a separate body. For this purpose, we will expand the ADF schema by adding a new node type called multiBodiedExtension. This node will allow for the storage of multiple bodies in separate entities, along with any other related data in macro parameters.
{
"type": "multiBodiedExtension",
"attrs": {
"extensionType": "com.atlassian.confluence.macro.core",
"extensionKey": "tabs-macro",
"parameters": {
"macroParams": {
"tabs": ["Tab1 Title", "Tab2 Title"]
}
},
},
"content": [
{
"type": "extensionBody",
"content": []
},
{
"type": "extensionBody",
"content": []
}
]
}
A new macro type
A new macro type will be available in the dynamicContentMacro module. Marketplace partners will define it with the bodyType = multi-rich-text property. We don’t expect to change any other properties.
A new UX for the editor and the render
MultiBodiedExtension will be rendered differently from bodiedExtension.
For Tabs, it will consist of two parts:
- Partner app (at the top)
- The frame (at the bottom) where the content will be rendered. You can think of a frame as a viewport, where only one body is displayed at any given moment. In edit mode, it will represent the input field (same as for bodiedExtension) where the user can add most Confluence elements as well as bodiedExtensions from other partners. In view mode, the content will be handled and rendered by the Editor. The macro will be rendered in the same way in the editor and the renderer, providing users with a WYSIWYG experience. Marketplace partners will no longer be responsible for rendering the content. No more hassle with conversion
. Instead, we provide a different API so marketplace partners can control which body is currently active/visible in a frame. This and other API functions are described in the next section.
Difference between bodiedExtension and multiBodiedExtension:
| bodiedExtension | multiBodiedExtension | |
|---|---|---|
| Number of bodies | One | Many (the number can be limited depending on performance) |
| UX | Two different representations in Editor and Renderer | Very close to WYSIWYG experience |
| Body render | by app developer | by Editor |
New AC JS functions to control bodies of the macro
Marketplace partners will have the ability to add or remove a new body, activate the body in a frame, and save additional app data (such as tab titles, active tabs, etc). This interaction will be accessible through the new ACJS API. Although we recognize the potential need for other functions, our initial milestone will focus on adding only the following:
- addBody
- removeBody
- showBody / setActiveBody
- getParams
- updateParams
Let’s go through some of the flows of how it is going to work
Switching tabs:
- The user clicks a
Tab2element - Behind the scenes, the app calls setActiveBody(1) // second tab
Adding a new tab:
- The user clicks a
button - Behind the scenes, the app calls
- addBody()
- setActiveBody(2) // set active a new tab
- updateParams() // adding a new default title (
Tab3) to tab titles
Removing a tab:
- The user hovers over the Tab element, the remove button
appears - The user clicks a button
- Behind the scenes, the app calls
- removeBody()
- setActiveBody(1) // set active the previous tab
- updateParams() // updating the list of tab titles
Migration from legacy to new editor
To improve the experience for customers who migrate from server to cloud, we recommend that partners migrate old Tabs macros to new multi-bodied Tabs after the page has been converted from the legacy to the new editor. In some cases, this may be the only option if the old Tabs were based on nested-bodied macros. To make it possible, both macros should be installed on the instance.
Currently, when a page is moved from server to cloud, it ends up in the legacy editor. Most partners have already built cloud apps that display tab macros appropriately as the legacy editor supports nested-bodied macros. However, when a page is converted to the new editor, these macros stop working as nested-bodied macros are converted to regular plain-text macros.
Instead of displaying a broken macro, we recommend that partners display an alternative view that explains why the macro is broken and how it can be fixed. This could be done through a button or a link that converts the existing macro to a multi-bodied macro using the update page API.
As part of this conversion flow, partners would need to:
- Have both macros installed on the instance
- Update an old
Tabsmacro to display an alternative UI when it’s rendered on the new editor - Implement the conversion of the node that corresponds to a legacy macro to a new node that is based on a multi-bodied macro.
This flow represents how it may look from the user’s perspective:
Other items under consideration
The following items are out of the scope of our initial release. However, we recognize the significant potential in multi-bodied macros that can be utilized for various use cases. To enable this, we’re considering supporting the following functionalities in future releases:
- Ability to retrieve/update the content of the macro bodies
- Positioning the frame in different locations
- Rendering multiple frames for a single macro
- Configuring the layout for multi-bodied macros
Asks
While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:
- How excited are you about multi-bodied macros? If you have (or if you might have) a
Tabsmacro, would you be interested in migrating it to a multi-bodied macro? - Feature parity with your existing tab apps. What can’t be built but is very important for you?
- Is there any improvement you can see that would benefit the proposed approach?
- Although our current focus is on the Tabs use case, we are considering the possibility of using multi-bodied macros as a foundation for developing other content formatting macros. Would you be interested in exploring this option?
Thank you!
