AutoSuggestWidget (XWiki.org)

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.

14

15

1.1.1 Suggest fields from a class defined in the wiki

16

17

Use information from a predefined class in your wiki (e.g. *XWiki.TagClass*, *XWiki.XWikiUsers*, etc.) or from a class defined by yourself.

18

For example, use *XWiki.TagClass* to suggest tags from the wiki tag cloud:

19

20

{image:suggest.png|document=DevGuide.AutoSuggestWidget}

21

{code}

22

23

$!xwiki.jsx.use("DevGuide.AutoSuggestWidgetExample")

24

25

<label for="myinput">Type the name of a tag and test the suggest list:</label>

</form>

{code}

The *JavascriptExtension* object from the *DevGuide.AutoSuggestWidgetExample* page contains the Javascript code to enable the widget when focusing on the text field:

{code}

(function(){

document.observe('dom:loaded', function () {

36

if($('myinput')) {

37

Event.observe($('myinput'), "focus", function() {

38

new ajaxSuggest(this, {script: '$xwiki.getURL("${doc.space}.WebHome", "view")?xpage=suggest&classname=XWiki.TagClass&fieldname=tags&secCol=-&', varname: "input", seps: " ,|", offsety: 13});

39

});

40

}

41

}); // end of doc observe

})();

{code}

1.1.1.1 Options used in the *suggest.vm* template:

{table}

Option|Details

xpage|Must use *xpage=suggest* because suggest.vm template is used to manage the request.

50

classname|The name of the class for the elements of the suggest list.

51

fieldname|The field name from the class considered for the suggest list.

52

firCol|First column of the list of results.

53

secCol|Second 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.

{table}

1.1.1.1 Example

* Check out the example for class field values at [Class Field Example>DevGuide.AutoSuggestWidgetExample]

1.1.1 Suggest custom information

63

64

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 *xpage=plain* parameter in the url) that maps your results to the *xml* input accepted by the *autosuggest* class.

65

For example, you can build a list of suggestions that contains the wiki page names within a certain space:

66

67

{image:customsuggest.png|document=DevGuide.AutoSuggestWidget}

{code}

$!xwiki.jsx.use("DevGuide.AjaxSuggestCustomExample")

72

73

<label for="myinput">Type the name of an example page from the *DevGuide* space and test the suggest list:</label>

</form>

{code}

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.

{code}

(function(){

document.observe('dom:loaded', function () {

86

if($('myinput_suggest')) {

87

Event.observe($('myinput_suggest'), "focus", function() {

88

new ajaxSuggest(this, {

89

script: "$xwiki.getURL("DevGuide.SuggestService", "view", "xpage=plain&spacename=DevGuide")&",

varname: "input",

seps: " ,|",

offsety: 13,

minchars: 3

});

});

}

if($('mybutton')) {

Event.observe($('mybutton'), "click", function() {

99

location.href = $('myinput').value;

100

});

101

}

102

}); // end of doc observe

103

})();

104

{code}

105

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 *<results>* as a root node and *<rs>* as children.

106

{code}

107

##

108

## Service to generate the suggest list of files from a certain space.

## @spacename

## @input

##

#set($input = $request.get("input").toLowerCase())

113

#set($spacename = $request.get("spacename"))

114

$response.setContentType("text/xml") ## generate a xml file

115

## select pages

116

#if("$!input" == "")

117

#set($query = "where doc.space='$spacename' and doc.name<>'WebHome' and doc.name<>'WebPreferences' order by doc.date desc")

118

#else

119

#set($query = "where doc.space='$spacename' and doc.name<>'WebHome' and doc.name<>'WebPreferences' and lower(doc.name) like '%" + $input + "%' order by doc.date desc")

120

#end

121

#set($searchresults = $xwiki.searchDocuments($query, 30, 0))

122

123

#foreach($result in $searchresults)

124

#set($resultDoc = $xwiki.getDocument($result))

125

#set($resultDocName = $resultDoc.name)

126

#set($resultDocURL = $resultDoc.getURL())

127

<rs id="1" info="$resultDocURL">$resultDocName</rs>

#end

</results>

{code}

1.1.1.1 Example

* Check out the example for custom information at [Custom Information Example>DevGuide.AjaxSuggestCustomExample]

136

137

1.1 Javascript parameters for the *ajaxsuggest* class

{table}

Parameter|Details

minchars|The minimum number of characters after which to trigger the suggest. Default value is 1.

142

get|The HTTP method for the AJAX request.

143

varname| The name of the request parameter holding the input stub. Default value is *input*.

144

className| The CSS classname of the suggest list. Default value is *ajaxsuggest*.

145

timeout|Default value is *2500*.

146

delay|Default value is *500*.

147

offsety|Default value is *-5*.

148

shownoresults|Display a "no results" message, or simply hide the suggest box when no suggestions are available.

149

noresults|Default displayed message is *No results!*.

150

maxheight|Default value is *250*.

151

cache|Default value is *false*.

152

seps|Default value is "".

153

resultsParameter|The name of the JSON variable or XML element holding the results.Default value is *results* for the old suggest, *searchResults* for the REST search.

154

resultId|The 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.

155

resultValue|The name of the JSON parameter or XML attribute holding the result value.Default *value* for the old suggest, *pageFullName* for the REST page search.

156

resultInfo|The 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.

157

parentContainer|The id of the element that will hold the suggest element. Default value is *body*.

158

script|Url 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.

{table}

1.1 Tips

* Check out the Javascript code for more details: *{pre}http://localhost:8080/xwiki/resources/js/xwiki/suggest/ajaxSuggest.js {/pre}*.