EditChapterPlugin

An easy section editing facility

Description

This plugin implements a simple section editing feature comparable to the one available for MediaWiki. It adds link urls to headings so that users can edit the section below. Edit links are enabeld only for those users that have edit access. Edit links are hidden unless you hover with the mouse pointer over them and then displays an icon, defaulting to a pencil Error: (3) can't find pencil.png in Extensions.

Once installed, the plugin automatically enables sectional editing without any further provisions. Note, that it will only detect headings created using TML (topic markup language), that is writing ---++ heading and the like. It is not sensitive to normal HTML-markup, so it does not add an edit link to normal <h2>headings</h2>.

Sections might be included into the current topic using INCLUDE. The edit link will be adjusted approriately, allowing to edit the correct target topic and then redirect back to the current topic it has been included to.

Configuration

There are a couple of preference variables to influence how and which headings are processed:

Name	Description	Default
EDITCHAPTERPLUGIN_MINDEPTH	min depth of heading to edit the sections, 1=h1, 2=h2, 3=...	1
EDITCHAPTERPLUGIN_MAXDEPTH	max depth of headings to edit	6
EDITCHAPTERPLUGIN_EDITIMG	icon to be used in the edit link	<img src="%$nopPUBURLPATH%/%SYSTEMWEB%/EditChapterPlugin/uweb-g.gif" height="16" width="16" border="0" />
EDITCHAPTERPLUGIN_EDITLABELFORMAT	full format string to render the detected heading of a chapter	<span class="ecpHeading">$anchor</a>$heading<a class="ecpEdit" href="$url" title="Edit this chapter">$img</a></span>
EDITCHAPTERPLUGIN_ENABLED	variable to enable/disable the EditChapterPlugin	on

Syntax

ENABLEEDITCHAPTER, DISABLEEDITCHAPTER

In addition to enable/disable the plugin using the EDITCHAPTERPLUGIN_ENABLE preference variable, it can also be enabled disabled using the %ENABLEEDITCHAPTER% / %DISABLEEDITCHAPTER% tags.

EXTRACTCHAPTER

Dedicated chapters of a topic can be extracted using the %EXTRACTCHAPTER{}% tag. it takes the following parameters:

Name	Description	Default
topic	target topic name to extract the chapter from	%BASETOPIC%
web	target web name	%BASEWEB%
nr	specify a single chapter to be extracted
from	specify first chapter to be extracted, use to to specify the last chapter	0
to	specify last chapter to be extracted, mostly used together with from	9999999
before	specify to extract all chapters before the given one
after	specify to extract all chapters after the given one
encode	enable/disable entity encoding, used when embeding into an HTML input element	on

Example:

<textarea style="display:none">
  %EXTRACTCHAPTER{before="1"}%
</textarea>
<textarea>
  %EXTRACTCHAPTER{nr="1" encode="on"}%
