How did I create Vertical Table Headers in Confluence

TL;DR

As a passionate Confluence user with a keen eye for problem-solving, I was intrigued by the longstanding request for vertical text functionality within table headers.

I was able to develop a Vertical Text Macro, which empowers users to effortlessly transform horizontal headers into crisp vertical text.

This project not only addresses a long-standing need within the Confluence Community, but it also demonstrates my ability to think creatively and my dedication to finding elegant solutions for real-world user pain points.

Why?

As Confluence users, we've all encountered the frustration of cumbersome table formatting. Horizontal headers, particularly for narrow data columns, can create wasted space and hinder readability, especially on smaller screens.

This pain point, highlighted by numerous user requests since 2016 (including e.g.?here for Confluence Server), has remained unaddressed for quite some time in Confluence Cloud.

However, fuelled by a desire to empower fellow users and my ongoing exploration of the Atlassian Forge ecosystem, I decided to tackle this challenge.

Inspiration & Opportunity

Personally, I've encountered this limitation countless times. Imagine a table with a?"Description" column needing ample space, while a "Status" column simply uses emojis like ? or ?. Horizontal headers force unnecessary width allocation, hampering visual clarity.

This frustration, coupled with my technical expertise and a recent deep dive into Atlassian Forge's capabilities, sparked a potential solution. While Confluence lacks native vertical text support, I recognized the power of custom macros. A?lightbulb moment struck – what if I could combine a custom macro with a?configuration to achieve the desired outcome?

Overcoming Technical Hurdles: A Creative Workaround

The journey wasn't without its challenges.

Implementing true vertical text that would support any formatting within Confluence's core functionality proved complex. However, I?focused on the user need to keep it simple: Transforming horizontal headers into space-saving, visually appealing simple formats.

I created a Custom UI macro that accepts the header text as a configuration and transforms it into the desired vertical format.

This approach offers several advantages:

• User-Friendly: The macro provides a simple interface for users to input their desired vertical header text.
• Non-Destructive: The original text remains intact within the macro, ensuring editability.
• Lightweight & Efficient: The solution leverages existing Confluence features, minimizing performance impact and keeping complexity low.

How?

Confluence Forge offers three options for creating custom macros: UI Kit, UI Kit 2, and Custom UI. For achieving custom text styling, which was crucial for vertical display, the Custom UI was the only viable choice, because the other two options don't support custom styling.

The initial Proof of Concept presented some unforeseen obstacles:

• The table header itself wasn't resizing properly to accommodate the vertical content.
• Multiline text was not always completely visible.
• Rich text was not supported.

The Solution (technical)

I explored various avenues to overcome these hurdles. Here's where the technical details get interesting:

CSS for Vertical Transformation:

• To achieve the desired vertical alignment, I incorporated a custom stylesheet within the Custom UI content. Initially, I attempted using the writing-mode CSS property (vertical-lr or vertical-rl). While this rotated the text technically, the rendering appeared unnatural and visually unappealing.

• I opted for a more refined approach using the transform CSS property with transform CSS property: scaleX(-1) scaleY(-1). Both these together effectively rotated the text 90 degrees while maintaining a natural presentation for multi-line text.

Responsive Height:

