Structured Active Rich Document (SARD)

What You See Is What You Get (WYSIWYG) on steroids

(Work-in-progress since 2002, by Allan Ebdrup)

This document is intended for web developers. It is a description of the principles behind the SARD technique. SARD can be used when normal users will be editing any kind of structured document, it is used in the obsurvey application, but I have used it successfully for other projects as well. The principles of SARD are:

Modify data or documents according to their structure
Support the notion of a document
Define a model for your document structure, a conceptual display model
Databind your conceptual display model
Inject objects from your conceptual display model into your view
Show only the structure that is in use, support outlining if needed
Make your document active
Don’t waste space
Rich text formatting
Real or “close to” WYSIWYG editing
Never leave the document while editing
Support the use of drag and drop
Let the user undo
Provide context sensitive help

Each principle is described in detail in the following sections.

Modify data or documents according to their structure

If you have a model for the structure of your data, typically some kind of hierarchy, and you want to edit this data dynamically, SARD might be a good idea.

At he heart of SARD is the use of Rich text formatting capabilities in the browser, from here called Browser Rich Text (BRT). The typical use of BRT is that you have a single fixed size editing area. Right above the editing area you have formatting functionality in a toolbar, with buttons for making text bold, italic and other more or less advanced formatting possibilities. Very much like in a word processor, you are free to edit everything in the BRT area in any way you like.

This is not how you edit documents in SARD. In SARD you have a document structure that needs to be enforced. So basically you limit the editing capabilities of the user, so he/she can only modify the document in a way that adheres to the structure.

For example in obsurvey you have a select-one-option-question, where you are constructing a question that has several answer options. The idea is that when the user is done editing the question the respondent can answer the question by selecting one of the answer options by clicking the radio button next to the relevant answer option.

In order for the user to construct a meaningful question, there needs to be one and only one radio button for each possible answer option. When using SARD you enforce this structure by making only the question text and the answer option text editable BRT areas.


As shown on screen	Editable elements marked in green	Uneditable elements marked in red

Video explaining basic SARD (41 sec)

Furthermore, the user can add another answer option is by clicking the plus icon at the bottom of the question, shown below. And the user can remove an answer option is by clicking the minus button to the right of the answer option. It is also possible to move the individual answer options up and down, changing their order, by clicking the up and down arrows.

Video explaining basic SARD structure modifications (25 sec)

This effectively makes sure the document is well structured, and in this case that means a valid question is always constructed. It also means that when a respondents have given their answers, it's possible to generate a meaningfull report. Having a structure in the document not only means you get well-formed documents, it also means you can do intelligent things with the data in the document.

Support the notion of a document

You should make editing your document feel like a single document. When splitting the document editable and non editable parts, you can easily break the notion of a single document for the user.

If your editable text area is typically just one line of text, you should override the default behavior of pressing return. Instead pressing return should do the logical thing and insert new elements below where you are, according to your conceptual display model, discussed in the next section. Alternatively pressing return can be ignored or cause the cursor to jump to the next editable text area.

Furthermore pressing arrow down, when the cursor is at the last line of an editable text area, should jump to the next editable text area in the document. Pressing arrow up, when the cursor is on the first line of an editable text area, should jump to the previous editable text area. Pressing arrow left, when the cursor is before the very first character in your editable text area, should jump to the previous text area. And pressing arrow right, when the cursor is placed after the very last character in your editable text area, should jump to the next editable text area in your document. You should also consider doing something meaningfull when the user presser page down, page up, ctrl+home and ctrl+end.

Finally if your editable text area is complete empty and the user presses backspace, you might consider deleting the editable text area and its associated un-editable elements.

Video showing how to support the notion of a document in SARD (28 sec)

Define a model for your document structure, a conceptual display model

Draw a class diagram of the model that defines the structure of your document. Implement this model i JavaScript in your frontend. For example the model for obsurvey looks something like this:

The conceptual display model for obsurvey is actually bigger, this is the part that is used in the survey editor.

The important thing in creating your conceptual display model is keeping anything directly related to HTML out of your conceptual display model, but at the same time having your display concepts in your conceptual display model. For example a boolean indicating wether something is hidden can be in your conceptual display model, but that's all, just a boolean in the model. You can't put any details about how the hiding is done in your conceptual display model.

You should alway strive to divide and conquer, reuse and have a high abstraction level in your main conceptual display model. If you are modelling a concept, like an array of elments where one and only one element is shown at any given time, this concept should be extracted out as a concept in it's own right, with it's own model that can be reused.

