EX

Summary: Simple "edit section" for wiki pages
Version: 20230429
Prerequisites: PmWiki 2.3.18 or more recent, JavaScript, recent browser
Status: experimental
Maintainer: Petko
License: GPL
Users: (view? / edit)
Discussion: EX-Talk

Simple "edit section" for wiki pages.

Description

The recipe allows editing of wiki pages, section by section, where sections are separated by the top-level headings in the page.

Here are the differences from Cookbook:SectionEdit:

  • Single level sections. The recipe finds the largest heading in a page ("!", "!!", "!!!"...), then splits the page into sections starting with this level of headings.
    • An anchor preceding the heading like [[#description]] will be included in the section with that heading.
  • Only headings from the current page will have "edit" links.
    • Included pages, sections, and page text variables won't have edit links, however from PmWiki 2.3.0 you can list the included sections in the edit form, see $EnableListIncludedPages to easily access these too.
  • The PHP code is much simpler, and doesn't override core functions including text sections.
  • There is a JavaScript program that does most of the work on the browser.
  • In the editing form, a dropdown menu allows to edit other sections in the page, or the full page. It is inserted above the edit text area and before the GUI edit buttons (if you have them enabled).
    • The dropdown is updated automatically as you add, modify, swap or remove headings and sections.
  • You can edit the "Lead section" (before the first heading) from the dropdown menu.
  • Works when you "save-and-edit" the page, when you "preview" the page (the full page is shown) and with Cookbook:PreviewChanges.
  • It may make it easier to edit per section with Cookbook:PmSyntax for very large pages or on slower hardware (also applies to SectionEdit).

The recipe is enabled on this page and on the Talk page, feel free to test it.

For testing purposes, you can enable or disable the recipe on pmwiki.org.

Installation

  1. Get ex.zipΔ, open it, and place the file ex.php in your pmwiki/cookbook directory, and the file ex.js in your pmwiki/pub directory.
  2. Add to config.php this line:
    include_once("$FarmD/cookbook/ex.php");
    

Configuration

You can place these in local configuration:

  • $EnableAuthLinksEX = 1; # only show Edit links to people with edit access for the page.
  • $EnableListIncludedPages = 1; # after the edit textarea, adds links to edit pages included from the current page.

Internationalization

The following strings can be translated in an XLPage, for example in French:

  'Edit section...' => 'Éditer la section...',
  '*Full page' => '*Page entière',
  '^Lead section (before the first heading)' => '^Résumé introductif (avant la première section)',

Note that I am not completely satisfied with these strings, if you have suggestions for better ones, we can change them. (In such a case, the translations will also need updating.)

The recipe also reuses the "Edit" word which is usually already translated.

Usage

When you browse a page you can edit, [Edit] links appear after the top level headings in the page. Click on such a link to edit that section.

Use the dropdown to change sections.

Notes

Things to check when testing the recipe:

  • Will it break in some cases with complex markup?
  • Will it lose a section when saving a page?
  • Will it work with Markup blocks, and with multiline page text variables in the page?
  • Will it insert extra linebreaks between the sections?

If you notice any of these, or other problems, please make a page in the Test group where we can test and review the behavior.

Known issues

  • Sometimes leaving the edit form without making any changes may cause a wrong warning about changes not saved.
  • Some rare combinations of markups on the same line before a heading may cause the edit links to open different sections, or to not have edit links. Until we figure out workarounds, you could either avoid these markup combinations or select "*Full page" from the drop-down.
(:nolinebreaks:)!! After some directives, on the same line

(:PTV:value:)!! After a PTV, on the same line

(:if true:)!! Within a conditional, on the same line

(:else:)
!! Inside a conditional evaluating to false

(:ifend:)!! Immediately after a conditional

Text after a line break \\
!! Not a heading \
!! or after a line-join

The above are not headings, but may be incorrectly split into sections in the edit form.

(markupend)!! Immediately after a markupend

After some directives, on the same line

After a PTV, on the same line

Within a conditional, on the same line

Immediately after a conditional

Text after a line break
!! Not a heading !! or after a line-join

The above are not headings, but may be incorrectly split into sections in the edit form.

(markupend)!! Immediately after a markupend

To do / some day / maybe

  • After a page is saved, maybe scroll to the last edited section.

Change log / Release notes

  • 20230429 - Update to work with EncodePost.
  • 20230313 - Add variable to only show edit links to editors, suggested by HansB. Refactor/simplify markup functions.
  • 20230312 - Fix bug when there is no text or anchor before the very first heading, reported by HansB.
  • 20230303 - Fix a bug when there are no headings in the page.
  • 20230302 - Update to work with PmSyntax, update styles for new GUIButtons, refactor/simplify code, skip multiline page text variables containing headings.
  • 20220101 - First public release, ready to be tested.

See also

Cookbook /
BreakPage  Breaks pages into sections with inserted markers and displays one section at a time (Stable)
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.)
SectionEdit  Split a wiki page into separately editable sections with an edit link for each section (Stable)

Contributors

Written and maintained by Petko.

Comments

See discussion at EX-Talk

User notes? : 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.