Worse (is better)

Summary: Simple WYSIWYG editing for PmWiki
Version: 20170813
Prerequisites: UTF-8, PmWiki 2.2.56, PHP 5.2, recent browser
Status: experimental
Maintainer: Petko
License: GPLv2+ (Worse), MIT (Trix library)
Users: (view? / edit)
Discussion: Worse-Talk?

Questions answered by this recipe

ScreenshotΔ

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.

Browser support

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";
    
Notes:
  • 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.',

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

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

   # 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 pagesin 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

  • 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.

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).

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

  • 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

PmWiki /
WYSIWYG  Notes about WYSIWYG support in PmWiki
WYSIWYG-Talk  Talk page for WYSIWYG.
Cookbook /
AjaxEditSupport  Adds a wikipage/attachment/category AJAX browser to Edit pages (WIP)
CodeMirror  An enhanced page editor for PmWiki (Release Candidate)
DragDropMultiUpload  Allow authors to upload files by simply dropping them into the wiki page (Beta)
EditHelp  Easier editing with automatic detection and insertion of some wiki markups (Experimental)
FileAttachList  Adds a Ajax list of quickly attachable files to the edit page (Stable)
FixURL  Encode special characters in link addresses (Beta)
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.)
NotSavedWarning  Warn authors when they move away from a page without saving it; optionally request an edit summary or an author name (beta)
PasteImgUpload  Upload an image by copying and pasting in the editing area directly.
RichEdit  WYSIWYG editor (Abandoned)
SectionEdit  Split a wiki page into separately editable sections with an edit link for each section (Stable)
Wikiwyg  Integrate Wikiwyg into PmWiki for WYSIWYG editing (pre-alpha)
WYSIWYGFundDrive  Pledge card for PmWiki WYSIWYG development
PITS /
00421  WYSIWYG editor (like FCKEditor) integration (closed)

Contributors

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

Comments

See discussion at Worse-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.