atlascamp 2010: macro migration guide for confluence 4.0 - ryan thomas

Confluence 4.0, Macros and Migration

Ryan Thomasryan.thomas@atlassian.com

1

Tuesday, November 2, 2010

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

confluence4@atlassian.com

OR

Ryan Thomas

ryan.thomas@atlassian.com

Tuesday, November 2, 2010