Having tested this early preview I’ll post my findings here.
This feature essentially seems to be a pub/sub event mechanism to enable data sharing between macros. Like AP.Events, but more restrictive, as I’ll detail further below.
Perhaps the most important point to start with is one raised by others here - data sharing is not nesting, and a data sharing solution like this or AP.Events is not a nesting solution.
For Confluence users, nesting means having a rich text macro and working inside the body area, using the native page composition tools (including adding macros) of the Confluence editor to compose content - take the following basic example:
There are virtually unlimited possibilities for nesting native and third-party macros in various arrangements inside rich-text macros - offering significant value to the user.
Consider now how would we try to implement nesting using this new feature:
You insert the target rich-text macro from a source macro and… Then what? Even assuming the feature is developed further to support multiple source macros, how are we to infer what the user wants to do with these macros inside the rich-text body, or where to place them in relation to the other body content? A data sharing mechanism such as this one is really not designed to support the complex nesting functionality that users have enjoyed thus far.
On Connect this does not have a huge impact because we have rich-text macros and can implement our own nesting solutions without this new feature. As others have pointed out though, fast-forward to a future with native Forge modules seemingly not supporting rich-text macros and this becomes a significant feature absence on that platform, and significant loss of value delivered to the users.
Based on this preview, I feel like the feature is not going to live up to what was sold in the original blog as addressing the nesting gap on cloud.
Another point to make relates to the following:
What should be made explicit here is the additional requirement that you must insert target macros using the new context toolbar UI element found on source macros. Let’s consider the following scenario:
Often when macros work together, they are not necessarily placed directly beside each other. Many apps contain such macros - an example pair of macros from Content Formatting are Footnote and Footnote Display. With Referentiality, in such a scenario the user would no longer be able to insert macro2 freely at any point on the page. They would need to insert it using the new UI element on macro1, then drag it to where they would like it to be. This is a far less convenient user experience than simply inserting the macro where the user wants it, which AP.Events supported through data sharing which was not hindered by restrictions such as this.
The one new piece of functionality introduced here which was not available using AP.Events is the introduction of published data from native macros such as Table. It should be noted however that the data emitted could already have been retrieved by a custom macro using the content API - establishing the correct relationships could also be done this way, based on page placement of the macros.
Some additional restrictions from my testing:
- Does not work if the source macro is inline
- Does not work if the source macro is rich-text
Is this because Forge will not support inline and rich-text macros, or are these planned?
- The target macro can be rich-text, though when you perform the macro insertion it renders as a bodiless macro initially. Seems like a bug.
- The restrictiveness of Referentiality’s data sharing model prohibits use cases supported by AP.Events where only a single macro is involved, such as sharing data between a dialog and the primary macro iframe, or a dialog and a custom editor. We have this kind of functionality in Content Formatting, which AP.Events is useful for.
- The Native Chart functionality was not there so I could not verify this. Based on the matrix in the original post, Chart should be visible on Table’s context toolbar even before adding any custom macros, but on my instance it was not:
Considering Forge, of course we know that in native Forge modules, we have lost access to the Connect AP library. As Referentiality presents functionally as the replacement for AP.Events going forward it’s worth asking: are there any plans on recreating AP.Events more fully in Forge, eg without the restrictions mentioned above?
I would echo this - when planning ahead for Forge we need to acknowledge that it currently does not support bodied macros and unless I am mistaken we haven’t had an indication that it will. Having established that Referentiality is not a nesting solution, it’s becoming increasingly difficult to be an advocate for Forge adoption.
In case this wasn’t clear from other posts I can confirm from my testing:
- Any string value can be used for the outputType and inputType properties
- Macros are matched based on matching values in these properties
So what is special about table-adf and table-json?
- Automatic validation is provided when these particular values are specified, based on the criteria in the original post. The emit call will fail if the validation does not pass.
- Atlassian are adding these to native macros (eg outputType: table-adf on Table macro), allowing for example a custom macro to specify inputType: table-adf to pair with the Table.