atlascamp 2010: macro migration guide for confluence 4.0 - ryan thomas
DESCRIPTION
TRANSCRIPT
Overview
• Confluence 4.0
• XHTML Storage Format
• New API
• Migration
• Macro Migration
2
Tuesday, November 2, 2010
Introducing Confluence 4.0
3
Tuesday, November 2, 2010
New RTE Interface
4
Tuesday, November 2, 2010
Macro Placeholders
5
Tuesday, November 2, 2010
Many WYSIWYG Improvements
6
Tuesday, November 2, 2010
Inline Wiki Markup Completion
[space]
[*]
7
Tuesday, November 2, 2010
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
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
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
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
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
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
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
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
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
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
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
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
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
Macro Migration
21
Preferred Method
Start
bodyless? AutomaticMigration
XHTML? Custom?
Use CustomMigrator
AutomaticMigration
Yes
No
Yes
Yes
No
No
Wrap withunmigrated-wiki-markup macro
To be deprecated
Tuesday, November 2, 2010
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
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
Summary
24
• Confluence 4.0 is going to ROCK!
• XHTML Storage Format
• New API
• Migration
• Macro Migration
Tuesday, November 2, 2010
Confluence 4.0 Alphahttp://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
Confluence 4.0 Alpha
26
<dependency> <groupId>com.atlassian.confluence</groupId> <artifactId>confluence</artifactId> <version>4.0-alpha2</version> </dependency>
<confluence.version>4.0-alpha2</confluence.version>
Tuesday, November 2, 2010
Questions?
27
Questions / Problems / Feedback
OR
Ryan Thomas
Tuesday, November 2, 2010