• This web contains the official documentation of the TWiki-6.0 Release, code named JerusalemRelease.
• It is a read-only web for reference. Please update documentation at TWiki.AutoSectionsPlugin.
create new tag
, view all tags


Automatically make editable sections based on headings


This plugin automatically adds the "Edit" links to all the headings (---++ etc.) making the sections underneath them editable right in place.

If the plugin is installed and enabled, all the headings get the "Edit" links, except for some special circumstances (see below). When the mouse cursor is over an "Edit" link, the area edited with the link changes its background.

In addition to editing a section, you can see the raw text of a section by clicking the "Raw view" link. This is handy to copy-paste a section from a topic to another.

Whether to show or hide all the "Edit" links can be controlled by setting AUTOSECTIONS preferences variable.

   * Set AUTOSECTIONS = on

"Edit Sections" button

It comes with a variable %EDITAUTOSECTIONS%, which is expanded as an "Edit Sections" button. If this variable is used anywhere, all the "edit" links on the headings are hidden by default, only until you click the button.

The %EDITAUTOSECTIONS% button can optionally take the parameters below to change custom button labels:

Parameter Default Description
DEFAULT or label "Edit Sections" The button label to start editing sections.
endlabel "Finish Editing" The button label to end editing sections.

URL parameters, preferences variables, and configurations

URL Parameter Preference Variable Configuration Default Description
?AutoSections= * Set AUTOSECTIONS = $cfg{Plugins}{AutoSectionsPlugin}{Default} hover Enable/disable the plugin. Possible values are on, off, and hover.
?AutoSectionsEditLabel= * Set AUTOSECTIONS_EDITLABEL = $cfg{Plugins}{AutoSectionsPlugin}{EditLabel} Edit Alter the "Edit" link label. Specify off to hide the link.
?AutoSectionsRawLabel= * Set AUTOSECTIONS_RAWLABEL = $cfg{Plugins}{AutoSectionsPlugin}{RawLabel} Raw view Alter the "Raw view" link label. Specify off to hide the link.
?AutoSectionsCancelLabel= * Set AUTOSECTIONS_CANCELLABEL = $cfg{Plugins}{AutoSectionsPlugin}{CancelLabel} Cancel Alter the "Cancel" link label.
?AutoSectionsFontStyleButton= * Set AUTOSECTIONS_FONTSTYLEBUTTON = $cfg{Plugins}{AutoSectionsPlugin}{FontStyleButton} on Show/hide the font style button (proportional/fixed) while editing a section
?AutoSectionsResizeButton= * Set AUTOSECTIONS_RESIZEBUTTON = $cfg{Plugins}{AutoSectionsPlugin}{ResizeButton} on Show/hide the resize button (enlarge/shrink) while editing a section
?AutoSectionsHighlight= * Set AUTOSECTIONS_HIGHLIGHT = $cfg{Plugins}{AutoSectionsPlugin}{Highlight} separate Control when the highlight (background and right bar) is turned visible. Possible values are on, off, separate, and minimum.

The default behavior of this plugin is that the edit link is displayed only on hover over a heading (hover mode). If the configuration value is set to on, all the edit links become always visible.

In any of the link labels, TWiki variables can be included, such as %ICON{...}%.

How exactly are the sections determined?

The headings are detected as a nested structure. For example, a section under the level 2 heading (---++) will contain all the level 3, 4, 5, ... sections (---+++, ---++++, etc.) right underneath it.

One exception is that a level 1 heading (---+) is interpreted the same as level 2 (---++). The reason is because it is usually encouraged to use the level 1 heading only once at the top of each page, and if it were interpreted to contain everything else, the "edit" link would be to edit the entire page. The level 1 heading rather allows you to edit the top portion of the page more quickly (typically a few paragraphs plus %TOC%).

Is it possible to add a new section or remove an existing section?

Yes. Since the text in the edit box will simply replace the edited section, just edit a nearby section to put any additional headings (---++) at an appropriate position, or erase the whole section.

How can I hide "edit" links by default?

There are several ways that affect the default behavior:

  • At the TWiki installation level (configure):
    • $TWiki::cfg{Plugins}{AutoSectionsPlugin}{Default} = 0;
  • In the WebPreferences, or in an individual topic:
       * Set AUTOSECTIONS = off
  • Use the %EDITAUTOSECTIONS% button somewhere in the topic
  • Append ?AutoSections=off to the URL

How can I show "edit" links on some occasions only?

Append ?AutoSections=on to the URL, which will enable the "edit" links regardless of the settings.

When are "edit" links not added to some headings, while it is enabled?

This plugin only detects the heading notations that appear in the raw text (saved text).

