Suggest Widget

Last modified by Ecaterina Moraru (Valica) on 2018/09/12 15:08

This draft is a page redesign that aims to replace the page at http://platform.xwiki.org/xwiki/bin/view/DevGuide/AutoSuggestWidget when ready.

The suggest widget is a user interface component designed to provide live suggestions as user types in a text field.

This UI component is bundled in the XWiki Platform.

The screenshot below illustrates a usage of the suggest widget in XWiki, used to suggest existing tags as a user do add tags to a document :

tags.png

Usages

According to the use case, several usages are possible for the suggest widget. Commons use case are covered by behavioral CSS class names, and more sophisticated scenarios are achieved using custom scripts and possibly dedicated suggestions sources.

Behavioral CSS class names

XWiki provides several behavioral class names to provide suggestions for the most common use cases of suggestions. The table below summarizes these class names.

Class nameDescriptionAvailable since
suggestDocumentsSuggest document names as the user types. For example, you can see this example live in XWiki when editing the parent field of a documentXE 2.5
suggestUsersSuggest users. This behavior is visible in XWiki when adding a user to a groupXE 2.6
suggestGroupsSuggest groups. This behavior is visible in XWiki when adding a group to a groupXE 2.6
suggestSpacesSuggest spaces. This behavior is visible in XWiki when importing an office documentXE 2.6

Using such behavioral class names is a breeze. Just add the targeted class to your text input, and the magic will take care of the rest. For example, to suggest documents :

<input type="text" name="myinput" class="suggestDocuments withTip" value="Document Name" />

Note the withTip class here is another behavioral class name that clears the default value as the field is focused, and puts it back if the field is blurred with an empty value.

More information about XWiki's behavioral class names is available on the Special CSS Classes document

Custom suggestions from XWiki REST API

While they are handy, behavioral class names for suggestions cannot cover all use cases. One way to cover other use cases is taking advantage of XWiki's REST API. For example, we might want to provide page name suggestions restricted to a certain space. The REST API can help us doing this.

To provide suggestions on pages within a the Blog space using the REST API, you first need an <input> of text, and a way to identify it from JavaScript. An id attribute is a working approach for this :

<input type="text" name="blogPost" id="blogPostInput" class="withTip" value="Blog post name" />

From there, you need to hook a suggest widget with a custom REST source that targets the search API on the Blog space. For example you can place the following JavaScript snippet in an Skin extension :

document.observe("xwiki:dom:loaded", function(){
var myInput = $('blogPostInput');

// Create the suggest widget by instantiating XWiki.widgets.Suggest
var mySuggest = new XWiki.widgets.Suggest(myInput, {
   // script is the URL end-point that will provide suggestions. In our case it's a REST API URL.
   script: XWiki.Document.getRestSearchURL("scope=name&number=10&media=json&", "Blog"),
   // vaname is the name of the request variable on which to pass the text fragment passed by the user.
   varname: "q",
   // icon is an option to display an small icon with the passed URL, next to each suggestion
   icon: "$xwiki.getSkinFile('icons/silk/page_white_picture.gif')",
    noresults: "Blog post not found",
    json: true,
    resultsParameter : "searchResults",
    resultId : "id",
    resultValue : "pageFullName",
    resultInfo : "pageFullName"
  });
});

That's it. When a user will start typing in the text field, pages from the Blog space matching the text entered will be proposed :

suggestBlog.png

Reference documentation

TBD.

Tags:
   

Get Connected