• Confluence conveniently injects iframeResizer (https://github.com/davidjbradshaw/iframe-resizer) for Custom UI macros. This script is designed to automatically adjust the height of the iframes within the macro content. Unfortunately, in this case, it wasn't seamlessly within the context of the table header when the text was vertical, because the header height kept increasing…

• Rather than delving into a lengthy investigation of the iframeResizer behavior, I chose a more direct approach. I implemented a custom callback function within the ReactDOM.render function (React 16 legacy function - still used by Atlassian Forge SDK). This custom callback function calculates the actual height of the vertical header content and dynamically updates the corresponding CSS style to ensure proper sizing.

Addressing Multi-Line Text:

With the vertical text rendering and height adjustments working as intended, two final hurdles remained. The table header width wasn't adjusting automatically for multi-line vertical text. To address this, I employed a whitespace CSS property and set it to no-wrap. This ensures the entire header displays on a single line, preventing unwanted width expansion.

The Solution for Rich Text (even more technical)

While using the Config to set the desired header text was a feasible solution, it had a limitation: The header text could only be in plaintext, it could not be a rich text with formatting or any other content.

After building and verifying this Proof of Concept, I’ve found an innovative solution to support rich text and preserve the formatting when displaying it as the vertical text.

Here's a glimpse into the technical aspects (feel free to skip ahead if technical details are less interesting):

• Custom Macro Development: I created a macro that is added next to the table header text.
• Page Trigger Integration: The macro integrates with a page trigger, a Forge feature that executes code when a page is saved. Upon saving the page, the trigger activates, finds the header text, the macro’s unique ID (localId) and stores the ID and the text as a key-value pair as the page content property using Confluence REST API. It also removes the header text from the page, keeping only the macro in the table header cell and saves a new version of the page, with only the macro in the header.

• Dynamic Text Manipulation: When the macro loads, it dynamically loads the text from the page content property using the Confluence REST API and transforms the text it into the desired vertical format. In order to update the header text again, a new text can be added next to the macro and the process will be repeated.

What's next?

The future holds exciting possibilities for further development.

Roadmap:

• Rich Text & Emoji Support: Currently, the macro supports plain text. Future iterations could leverage advancements in the Atlassian Forge SDK to incorporate rich text formatting options and even emoji integration within vertical headers. This would inject a new level of visual appeal and flexibility for users.
• Multi-Line Text: A Calculated Approach: The first version intentionally focuses on single-line text to ensure a smooth user experience. However, based on user feedback and demonstrated interest, exploring multi-line capabilities is definitely within reach. Careful design and implementation will be essential to maintain clean visuals and efficient performance.

User-Driven Development: Your Feedback Matters Most

The Vertical Text Macro empowers users to streamline their Confluence tables, enhancing readability and optimizing space utilization. This project not only addresses a long-standing user pain point but also showcases the potential of creative problem-solving within the Atlassian ecosystem.

Looking ahead, I envision further improvements:

• Enhanced User Interface: Exploring options for a more intuitive macro interface.
• Conditional Formatting: Investigating the possibility of integrating conditional formatting based on column type.
• Collaboration & Feedback: Inviting the Confluence community to contribute to defining the macro's features and shape its future.

By combining user experience, technical expertise, and a detailed understanding of the Atlassian Forge, I was able to deliver a solution that improves the Confluence experience for many. This project exemplifies my ability to identify user needs, translate them into innovative solutions, and leverage technology effectively.

While the Vertical Text Macro offers benefits for all Confluence users, the macro is currently available as an Early Access release (Sign up here), with Confluence Administrators and users with the ability to install third-party add-ons being the primary user base.

A Leader Who Codes: Beyond the Code

As a Software Engineering Manager (EM) and a passionate technologist, I believe continuous learning is paramount for effective leadership. This project exemplifies my commitment to both technical expertise and people management skills.

Expanding my technical skillset, I explored the capabilities of Atlassian Forge SDK, and Atlassian APIs and navigated the intricacies of the Atlassian ecosystem.

While the coding provided a technical challenge, this project wasn't solely about the code itself. Understanding the user experience (UX) frustrations motivated me to find a solution that would allow me to reach out and interact with the broader Confluence community.

I believe collaboration fuels innovation. My vision for the Vertical Text Macro extends beyond a personal project. My goal is to continuously improve this tool by:

Seeking User Feedback and understanding user needs and gathering feedback are crucial for future development. Involving the community empowers me to prioritize features that truly enhance the user experience.

By fostering an open dialogue and sharing my knowledge, I hope to inspire others within the Confluence community to contribute their ideas and expertise and to help building a thriving ecosystem.

This journey with the Vertical Text Macro is a testament to my commitment to:

• Technical Proficiency: Keeping my technical skills sharp and adapting to new technologies.
• People-Centric Leadership: Leveraging technology to create solutions that empower users and improve workflows.
• Collaboration & Innovation: Believing in the power of community to drive progress and shape the future.

Hope this helps.

Technology Used

• Git
• npm
• curl
• jest
• bash
• CSS
• SVG
• HTML
• JSON
• eslint
• pnpm
• React
• VSCode

• Unicode
• TypeScript
• JavaScript
• Markdown
• Atlassian Forge
• Atlassian Confluence
• Atlassian Confluence REST API