Daisy Wiki Editor Usage Notes

Introduction

This document describes the editor used to modify pages stored in the document repository. The editor features wysiwyg editing.

Where do I find the editor?

The editor can be reached by either editing an existing document or creating a new document.

To edit an existing document, use the [Edit] link in the action menu of a document (by default, this is the menu shown on the right). This link is only visible if you are allowed to edit the document.

To create a new document, use the "New Document" link (in the the top-right navigation). You are then first presented with a list of document types, after selecting one the editor will open.

Document Type Influence

The content of the edit screen depends somewhat on the document type of the document you're editing or creating. See documents for a general discussion on documents and document types. As a quick reminder, a document can consists of multiple parts and fields. The parts contain the actual content, the fields are for more structured (meta)data.

If a part is marked as a "Daisy HTML" part, you will be presented with a wysiwyg editor for that part. Otherwise, a file upload control will be shown.

Supported browsers

In theory, the document editing screen should work on most browsers. However, to use wysiwyg editing, it is advisable to use a recent version of one of the mainstream browsers, Mozilla/Firefox or Internet Explorer. We did most of our testing using Mozilla 1.7, Firefox 1 and Internet Explorer 6.

On other browsers, the editor will fall back to a textarea allowing you to edit the HTML source. On browsers that support wysiwyg editing, you can also switch to source editing.

In any case, Javascript (and cookies) must be enabled.

Heartbeat

While editing a page, the server keeps some state about your editing session. After a certain period of inactivity, the server will clean up the editing session. To avoid the editing session to expire while you're working on a document, a 'heartbeat' signal keeps your session alive. (Technically speaking, this is a hidden frame that refreshes itself each 10 minutes).

Document locking

When you edit an existing document, the daisywiki will automatically take an exclusive lock on the document to ensure nobody else can edit the document while you're working on it. The duration of the initial lock is 15 minutes, the lock is then automatically extended if needed via the heartbeat signal.

If you start editing a page but decide you didn't want to after all, it is best to use the "Cancel editing" button at the bottom of the edit screen, so that your lock get cleared. If you don't do this, the lock will expire after at most 15 minutes, so this is not a big problem.

The locking behaviour can be adjusted by the site administrator. For example, the locking can be turned of completely. However, we expect that in most cases it will be left to the default behaviour described here.

Editing multiple documents at once

Editing multiple documents concurrently in different browser windows or tabs is supported.

Supported HTML subset and HTML cleaning

Although a wysiwyg editor is shown for the "Daisy HTML" parts, the goal is to limit the editing to a subset of HTML mainly focussing on structural aspects of HTML. So forget fonts, colors, special styling tricks, embedded javascript, and so on. Inserting those while editing in source view won't work either, as the HTML is cleaned up on the server side.

This cleanup process can also be triggered manually, by pressing the "Cleanup edited HTML" button. This can be useful if you pasted content copied from an external application and you want to see how it will look finally. When switching from wysiwyg to source view, the cleanup is also performed.

Supported HTML subset

These are the supported tags (or "elements") and attributes:

<html> and <body>
<p> with optional attributes align and class. The class attribute is only kept if it has one of the following values: note, warn, fixme
<br>
<pre> with optional class attribute. The class attribute is only kept if has one of the following values: query, include, query-and-include
<h1>, <h2>, <h3>, <h4>, <h5>
<a> with required attribute href. If the href attribute is missing, the <a> will be dropped.
<strong>, <em>, <sup>, <sub>, <tt>
<ul>, <ol>, <li>
<img> with attributes src and align (optional)
<table> with optional attribute class, <tbody>, <tr>, <td>, <th>. <td> and <th> can have the attributes colspan, rowspan and valign

All tags not listed above will be removed (but their character content will remain).

The supported tags can have any content model as allowed by the HTML DTD, but of course limited to the supported tags. If an element occurs in a location where it is not supported, an ancestor is searched where it is allowed and the containing element(s) are ended, the element inserted, and the containing elements reopened. This happens for example when a <table> occurs inside a <p>.

<b> and <i> are translated to <strong> and <em> respectively, as are <span> tags with font-weight/font-style specifications.

If two or more <br> tags appear after one another, this is translated to a paragraph split. The meaningless <br>'s that the Mozilla editor tends to leave everywhere are removed. Text that appears directly in the <body> is wrapped inside <p> elements.

<br> tags inside <pre> are translated to newlines characters.

The result is serialized as a XML-well-formed HTML document (not XHTML) (UTF-8 encoded). Lines are split at 80 characters (if possible), meaningless whitespace is removed.

All this should also ensure that the resulting HTML is (mostly) the same whether it is edited using Mozilla or Internet Explorer.

The supported tags, attributes and classes for <p> are not hardcoded but can be configured in a file (htmlcleaner.xml). However, making arbitrary adjustments to this file is not supported (the html-cleaner code expects certain tags to be there). Adding new tags or attributes should generally not be a problem, but those won't have the necessary GUI editing support unless you implement that also.

