AtlasCamp 2010: Macro Migration Guide for Confluence 4.0 - Ryan Thomas

Conﬂuence 4.0, Macros
and Migration
Ryan Thomas
ryan.thomas@atlassian.com
1
Tuesday, November 2, 2010

Overview
• Conﬂuence 4.0
• XHTML Storage Format
• New API
• Migration
• Macro Migration
2

Introducing
Conﬂuence 4.0
3

New RTE Interface
4

Macro Placeholders
5

Many WYSIWYG Improvements
6

Inline Wiki Markup Completion
[space]
[*]
7

Conﬂuence 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

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

Headings
10
h3. Creating a new macro in Confluence 4.0
Wiki Markup
<h3>Creating a new macro in Confluence 4.0</h3>
XHTML

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

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

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

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

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-ﬂy migration of
unmigrated and previous content versions.

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

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

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

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>

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

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

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

Example / Demo
• Upgrading my macros from 3.x to 4.0, and
ﬁxing some things in migration.
•{mycheese}
•{mycolour}
red:Some red text
{mycolour}
23

Summary
24
• Conﬂuence 4.0 is going to ROCK!
• XHTML Storage Format
• New API
• Migration
• Macro Migration

Conﬂuence 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

Conﬂuence 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>

Questions?
27
Questions / Problems / Feedback
conﬂuence4@atlassian.com
OR
Ryan Thomas
ryan.thomas@atlassian.com

AtlasCamp 2010: Macro Migration Guide for Confluence 4.0 - Ryan Thomas

More Related Content

What's hot

More from Atlassian

Recently uploaded

AtlasCamp 2010: Macro Migration Guide for Confluence 4.0 - Ryan Thomas