Background and strategic fit
Up until now, we haven't allowed users to edit the underlying editor storage format (though this was easy for anyone to hack, using Firebug). As customers upgrade to Confluence 4.0, we're learning there are three main reasons people want source access:
1. Customers Feel "Locked-in"
With the switch from wiki markup to the new XHTML-based storage format, and because people were no longer able to edit a text-based version of their page directly, they felt they were locked into Confluence. While you could always still get your content out via the API or through WebDAV but people wanted to be able to see it directly.
2. Fixing Formatting Niggles
When a user hits an occasional bug, he or she wants a quick workaround. Over the years we trained everyone on this - what do you do when you hit a bug in the RTE? Switch to wiki markup. This wasn't really acceptable then and definitely isn't now, but some customers are asking for it... "give me access to the source so I can quickly fix something that's gone wrong."
3. Offline content editing
Some users want to copy the source of their page out of Confluence to work with it in other ways, whether it be updating content offline, sharing with others via email, or using a preferred text editor for things like bulk changing of link properties. Use cases include:
- Bulk edit link properties
- Bulk edit macro properties
- Confluence offline editing
- Editing via preferred editor (emacs, textmate, etc)
User Story Title
User Story Description
User can access source view from inside the Confluence editor.
1: Must have
|Copy paste source|
User can copy / paste source in full fidelity. Users should be able to:
|1: Must have||BETA 1|
|Edit link source||User should be able to change link source from inside the editor||1: Must have||This would help with bulk change operations like changing URLs, or parts of URLs in links.||BETA 1|
|Edit macro parameters||Users should be able to change macro parameters from inside the editor||1: Must have|
Example macro storage format:
|Validation||1: Must have|
There should be at least some basic validation (e.g. that the xml is well formed). This validation is performed when applying the changes in the source editor and returning to the Rich Text Editor.
Other markup, that is considered invalid, is either tolerated or stripped when saving the file (the content itself is not lost, just the markup tags). It would be desirable to validate this before save, but this may not be available in the first release.
If a save does result in a bad rendering of a page, then reverting an edit via the history is an acceptable trade-off.
|Syntax highlighting||The markup should be formatted and indented so that the source is as easy as possible to visually parse and spot invalid markup.||2: Should have||BETA 1|
|Search and replace||It should be possible to search and replace text in the source markup.||2: Should have|
There should be some basic search and replace functionality. More sophisticated searching may be possible (e.g. the reg. ex) depending on the final editing framework used. See CONF-24200 - Ability to Find/Replace on Formatting and Macro parameters within a page Resolved .
Admin can specify which users / groups can have access to edit source.
3: Nice to have
This is necessary so that only people who REALLY need access can get access.
|Validation||User can see which markup he posts is invalid - editor should refuse bad mark-up||2: Should have|
The source editor does validation for malformed XML - so if you forget to open or close a tag, it will not let you post it and will move your cursor to where the error exists if that location is knowable.
If you define a bad parameter in a macro, Confluence will ignore this parameter:
If you erroneously put a macro or link parameter in a rich text field the tags get stripped
- Expecting an icon to the left of help in the toolbar that will pop up a dialog when enabled for a user.
- This will be implemented as a separate plugin that can be installed by a Confluence site administrator.
- The plugin will be maintained by Atlassian.
We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large proportion of HTML in the storage format.