Images

Images can be inserted either by browsing for an existing image in the repository, or by uploading a new image in the repository. You can also insert images that are not in the repository, but available at some URL.

You can change the alignment of the images (using the usual text-align buttons), and change how the text flows around the image. This last option won't have effect in the PDF output.

Note that images are also documents in the repository, thus are versioned and such. If you have an updated version of an image you want to insert, it is recommend to NOT delete the existing image and upload the new image, but rather go to the document editor for that image (you can use the "Open image document" button for this), and upload the new version over there.

Currently it is hardcoded that images use the document type called "Image" with the part called "ImageData".

Links

The format of links to other documents in the daisy repository is:

daisy:<document id>
for example:
daisy:167

The daisy link can furthermore include branch, language and version specifications:

daisy:<document id>@<branch name or id>:<language name or id>:<version id>
or
daisy:<document id>@LAST
or
daisy:<document id>@LIVE

Each of these additional parts is optional. For example to link to version 5 of document 167, on the same branch and language as the current document variant, use:

daisy:167@::5

The <version id> can be a number or the strings "LAST" or "LIVE" (without quotes).

If you don't know the id of a document by hard (which is likely the case), use the "Create link by searching" button on the toolbar.

Upload and link ("attachment")

TODO

Includes

It is possible to include other documents into the document you are editing. For this, choose "Include" in the style dropdown, and enter a "daisy:" link in the paragraph.

The system checks for recursive includes (when the document is published, not when it is edited). If a recursive include occurs, an error notice will be shown at the location of the include.

It is also possible to include other sources into your document, for example "http:" or "cocoon:" URLs (however, see Include Permissions). In that case, those URLs must produce an embeddable chunk of HTML in the form of well-formed XML. These includes are currently only supported in the HTML publishing, thus not for PDFs.

Embedded queries

It is possible to embed a query in a page. To do this, put your cursor on an empty line, and choose "Query" in the style dropdown. The style of the paragraph will change to indicate it will now be interpreted as a query. Then enter the query in the paragraph.

The query must be written in the Daisy Query Language. It is advisable to first try out your query via the "Query Search" page, and once it works and gives the expected results, to copy and paste it in the document.

If you save a document containing an invalid query, an error notice will be shown at the location of the query.

Query and Include

The "Query-Include" option allows to specify a query, and the documents returned by that query will be included (rather then showing the query results). This allows to quickly created an aggregated document without needing to manually insert includes.

It is not important what you put in the "select" part of the query, you can simply do "select id where ....".

Anchors and fragment identifiers

Daisy has some basic support for linking to specific locations inside a document. To do this, the element to which you want to link (usually a header) must have an ID attribute with some value, and then in the URL you append this value after a hash sign, for example:

daisy:5#notes

This link will cause the browser to scroll to the element with an ID attribute with the value "notes". The part starting from the hash sign is called the "fragment identifier".

Assigning ids to elements is not yet possible in the wysiwyg interface, you need to switch to source view to do this. The id attributes are only retained on block-level elements, such as headers and paragraphs (though this can be changed in the htmlcleaner.xml).

Anchor elements (e.g. HTML <a name="notes"/>) are not supported, as these sort of elements are not visible in the wysiwyg editor and thus users would work blindly if these were used (deleting or moving them without being aware of it, and being impossible to edit in wysiwyg mode).

Editor shortcuts

Shortcut	Function
ctrl+b	bold
ctrl+i	italic
ctrl+z	undo
ctrl+y	redo
ctrl+c	copy
ctrl+x	cut
ctrl+v	paste
ctrl+1, ctrl+2, ...	switch to header level 1, 2, ...
ctrl+a	select all
ctrl+q	switch between bullets / no bullets
ctrl+r	remove formatting (same as the gum icon) (since Daisy 1.1)

Mozilla (or Firefox) notes

Pressing enter once in Mozilla inserts a newline (a <br>). To start a new paragraph, press enter twice.

The toolbar buttons for cut/copy/paste won't work because of security restrictions, though you can configure Mozilla to allow this for a specific site. More information is given when you click on one of these buttons while in Mozilla. However, using the keyboard shortcuts you can perform these operations without any special configuration.

When you switch to a tab containing a HTML editor for the second time, an automatic submit (server roundtrip) will be performed. This is to work around a bug in Mozilla whereby the editor becomes uneditable after having been hidden.

Character Set Information

By default, daisy is configured to use unicode (UTF-8) everywhere. For the part content you enter in the wysiwyg or source editor, you can use whatever unicode-supported characters (more correctly, it is limitted by as far as Java supports unicode). Metadata however, such as the document name, fields, etc is stored in a relational database, MySQL, which needs to be configured with a certain encoding (in West-Europe often latin1) and hence is limitted to the characters supported by that encoding. Contact your system administrator if you which to know what encoding that is, and thus to what characters (glyphs) you're limitted.

Comments (0)