• View
• Edit
• History
• Attach
• Print
• Backlinks

Worse (is better)

Questions answered by this recipe

Does PmWiki support any sort of WYSIWYG (What You See Is What You Get) editing?

Is there a more user-friendly way to create and update PmWiki content, especially for new users?

Description

Worse is a simple WYSIWYG editor for PmWiki.

Wiki's Overdue Rather Simple Editor (is better). It is worse for expert PmWiki users as it provides only a limited set of features but better for newcomers who do not need to learn any markup or read any documentation to use it. It follows the Worse is better philosophy focused on simplicity.

WYSIWYG Demo -- see and test the recipe here

Worse offers a simple and light-weight visual editing interface provided by the Trix library, highly integrated with PmWiki.

Editing: A Worse block in a page can be instantly edited by double-clicking on it or by clicking on an Edit label. Saving the page is done with Ajax calls. (Only one Worse block per page is supported for the moment.)

In edit mode, you can change both the text and the title of the page. Saving the page updates both the text and, if needed, a (:title...:) directive.

You can "paste" a piece of "rich text" copied from a text processing document or from a web page: in that case the formatting supported by Worse will be preserved or approximated, and any other formatting will be discarded.

Links: the interface is strongly WikiGroup-oriented - drop-down lists make it very easy to link to other pages in the same WikiGroup, and to create new pages in the same group. It reduces the risk a novice user unintentionally creating new groups by mis-typing an internal link.

Links to other groups and to files attached to other groups are as easy (or as hard) to input as external links, via an input box. The input box accepts literal URLs, there is no need to encode parentheses or brackets.

Uploads: files can be attached by simply dropping them into the edited page. They are automatically uploaded without a need to leave the edit form and a link is inserted in the page. A drop-down list allows to select a file uploaded to the wiki and to insert it into the page, and a button to select files from the user's computer and to upload them. Multiple files can be dropped or selected and uploaded at once.

Uploaded files are inserted into the page as links to them, with distinctive styling, and the file name and size are automatically shown.

Uploaded pictures are always embedded into the page, and it is easy to type or change the default caption. It is only possible to embed locally uploaded/attached pictures. Hotlinking is not supported.

If the uploads wiki feature is not enabled, or if the current user has no 'upload' permissions, she cannot upload files: some of the buttons may be hidden, and any dropped file will be discarded. However, if attachments are already uploaded, the user can select them from the drop-down list and insert them into the page text.

Text formatting: only bold, italic, strike through inline formatting and fixed-width block formatting is supported. The following block level elements are possible:

• Simple text paragraphs (<div>).
• Heading (<h2>) only one level of headings is supported.
• Code block (<pre>), fixed-width font, preserved spaces, but formatting and links are possible.
• Quote/citation blocks (<blockquote>), rendered with a left border, nestable.
• Bulleted and numbered lists, nestable.
• Figure and Caption (<figure>, <figcaption>) for embedded pictures.

Table of contents can be seamlessly included with AutoTOC.

Wiki source markup: While the browser returns an HTML5 string, Worse converts it to a small subset of PmWiki markup rules and that WikiText is saved into the page. This makes it possible for the text to be indexed for searches, and to occasionally edit the plaintext markup by hand, for example when a user is temporarily stuck with an old browser. It also makes it easy to understand the page history (as opposed to storing the HTML code diffs).

The markup saved in the page looks like this:

(:worse:)
Paragraphs with literal 
line breaks, 
{*bold*}, {~italic~}, {-deleted-}

