SectionEdit

Summary: Split a wiki page into separately editable sections with an edit link for each section
Version: 20230302
Prerequisites: at least PmWiki 2.2.110, last tested with version 2.2.122.
previous 2.1.x versions of the recipe, compatible with PmWiki 2.1.6 (??) can be found in the Development-Archive
Status: Stable
Maintainer:
Discussion: SectionEdit-Talk
Users: +10 -1 (View / Edit)

Solution

  1. Download sectionedit.phpΔ and save it in the cookbook directory
  2. Download the Cookbook MarkupToUnstyled script: markuptounstyled.phpΔ and save it in the cookbook directory
  3. Add include_once("$FarmD/cookbook/sectionedit.php"); to your config.php

Recent community versions

  • 20230302 - Petko : update for autoscroll and autotext, reported by Martin.
  • 20211114 - Petko : update for PHP 8.
  • 2.4 - 2019-05-06 - Petko : Updated for PHP 7.2. (Petko May 06, 2019, at 04:04 PM)
  • 2.3 - 2016-02-06 - farvardin : Fixed to use new Markup_e

Older Versions 2.2.x

Using the recent V 2.1.8 I thought that with a bit of taming SectionEdit would be a great recipe. So I started editing the source to apply some minor enhancements and ended up with a complete rewrite.
Since Klonk told me that at the moment he has no spare time to care for SectionEdit, I decided to publish the rewritten script as Version 2.2.0. Tontyna February 14, 2009, at 06:33 AM

New Features and Fixed Bugs:

  • "Section edit button" can be appended to heading text.
    Set $SectionEditHeaderLinkSpan to true to activate that feature.
  • Edit link has html title to indicate which section will be edited.
  • Extended css styling for edit links. See Customization/Styling
  • Editing a section and pressing [Cancel] returns to the section.
  • Ignores headings in (:markup:) and other header eating markup.
  • Creates sections for includes even when main page has none.
  • Updates page's targets field.
  • Handles simultaneous edits by displaying whole page text, when available the diff is shown.

To have a working TOC - use PmWiki:Table of contents, SlimTableOfContents or AutoTOC

Hint: Previous 2.0 and 2.1 Versions can be found in the Development-Archive

Description

Information

This recipe is based on break-page.php written by Schlaefer. This version here contains some enhancements and additional bugfixes. I created a new cookbook recipe as a beginner wouldn't find this really nice feature (which might be missed when someone knows e.g. MediaWiki).

Sections are automatically generated by default. Every heading in the wiki text then marks the beginning of a new section. By default the sections are generated in MediaWiki style. This means, when editing a section beginning with a header the section contains everything (even subheadings) until a new section with the same or higher heading level starts. This behaviour can be switched to standard style. See Customization for details. To edit simply click on the edit link above the desired section. To edit the section in a new window do a right-click on the edit window and select open in new window (depending on your browser).

When editing a section you'll see either the heading or the ==== markup at the beginning. If you're now removing the ==== at the top you are adding the actual section at the end of the section before. By the way: You don't have to place ==== in a separate line, just at the beginning of a line is enough.

Sections are also automatically generated for included pages. This behaviour can be deactivated (see below). When editing the main page you will only edit the text of that page, i.e. you'll see the (:include ... :) markup. At the beginning of the included page always an additional edit link will be inserted to have the possibility to edit the very first part of the included page. After saving that file you get back to the main page where you started.

Links for editing section are only visible when you have "edit" rights, i.e. authenticated for edit.

Take a look at the source when you're interested in the history. The history for the 2.x versions can be found in the Development-Archive.

This recipe also supports Site.EditForm.

Caveats

When editing a section the section marker is visible in the edit window. You should not remove the marker (==== or a heading) otherwise the currently edited text is not a section anymore.

When placing (:if anything :) directly before the section markers. you will see e.g. ====(:ifend:) at the beginning of the edited text. Don't get confused from the fact you don't see the starting (:if anything :). It simply belongs to the section before.

Limitations

Not really a limitation, but you should keep it in your mind: Sections are only generated for the main wiki page. Every other text that is included through the skin will not contain any section editing capabilities.

Well not really a limitation more kind of warning. If it happens that a section of a page or different sections of the same page are edited, you'll get a message that the page has changed (see SimultaneousEdits for more information). You then are editing the whole wiki page, not only the actual section. The reason is simply that otherwise you won't see or recognize the conflicts correctly.

