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
- Show only the structure that is in use, support outlining if needed
- Make your document active
- Now you see it, now you don’t
- 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.
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.
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.
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.
Now you see it, now you don’t
You should hide the active functionality (buttons, popup-menus, etc.) in the document
when they can’t possibly be activated. The user should be able to move the mouse
away from the document and see the document without any clutter of the active elements.
In the example from earlier, the select-one-option-question the plus, minus and
arrow icons dissapear when the mouse is moved away from the question.
| |
Mouse over | Mouse out |
Usually you only show the active functionality for a part of the document, when
the mouse is over that part of the document. You hide the active functionality when
the mouse is moved away.
Video showing basic now you see it, now you don’t in SARD (21 sec).
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
No comments:
Post a Comment