Note that if you have a model in your business logic on your server, the conceptual display model may differ from that model. The conceptual display model is specifically modelled for displaying on the screen. For example in obsurvey a page break is an entity in the conceptual display model and not an entity in the business logic.

Databind your conceptual display model

Databind your model to your HTML, your display. A good idea is to use a JavaScript framework to assist you in databinding. Unfortunately the databinding capabilities of the main stream JavaScript frameworks are not that good, but hopefully this will change in the future. There are some of the frameworks that supoort rich two way databinding. I use my own JavaScript framework. Databinding allows you to make changes to the model and have the display automatically update and vice versa. If you do not have databinding capabilities in your JavaScript framework you'll have to wire things together manually.

Inject objects from your conceptual display model into your view

Another way to look at databinding is to see it as injecting objects fromyour conceptual display model into your view. You pass the smallest part of your model objects as possible to the view, and the view databinds itself to this model. A huge advantage of this approach is that it lets you inject your model into several different views. I've had a lot of use for this in the applications I've build. Often, if I make the mistake of including part of the conceptual display model directly in the view, I find myself having to do the work of seperating the conceptual display model from the view, in order to reuse the objects from the conceptual display model for injecting into a different view of the same data.

Show only the structure that is in use, support outlining if needed

Never show parts of the structure that don’t contain data, except when the user has indicated he/she wants to add data there. When following this principle you can potentially have a massively complex structure, but the individual documents may not appear cluttered with information about the structure the document adheres to. Only the part of the structure that is in use is visible.

If you have large documents you can support outlining, where you can collapse and expand parts of the document. If you support outlining you should add mouseover effects to the collapsed parts that shows a summary of what has been collapsed.

Make your document active

Add the functionality (buttons, popup-menus, etc.) that is needed to modify the structured document where it is relevant. That means buttons for modifying data to the document is right there in the document where the data is added. Like the plus, minus and arrow icons in our example from before.

This way it will be clearer to the user what the buttons do. It also gives the user an understanding of what the underlying structure of the document is. The user should be able to click a document expanding action to see what it does and easily undo the expansion. This is essential to allow users that are unfamiliar with the structure of the document, to discover the structure of the document by trial and error.

Don’t waste space

You should always try to use flow layout. Specifying the width or height of an element should only be done for elements like buttons, menus and the like. The document itself should use the powers of the browser to let the browser decide how big or small parts of the document should be. You can decide the width or height of the entire document, for example if you want paragraphs to be easily readable and therefore not too wide, but you should never specify the size of elements inside the document.

Rich text formatting

Support rich text formatting if your users need it. You can also use resizing textboxes that don’t allow formatting. However this solution is made difficult because textboxes don’t inherently support automatic resizing to the content they contain. You'll have to make the resize.

Video of basic rich text formatting in SARD (28 sec)

Real or “close to” WYSIWYG editing

You should strive for What You See Is What You Get editing. The users view of the document when editing should be as close to what it looks like when it’s published, printed etc. If you show active elements (buttons, icons etc.) the user should be able to move the mouse away from the document and see the document as it will look like when it’s published, printed etc.

Never leave the document while editing

The user should never have to leave his/her document while editing it. You can provide menus, toolbars, buttons, icons etc. pop-up expansions but the user should never feel he/she has left the document. This means you should always see part of the editing environment. Wizards should be kept small and only hide part of the document; you should avoid wizards if you can.

The exception to this rule is previewing the document. If you have some kind of preview function, having it take over the browser is often a good idea, in order to provide a clean and undisturbed preview of the document.

Support the use of drag and drop

You should make it possible for the user to drag and drop parts of the document. Drag and drop is a great way for the user to quickly manipulate a structured document. It is also a good idea to provide a way to add top level parts of the document by using drag and drop. When dragging, use the conceptual display models classes and have the databinding take care of the changes to the HTML. (Drag and drop is almost fully implemented in obsurvey)

Let the user undo

You should let the user undo any manipulation of the structured document. For example the user should be able to undo a deletion if he/she deleted something by accident.

Video of undo implementation in SARD (43 sec).

Provide context sensitive help

You should integrat help into your user experience, in obsurvey I pop up examples when a user is selecting a question type, and I also pop up some help text in the bottom right corner of the screen. This pop up help text is shown in direct relation to what the user is currently doing. It is context sensitive.

The technology behind SARD

The technology behind SARD is all well known, SARD is just combining them in a new way. The technology in use is

An Internet browser
JavaScript
Dynamic HTML
Rich text formatting capabilities in the browser (Content editable in Internet Explorer, Chrome and Safari or design mode in Firefox)
CSS
AJAX