Pages with Deck and Card macros are Broken After Upgrading to Confluence 4.x/5.x

Add-on:Composition
Question:Pages with Deck and Card macros are Broken After Upgrading to Confluence 4.x/5.x
Answer:

There are several reasons that could cause this issue:

 

 Deck & Card Macros without Nested Decks or Section & Column Macro

e.g.

{deck}
{card:label=Label 1}my contents in 1st card{card}
{card:label=Label 2}my contents in 2nd card{card}
{deck}

If the pages with above format broken after upgrade, most probably because the upgrade process is not following our upgrade guideline here.

Ref on reported issue here.

 Deck & Card Macros without Nested Decks but Enclosed within Section & Column Macro

e.g.

{section}
{column}
{deck}
{card:label=Label 1}my contents in 1st card{card}
{card:label=Label 2}my contents in 2nd card{card}
{deck}
{column}
{column}Contents of second column{column}
{section}

We are seeing several users reported the pages with above format broken after Confluence upgrade.

"I think part of the problem is due to Sections - if the deck is contained inside a Section, the entire card/deck structure breaks. Removing the Section is often all that is needed (but not always) Sections within cards seem to render fine. Decks within Sections do not" - shared by Sean Diggins (ref).

Workaround

The workaround is either edit the page before upgrade by removing outer Section & Column macros; or manually editing the page after upgrade, by putting the contents back to its original place.

 Deck & Card Macros with Nested Decks

e.g.

{deck}
{card:label=1st Outer Tab}
{deck}
{card:label=Label 1}my contents in 1st inner card{card}
{card:label=Label 2}my contents in 2nd inner card{card}
{deck}
{card}
{card:label=2nd Outer Tab}Contents of second outer card{card}
{deck}

This issue is heavily discussed here. The system does not recognize the last {deck} should match the first {deck}. It took the second {deck} to match the first and thinks the third {deck} should match the last {deck}.

The workaround was to edit every individual page in Confluence 3.5.x and use {deck1} {deck2} {deck3} and {card1} {card2} {card3}.....

So, you need to edit e.g. to as follows:

{deck}
{card:label=1st Outer Tab}
{deck1}
{card1:label=Label 1}my contents in 1st inner card{card1}
{card1:label=Label 2}my contents in 2nd inner card{card1}
{deck1}
{card}
{card:label=2nd Outer Tab}Contents of second outer card{column}
{section}

and we will have to add the macros to the plugin.

Note that this means you would essentially have to edit all pages while in Confluence 3.5.x before upgrading and this will cause errors at your end when you save. We figure out this will not solve the overall problem and moreover where do we end.

We ran through the plugin with our developers & they did confirm that there is nothing that we can do about this issue with the switch from Confluence 3.x to 4.x. We would have come up with a fix if we could but this problem cannot not be fixed. As for designing a workaround, we ran through in detail and concluded the workaround would be manual and it would take as much time to resolve compared to editing each page individually. The problem is caused by the architectural differences between Confluence 3 and 4 and the very nature of how the content is displayed with Composition.

Workarounds

So far we found several manual workarounds for users that will require other plugins/macros:

(i) Add the nested deck in a template, and call the template via Live Template macro from Scaffolding plugin. Another way is to create two templates where first template having the outer deck, and second template having inner deck; the first template could pull second template using Live Template macro, and original page pull first template using the same macro from Scaffolding. (ref)

(ii) Move the inner deck(s) to child page, then using Reporting plugin to retrieve the child pages from parent page; described in details here.

(iii) Similar to (ii), but users could easily pull the child pages using Include macro instead of Reporting plugin.

(vi) Using Cloak macro to replace nested Deck & Card, as described here.

Example of correct nested Deck & Cards: