Atlassian Partner Developers,
The developer preview of Referentiality has been released! This developer preview provides developers* like you in our Ecosystem App Developers Group insight into how we are thinking of solving the issues with nested bodied macros and how you can solve them with Referentiality. In our sneak peak post, we explained the why we’re tackling this issue and in this post, we are going to go over the how and what: how to use a Connect app for Referentiality and what is happening within Confluence to enable this feature.
Let’s start off with a Connect Macro sourcing its data from a Native Confluence Macros, such as a Native Table Macro**. This solves one of our most common use cases of extending the functionality of Native Table Macro within the page. To achieve this, we’ve introduced a customizable
refDataSchema property for Dynamic Content Macros which provides support as a Target for Native Table Macro with
table-adf. This property allows for different
inputTypes which Confluence uses to identify the different compatible types for an existing macro. When a subscribing macro is set with
table-adf as its
inputType, it allows for a user to append it under a Native Table via the ContextualToolbar.
Another common use case is for our users to use 2nd party Connect dynamic content macros to be able to share, chain data, and have the macros react to incoming changes in realtime. What was possible in the Server with nesting, we’re enabling Cloud users to connect and chain macros. And as Confluence discovers and links all compatible macros by the
refDataSchema at runtime, the Target macro would require the same
inputType property as the Source macro’s
outputType property for a link to be established. Support for chaining macros is also made possible should the chained macros have compatible
Another connection we have enabled is for macros to target the Native Chart macro. Wouldn’t it be nice if your macro can extend this commonly used macro? With Referentiality enabled, it now can. You can access the same Native Chart as the Native Table can by updating your macro’s
In addition to Native Chart and Connect macros as Targets, we are also supporting Forge macros. All Custom UI and UI-Kit macro modules are supported as Targets.
And here is a table of all the different combinations between macro types, and which can be a Source and Target macro.
|Native to …||Native Table → Native Chart||
Native Table → Compatible Connect Macros with
Native Table → UI Kit & Custom UI Compatible Forge Macros with
|Connect to …||
Compatible Connect Macros with
Any Compatible Connect Macros that share similar
Any Compatible Connect and Forge Macros that share similar
As developers, we know the best docs are well-written docs that come with a companion app. So to demonstrate the uses of Referentiality, we have released a demo companion Connect app and a Forge app that will allow you to locally run and test this feature. You can find all of the code used in the examples here in the Connect app repo and Forge app repo.
In order for Referentiality within Confluence to work, a few things must be wired up:
- A Source macro must publish data using the
- A Source macro must have an
outputTypedefine within its Descriptor
- A Target macro must have an
inputTypethat is of a compatible
outputTypeas the Source macro
- A Target macro must register to listen for the
It’s a match given source macro’s
outputType is same with target macro’s
inputType. When it’s a match, the target macro will be listed in the ContextualToolbar dropdown of the source macro.
Currently, there are 2 supported types for output and input that are validated before passing the data to the target:
table-adf: expected to be a valid json that conforms with table-adf schema.
table-json: expected to be a two-dimensional json array, that can include any valid json primitive or object.
If a macro defines
table-json as their
inputType then they can expect that the incoming data will be valid objects. If the data validation fails, then an error message is passed back to the source macro’s callback function and nothing is passed to the target macro.
We plan to work with developers, address concerns that you may have regarding this feature and release this feature to end users in the next few months. And as part of our Open culture, we want to share with you the upcoming changes we plan to make.
Now you may be asking how this 1:1 relationship between macros solves the needs for a more complex chained list of macros. Within the same page, you can currently chain a list of supported macros that share a common schema; that is, they both include the same
inputType. We know some of you might like it stacked atop each other, while others prefer a singular viewport, so we are working on improving this user experience to allow chaining multiple macros together within the same Viewport.
Concept showing how chained macros share the same viewport, in Confluence. Additionally, a portion of the RightContextPanel shows the full chaining relationship and allows navigation between chained macros.
Partner macros will be shown separately from native macros inside toolbar, for an improved browsing experience
A dedicated dropdown within the ContextualToolbar for partner macros. The current iteration of this design allows for developers to easily access their macros within the ContextualToolbar while testing their changes; and while this is optimal for developers, the experience may be difficult for end users to navigate. We plan on adding an additional dropdown to hold a list of Target macros, as the concept below illustrates. Each option will showcase a macro’s icon and name, as described within the manifest. The manifest will be updated to include an optional icon property or will be substituted with a default icon.
Concept showing an extensible toolbar for a macro in Confluence. Native apps are shown in the main toolbar body, and partner macros are shown in a dropdown menu.
Configuration options within the RightContextPanel to set Source and Target macros for the selected macros. This would be a natural extension of the existing macro configuration that users can customize.
Concept showing a macro’s connections (a Source macro, and a Target macro) inside the RightContextPanel.
A new identifier will be introduced to enable referencing multiple ADF nodes. This would expand the pool of references by allowing users more flexibility to create references; as currently, single content block nodes can be used for references.
We are releasing this feature so early adopters can begin to experiment with your modified macros in a test environment before we enable to the general public. After this main release, we are planning on iterating on our designs and releasing more frequently.
We are actively working on making this developer preview better and are open to your feedback and concerns. We are committed to sharing updates and engaging with the Developer Community. We can’t wait to see what you build with Referentiality.
* If you’re not a part of our Ecosystem App Developers Group, please visit http://go.atlassian.com/cc-eco-beta .
** Yes, we’re deliberately calling the Native Table Element a macro because it flows better in the Nested Bodied Macros narrative.