ContentsThe [toc] macro is a standalone macro and it cannot be used inline. Click on this message for details.

This is a Javascript widget bundled by default with the XWiki platform.

Usage

The suggest widget can be triggered when typing something in a text field. The suggested list can contain field values from a class defined in your wiki or any custom information you provide.

Suggest fields from a class defined in the wiki

Use information from a predefined class in your wiki (e.g. XWiki.TagClass, XWiki.XWikiUsers, etc.) or from a class defined by yourself. For example, use XWiki.TagClass to suggest tags from the wiki tag cloud:

suggest.png


<form method="post" action="#">
 <label for="myinput">Type the name of a tag and test the suggest list:</label>
 <input id="myinput" size="20" type="text" value=""/>
</form>
The JavascriptExtension object from the DevGuide.AutoSuggestWidgetExample page contains the Javascript code to enable the widget when focusing on the text field:
(function(){
 document.observe('dom:loaded', function () {
   if($('myinput')) {
     Event.observe($('myinput'), "focus", function() {
       new XWiki.widgets.Suggest(this, {
             script: '/xwiki/bin/view/Documentation/DevGuide/FrontendResources/AutoSuggestWidget/?xpage=suggest&classname=XWiki.TagClass&fieldname=tags&secCol=-&',
            varname: "input",
            seps: " ,|",
            offsety: 13
        });
      });
    }
  }); // end of doc observe
})();

Options used in the suggest.vm template:

OptionDetails
xpageMust use xpage=suggest because suggest.vm template is used to manage the request.
classnameThe name of the class for the elements of the suggest list.
fieldnameThe field name from the class considered for the suggest list.
firColFirst column of the list of results.
secColSecond column of the list of results. For a user defined query, use - value for one column and no hidden input. Otherwise the list of results will have two columns and a hidden input.

Example

Suggest custom information

When the information you want to suggest is not available through a class field or you generate it using a custom query, you need to create a service (plain wiki page called with the get action and with outputSyntax=plain parameter in the url, eg: xwiki/bin/get/Space/Page?outputSyntax=plain) that maps your results to the xml input accepted by the autosuggest class. For example, you can build a list of suggestions that contains the wiki page names within a certain space:

customsuggest.png


<form method="post" action="#">
 <label for="myinput">Type the name of an example page from the *DevGuide* space and test the suggest list:</label>
 <input id="myinput_suggest" size="20" type="text" value=""/>
 <input id="myinput" type="hidden" />
 <input id="mybutton" type="button" value="Go" /><br/>
</form>
The JavascriptExtension object from the DevGuide.AjaxSuggestCustomExample page contains the Javascript code to enable the widget when focusing on the text field. Also, the script option uses the url for the results page.
(function(){
 document.observe('dom:loaded', function () {
   if($('myinput_suggest')) {
     Event.observe($('myinput_suggest'), "focus", function() {
       new XWiki.widgets.Suggest(this, {
             script: "/xwiki/bin/get/DevGuide/SuggestService?outputSyntax=plain&spacename=DevGuide&",
             varname: "input",
             seps: " ,|",
             offsety: 13,
             minchars: 3
        });
      });
    }
  }); // end of doc observe
})();
The service page uses a query to get all the pages from the space provided using spacename parameter in the url. The generated response must be a xml file that has as a root node and as children.
 <results space="$spacename">
 </results>
To provide autosuggest to several elements on the form, you can use JavaScript to loop through all the form elements and provide autosuggest if they meet certain conditions. In the example below, if there are form elements with id 'Supplier' in the 'inline' form, they get assigned an autosuggest that uses the Suppliers space as its source. If the element id matches 'Product' the autosuggest is told to use the 'Products' space as it's source instead.

This method can be very useful when a form contains a lot of similar elements that require autosuggest. If you make sure the naming is done consistently, you can also use javascript to assign autosuggest based on part of the element id, for example 'all elements ending with _foo' or 'all elements starting with Bar_'. You can use the velocity code from the example above with the code below.

(function(){
document.observe('dom:loaded', function () {
myForm = document.getElementById('inline').elements;
for(i=0; i<myForm.length; i++){
if(myForm[i].id =='Supplier'){
mySuggest(myForm[i], 'Suppliers');
}
if(myForm[i].id=='Product'){
mySuggest(myForm[i], 'Products');
}
}
}); // end of doc observe
})();

function mySuggest(element, space) {
if (!element.suggest) {
element.suggest =  new XWiki.widgets.Suggest(element, {
script: "/xwiki/bin/get/Sandbox/AutoSuggest"+ "?outputSyntax=plain&spacename="+space+"&",
varname: "input",
seps: " ,|",
offsety: 13,
minchars: 1
});
}
}

Example

Suggest Users or Groups from the wiki

Local or global users and groups from the wiki can be suggested using the uorgsuggest.vm template.

Example:

Here is the code that made the suggestion of global users from the wiki possible:

...
<input name="userInput" id="userInput" value="" type="text"/>
...
(function(){
 document.observe('dom:loaded', function () {
   if($('userInput')) {
     Event.observe($('userInput'), "focus", function() {
       new XWiki.widgets.Suggest(this, {
             script: '/xwiki/bin/view/Documentation/DevGuide/FrontendResources/AutoSuggestWidget/?xpage=uorgsuggest&classname=XWiki.XWikiUsers&wiki=global&uorg=user&',
            varname: "input",
            seps: " ,|",
            delay : 200,
            timeout: 5000,
            offsety: 13
        });
      });
    }
  }); // end of doc observe
})();

Javascript parameters for the ajaxsuggest class

ParameterDetails
mincharsThe minimum number of characters after which to trigger the suggest. Default value is 1.
getThe HTTP method for the AJAX request.
varnameThe name of the request parameter holding the input stub. Default value is input.
classNameThe CSS classname of the suggest list. Default value is ajaxsuggest.
timeoutDefault value is 2500.
delayDefault value is 500.
offsetyDefault value is -5.
shownoresultsDisplay a "no results" message, or simply hide the suggest box when no suggestions are available.
noresultsDefault displayed message is No results!.
maxheightDefault value is 250.
cacheDefault value is false.
sepsDefault value is "".
resultsParameterThe name of the JSON variable or XML element holding the results.Default value is results for the old suggest, searchResults for the REST search.
resultIdThe name of the JSON parameter or XML attribute holding the result identifier. DEfault value is id for both the old suggest and the REST search.
resultValueThe name of the JSON parameter or XML attribute holding the result value.Default value for the old suggest, pageFullName for the REST page search.
resultInfoThe name of the JSON parameter or XML attribute holding the result auxiliary information. Default value is info for the old suggest, pageFullName for the REST search.
parentContainerThe id of the element that will hold the suggest element. Default value is body.
scriptUrl for the ajax request that will get the suggested list. Must end with & because varname parameter will be appended. Use suggest.vm to get field values from a wiki class or a custom url to generate the suggested list.

Tips

  • Suggest event: xwiki:suggest:selected
Event.observe($('myInput'), "xwiki:suggest:selected", function(event) {
      // do something with event.memo.value or event.memo.id or event.memo.info ...
     });

Bugs we know about

   

Get Connected