RFC-63: Page Extension in Editor, Design changes and more

[TamimNoorzad]

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!

• Publish: September 5th, 2024
• Discuss: September 26th, 2024
• Resolve: October 3rd, 2024

Summary of Project

Hi everyone, we are seeking feedback on:

1. Adding extensions points into the editor
2. Making design changes unifying the experiences in editor and renderer
3. Deprecating and consolidating certain extension points (from editor and renderer)
4. These changes will be initially tested in the Live Pages EAP (Early Access Program) starting early October.
5. There will be no changes outside of the Live-Pages EAP until the earliest April 2025.

Problem

There is a need to expand the surface area of extension points in to the Editor. There is also a requirement to simplify and standardise the design of extension entry points across all Confluence pages. The current design of extension points in Confluence lacks consistency and clarity and will make it difficult for users to easily access Marketplace apps across different page modes. This inconsistency hinders the overall user experience and detracts from the cohesive look and feel of Confluence.

We heard from you in RFC-36 that it was critical for users to access extension points across different page modes. This update will make it easier for users to access and utilise page extensions effectively across all Confluence pages, simplifying and enhancing the overall user experience.

Proposed Solution

Location 1: Page byline

We propose to display the following extensions into the byline (in the renderer and editor): contentBylineItem, confluence:contentBylineItem

Proposed updates

• Releasing a page byline feature in the editor; introducing apps to this byline, similar to how they appear in the byline of a published page (i.e rendered page)
• contentBylineItem and confluence:contentBylineItemPage extension apps display in this byline in the editor, next to the page authoring metadata
• Removing individual app icons
• App content appears on click of app name
• App content can appear as a popup or in a modal dialog

Location 2: Sidebar overflow menu

We propose to consolidate the following extension points into the Sidebar overflow menu:

• Forge
  • confluence:contentAction
• Connect
  • system.content.action/modify
  • system.content.action/primary
  • system.content.action/secondary
  • system.content.action/marker

Proposed updates

We would like to introduce apps into the overflow menu in editor, grouped into a section.

• Access apps by opening the overflow menu in the top right action bar
• The overflow menu includes a new section ‘Apps’
• ‘Select app’ opens a secondary menu listing app extensions
• On selecting an app extension from the ‘Select app’ menu, a modal dialog appears (if applicable to the app)
• App content can be displayed in a modal dialog

Location 3: Contextual floating toolbar

We propose to introduce the following extensions in the contextual floating toolbar in the editor:

• confluence:contextMenu
• page.view.selection/action-panel

Proposed updates

Inline apps may be displayed in a contextual floating toolbar on highlight of page content. We would like to also introduce apps to the contextual floating toolbar in the editor.

• Apps performing inline actions are grouped under a new app icon in the contextual floating toolbar
• On highlight of page content the contextual floating toolbar appears
• Selecting the app icon displays a list of inline app extensions
• On selecting an inline app extension from the app icon, a modal dialog appears (if applicable to the app)

Location 4: atl.general

atl.general will appear in the editor as it does in the renderer.

Extension points considered for deprecation

We are proposing to exclude certain extension points from the editor and considering phasing them out from published pages. This aims to enhance the consistency and user experience of all Confluence pages:

• page.metadata.banner
• atl.page.metadata.banner
• system.content.button
• atl.editor.savebar
• system.editor.precursor.buttons

Asks

We’re eager to hear your thoughts:

• What are your thoughts on the new page extension locations?
• Would it be beneficial to introduce an additional configuration option that enables you to choose whether your application appears in the editor in addition to the renderer? Alternatively, would it be preferable to have a separate extension point location name for the editor, rather than re-using the view page extension point?
• Are there any other potential challenges / opportunities you anticipate?

Your insights will help us refine the solution to better meet the needs of our users.

Rough Timelines

Early October 2024: We plan to test all of the above changes in the Live-Pages EAP. Click here to join the Vendor EAP and test out these changes prior to this initial release.

Further updates will be provided regarding the implementation of these changes outside of the live-edit pages stream; no changes are expected until the earliest April 2025.

[marc]

Hi @TamimNoorzad ,
Thank you for the RFC with screenshots. This makes the proposed changes clear.
I do have a question: RFC-59 (RFC-59: Upcoming changes to Confluence navigation) will also change some of the extension points in Confluence. For me it is unclear what the end result of both of these changes are, as both seem to touch some of the same extension points.

