EditChapterPlugin < TWiki

---+!! %TOPIC%
<!--
   * Set SHORTDESCRIPTION = An easy section editing facility
-->
%SHORTDESCRIPTION%

%TOC%
---++ Description
<table style="float:right">
<tr>
  <td><img src="%ATTACHURLPATH%/wikiringlogo40x40.png"></td>
  <td><a href="http://wikiring.de" title="Make your Wiki ring!" style="text-decoration:none">
      Powered by <br /> <nop>WikiRing Consultants </a>
  </td>
</tr>
</table>
This plugin implements a simple section editing feature comparable to
the one available for [[http://en.wikipedia.org/wiki/Help:Section#Section_editing][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 the "Universal Wiki Edit Button" 
<img src="%PUBURLPATH%/%WEB%/%TOPIC%/uweb-g.gif" border="1" />.

Once installed, the plugin automatically enables sectional editing without any further
provisions. Note, that it will only detect headings created using TWiki-markup, 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 =&lt;h2>headings&lt;/h2>=.

Sections might be included into the current topic using [[VarINCLUDE][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.


---++ Previous work
There are a couple of other plugins that try to implement a section editing feature, along with some
other more exotic features. The first plugin of that kind was TWiki:Plugins/SectionalEditPlugin.
Later on, its functionality was extended to process sections in a broader sense in the
TWiki:Plugins/MultiEditPlugin. By the time of this writing both plugins were about to
be merged again into one TWiki:Plugins/EditSectionPlugin. These three plugins all depend
on an extra package called TWiki:Plugins/EditContrib which factors out common code. In addition
<nop>EditContrib contains a patch to the TWiki core engine, available for TWiki-4.0 and TWiki-4.1.x.
All these plugins are currently non-functional on TWiki-4.2.

While first looking at the code of <nop>SectionalEditPlugin, it was clear very soon, that it
would be better to start from scratch and remove some features for the sake of a cleaner
implementation, that is in sync with recent developments, i.e. <nop>PatternSkin, <nop>NatSkin
and <nop>NatEditContrib in this area.

The other substantial difference between <nop>SectionalEditPlugin and <nop>EditChapterPlugin is
that while the former introduces additional code to save an isolated subsection back into the topic,
the latter always saves complete topics, despite the fact that only part of it is editable.


---++ 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 \
| =&lt;img src="%$nopPUBURLPATH%/%<nop>TWIKIWEB%/EditChapterPlugin/uweb-g.gif" height="16" width="16" border="0" />= | 
| EDITCHAPTERPLUGIN_EDITLABELFORMAT \
| full format string to render the detected heading of a chapter \
| =&lt;span class="ecpHeading">$anchor&lt;/a>$heading&lt;a class="ecpEdit" href="$url" title="Edit this chapter">$img&lt;/a>&lt;/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 =%<nop>ENABLEEDITCHAPTER%= / =%<nop>DISABLEEDITCHAPTER%=
tags.

---+++ EXTRACTCHAPTER
Dedicated chapters of a topic can be extracted using the =%<nop>EXTRACTCHAPTER{}%= tag.
it takes the following parameters:

| *Name* | *Description* | *Default* |
| topic | target topic name to extract the chapter from | =%<nop>BASETOPIC%= |
| web | target web name | =%<nop>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:
<verbatim>
<textarea style="display:none">
  %EXTRACTCHAPTER{before="1"}%
</textarea>
<textarea>
  %EXTRACTCHAPTER{nr="1" encode="on"}%
</textarea>
<textarea style="display:none">
  %EXTRACTCHAPTER{after="1}%
</textarea>
</verbatim>

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.


---++ 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
     =%<nop>INCLUDE{"TargetTopic" section="onlythis"}%=. 
   1 wysiwyg editor:
     it currently does not work work together with TWiki:Plugins/WysiwygPlugin
   1 explicit sectioning: 
     users can't specify any other section to be editable in isolation (e.g. using some
     =&lt;section> ... &lt;/section>= markup) other than by giving the respective section
     a heading.
   1 jQuery: the <nop>EditChapterPlugin currently depends on the JQueryPlugin, used
     to hook into the edit interface. You may be facing an increased javascript download overhead in 
     your TWiki html pages as you are already using TWiki:Plugins/BehavourContrib, TWiki:Plugins/TwistyContrib
     and TWiki:Plugins/TwistyPlugin. Consider uninstalling these three and replace them with
     TWiki:Plugins/JQueryTwistyPlugin. You should have installed JQueryPlugin anyway already.
     Last not least you get less javascript but more features.

---++ 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 where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully
automatic installer script written using the Build<nop>Contrib.
   * If you have TWiki 4.2 or later, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.
   * If you have any problems, then you can still install manually from the command-line:
      1 Download one of the =.zip= or =.tgz= archives
      1 Unpack the archive in the root directory of your TWiki installation.
      1 Run the installer script ( =perl &lt;module&gt;_installer= )
      1 Run =configure= and enable the module, if it is a plugin.
      1 Repeat for any missing dependencies.
   * If you are *still* having problems, then instead of running the installer script:
      1 Make sure that the file permissions allow the webserver user to access all files.
      1 Check in any installed files that have existing =,v= files in your existing install (take care *not* to lock the files when you check in)
      1 Manually edit !LocalSite.cfg to set any configuration variables.

%IF{"defined 'SYSTEMWEB'" else="<div class='twikiAlert'>%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your %MAINWEB%.TWikiPreferences, if they are not already there:<br><pre>   * <nop>Set SYSTEMWEB = %<nop>TWIKIWEB%<br>   * <nop>Set USERSWEB = %<nop>MAINWEB%</pre></div>"}%


---++ Plugin Info

Many thanks to the following sponsors for supporting this work:
   * [[http://www.tecdoc.de][TecDoc Informations System <nop>GmbH]]

|  Plugin Author(s): | TWiki:Main/MichaelDaum |
|  Copyright &copy;: | 2008, Michael Daum http://michaeldaumconsulting.com |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | v1.15 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 &lt;literal> ... &lt;/literal> for TWiki engines before 4.2 |
|  14 Feb 2008: | have a little space in the default heading format to let <nop>TWikiMarkup do its job; \
                  added support for legacy heading markup like =--------#####= |
|  05 Feb 2008: | compatibility with old <nop>PatternSkin versions |
|  03 Jan 2008: | initial release |
|  Dependencies: | <table border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">TWiki::Plugins::JQueryPlugin</td><td align="left">&gt;=0.4</td><td align="left">Required.</td></tr></table> |
|  Plugin Home: | TWiki:Plugins/EditChapterPlugin |
|  Feedback: | TWiki:Plugins/EditChapterPluginDev |
|  Appraisal: | TWiki:Plugins/EditChapterPluginAppraisal |

<!-- 
  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	Comment
js	ecpjavascript.js	r1	manage	1.1 K	2008-07-03 - 12:47	TWikiAdminUser	Saved by install script
css	ecpstyles.css	r1	manage	0.6 K	2008-07-03 - 12:47	TWikiAdminUser	Saved by install script
png	ueb.png	r1	manage	0.7 K	2008-07-03 - 12:47	TWikiAdminUser	Saved by install script
gif	uweb-g.gif	r1	manage	1.0 K	2008-07-03 - 12:47	TWikiAdminUser	Saved by install script
png	wikiringlogo40x40.png	r1	manage	2.5 K	2008-07-03 - 12:47	TWikiAdminUser	Saved by install script
This topic: TWiki > EditChapterPlugin
Topic revision: r3 - 2008-11-18 - TWikiAdminUser
Copyright &© 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.EditChapterPlugin