[[Page|internal link]], [[http://www.pmwiki.org|external link]]
[[Attach:file.odt]] attached file, link text is automatic (name, size)

[[Attach:picture.jpg|embedded picture with caption]]

!! Heading
 code block starts with 1 space
 spaces       are           preserved

> quote block
>> can be nested

* unordered list
* unordered list

# ordered list
# ordered list
** nestable
### nestable
(:worseend:)

It is possible to have regular PmWiki markup before or after the Worse block.

Browser support: The content will be "readable" with most browsers, JavaScript is not required for reading. To use the WYSIWYG interface you'll need a fairly recent browser, see below.

Obviously, you can use the plain-text PmWiki editing interface to edit the Worse markup "by hand", this requires neither a recent browser, nor JavaScript.

Installation

1. Get worse.zipΔ, place the file "cookbook/worse.php" in your pmwiki/cookbook directory, the directory "pub/worse" in your "pub" directory.
2. Add to config.php this block:

   include_once("$FarmD/cookbook/worse.php");
   $DefaultPageTextFmt = "(:worse:)(:worseend:)\n";
   

• The JSON data exchange format used by Worse requires UTF-8 to be enabled on the wiki even if there is not a single international or extended character in the wiki.

Configuration

The following variables can be configured in local configuration:

• $Worse['GroupRecentChangesName'] = 'RecentChanges'; # The name of your RecentChanges pages, if you have customized them (needed to check if the cache needs rebuilding).
• $Worse['FilterPageNames'] = '-*.GroupAttributes,-*.GroupFooter,-*.GroupHeader'; # page names to NOT include in the drop-down list of links, joined by commas, note the minus before each name. You may want (or not) to add here RecentChanges and SideBar for example. Reminder: only pages in the current group are listed.
• $Worse['FilterFileNames'] = '-th*---*'; # file names to NOT include in the drop-down list of attachments, joined by commas, note the minus before each name. In the example, Mini or ThumbList thumbnails will be skipped. Reminder: only files available in the upload directory of the current page are listed (per-page, per-group or per-wiki, see $UploadPrefixFmt).
• $Worse['EditForm'] = "<form class='notoc' id='worseform'>...</form>"; # The Worse edit form template. Only experienced users should modify this template, eg. to hide the Author field.
• $Worse['CacheDir'] = "$WorkDir/.worse"; # Where to store the cache files with the page names and titles, per wikigroup.
• $Worse['PageTitlesFunction'] = "WorsePageTitles"; $Worse['FileDataFunction'] = "WorseFileData"; # use to override the default caching functions -- in case you have some exotic customization, you can write your own functions.

Internationalization

The following strings can be translated in an XLPage:

   # buttons
  'W_Attach' => 'Attach',
  'W_AttachFiles' => 'Attach files',
  'W_UpNewFiles' => 'Upload new files...',
  'W_CreateNewPage' => 'Create new page...',

   # drop-downs
  'W_SelectPageLink' => 'Select page link...',
  'W_SelectUpFile' => 'Select uploaded file...',
  'W_DropFiles' => 'Drop files in the page to upload them.',

   # dialogs
  'W_CreateNewPageTypeTitle' => 'Create New Page, type the page title:',
  'W_InvalidPageName' => 'Invalid page name.',

   # The user leaves the page without saving
  'W_NotSaved' => 'Content was modified, but not saved.',

   # Saving a page failed for some other reason, %s = $WikiTitle
  'W_ChangesNotSavedReplied' => 'Changes NOT saved. %s replied:',
  'W_NoUploadPerm' => 'No upload permissions.',
  'W_AuthorNameReq' => 'An author name is required.',

   # The edit form
  'Type your text here' => 'Type your text here',
  'Change summary' => 'Change summary',

Usage

When you follow a link to a page not yet created, the editor will be open so you can start typing in it. When a page exists, double-click on the Worse block, or click on the Edit label near its right top corner. The editor will appear.

Type or change the content, drop files to upload them. Use the buttons from the toolbar to format the text or to insert links and attach files.

At the end, press on the "Save" button to save the page which will close the editor.

Page and file data caching

The editor provides a list of local links with the URLs and titles of the pages in the current group. Another list with the attached files contains their URLs, names, types, sizes, and for pictures widths and heights.

Both these lists may take a considerable amount of time and server resources to build (every page has to be open, and every file needs to be examined), especially if there are many pages in the current group or many files attached to the current group or page.

Worse will cache the two lists in 2 different files, the page titles in "$WorkDir/.worse-cache/Group,cache" and the files in their upload directory (per-group, per-page or per-wiki, see $UploadPrefixFmt).

When a page in the group is added or edited, the cache file is updated with the new title of the page, and when a page is deleted, its entry is removed from the cache.

When a file is uploaded, again, the cache file is updated with the attributes of the file.

If you add, delete or modify pages and files in a way other than Worse, other than the PmWiki regular edit/upload interface and other than the UpdatePage() function, the Worse cache files will need to be rebuilt. In that case, open your wiki page with the action=worserecache, eg [[Main.HomePage?action=worserecache]]

Note that you should do this in every Group where pages have been modified in a non-standard way.

For example, if you upload or delete files via FTP, the cache needs to be rebuilt.

If your wiki stores uploads per-group, do this in every group where files have been added, modified or deleted. If your wiki stores uploads per-page, do this in every page where files have been added, modified or deleted.

Alternatively, you can simply delete the Cache files from the directories mentioned earlier.

Notes

• Wiki pages created in the default source editor cannot be edited directly by Worse, only new pages will be created with a worse block, or you can manually insert a (:worse:)(:worseend:) markup to enable the editor in the existing page.
• To edit the page title, the skin should have the page title either in a <h1 class="pagetitle"> tag or in a "<div class="pagetitle">...<h1...>" block (most skins do).
• If there is a single invalid character in a file name, the file will not be attachable. (Invalid = Not "valid UTF-8".) You may have to rename such existing files. To prevent people uploading such files, you can set in config.php either one of the following lines:

  $UploadNameChars = '\\w\\x80-\\xfe. -'; # allow UTF-8
  $UploadNameChars = 'a-zA-Z0-9_. -'; # only basic alphanumeric
  

  The default PmWiki setting '\\w. -'; under some locales will cause a filename to have characters that are not "valid UTF-8".
• The recipe does not currently work with $EnableDirectDownload set to 0.
• The core conflict resolution for Simultaneous edits is not currently operational. A later page save always overwrites an earlier one that has been done in the meantime, without warnings.
• Please remember, when you upload or delete attachments or edit or delete pages directly on the file system shell (or via FTP) without using the functions of PmWiki (?action=upload or edit), the page and file caches need to be rebuilt: call your wiki with the ?action=worserecache. See section Page and file data caching. You may want to add such an entry in your page [[Site.PageActions]].
• If used together with DragDropMultiUpload, first include Worse, then DDMU.
• Only the specific features documented above should be expected to work in a Worse text block - a small set of text formatting and attachments. No other PmWiki features are implemented in Worse, for example page variables, page lists, inclusions from or to other pages, conditionals, styles, anchors, tables or any other PmWiki markup. In that sense it is "worse" than the default wiki editor. Worse should only be considered for wikis where the people who write the content only need that basic set of features and at the same time cannot learn the basic editing rules.

To do

In the next few days/weeks:

• i18n for the core library
• make it easier to login if user cannot edit
• address multiple and/or included Worse blocks in one page (at least, make those read only)
• review the HTML5 library for update to latest version

Some day, maybe (if there is interest/€€€)

• Ape integration.
• Some way to delete a page.
• Simultaneous edit conflict resolution.
• Autocompletion for links to @pages and +attachments.
• Easier cross-group linking, but still unlikely to mistype a link.
• Automatic linking while typing a URL, lazy web/e-mail links.
• Possibility to change the default formatting tags, e.g. replace Blockquote with Frame, Struck-through text with code or whatever.
• Make it work with $EnableDirectDownload disabled.

Change log / Release notes

• 20231213: Update for recent PmWiki versions with PmToken (reported by Peter Waldhaeuser).
• 20221226: Fixes for PHP 7.4 (suggested by Walter Keller) and for PHP 8.2.
• 20170929: Accept more flexible responses (trailing spaces or new lines) for saved pages, reported by Walter Keller.
• 20170813: Fix unneeded message when leaving the page if the title was modified and saved.
• 20170803b: Detect clicks on the "?action=edit" links in the page actions and footer and open the Worse editor instead of the PmWiki source editor; if the Worse editor is already open, let the browser follow the links.
• 20170803, 20170803a: The recipe will now try to automatically rebuild the file data cache if the cache file appears corrupted. If individual filenames contain invalid characters, they will now be ignored instead of halting the editor.
• 20170802: Fix display bug when saving a title (showed the old title until the page is reloaded). Fix bug when several text formatting markups were glued together. Warn user when an author name is required, or when s/he tries to leave the page before saving it. Internationalization completed. Most errors should have been captured, please report if anything was omitted. Bold and italics source markups replaced to prevent ambiguous situations. Hitting Enter/Return in the Summary or Author fields now saves the page.
• 20170801: Show messages when no permissions to edit or upload, or when the save failed for some reason (if $MessagesFmt is populated, it is shown). Disable drop-uploads and attach button when no permissions. Disable Attach dialogs and drop-uploads when $EnableUploads is disabled. Blocklist integration. Various other fixes.
• 20170731: Rewrote/refactored the Cache functions (configurable) and files, add action=worserecache, swap summary and author in the edit form (like the regular editor), make the edit form configurable, pass the PmWiki variables and arrays as plain JavaScript instead in data-* attributes.
• 20170730: Improvements for editing the title, various small fixes.
• 20170729:
  • Fix: File names with spaces fail to embed.
  • Fix: '*bold*' markup spanning multiple lines can be mis-interpreted as a list item.
  • Add: Edit the title of the page.
  • Fix: Save button appears out of the viewport on a mobile screen.
  • Fix: Change summaries appeared on RecentChanges but not in page history.
• 20170728: First release, ready to be tested.

See also

Contributors

• Recipe written and maintained by Petko. The JavaScript part relies on the Trix library by Basecamp.

Comments

See discussion at Worse-Talk