When previewing you won't see any "edit section" links. This is normal behaviour.

The html title for the edit link can't be extracted correctly for heading text containing markup (e.g. links). Fixed in Version 2.2.1 with the help of cookbook MarkupToUnstyled

Apparently does not work with the following skins: BeeblebroxNetGila, Simple, Sinorca

To make section edit work with Sinorca and BeeblebroxNetGila, just change "clear:both" to "clear:none" inside div.sectionedit css rule. CarlosAB July 22, 2007, at 03:28 PM

SectonEdit does not work with FoxForum, since FoxForum uses one (:include...:) markup for each message. Use FoxEdit for individual message editing. HansB

Possible Customization

Configuration

These Customizations have to be set before including the script!

    $SectionEditWithoutHeaders = true;

Disables the automatic generation of sections, i.e. only ==== works for marking the beginning of a new section.

    $SectionEditAutoDepth = 2;

This variable defines up to which level the headings are used to mark the beginning of a new section. Default is 6 which means all headings are used. If you define e.g. 2 (as staed above) only the headings ! and !! will start a new section. !!! will be handled as normal text. Of course this variable only has an effect when $SectionEditWithoutHeaders is false.

    $SectionEditHeaderLinkSpan = true;

When true the "Edit link" for headings is appended in a span at the end of the heading text. You also need to enable this for PmWiki:TableOfContents to work better with SectionEdit, see [1]. Default is false.

    $SectionEditMediaWikiStyle = false;

Disables the default MediaWiki autosectioning style. The default value is true. Following a small example to illustrate the differences.

    value:TRUE  (sections)     FALSE (sections)   meanings:
          Text                 Text               Start of section:  \
          !Head1          \    !Head1    \        Middle of section: |
          Text            |    Text      /        End of section:    /
          !!Head2       \ |    !!Head2   \
          Text          | |    Text      /
          !!!Head3    \ | |    !!!Head3  \
          Text        | | |    Text      /
          ====      \ | | |    ====      \
          Text      / | | |    Text      /
          !!!!Head4 \ | | |    !!!!Head4 \
          Text      / / | |    Text      /
          !!!Head5    \ | |    !!!Head5  \
          Text        / / /    Text      /
          !Head6          \    !Head6    \
          Text            /    Text      /

    $SectionEditInIncludes = false;

Disables the creation of sections for included pages. Default value is true.

    $SectionEditLinkText = "[ edit ]";

Sets the text of the edit links to whatever you like. Default value is "$[(Edit)]".

Horizontal Line Sectioning:
This means that every horizontal line ---- is used for starting a new section. To enable this option set the variable

    $SectionEditHorzLines = true;

By default the value is false;
See also markups: (:horzsections:) and (:nohorzsections:)

Styling

The only default style applied by the script is

    div.sectionedit { text-align:right;font-size:smaller;clear:both;}