</textarea>
<textarea style="display:none">
  %EXTRACTCHAPTER{after="1}%
</textarea>

See the edit.chapter.tmpl for a real-world example, used as a cover to the standard edit templates, thus hooking in section editing into the standard editing process.

STARTCHAPTER/STOPCHAPTER

A chapter normally starts with a heading and ends at the next heading. To further reduce the chunk that is made editable use the %STARTCHAPTER% and %STOPCHAPTER% marks within a chapter. That way you might exclude markup that is physically located between the two adjacent headings but should not be part of the edit session.

Example:

<table class="foswikiTable">
  <tr>
    <td>
---++ Cell 1
some text
%STOPCHAPTER%
   </td>
   <td>
---++ Cell 2
some other text
%STOPCHAPTER%
   </td>
  </tr>
</table>

---++ Warning
<div class="foswikiErrorMessage">
%STARTCHAPTER%
This is an error.
%STOPCHAPTER%
</div>

Limitations

For the purpose of simplicity a couple of shortcomings have to be accepted.

1. parametrized includes: the plugin does not know anything about parametrized includes, that is it won't work as expected if a topic includes text from a named section of another topic using %INCLUDE{"TargetTopic" section="onlythis"}%.
2. wysiwyg editor: it currently does not work work together with Foswiki:Extensions/WysiwygPlugin
3. explicit sectioning: users can't specify any other section to be editable in isolation (e.g. using some <section> ... </section> markup) other than by giving the respective section a heading.

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Plugins::JQueryPlugin	>=4.10	Required.
Foswiki::Contrib::JsonRpcContrib	>=1.1	Required.
Foswiki::Plugins::RenderPlugin	>=3.1	Required.
Foswiki::Plugins::NatEditPlugin	>=5.20	Optional.
Foswiki::Plugins::ZonePlugin	>=1.0	Required. required for Foswiki < 1.1

Change History

19 Jan 2024:	made js and css a proper jQuery module
29 Apr 2022:	fixed error handling in case of a lock; add support for "force new revision" and RevCommentPlugin; using jsonTemplate now for better integration of the editor being loaded
12 Nov 2019:	performance improvements checking for headings in a topic; support for TopicInteractionPlugin's attachment uploader; fixed geometry of the textarea within a dialog box being resized
08 Mar 2016:	added a beforeSubmit event so that other plugins (wysiwyg, codemirror, ...) can interact with the textarea before it is submited; properly construct urls in javascript respecting SCRIPTSUFFIX and the like
17 Jul 2015:	fix positioning of modal dialog
16 Dec 2014:	make it cope with async page loads
04 Apr 2014:	improve cleaning up link titles
12 Dec 2013:	properly unlock cancelled edits
06 Nov 2013:	prevent WikiWords being expanded in HTML attributes
02 Sep 2013:	improved javscript click behavior editing chapters; fixed html markup displayed un-rendered in the modal dialog's title bar
13 Aug 2013:	check access rights before locking a topic; removed check for oldIEs
01 Oct 2012:	fixed construction of edit urls
16 Apr 2012:	fixed strange TOC links; adding missing dependency on Foswiki:Extensions/NatEditPlugin; properly encoding hidden text fragments while editing a chapter; fided ui::dialog not being loaded
10 Jan 2012:	added missing dependency on Foswiki:Extensions/RenderPlugin; using jquery.ui.dialog now instead of jquery.simplemodal; added plugin translations for german
29 Aug 2011:	added missing dependency on jquery-ui to make simplemodals resizable/draggable; locking a topic properly in edit chapter mode
26 Aug 2011:	fixed STARTCHAPTER, STOPCHAPTER not being cleaned up until logged in
25 Aug 2011:	added STARTCHAPTER, STOPCHAPTER; made modal dialog movable and resizable
06 Jun 2011:	using less obstrusive JavaScript to add the edit behavior to headlines; editing is now done in modal dialogs instead of jumping into a full-fledged editing screen
30 Nov 2010:	fixing compatibility with latest foswiki engine
15 Feb 2010:	fixing breakage with latest Foswiki:Extensions/JQueryPlugin
12 Feb 2010:	minify and compress css and js; forward compatibility for newer foswikis
16 Nov 2009:	disabling wysiwyg during sectional edits
02 Jul 2009:	fixing javascript order and TOC links
17 Apr 2009:	working towards a pure foswiki plugin
08 Jan 2009:	certified for foswiki/compat
26 Nov 2008:	replaced the uggly universal edit button with a nice pencil
26 Jun 2008:	new universal edit button
29 Apr 2008:	removed "literal" hack again; removed check for body_text context; only the icon is clickable - was all of the heading before
13 Mar 2008:	add <literal> ... </literal> for TWiki engines before 4.2
14 Feb 2008:	have a little space in the default heading format to let TopicMarkup do its job; added support for legacy heading markup like --------#####
05 Feb 2008:	compatibility with old PatternSkin versions
03 Jan 2008:	initial release