This document describes the editor used to modify pages stored in the document repository. The editor features wysiwyg editing.
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 document action menu. This link is only visible if you are allowed to edit the document.
To create a new document, select the New Document link in the menu. You are then first presented with a list of document types, after selecting one the editor will open.
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. Because of the ability to plugin in custom part editors, other types of editors might also appear (e.g. for editing book definitions).
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 do most of our testing using recent versions of Firefox and Internet Explorer 6/7.
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.
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. The heartbeat signal also serves to extend your lock on the document. (Technically speaking, the heartbeat signal is an Ajax-request).
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 concurrently in different browser windows or tabs is supported.
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.
These are the supported tags (or "elements") and attributes:
All tags not listed above will be removed (but their character content will remain). On the block-type elements and images, the id attribute is supported. For the most accurate list of elements and attributes, have a look at the htmlcleaner.xml file (see below).
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 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 in new window" toolbar button for this), and upload the new version over there.
Currently it is hardcoded that images should have an "ImageData" part. They can however be of any document type.
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>
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.
If you don't know the id of a document by heart (which is likely the case), use the "Create link by searching" button on the toolbar.
A link can furthermore contain a fragment identifier. A fragment identifier is used to directly link to a specific element (e.g. a heading or a table) in a document. For this you first need to assign an ID to the element you want to link to (there is an "Edit ID" for this on the toolbar), and then you can adjust the link. The link editor dialogs make it easy by allowing to browse for available element IDs.
TODO
It is possible to include other documents into the document you are editing. This can be done in two ways:
using the toolbar button "Insert new include"
(manual) choose "Include" in the style dropdown, and enter a "daisy:" link in the paragraph.
To look up the actual document to include, use the toolbar button "Search for document to include". This will automatically insert an appropriate "daisy:" link.
After the "daisy:" link, you can put some whitespace (e.g. a a space character), and then put whatever additional text you want. This text will not be published, but is useful to leave a comment (e.g. the name of the included document).
By default the included document will look exactly as when it is displayed stand-alone. It is however possible to let the headings in the document shift (e.g. let a h1 become a h2 or h3) so that it better fits within the context. This heading shifting can be specified by opening the "Include settings" dialog using a toolbar button. In the HTML source, the include preference is stored in an attribute named daisy-shift-headings.
The editor will automatically show a preview of the included documents. The preview shows the content of Daisy-HTML parts and the fields, however without document type styling or heading-shifting applied. There are toolbar buttons to refresh or remove the previews. The include previews are not editable, when you try to edit them you will be asked to open the included document in a new window. Due to limitted control over the in-browser editors, you might find ways to edit the include previews anyway (e.g. using drag and drop), however these edits will be ignored.
When a document is published (= displayed), the includes are processed recursively. If an endless include-recursion is detected, 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.
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.
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 ....".
In the same way as for includes, it is possible to specify that heading-shifting to be performed.
It is not only possible to link to a document, but also to a specific location in a document. The element to which you want to link (a header, image, ...) must have an ID assigned. To do this, place the cursor inside the element to which to assign the ID, and then press the "Edit ID" button on the toolbar.
Then to link to the specific element, just insert a link like you always do. Both the "Create link" and "Create link by searching" dialogs allow to select the ID from the target document (in the "fragment ID" field). In the HTML source, the target ID is specified in the link as in this 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".
Explicit 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).
|
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) |
Pressing enter once in Firefox 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 Firefox to allow this for a specific site. More information is given when you click on one of these buttons while in Firefox. However, using the keyboard shortcuts you can perform these operations without any special configuration.
When you add a link or apply a styling to some words on the end of a line, it might be difficult (read: impossible) to 'move after' the link or styling. You can interrupt the link or styling by moving the cursor to the end of the line, and pressing the 'Remove link' or 'Remove formatting' button (thus without making a selection).
Merging table cells in IE works a bit counter-intuitive. You cannot simply select multiple cells and click on the merge cell button. Instead, put the cursor in one cell, and click on the merge cell button. You will then be asked how many rows and columns you want to merge.
To copy content from one document to the other, it is recommended to open the source document in the editor and copy from there. This way you make sure you copy the original source content, e.g. with "daisy:" links intact.
Hierarchical field values are entered as a slash-separated sequence. For example: abc / def / ghi. The whitespace around the separator slashes is not significant, it will be dropped. An extra slash at the start or end is allowed and will be ignored. Slashes separated by only whitespace will be dropped (i.o.w. they will not cause the addition of an element in the hierarchical path). If you want to use the slash character in a value itself, this can be done by escaping it as a double slash (//).
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 limited 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 limited 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 limited.