I suggest that you add something like that to your CSS file:

    /* default for edit link */
    div.sectionedit { text-align:center;font-size:smaller;clear:none;}

    /* enhanced styling for different types of edit links */
    /* edit link created by horizontal line markup ---- */
    div.sectionhorzline{}
    /* edit link created by section markup ==== */
    div.sectionsplit{border-top:1px dotted #369; }
    /* edit link created by header markup !!! when $SectionEditHeaderLinkSpan is false */
    div.sectionhead {border-top:1px dotted #369; }
    /* edit link created at the beginning of included page */
    div.sectionpage{border-top:3px double #00c; }

    /* edit link created by header markup !!! when $SectionEditHeaderLinkSpan is true 
     * decrease font size according to your h1..h6 font size to make link the same size
     * in all headings
     */
    span.sectionedit { font-size:smaller; font-weight:normal;}
    h1 .sectionedit{ font-size:0.4em; }
    h2 .sectionedit{ font-size:0.52em; }
    h3 .sectionedit{ font-size:0.6em; }
    h4 .sectionedit{ font-size:0.7em; }
    h5 .sectionedit{ font-size:0.75em; }
    h6 .sectionedit{ font-size:0.75em; font-variant: normal;}

    /* don't print edit links */
    @media print {
      span.sectionedit,
      div.sectionedit { display:none; visibility:hidden;}
    }

Provided Markup

The directives below work also when placed in the GroupHeader or GroupFooter and can be used within conditional markup.

    ====

After this markup a new section begins. The setting of $SectionEditAuto doesn't have any influence on this markup. This markup should be located at the beginning of a line.

    (:nosections:)

This markup disables the separation into sections. Could be used for e.g. ConditionalMarkup or other purposes.

    (:autosections:)

This markup overrides the settings of $SectionEditWithoutHeaders. When you use it the automatic generation of sections is actived ($SectionEditWithoutHeaders = false;). This must be placed before the first section heading or the edit section links will edit incorrect sections.

    (:noautosections:)

With this markup the automatic generation of sections is deactivated. ($SectionEditInIncludes = false:).

    (:nosectionsinincludes:)

This markup disables the generation of sections for included pages.

    (:horzsections:)

This markup enables the generation of sections for each horizontal line.

    (:nohorzsections:)

This markup disables the generation of sections for each horizontal line.

Changing the default (Edit Section↓) labels

If you wish to change the default labels of the edit links, e.g. to 'edit', set this in config.php:

   XLSDV('en', array('(Edit Section ↓)'=>'edit'));

The last quoted string will replace "(Edit Section ↓)".

If instead of English language, you are using Internationalizations, see the next section.

To hide the "Edit Section↓" (or other, customized as above) links only while printing the page, you can create a file pub/css/local.css (if it doesn't already exist) and add the following code:

 @media print {
  .sectionedit {display: none; visibility:hidden;}
 }

Translateable Strings

Add this to your XLPage or XLPageCookbook (if it's already contained in one of these files you don't have to add it, of course):

    ### Strings for SectionEdit
    '(Edit Section ↓)' => '',
    'Section' => '',
    'of' => '',
    'edit section: ' => '',
    'edit number x' => 'Nr. ',
    'edit page' => '',

and you are able to change the section edit link to whatever you like.

Alternatively you can customize these strings in your config.php by adding e.g.:

    XLSDV('de', array('(Edit Section ↓)'=>'[Bearbeiten]',
                      'Section' => 'Abschnitt',
                      'of' => 'von',
                      'edit section: ' => 'Abschnitt bearbeiten: ',
                      'edit number x' => '#',
                      'edit page' => 'Seite bearbeiten'));

Development

Since version 1.3.7 I included checking for PHP version to fix a PHP 4.1.2 problem. Currently this fix is only applied when PHP 4.1.2 is used. Please report when your version does have the same problem so I could include it to the fix list. Problem description: In the very last section the first character got lost (e.g. "===" instead of "====" or "!!" instead of "!!!") in editing and browsing.

Since version 2.2.1 the slicing into sections is done with the help of an array, $SectionEditEscapePattern - filled with regex patterns for markup that might contain headings (or horzlines or ====) which normally (i.e. when browsing) don't produce sections but when action=edit they explicitly must be ignored. Otherwise you won't edit the section you selected but only part of it.

The current version contains regex for the following potentially header eating markup:

  • (:markup:)
  • [@..@]
  • [=..=]
  • (:source:) and (:code:) (from Cookbook SourceBlock )

The array will be extended in future versions for each coming-to-know recipe / markup that eats headings.

When it occurs to you that you click on a section edit link but the textarea in the edit form misses half of the section that was displayed in browse mode - then you can help yourself by adding the markup concerned to the $SectionEditEscapePattern - but please leave a comment here, too.

Development Archive

sectionedit-archive.zipΔ

See Also

Cookbook /
BreakPage  Breaks pages into sections with inserted markers and displays one section at a time (Stable)
EX  Simple "edit section" for wiki pages (experimental)
FoxEdit  add edit links for editing page sections and PTVs with Fox (stable)
IncludeWithEdit  Enable editing of included text (last tested on PmWiki Version 2.2.0.beta45)
LiveEdit  Edit blocks of wiki-text in pop-up windows right from the wiki page. Editable blocks can be automatically detected/created on existing wiki pages using a Javascript-based GUI-like tool. An authenticated user with edit permission can edit the contents inside the blocks right from the page's view in a 'pop-up' editing environment. One can now choose from different themes/skins for the LiveEdit environment, as well as create custom themes/skins. Very useful for better organizing and maintaining contents of a wiki page, especially if the page is large. (Working great! Latest improvements in auto-detect tool are in beta test.)

More Wikipedia-like Experience:

Contributors

User notes +10 -1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.