Can you give more information on this?

[klaussner]

Thank you for this RFC, @TamimNoorzad. I appreciate that you are planning to make more extension points available in edit mode.

What will be a big problem for us and other vendors, however, is the removal of dynamic titles and icons for content byline items. These are absolutely essential for our app because we are using them to show a page status to users when they open a page. If only the app name is shown instead and users have to click on the item first to see the status, this will drastically reduce the value our app can provide to our customers.

It’s also not entirely clear to me what improvements the proposed solution would bring. In your first example under “Location 1: Page byline”, the screenshot of the current solution shows eight app byline items. How do these items map to the three byline items shown in the proposed solution? For example, how can users access the “Read in 1min” byline item in the proposed solution? Also, the space available for apps appears to be significantly reduced in favor of emoji reactions and whitespace.

I hope you will reconsider this design. For example, a compromise could be to allow one byline item per app with a dynamic icon and title and to make additional byline items by the same app accessible via an overflow menu.

[osiebenmarck]

Hey @TamimNoorzad, thank you for the RFC!

I’d like to expand on @klaussner’s point about the byline items. Today, apps use the dynamic nature of the byline items to directly provide contextual information to the user. Hiding this information will in many cases make the whole byline item moot. Information currently displayed by apps like:

• Does this page need a review?
• Is this page outdated?
• Is this classified information?

won’t work as well hidden behind an extra click. App users will very much loose value with this change. As not just an app vendor, but also a user of Confluence, I hope you reconsider this particular aspect of this RFC.

[RobertMayerK15t]

Hi there, thanks for sharing. – The mentioned deprecations will have a big impact on the user experience for apps that are in need of more direct page action. – All remaining options, the byline item, and the overflow menu don’t really offer the same level of visibility to users, as they can be hidden from view.

For that reason, I would argue to keep the entry points system.content.button and page.metadata.banner BUT to give them stricter usage options instead (No custom designs, icon buttons only, …)

Regarding the proposed solutions, two ideas for improvement:

• As a user, I struggle to understand what action in the overflow menu belongs to what app. → Add separation lines or even section titles (App name) for the app actions in the overflow menu?
• As a user, I am overwhelmed by the amount of byline items on my page. The app names don’t really tell me what actions I can do with them → Allow app vendors to combine actions from multiple apps into one “solution byline item” E.g. One Scroll Exporters item would enable users to export in different formats (PDF, Word, HTML).

Happy to provide more details if needed

[Corentin]

Hi, thanks for the RFC.

Not sure if it falls under the definition of “Extension point”, but are there any plans to extend the APIs provided to apps in the Confluence Editor?

For instance:

• Allow apps to modify the page content highlighted in the Contextual floating toolbar (page.view.selection/action-panel), to replace the highlighted text by an inline macro.
• Allow apps to insert adf at the cursor position via an editor tool (Insert a link, a table with predefined columns, etc) ?

As far as I’m aware, that is not currently possible (please let me know if that’s wrong)

Best regards, Corentin.

[DmitriyLadutsko]

Hi everyone,

@TamimNoorzad, I have a few concerns regarding this RFC. As a developer of the Handy Macros app from Stiltsoft, I see critical blockers for the app in the proposed changes.
Deprecation of the atl.page.metadata.banner will affect UX and UI when interacting with our app feature for setting advanced page statuses. Please note that this is a major feature of the app that users regularly add and interact with. There’s no feasible workaround or alternative in the context of this RFC. For better understanding, please see the screenshots of the app UI before and after the proposed changes.

After the proposed changes:

I also want to point out that we have already reported this issue in the context of the Live-Pages EAP.Another question concerns the deprecation of the system.content.button . We use this button to allow users to interact with the app faster. Placing this functionality in the second level of the menu hierarchy will downgrade UX.

I look forward to hearing from you and am open to further discussion.

[scott.dudley]

Hi Atlassian,

Thanks for sharing this RFC. I have a number of reservations:

Byline items

I have concerns similar to the other comments posted so far. For bylines, what is wrong with the status quo? The rationale for making these changes was not stated, but I think this entire change would be a mistake. Byline items are used to deliver app-based features and functionality to users. Diminishing their visibility (and removing their easily-visible dynamic components) prevents apps from communicating in an effective way with users.

