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
  UPDATE 26th September
  Discuss: October 4th

• Resolve: October 11th, 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.

[nathanwaters]

Focusing on clutter: I think the sensible solution is to let admins control what is displayed in the byline. Much like you can control what’s in the top menubar or app dock on MacOS, or the extensions bar and overflow dropdown in Chrome.

And this should extend to whatever bloat Atlassian thinks should be in there. eg let admins remove any or all of this:

You can find plenty of customer complaints online where they want to remove the page creator from that byline.

[adapps]

Honestly, many of these proposals seem more like regressions than evolutions. In fact, the only thing being suggested is adding some extension points that are already present in the view mode to the new unified mode. Additionally, many of these extensions are deprecated or restricted in functionality.

Extension points that can directly interact with and modify the page content would be very useful. That would be the real turning point for the Confluence editor. Currently, the only way to add content to a page is through macros, but macros are small sandboxes with no awareness of the surrounding content and cannot interact with each other. This makes it hard or impossible for third-party apps to communicate with one another, resulting in constant friction with users who don’t understand why many apps are incompatible.

In any case, the biggest issue with this proposal, as many others have already mentioned, is removing the interaction from the byline.

Countless apps on the store rely on dynamic byline items as their main extension point. This change would break them or render them almost entirely useless.

For example, like many other apps that add multilingual functionality to Confluence, our app Lango uses the byline as the main extension point to display the page’s language with the language name and icon. Without this capability, all translation apps would lose significant value.

Has Atlassian conducted an impact assessment on these changes, analyzing how many apps on the store rely on these extension points and how they would be affected? Could you share the results of this analysis?

[AlexeyMikhaylovStilt]

Hi there,
These changes will affect the Table Filter, Charts & Spreadsheets app with over 15k installations.
The removal of system.content.button extension point will break users’ workflow and reduce their awareness of the app features, decreasing app usage by customers and their loyalty.
The atl.page.metadata.banner extension point is used as a shadow controller that shows onboarding, updates, feedback, and tips and tricks forms in the context of pages. Removing this point will also reduce users’ awareness of the app’s capabilities and break the users’ feedback loop making it harder for us to get in touch with target app users.
Please, consider not removing the existing extension points so that vendors won’t need to reinvent worse solutions with worse UX.

[TamimNoorzad]

Hey everyone, thank you for your patience and for your constructive feedback. We’ve tried to thematically address most points below:

Byline

Based on your feedback, we have revised the designs for the byline:

We will display up to 5 apps in the byline

• If there are fewer than 5 apps, all will display
• Beyond 5 apps, some apps will display in an app overflow menu
• For the near term, apps are ordered according to their installation dates, with a pathway to allow admins/customers to decide which 5 to show

We will include an optional app icon for each byline app

• App icons are standardized at 16px
• We recommend using color tokens from the Atlassian Design System to increase visual harmony of your icon with the rest of the page content

Byline apps can be dynamic

• App names may be dynamic in the byline
• To accommodate 5 apps and their icons in the standard page byline, we recommend keeping your app name under 20 characters in length (approximately 115px wide)

When clicking an app in the byline or the byline app overflow menu, a popup or modal may appear for users to further interact with app content. This is existing behaviour, and we are not changing that.

Overflow location design

Similar to the byline, apps in the overflow menu may also display further content in a pop up (shown above) or in a modal.

Deprecation of existing locations

With regards to atl.footer , page.metadata.banner and atl.editor.savebar we are going to deprecate them to create a clearer and more consistent UI experience across Confluence. We believe the updated byline designs should be able to cater for these existing location use cases.

This deprecation will commence at the earliest in 6 months time. We recommend reviewing your usage of this extension point and exploring alternatives for upcoming changes.

Letting Admins or Users control the order or hide apps

We’ll take this suggestion into consideration as part of the byline design review process, especially in relation to similar feedback we’ve received from customers. However, we will consider this outside of the scope of this RFC.

Link to RFC-59

I do have a question: RFC-59 (RFC-59: Upcoming changes to Confluence navigation 1) will also change some of the extension points in Confluence.

The changes outlined in this RFC (RFC-63) focus solely on entry points and usage of page-level apps.

RFC-59 discusses changes to the left rail impacting site and space-level apps and some settings preferences of apps.

Other items

Are there any plans to extend the APIs provided to apps in the Confluence Editor?

At this time, there are no plans to extend the APIs provided to apps in the Confluence Editor.

Allowing apps to insert adf at the cursor position via an editor tool (Insert a link, a table with predefined columns, etc)

Allowing page extensions to modify the page content is currently not within the scope of the changes we’re making. We recognise the potential benefits and will keep this in mind for future improvements as we continue to evolve the Confluence experience.

Thank you for your questions and comments! Feel free to join the Live Pages EAP (Click here) to test these changes ahead of the initial customer release in October.

Keep the feedback coming!

[klaussner]

@TamimNoorzad Thank you for revising the design of the content byline items. The new layout looks much better. Do I understand correctly that only the title can be dynamic and not the icon?

[nathanwaters]

I’m not sure how others are using alt.footer but I do know it’s often used by Connect apps to inject a background page script that doesn’t have any UI elements. If you’re going to remove that you need to provide an alternative for that use case.

[david]

This will break things for us.

I mean I could put things in atl.header, but really just wanted my stuff to load last.

I don’t want to see a nasty loading icon from Atlassian Connect at the top of the page if Confluence is loading resources slowly. I can’t use Forge instead for this functionality becuause forge is not ready yet.

[scott.dudley]

@TamimNoorzad

• For the near term, apps are ordered according to their installation dates, with a pathway to allow admins/customers to decide which 5 to show

Letting Admins or Users control the order or hide apps

We’ll take this suggestion into consideration as part of the byline design review process, especially in relation to similar feedback we’ve received from customers. However, we will consider this outside of the scope of this RFC.

For the love of Confluence, the MVP absolutely has to include the ability (for at least admins, if not users) to configure the apps that appear above the overflow. Vendors already communicated clearly in past comments that it was critical to usability that their byline items be visible at a glance, without clicking.

Using “installation order” is effectively the same as saying that five apps will be randomly selected, since customers have little control over this (and especially not retroactively). This proposed change is thus still imposing the original problem (the one that vendors already said was unacceptable) on all but five randomly-selected apps.

Customers cannot uninstall and reinstall apps to modify the installation order. Uninstalling deletes all of an app’s data in Forge storage (by Atlassian design). Aside from that critical issue, it would also be unreasonable for vendors to ask customers to incur app downtime and uninstall/reinstall other vendors’ apps in order to correctly provision functionality for their own app.

If it is “outside the scope of this RFC” because you do not have enough person-hours to do it in the current scope, or because it is harder to implement, please consider whether you can drop some of the other changes from this RFC to allow yourself enough resource time to make it happen. If you cannot, then please consider postponing all of the byline changes until you do have the time to do it all at once.

[scott.dudley]

@TamimNoorzad

Byline apps can be dynamic

• App names may be dynamic in the byline

Does this really mean “app names”? Can you confirm that this actually means the existing Forge dynamic properties for “title”, “icon” and “tooltip”, and the Connect “name”? If not, how will this information be supplied?