This server will be upgraded at 3pm Sydney time on December 3rd (December 2nd, 8pm PST) and will be down for up to 30 minutes.

Sub-Section Macro

Added by Alain Moran, last edited by Matt Bovett on Feb 20, 2008  (view change)
Name Sub Section Macro
Vendor Adaptavist.com Ltd (Website)
Authors Jean-Maxime Guay, Alain Moran
Homepage http://confluence.atlassian.com/display/CONFEXT/Sub-Section+Macro
Issue Management http://developer.atlassian.com/jira/browse/SUBS
Continuous Integration n/a
Categories Advanced Macros
Most Recent Version 1.0.10
Availability Confluence v2.1 to v2.10
State Beta
Support Unsupported Plugins
License Freeware / Open Source (BSD)
Price Donate
Release Docs http://confluence.atlassian.com/display/CONFEXT/Sub-Section+Macro
Java API Docs n/a
Download Source http://svn.atlassian.com/svn/public/contrib/confluence/sub-section/
Download JAR merck-adaptavist-subSection-1.0.10.jar

Description

A macro which allows you to create editable sub sections within a document
  • Each {sub-section} has to be distinguished by an unique ID.
  • Addresses CONF-5913
{sub-section:1}1st section of doco - test addition...
test{sub-section}

Parameters

Required

  • An ID must be specified directly after the : (colon). The ID used to identify the sub-section on the page, all sub-sections with the same id will end up with the same content after editing, hence this ID should be unique for the page.
    • Note: If the page content is included elsewhere by {include}, {metadata-from} or {zone-template-instance} or the like, the sub-section should be unqiue for the entire confluence installation, perhaps using the pageid in the sub-section id.

Optional

  • showComment - Show/Hide the comment textbox in the sub-section. Either true or false. Default to true.
  • comment - Set the text of the version comment. Default : "sub-section:ID edited".
  • showMinorChange - Show/Hide the minorEdit checkbox in the sub-section. Either true or false. Default to true.
  • minorChange - Either true or false. A minor change won't send a notification to watchers. Default to false.
  • metadata - The key of the metadata in which the wikimarkup will be stored. Default: no metadata set.

All the parameters (keys and values) are case insensitive. Metadata keys are still case sensitive.

Release History

Plugin Versions

