AtlasCamp 2010: Macro Migration Guide for Confluence 4.0 - Ryan Thomas
0 likes1,029 views
Confluence 4.0 introduces a new XHTML storage format, API, and migration process from wiki markup to the new format. Content and macros will be automatically migrated to the new format, but anything that cannot be migrated will be wrapped in a macro. A custom migration can also be implemented. The document demonstrates the new features and encourages feedback on the alpha release.
![Inline Wiki Markup Completion
[space]
[*]
7
Tuesday, November 2, 2010](https://image.slidesharecdn.com/macromigration-101102182021-phpapp01/85/AtlasCamp-2010-Macro-Migration-Guide-for-Confluence-4-0-Ryan-Thomas-7-320.jpg)
![Links
11
[Link To Home Page|Home]
Wiki Markup
<ac:link>
<ri:page ri:space-key="ds" ri:content-title="Home" />
<ac:link-body>Link To Home Page</ac:link-body>
</ac:link>
XHTML
Tuesday, November 2, 2010](https://image.slidesharecdn.com/macromigration-101102182021-phpapp01/85/AtlasCamp-2010-Macro-Migration-Guide-for-Confluence-4-0-Ryan-Thomas-11-320.jpg)
![Macros
12
{code:java|title=Migrator Interface}
public interface Migrator {
String migrate(String wiki, RenderContext renderContext,
List<RuntimeException> exceptions);
}
{code}
Wiki Markup
<ac:macro name="code">
<ac:parameter name="title">Migrator Interface</ac:parameter>
<ac:default-parameter>java</ac:default-parameter>
<ac:body><![CDATA[
public interface Migrator {
String migrate(String wiki, RenderContext renderContext,
List<RuntimeException> exceptions);
}]]>
</ac:body>
</ac:macro>
XHTML
Tuesday, November 2, 2010](https://image.slidesharecdn.com/macromigration-101102182021-phpapp01/85/AtlasCamp-2010-Macro-Migration-Guide-for-Confluence-4-0-Ryan-Thomas-12-320.jpg)
![Disabled Macros
14
{diabledMacro:param1|param2=value2}
And I have a body
{disabledMacro}
Wiki Markup
<ac:macro name="unmigrated-wiki-markup">
<ac:body><![CDATA[
{disabledMacro:param1|param2=value2}
And I have a body
{disabledMacro}
]]></ac:body>
</ac:macro>
XHTML
Tuesday, November 2, 2010](https://image.slidesharecdn.com/macromigration-101102182021-phpapp01/85/AtlasCamp-2010-Macro-Migration-Guide-for-Confluence-4-0-Ryan-Thomas-14-320.jpg)
![Migration
• Anything that cannot be migrated gets
wrapped in a new macro: unmigrated-wiki-
markup
19
<ac:macro name="unmigrated-wiki-markup">
<ac:body><![CDATA[
{bad-wiki[markup|
]]></ac:body>
</ac:macro>
Tuesday, November 2, 2010](https://image.slidesharecdn.com/macromigration-101102182021-phpapp01/85/AtlasCamp-2010-Macro-Migration-Guide-for-Confluence-4-0-Ryan-Thomas-19-320.jpg)
AtlasCamp 2010: Macro Migration Guide for Confluence 4.0 - Ryan Thomas
- 1. Confluence 4.0, Macros and Migration Ryan Thomas ryan.thomas@atlassian.com 1 Tuesday, November 2, 2010
- 2. Overview • Confluence 4.0 • XHTML Storage Format • New API • Migration • Macro Migration 2 Tuesday, November 2, 2010
- 4. New RTE Interface 4 Tuesday, November 2, 2010
- 5. Macro Placeholders 5 Tuesday, November 2, 2010
- 6. Many WYSIWYG Improvements 6 Tuesday, November 2, 2010
- 7. Inline Wiki Markup Completion [space] [*] 7 Tuesday, November 2, 2010
- 8. Confluence 4.0 • No more wiki-markup! • Better keyboard shortcut support. • Legacy ‘insert wiki-markup’ support. • We have many wiki-markup fanatics at Atlassian - we have to satisfy them all. 8 Tuesday, November 2, 2010
- 9. New Storage Format • No more wiki-markup! • Content stored as XHTML with custom namespaces. • We provide an API to interact with the Storage Format 9 Tuesday, November 2, 2010
- 10. Headings 10 h3. Creating a new macro in Confluence 4.0 Wiki Markup <h3>Creating a new macro in Confluence 4.0</h3> XHTML Tuesday, November 2, 2010
- 11. Links 11 [Link To Home Page|Home] Wiki Markup <ac:link> <ri:page ri:space-key="ds" ri:content-title="Home" /> <ac:link-body>Link To Home Page</ac:link-body> </ac:link> XHTML Tuesday, November 2, 2010
- 12. Macros 12 {code:java|title=Migrator Interface} public interface Migrator { String migrate(String wiki, RenderContext renderContext, List<RuntimeException> exceptions); } {code} Wiki Markup <ac:macro name="code"> <ac:parameter name="title">Migrator Interface</ac:parameter> <ac:default-parameter>java</ac:default-parameter> <ac:body><![CDATA[ public interface Migrator { String migrate(String wiki, RenderContext renderContext, List<RuntimeException> exceptions); }]]> </ac:body> </ac:macro> XHTML Tuesday, November 2, 2010
- 13. Formatting Macros 13 {color:red}This is some text that should appear in red{color} Wiki Markup <span style="color: red;">This is some text that should appear in red</span> XHTML Tuesday, November 2, 2010
- 14. Disabled Macros 14 {diabledMacro:param1|param2=value2} And I have a body {disabledMacro} Wiki Markup <ac:macro name="unmigrated-wiki-markup"> <ac:body><![CDATA[ {disabledMacro:param1|param2=value2} And I have a body {disabledMacro} ]]></ac:body> </ac:macro> XHTML Tuesday, November 2, 2010
- 15. API 15 • The BodyContent class now has a BodyType member. • Current types are: Wiki, Mail and XHTML • Initial values are populated as an upgrade task. • Why? Selective and on-the-fly migration of unmigrated and previous content versions. Tuesday, November 2, 2010
- 16. API •ContentEntityObject.getContent()has been removed. •This is to intentionally break plugins that use this, in 4.0. •XHTML Storage Format will be returned with ContentEntityObject.getBodyAsString() 16 Tuesday, November 2, 2010
- 17. API • New bean XhtmlContent for performing common operations on the Storage Format. • Allows you to migrate wiki-markup to Storage Format. • Ideally you will not need to touch XHTML when performing operations with this API. 17 Tuesday, November 2, 2010
- 18. Migration • If an instance is upgraded, we need to migrate the content to the XHTML Storage Format. • The latest version of content will be migrated and saved as a new version. • We do this by using a custom renderer that renders wiki-markup to XHTML. 18 Tuesday, November 2, 2010
- 19. Migration • Anything that cannot be migrated gets wrapped in a new macro: unmigrated-wiki- markup 19 <ac:macro name="unmigrated-wiki-markup"> <ac:body><![CDATA[ {bad-wiki[markup| ]]></ac:body> </ac:macro> Tuesday, November 2, 2010
- 20. Macro Migration • Macros also need to be migrated! • Macros don’t have to be 4.0 macros to be migrated (for now). • Custom migration implementations are available to plugins. 20 Tuesday, November 2, 2010
- 21. Macro Migration 21 Preferred Method Start bodyless? Automatic Migration XHTML? Custom? Use Custom Migrator Automatic Migration Yes No Yes Yes No No Wrap with unmigrated-wiki- markup macro To be deprecated Tuesday, November 2, 2010
- 22. Macro Migration • Automatic migration will select one of the built in migrators depending on the body type: •PlainTextMacroMigrator •RichTextMacroMigrator • Custom migration can be used by implementing the MacroMigrator interface. 22 Tuesday, November 2, 2010
- 23. Example / Demo • Upgrading my macros from 3.x to 4.0, and fixing some things in migration. •{mycheese} •{mycolour} red:Some red text {mycolour} 23 Tuesday, November 2, 2010
- 24. Summary 24 • Confluence 4.0 is going to ROCK! • XHTML Storage Format • New API • Migration • Macro Migration Tuesday, November 2, 2010
- 25. Confluence 4.0 Alpha http://atlss.in/confdev4 • This is an ALPHA release for AtlasCampers! • Provided to assist with plugin migration. • Feedback - especially on migration and interacting with the storage format - encouraged! • Please, PLEASE do not install this on a production instance... • There is NO upgrade path from this alpha! 25 Tuesday, November 2, 2010
- 27. Questions? 27 Questions / Problems / Feedback confluence4@atlassian.com OR Ryan Thomas ryan.thomas@atlassian.com Tuesday, November 2, 2010