It is even less clear why the icons are being removed: text-only buttons are harder to discover and less memorable, and users are less likely to click on them. I imagine that the proposed app buttons/menus look more harmonized and similar when they do not have icons, but that is only a good thing if you want to file away these menu items and never actually use them. (I note in passing that absolutely everything else on the same line is adorned with icons for the built-in features that are rendered here. Imagine how difficult the page would be to read if you removed those icons too. If it is good for Atlassian, then it should be good for vendors too.)

If the problem is that there are potentially too many byline items shown, can Atlassian instead consider a method for controlling this, such as by allowing users or admins to hide or prioritize them? For example, see what was proposed by Atlassian in RFC-59.

Sidebar overflow menu lumping everything under “apps”

I understand that menu real estate is at a premium, but I think this is also reminiscent of the issue I mentioned in RFC-59. Third-party apps deliver functionality to users, and Atlassian is proposing to take these previously-defined localized extension points and throw all of it under a separate “Apps” menu.

The recent focus from Atlassian is to harmonize working across products (“System of Work”), but the proposed change goes in the opposite direction by creating an artificial barrier by throwing everything non-Atlassian under an “Apps” menu. Users do not know or care whether a feature is native to the platform or whether it is provided by a third-party vendor, and moving these existing items will create friction and get in the way of a seamless user experience. It also hurts discoverability. (Why do end users need to know that something is an “App” when they just want to approve the page?)

If the concern is (again) too many items in the menu, there are a number of other ways to solve the problem. For example:

1. Allow app vendors to create sub-menus. If my (say) page approval app has options like “approve page”, “disapprove page” and “escalate page”, it might make sense to put these under a new “Page Approvals” submenu that is created by the app. But other options belong more properly directly within the content menu, where they have previously lived.
2. Allow admins or users to control the order or hide items, or simply display the first ‘X’ items, with an overflow once vertical screen real estate is exhausted.

Missing various web-panels and web-items

Atlassian is positioning the direct-edit page as a replacement for the view page. From this point of view, direct-edit should support everything that the view page does. Since sites will potentially have both types of content, the two should be consistent in terms of extension points and rendering.

For example, what happened to the atl.footer extension point? This should also be rendered in the direct edit view.

Also, reading more closely, can you confirm if this RFC is actually a deprecation notice for the other plugin points you mentioned? Not just in the editor, but actually system-wide? (I am referring to page.metadata.banner, atl.editor.savebar, and so on.)

[david]

Yet again, @scott.dudley is bang on with another RFC. I agree with all of the above.

And please add atl.footer back into the edit view for live edit pages. There was no deprecation notice. It was there during the beta, but now it has mysterious vanished. I need it back – you’ve broken my app.

[MattiaLomazzo]

Hello Atlassian,

I would also like to thank you for the RFC and insight into the various planned changes. I agree with the previous feedback.

This quote from Scott summarizes the most important insight regarding end users, which the UX team apparently has not yet recognized.

@scott.dudley

Users do not know or care whether a feature is native to the platform or whether it is provided by a third-party vendor, and moving these existing items will create friction and get in the way of a seamless user experience.

As Scott writes, a look at many questions in the community or interviews with end users shows that the majority, in most cases, do not know the Atlassian product very well, its hosting or which features and functions come natively or via third parties.

The changes proposed here and in the RFC regarding the navigation changes do not take this into account; on the contrary, the end user is expected to know which app offers the functionality they are looking for.

I believe that you need to rethink and revise these proposals accordingly.

[JackGraves]

Thanks for sharing this RFC with us. The improvements to integration within the editor look very interesting - we know our customers would love to use our functionality (byline and context menu) from within the editor - it’s usually how people expect things to work.

We do however share the concern that most of the other developers have raised in this thread.
The removal of dynamic byline entries severely hampers the ability of apps to give concise and easy to view feedback to users.

As a lot of apps have some sort state machine or state data that is often highly relevant to users especially in an at-a-glance format.

With the potential removal of these dynamic byline entries all apps would either fight for the few data points that are available for providing a status/state or you would see a lot of large panels or “hacky” workarounds with developers doing their best to ensure users can keep current functionality.