Suggest Widget
The suggest widget is a user interface component designed to provide live suggestions as user types in a text field.
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 :
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 name | Description | Available since |
---|---|---|
suggestDocuments | Suggest document names as the user types. For example, you can see this example live in XWiki when editing the parent field of a document | XE 2.5 |
suggestUsers | Suggest users. This behavior is visible in XWiki when adding a user to a group | XE 2.6 |
suggestGroups | Suggest groups. This behavior is visible in XWiki when adding a group to a group | XE 2.6 |
suggestSpaces | Suggest spaces. This behavior is visible in XWiki when importing an office document | XE 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 :
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 :
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 :
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 :
Reference documentation
TBD.