Headings that result from the below will not have the "edit" links:

  • Explicit HTML tags: <h1>, <h2>, etc.
  • The ---++ notations generated by variable expansion
    •    * Set SOMEVAR = ---++
    • %SOMEVAR%
  • Included topics via %INCLUDE{...}%
  • Insufficient CHANGE permission

What if MultiEditPlugin (namely <section> tags) is used at the same time?

MultiEditPlugin allows you to add sections anywhere by placing <section> tags, which would result in confusing "edit" links together with this plugin. In order to minimize the potential confusion, all the "edit" links on headings are suppressed when some <section> tags are present. Thus, this plugin can be installed in a non-destructive way even if MultiEditPlugin has already been installed.

On the other hand, if AUTOSECTIONS variable is explicitly set to on, the heading-based "edit" links are rather respected, while all the <section> tags are ignored.

When there are a lot of images, the page seems to be scrolled in a strange way right after a section is saved.

This is currently a known issue that results from the plugin trying to take you back to the original position you were editing, while the exact image size is unpredictable until the images are actually loaded.

Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip AutoSectionsPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/AutoSectionsPlugin.txt Plugin topic
      data/TWiki/VarEDITAUTOSECTIONS.txt %EDITAUTOSECTIONS% variable documentation
      lib/TWiki/Plugins/AutoSectionsPlugin.pm Plugin Perl module
      pub/TWiki/AutoSectionsPlugin/AutoSections.js JavaScript
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies.

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Configure additional plugin settings in the Extensions section if needed.
    • Test if the installation was successful using the example above.

Plugin Info

Many thanks to the following sponsors for supporting this work:

  • Acknowledge any sponsors here

Plugin Author(s): TWiki:Main.MahiroAndo
Copyright: © 2013-2016 TWiki:Main.MahiroAndo
© 2013-2016 TWiki:TWiki.TWikiContributor
License: GPL (Gnu General Public License)
Plugin Version: 2016-10-05
2016-10-05: TWikibug:Item7555: During edit mono/proportional font preference fails - TWiki:Main.HideyoImazu
2016-07-29: TWikibug:Item7550: Fix triple-click issue with FF; Fix NOTOC detection bug (TWikibug:Item7724); Make plugin aware of READONLYSKINMODE (TWikibug:Item7609); Handle DisplayTimeValues=servertime correctly (TWikibug:Item7739) - TWiki:Main.MahiroAndo
2016-02-16: TWikibug:Item7726: eliminate hard-coded /pub/TWiki/ and to add AutoSections.css to MANIFEST
2014-10-08: TWikibug:Item7550: Change "raw" to "raw view"; add margin and padding to auto section links; remove undocumented dependency on DateTimePlugin; add a gray highlight bar on the right on hover over heading; show buttons on hover over heading - TWiki:Main.PeterThoeny
2013-10-30: TWikibug:Item7374: Refined error handling - TWiki:Main.MahiroAndo
2013-10-21: TWikibug:Item7374: Display errors on edit conflicts - TWiki:Main.MahiroAndo
2013-09-18: TWikibug:Item7348: raw view should use "readonly" rather than "disabled" - TWiki:Main.MahiroAndo
2013-08-27: TWikibug:Item7326: Compatibility issue with jQuery upgrade - TWiki:Main.MahiroAndo
2013-08-26: TWikibug:Item7325: Adding "raw view" link next to "edit" link at each section - TWiki:Main.MahiroAndo
2013-06-10: TWikibug:Item7280: documentation enhancement
2013-05-17: TWikibug:Item7258: Style sheet improvement - TWiki:Main.HideyoImazu
2013-05-05: TWikibug:Item7249: Refactoring and testing - TWiki:Main.MahiroAndo
2013-05-02: TWikibug:Item7249: Initial version - TWiki:Main.MahiroAndo
Plugin Home: http://twiki.org/cgi-bin/view/Plugins/AutoSectionsPlugin
Feedback: http://twiki.org/cgi-bin/view/Plugins/AutoSectionsPluginDev
Appraisal: http://twiki.org/cgi-bin/view/Plugins/AutoSectionsPluginAppraisal

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, TWikiPreferences

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng autosections-demo.png r1 manage 62.7 K 2013-06-10 - 06:02 TWikiContributor  
PNGpng autosections-demoraw.png r1 manage 54.0 K 2013-08-26 - 08:35 TWikiContributor  
PNGpng autosections-editing.png r1 manage 46.5 K 2013-08-26 - 08:35 TWikiContributor  
PNGpng autosections-hover.png r1 manage 54.0 K 2013-08-26 - 08:35 TWikiContributor  
PNGpng autosections-rawview.png r1 manage 46.6 K 2013-08-26 - 08:35 TWikiContributor  
Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r2 - 2016-10-09 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.AutoSectionsPlugin.