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!
RFC dates:
- Publish: May 10, 2024
- Discuss: May 21, 2024
- Resolve: June 7, 2024
Summary of the project
Our goal with this RFC is to get your feedback on a proposed solution to make it clear and intuitive for users to both interact with AND configure macros within the Editor. We’ve found that making macros more functional in the Editor can improve their adoption, and we want to continue bridging the gap between Editor and Renderer functionality.
Problem
First, some definitions. Confluence has two primary page modes today:
- Renderer / View page - the static rendered mode that users land on once a page is published. Uses Atlaskit Renderer
- Editor - A separate component that enables building page structure and collaborative editing. Uses Atlaskit Editor core. To reduce friction to collaboration in Confluence, we are gradually experimenting with making the Editor the primary way to consume pages via live-edit pages (learn more in the RFC here, and sign up for the partner EAP if you haven’t).
In the Editor today, macros have very limited functionality. The primary limitation we want to focus on solving in this RFC is as follows:
- Many macros are designed to be interactive, i.e. the user can click on them to trigger their experiences. Think buttons, cards, links, diagrams, etc. that can be clicked.
- Macro interactivity is not currently available in the editor (besides a select group of Atlassian-built macros like Table of Contents, Child pages, etc). For most macros, there is a “glass pane” over them that prevents them from being interacted with. Due to this “glass pane”, when macros are clicked in the Editor, instead of triggering any interactive elements within them, the macro is simply selected and the user is presented with an editing toolbar.
Unfortunately, just removing this “glass pane” does not fully solve the problem. While removing the glass pane makes the macro content interactive, it becomes unclear how a user would trigger the editing toolbar in order to configure the macro.
Let’s use the Atlassian-built Create from Template macro, which is a button a user can click to create a new page with a certain template, as an example.
Current state experience: when a user clicks the Create from Template button macro, they instantly create a new page.
Let’s say the user is editing and we’ve removed the glass pane from the macro to make it interactive.
If the user clicks the Create from template button, then it will trigger the macro’s interactivity, creating a new page with a template. But, how might the user actually select the macro in order to configure it (or copy it, delete it, etc)? It’s unclear. Technically, users can already click on the macro name or border that appears on hover in order to select & configure it, but that is not necessarily intuitive. We also heard this directly from partners participating in our live-edit pages EAP where we have removed the glass pane from all macros.
Our goal with this RFC is to get your feedback on a proposed solution direction to make it clear and intuitive to a user how to both interact with AND configure macros within the Editor.
Proposed Solution
To make it intuitive for users to be able to both interact with AND configure macros within the Editor, we are proposing the following interaction design.
When a user hovers over a macro, a selection / configuration control will appear in the top right corner of the macro’s content. That way, it’s clear that:
- If a user wishes to interact with the macro, they can simply click on whatever they wish to interact with within the macro frame (example: clicking on the button to create a new page from a template.)
- If a user wishes to select the macro or configure the macro (i.e. to update its parameters, copy it, delete it, etc), they can click on the new selection / configuration control in the top right of their of the macro’s content, which will bring up the editing toolbar when clicked.
- Note that, beyond these changes, we are also considering introducing a new, separate control to the left side of content blocks in the Editor. This new control will lets users select content (e.g. a heading, a paragraph, a macro) and drag it around the page, or move it with keyboard controls. This control may appear at the same time that the macro configuration affordance is shown to a user.
We recognize that some macros have interactive content in the top right corner of their frame in the renderer today. If we pursue this direction, we will update macro guidelines to recommend that there isn’t any interactive content in the top right corner of the macro, to prevent any potential overlap with this configuration menu button. We definitely want to hear your feedback about this direction.
Demo of the new macro configuration control concept in the Editor. Users can both interact with the macro content in the Editor and summon the editing toolbar to edit the macro or take any other actions present in the toolbar today (i.e. copy, resize, delete the macro). Note that the toolbar shown in this gif is an exploratory concept, and a first version release is likely to use the toolbar that exists in the product today.
Implications for Apps
These changes would apply to all macros when viewed in the editing experience:
- Macros built by vendors or customers using Connect
- Macros built by vendors or customers using Forge
- Macros built by Atlassian
No changes would be made to macros when viewed in the rendered experience.
Updates/work would be required on your end as a result of these changes if your macro has interactive content in the top right corner of the frame that would need to move so as not to overlap with the configuration control. Otherwise, no updates/work would be required.
What about macros that are bodied extensions?
These changes will apply all types of macros, including bodied extensions. However, bodied macros still have an additional challenge where they currently only show their nested content in the editor, and the “rendered” view cannot be displayed in the Editor. This RFC does not cover how we plan to bridge that gap.
Asks
- What feedback / concerns do you have around this updated macro interaction design?
- Are there any other areas, use cases, etc that we are missing?
Next Steps
After hearing your feedback, we plan to make any necessary design iterations to make sure we’re best meeting the needs of our shared customers. Once your feedback is incorporated, we will update with our final direction when the RFC is resolved at the end of this month.
.