Version Date State License Price
Show description 1.0 (#1) 02 Oct 2006 Alpha Freeware / Open Source (BSD) Donate

Release Notes
The inital release.

Contributors

Show description 1.0.1 (#2) 03 Oct 2006 Alpha Freeware / Open Source (BSD) Donate

Release Notes
Added notation guide and fixed bug that wiped out the contents of other sub-sections on the page.

Contributors

Show description 1.0.2 (#3) 10 Oct 2006 Alpha Freeware / Open Source (BSD) Donate

Release Notes
Use unique package name to avoid breaking other plugins.

Contributors

Show description 1.0.3 (#4) 11 Oct 2006 Alpha Freeware / Open Source (BSD) Donate

Release Notes
Use POST.

Contributors

Show description 1.0.4 (#5) 11 Oct 2006 Alpha Freeware / Open Source (BSD) Donate

Release Notes
Fix POST changes.

Contributors

Show description 1.0.5 (#6) 01 Oct 2007 Alpha Freeware / Open Source (BSD) Donate

Release Notes
Dollar sign and other special regx characters no longer cause unexpected behaviour or crashing

Contributors

Show description 1.0.6 (#7) 15 Oct 2007 Alpha Freeware / Open Source (BSD) Donate

Release Notes
Comment textbox and minorChange checkbox added

Contributors

Show description 1.0.7 (#9) 22 Oct 2007 Beta Freeware / Open Source (BSD) Donate

Release Notes
metadata parameter added

Contributors

Show description 1.0.8 (#10) 07 Nov 2007 Beta Freeware / Open Source (BSD) Donate

Release Notes
Sub-sections use Asynchronous JavaScript and XML (AJAX).

Contributors

Show description 1.0.9 (#13) 14 Nov 2007 Beta Freeware / Open Source (BSD) Donate

Release Notes

Jira Issues
Type Key Summary Assignee Reporter Priority Status Resolution Created Updated Due
New Feature SUBS-2 Implement sub-section save function with AJAX Jean-Maxime Guay James Mortimer Major Resolved Fixed Nov 14, 2007 Nov 15, 2007 Nov 13, 2007

Contributors

Show description 1.0.10 (#14) 07 Dec 2007 Beta Freeware / Open Source (BSD) Donate

Release Notes

Jira Issues
Type Key Summary Assignee Reporter Priority Status Resolution Created Updated Due
Bug SUBS-4 Sub-section only works under root context Jean-Maxime Guay Liam Jones Major Resolved Fixed Nov 23, 2007 Dec 07, 2007
Bug SUBS-3 metadata keys are casted into lower case Jean-Maxime Guay James Mortimer Critical Resolved Fixed Nov 22, 2007 Nov 22, 2007

Contributors

Example of use

The live example below is from the sub-section test page (View Source)

this is cool. This is an add on.

Ja, dette er jo skikkelig bra!!!

Title Value
Alpha
a b
c d

ab

&&&&&&&&&&
Beta
aaaaaaaaaa
bbbbbbbbbb
cccccccccc
dddddddddd

$$$

Test Header

  • Bullet
    • Bullet 2
      • Bullet 3
        • Bullet 4
          • Bullet 5
  • 345
  • 345

this is totally freaken AWESOME!

it's versioned too!

yes, you can edit in section

Issue Tracking

This plugin is still a proof of concept and currently unsupported. Neither the initial author or subsequent authors are actively developing or handling issues on a regular basis.
Please report new issues in the JIRA project (linked above). In order to vote for any issues below, create a new JIRA issue with the appropriate details.
  • use POST instead of GET (to alleviate the current ~2kb character limit (and/or note this limit on the form)
  • manipulate text to be put into the page as a string, not regx. Regx manipulation was causing crashing when $ was used.
  • add revision comment to the form
  • add minor edit checkbox to the form (default=no)
  • create a 'metadata' parameterthat will automatically load the 'sub-section' content into the named metadata store on the page (in addition to putting it in the page source itself, for versioning). this avoids problems with having to try to nest metadata and subsection macros within each other. Currently {metadata:test}{sub-section:page1section1}test{sub-section}{metadata} doesn't work as expected, as the sub-section macro is IN the metadata, and the reverse puts the metadata IN the subsection.
  • Perhaps give parameter/option that lets you lose the "edit" button completely and make it so users can just click or double-click the text section to edit it? (...as shown here: http://www.appelsiini.net/projects/jeditable/default.html). This would be useful in tables. Imagine this with table-plus tables! Exciting!
  • if possible, add watch this page checkbox to the edit submission form (default=yes). User can choose to update their page watch status when they make a change, but default it turns it on. (see 'autowatch' plugin)
  • use a (configurable) 'pencil' edit icon to edit the sub-section rather than the grey edit box (aka [checklist plugin])
  • use a (configurable) plain text, right-justified [edit] button to edit the sub-section, rather than the grey buttons
  • change the 'edit' button (optionally?) to be FLOATING at the TOP RIGHT of the section that is editable, to minimize interruption of reading.
  • If possible, automatically size the 'edit box' to fit in the same area as the 'div' or 'span' that the rendered text is occupying to minimally interrupt the viewers experience. Set a minimum size of 2 lines by 30 columns, or something similar, which might be overridden by parameters. If difficult, at least set the number of rows to the number of rows of wiki source text.
  • create a table version that makes every cell in each table in the body a 'sub-section' editable field
  • create a heading version that makes every h1..h5 section in the body of the macro sub-section editable
  • sub-section does not require CAPTCHA, even if CAPTCHA is enabled for pages and comments for the site.
  • On IE6.0, but not firefox, including a sub-section macro on a page causes the entire 'preview' tab to not render while editing a page using the regular edit feature. No java error is returned, but the tab is entirely blank. Of course, there is differences in the way visibility et display of elements are set in the two platforms. This is also observed for other plugins, such as [pagetreesearch] and [pagetree] macros (others?), but was broken and fixed in other plugins (examples?).

sub-section macro fails when within a metadata-list macro and content contains blank lines META-45

Fixed somewhere between confluence 2.3.3 and 2.5.7 by updating the wiki renderer. It now allows macros, such as sub-section, in table syntax to contain blank lines without breaking the table.

In general, sub-section works well within a metadata-list and metadata-report, as long as each sub-section (on each page) uses a unique identifier. However, a problem arises if you have blank lines in wiki table syntax (which is used for metadata-lists). Behaviour for metadata table is different than that of the default wiki table renderer. The problem may need to be fixed for metadata or sub-section or the wiki table renderer or all three. I will cross post this bug report.

*** The following does not work properly (sub-section breaks):
{metadata-list}
|| Summary | {sub-section:myid}text

text{sub-section} |
{metadata-list}

*** The following fails for table rendering, but sub-section and meta-data still both work:
|| Summary | {metadata:Summary}{sub-section:myid}text

text{sub-section}{metadata} |

*** The following works for both meta-data and sub-section:
{metadata:Summary}{sub-section:myid}text

text{sub-section}{metadata}
Sub-section version 1.7 and later now have a metadata parameter which simplifies the usage of metadata and sub-section together
Full Size

Labels

sub-section sub-section Delete
macro macro Delete
plugin plugin Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (8)

 

  1. Jan 31, 2007

    Tom Miller says:

    I really like the way the openSuse wiki does this.   It is right justi...

    I really like the way the openSuse wiki does this.   It is right justified on the same line as the subsections title.  It is a link.

    So it looks somthing like this.  With the test section boxed

     
    My Title of My New Sub Section                                                       [edit ]

    Content of the subsection.

  2. Nov 01, 2007

    Jean-Maxime Guay says:

    A problem with the xml file has been fixed and the latest version (1.0.7) is now...

    A problem with the xml file has been fixed and the latest version (1.0.7) is now functional.

    I've tested it on my server and all features are working properly. Enjoy!

    Done : asynchronous update (AJAX)

  3. Feb 19, 2008

    Matt Bovett says:

    I don't suppose there'd be a way to do this without putting an edit button in ev...

    I don't suppose there'd be a way to do this without putting an edit button in every spot you use the macro, would there?

    Instead of clicking edit, I'd like to be able to click or double-click in any section and edit it in place, as you see here: (click all the bold text for different examples)

    http://www.appelsiini.net/projects/jeditable/default.html

    I thought this library could do it as well...

    http://script.aculo.us/

    1. Mar 03, 2008

      James Mortimer says:

      good examples. You are welcome to create a release of sub-section that impleme...
      • good examples. You are welcome to create a release of sub-section that implements this. It should be easy to 'capture' the double-click event on the entire span, instead of the single-click event on the associated edit button. If you make the change, bear in mind these concerns.
        • double click already is heavily used to select a block of text in most applications, including internet explorer and firefox. Many users are used to this behaviour.
        • the macro should be backwards compatible. either create an entirely new macro, or use a parameter such as "doubleclick=true/false" which defaults to false, so old sub-section use cases are supported. Or if you plan to impelement several interfaces, use something like "interface=(inlineEditButton|floatingEditButton|mouseOver|singleClick|doubleClick)", which defaults to editbutton, and "tooltip=xxxx" (with the appropriate defaults)
      • I suggest you raise this, with all relevant information, as a feature request using the JIRA issue tracking system, so your idea isn't lost when comments are cleaned up.

  4. Feb 20, 2008

    Allan Pratt says:

    Is there any chance of a version of this macro that invokes the Rich Text Editor...

    Is there any chance of a version of this macro that invokes the Rich Text Editor instead of the wiki editor? I know it's possible, because the UI for adding this comment popped up the RTE as the default entry mode.

    1. Mar 03, 2008

      James Mortimer says:

      a great idea. However, we have no further plans for development of this plugi...
      • a great idea. However, we have no further plans for development of this plugin at this time.
      • It would be a fantastic feature. You are welcome to try
      • please maintain backwards compatibility. i.e. create a new branch with a new macro name, or use a option such as 'editor=(simple|richText|wikiMarkup)' with a default of 'simple' keeping the current behaious.
      • I suggest you raise this, with all relevant information, as a feature request using the JIRA issue tracking system, so your idea isn't lost when comments are cleaned up.

      1. Mar 03, 2008

        Peter R. says:

        we have no further plans for development of this plugin at this time Does this m...

        we have no further plans for development of this plugin at this time

        Does this mean, then, that the plug-in is officially out of beta even though it's still labeled as such? We generally avoid using anything flagged beta or earlier. Thanks!

        1. Mar 03, 2008

          James Mortimer says:

          no. it's still somewhat of a proof-of-concept that hasn't been fully 'beta' te...
          • no. it's still somewhat of a proof-of-concept that hasn't been fully 'beta' tested by a large audience yet.
          • this plugin is user supported, but has no active developers at this time.
          • there are no known critical 'bugs' currently, just enhancement requests, so it might be considered a 'stable-beta' stage.
          • strategically, how to support the concept of sub-section edits in confluence is still not well developed. sub-section editing could be addressed by the main application (there is a major feature request for it) so I wouldn't get too excited about this plugin. But if it supports your current use case, it should be stable enough to use for 'internal' applications. it doesn't support captcha, so outward facing sites with anonymous or unregulated new user access would probably not want to use it.