wysiwyg autosuggestion.doc

WYSIWYG AUTO-SUGGEST

Contents

1 Quick Start Panel 2

2 Auto-suggest based on context 5

2.1 Global Context 5

2.2 Prefix Context 5

2.3 Syntax Context 6

2.3.1 Bold: **（Group 1） 9

2.3.2 Underline: __（Group 1） 10

2.3.3 Italics: //（Group 1） 10

2.3.4 Striped out : --（Group 1） 10

2.3.5 Monospace: ##（Group 1） 10

2.3.6 Superscript: ^^（Group 1） 10

2.3.7 Subscript: ,,（Group 1） 10

2.3.8 Verbatim: {{{（Group 1） 11

2.3.9 Groups: (((（Group 1） 11

2.3.10 Headings: =,==,===…（Group 2） 11

2.3.11 Lists: *,**,***…; 1. 11. 111. …（Group 2） 11

2.3.12 Definition Lists: ;, :（Group 2） 13

2.3.13 Tables: |=, |（Group 2） 13

2.3.14 Images: image:（Group 3） 14

2.3.15 Links: [[（Group 3） 16

2.3.16 Macro: __（Group 4） 18

Quick Start Panel

Usually the beginners have little common senses of xwiki syntaxes, however they want to try Source editors of WYSIWYG in order to get full control of what they want to type in, under this situation, the user often found it so difficult to remember and type correctly all the xwiki syntaxes. They have to refer to the syntax tutorials on the xwiki official site(http://platform.xwiki.org/xwiki/bin/view/Main/XWikiSyntax), even though they read all the tutorials, they will still make mistakes easily.

For experienced users, they might have exactly known how to organize their wiki docs using various syntaxes, they would sometimes forget some of syntaxes, their rules or attributes.

So, if there were a quick reference to the common used syntaxes, it would be very helpful for beginners to get a quick start and a good assistant to learn the xwiki syntaxes, it would also helpful for experienced users to have a quick reference to the syntaxes when they could not remember some of xwiki syntaxes.

Quick start panel is an overview of common xwiki syntaxes suggestion panel for solving those problems. Under global context, the panel will not be triggered immediately until the user press the hotkey ”Alt+Tab” or ”Tab twice”. It shows up as figure 1 as a whole, but it should be scrollable to save the spaces for practice.

Figure 1: Quick start panel

(http://www.flickr.com/photos/44893839@N00/5561100330/)

As you can see, the common xwiki syntaxes are listed with the syntax catalogs and their sub-syntaxes. The catalogs follow a small icon with different color before them, each represents a specific syntax catalog, it would be helpful for identifying the various kinds of syntaxes when auto-suggesting, it will be covered in the next paragraphs. Under each syntax catalog, the syntaxes belong to them are listed as the following format:

Icon syntax symbol –syntax name :examples or render results;

User can select the syntaxes in the quick start panel using “up” and “down” key from keyboard, when they type “Enter” key, the selected syntax will be inserted into the editor automatically.

Auto-suggest based on context

There are three contexts for auto-suggestion: global context, prefix context and syntax context.

Global Context

Under following situations, it will enter global context:

Prefix context are not triggered.
Not under a specific syntax context.

Under Global Context, users can only trigger Quick start panel using hotkeys “Alt+Tab” or “Tab twice”, then beside the input cursor, there will show up a tooltip panel, user can navigate syntaxes by “up” and “down” key, and select them by “enter” key or click on them.

Figure 2. Quick start panel under global context

(http://www.flickr.com/photos/44893839@N00/5560525231/)

Prefix Context

Some xwiki syntaxes are beginning with the same character, for example “bold(**)” and “bulleted list(*)”; images syntax may start with “[[imgaes:” and Link syntax start with “[[”; Table header “|=” and table cell “|”; Most of Macros like” {{html}}{{/html}}” are started with “{{” and end with”}}”;

Under these situations, the suggestion system would be confused with the prefix user type in. As default, the auto-suggestion will not triggered automatically, until user press the hotkey “Alt+Tab” or just ”Tab” like linux terminal. User can navigate syntaxes by “up” and “down” key, and select them by “enter” key or click on them. Once the user selected one, the context will enter to the selected syntax context, for example, if user select “image” (in figure 3), the in the source editor after “[[”, it will be filled with “[[image:]]”, and the cursor will focus after “image:” and before “]]”, waiting for user’s further input, and finally the context will be under image context.

Figure 3. Example for prefix context (“[[”)

(http://www.flickr.com/photos/44893839@N00/5561101256/)

Figure 4. Example for prefix context (“*”)

(http://www.flickr.com/photos/44893839@N00/5561100974/)

Syntax Context

Syntax Context will not be trigger unless user select one of syntax from Prefix Syntax, then the auto-suggestion system will understand which syntax context should be loaded.

For example, from prefix syntax in figure 3, if user selected “[[“ for Link syntax, it will enter link syntax context. Then the following features for link syntax context will be activated:

When user types the link name, link syntax will auto-suggest the related links with the prefix user inputed.
When user types ”>>” after “[[”, like “[[text>>”, it will trigger the same function as 1 to list related links following the user input.
When user types “||”, like ”[[text>>alink ||”, then it will suggest the attributes for links, etc. “rel”.
When user types “attach” after ”>>”, like “[[text>>attach:”, then it will suggest the attachments related to this page.

In the following we will discuss the details for each xwiki syntax context:

Headings:

=,==,===…

Text Formating:

Bold(**), italics(//), underline(__), striped out(--), monospace(##), superscript(^^), subscript(,,).

Lists:

Bulleted list(*), numbered list(1.)

Definition List:

Term(;), definition(:);

Links(for 2.1):

Link tag and attributes([[, >>, attach:, image:, ||rel)

Tables:

Table header(|=), Table cell(|)

Images(for 2.1):

Image related tag and attributes(image: ,@, ||, width, height)

Verbatim:

{{{

Quotations:

>,>>,>>>…

Groups:

(((

Macros:

Not fully support, should be discuss further

Others:

“(%” and its attributes

After evaluating all of them, I divided them into three groups:

Group1:simple enclosed syntax;

These syntax are enclosed, and when user select one of them in auto-suggestion list, the following syntaxes are in this group:

Text format: Bold(**), italics(//), underline(__), striped out(--), monospace(##), superscript(^^), subscript(,,);
Verbatim: {{{
Groups: (((

Group2:nested unclosed syntax;

These syntaxes are not enclosed, and it could be nested in some way:

Headings(=,==,===…)
Lists(*,**,***… or 1. 11. 111. …)
Definition list: (;, :)
Tables(|=, |);

Group3:Smart with auto-completion;

Except main syntax tag, it can contain some attributes to enhance its function, another feature is it might auto-suggest some Links such as xwiki pages or page attachments according. The following syntaxes are in this group:

Links(“[[”)
Images(“image:”)

Group4:macros with attributes;

Macro syntaxes are enclosed tags, they are in the form of {{syntax-name attribute1=’”” attribute2=”” …}} some contents{{/syntax-name}}

They will auto-suggest not only the syntax-name, but also the attributes. When user selects one, it should suggest the necessary attributes automatically.

The following are describes all these syntax contexts, they are organized as:

2.3.1 – 2.3.9: group 1;

2.3.10 – 2.3.13: group 2;

2.3.14 – 2.3.15: group 3;

2.3.16 – : group 3;

Bold: **（Group 1）

When user selected bold from globe context or prefix context, it would auto-complete as follow:

select “**” from the following suggestions.

(http://www.flickr.com/photos/44893839@N00/5561100974/)

Auto-suggest system will auto-complete bold syntax for users, and focus cursor in the middle of the syntax enclosed tags, as showed below:

(http://www.flickr.com/photos/44893839@N00/5561101392/)

Underline: __（Group 1）

The same scenario as Bold.

Italics: //（Group 1）

The same scenario as Bold.

Striped out : --（Group 1）

The same scenario as Bold.

Monospace: ##（Group 1）

The same scenario as Bold.

Superscript: ^^（Group 1）

The same scenario as Bold.

Subscript: ,,（Group 1）

The same scenario as Bold.

Verbatim: {{{（Group 1）

The same scenario as Bold.

Groups: (((（Group 1）

The same scenario as Bold.

Headings: =,==,===…（Group 2）

Step1: When users are in heading context, the suggestion results will be dynamically generated according to user input, for example, if user type “=”, then auto-suggestion results will be “=” and “==”; If user type”==”, the auto-suggestion will be “==” and “===”.

(http://www.flickr.com/photos/44893839@N00/5561101718/)

Lists: *,**,***…; 1. 11. 111. …（Group 2）

When user are under List syntax context , the suggestion will be trigger when user start a new line for sub-list, and the suggestion results will be dynamically increase or decrease according to the current depth of the list. For example, when in the first depth, auto-suggestion results will be “**” and “*”, while in the second depth, auto-suggestion results will be “***” and “**”.

When user select “List” from the suggestion list below , it will enter List syntax context.

(http://www.flickr.com/photos/44893839@N00/5561100974/)

In List syntax context, user type ”Enter” to start a new line for a sub list, then the list syntax context will auto-suggest as follow, in the suggestion list, you can find nested list too.

(http://www.flickr.com/photos/44893839@N00/5561102166/)

Definition Lists: ;, :（Group 2）

Using “Tab” or “Alt+Tab” to enter prefix context, as follow:

(http://www.flickr.com/photos/44893839@N00/5561104356/)

Select “;” to enter definition list context,when user press “enter” key in order to type definition, an auto-suggestion result box shows up, you can find nested definition in the results.

(http://www.flickr.com/photos/44893839@N00/5560529567/)

Tables: |=, |（Group 2）

Under Tables syntax context, when user press “space” key or “enter” key in order to enter new table header or table cell, it will shows up the autosuggestion boxes:

Press “space” key trigger auto-suggestion: