AutoSectionsPlugin < TWiki

---+!! !AutoSectionsPlugin
<!--
One line description, required for extensions repository catalog.
   * Set SHORTDESCRIPTION = Automatically make editable sections based on headings
-->
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%

---++ Usage

%ATTACHURL%/autosections-demo.png

%ATTACHURL%/autosections-editing.png

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.

%ATTACHURL%/autosections-demoraw.png

%ATTACHURL%/autosections-rawview.png

In addition to edit a section, you can see the raw text of a section by clicking the "raw" 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.
<pre>
   * <nop>Set AUTOSECTIONS = on
</pre>
It comes with a variable =%<nop>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 =%<nop>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. |

---+++!! Preferences variables and configurations

| *Preference Variable* | *Configuration* | *Description* |
| AUTOSECTIONS | =$cfg{Plugins}{AutoSectionsPlugin}{Default}=  | Enable/disable the plugin. Possible values are =on=, =off=, and =hover=. |
| AUTOSECTIONS_EDITLABEL | =$cfg{Plugins}{AutoSectionsPlugin}{EditLabel}= | Alter the "edit" link label. Specify =off= to hide the link. |
| AUTOSECTIONS_RAWLABEL | =$cfg{Plugins}{AutoSectionsPlugin}{RawLabel}= | Alter the "raw" link label. Specify =off= to hide the link. |
| AUTOSECTIONS_CANCELLABEL | =$cfg{Plugins}{AutoSectionsPlugin}{CancelLabel}= | Alter the "cancel" link label. |

Variables can be included in any of the link labels, such as [[%SYSTEMWEB%.VarICON][%<nop>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 =%<nop>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 ([[%SCRIPTURL{configure}%][configure]]):
      * =$TWiki::cfg{Plugins}{AutoSectionsPlugin}{Default} = 0;=
   * In the !WebPreferences, or in an individual topic:
   <pre>
   * <nop>Set AUTOSECTIONS = off</pre>
   * Use the =%<nop>EDITAUTOSECTIONS%= button somewhere in the topic
   * Append =?AutoSections=off= to the URL

---+++!! I want to have the section edit links but they look annoying

You can hide "edit" links and display a link only when the mouse cursor is over the link by setting AUTOSECTIONS as follows.
<pre>
   * <nop>Set AUTOSECTIONS = hover
</pre>

%ATTACHURL%/autosections-hover.png

---+++!! 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: &lt;h1&gt;, &lt;h2&gt;, etc.
   * The =---++= notations generated by variable expansion
      * &nbsp;&nbsp; =* Set SOMEVAR = ---++=
      * =%<nop>SOMEVAR%=
   * Included topics via [[%SYSTEMWEB%.VarINCLUDE][%<nop>INCLUDE{...}%]]
   * Insufficient =CHANGE= permission

---+++!! What if MultiEditPlugin (namely =&lt;section&gt;= tags) is used at the same time?

[[MultiEditPlugin]] allows you to add sections anywhere by placing =&lt;section&gt;= 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 =&lt;section&gt;= 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 =&lt;section&gt;= tags are ignored.

---++ 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.

%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section. 
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps: 
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/AutoSectionsPlugin.txt== | Plugin topic |
        | ==data/TWiki/VarEDITAUTOSECTIONS.txt== | %<nop>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 [[%SCRIPTURL{configure}%][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.

%ENDTWISTY%

---++ Plugin Info

Many thanks to the following sponsors for supporting this work:
   * Acknowledge any sponsors here

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author(s): | TWiki:Main.MahiroAndo |
|  Copyright: | &copy; 2013 TWiki:Main.MahiroAndo %BR% &copy; 2013 TWiki:TWiki.TWikiContributor |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Plugin Version: | 2013-10-30 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Dependencies: |  |
|  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:__ %TWIKIWEB%.TWikiPlugins, %TWIKIWEB%.DeveloperDocumentationCategory, %TWIKIWEB%.TWikiPreferences

<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the feedback topic on twiki.org instead. -->
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who
png	autosections-demo.png	r1	manage	62.7 K	2013-06-10 - 06:02	TWikiContributor
png	autosections-demoraw.png	r1	manage	54.0 K	2013-08-26 - 08:35	TWikiContributor
png	autosections-editing.png	r1	manage	46.5 K	2013-08-26 - 08:35	TWikiContributor
png	autosections-hover.png	r1	manage	54.0 K	2013-08-26 - 08:35	TWikiContributor
png	autosections-rawview.png	r1	manage	46.6 K	2013-08-26 - 08:35	TWikiContributor
Topic revision: r0 - 2013-10-30 - TWikiContributor
Copyright © 1999-2024 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.