Show last authors
1
2
3
4 1 AutoSuggest Widget
5
6 #startfloatingbox()
7 *Contents*
8 #toc ("2" "2" "")
9 #endfloatingbox()
10
11 #info("This is a Javascript widget bundled by default with the XWiki platform.")
12
13
14 1.1 Usage
15
16 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.
17
18 1.1.1 Suggest fields from a class defined in the wiki
19
20 Use information from a predefined class in your wiki (e.g. *XWiki.TagClass*, *XWiki.XWikiUsers*, etc.) or from a class defined by yourself.
21 For example, use *XWiki.TagClass* to suggest tags from the wiki tag cloud:
22
23 {image:suggest.png|document=DevGuide.AutoSuggestWidget}
24 {code}
25
26 $!xwiki.jsx.use("DevGuide.AutoSuggestWidgetExample")
27 <form method="post" action="#">
28 <label for="myinput">Type the name of a tag and test the suggest list:</label>
29 <input id="myinput" size="20" type="text" value=""/>
30 </form>
31
32 {code}
33
34 The *JavascriptExtension* object from the *DevGuide.AutoSuggestWidgetExample* page contains the Javascript code to enable the widget when focusing on the text field:
35
36 {code}
37 (function(){
38 document.observe('dom:loaded', function () {
39 if($('myinput')) {
40 Event.observe($('myinput'), "focus", function() {
41 new ajaxSuggest(this, {script: '$xwiki.getURL("${doc.space}.WebHome", "view")?xpage=suggest&classname=XWiki.TagClass&fieldname=tags&secCol=-&', varname: "input", seps: " ,|", offsety: 13});
42 });
43 }
44 }); // end of doc observe
45 })();
46 {code}
47
48 1.1.1.1 Options used in the *suggest.vm* template:
49
50 {table}
51 Option|Details
52 xpage|Must use *xpage=suggest* because suggest.vm template is used to manage the request.
53 classname|The name of the class for the elements of the suggest list.
54 fieldname|The field name from the class considered for the suggest list.
55 firCol|First column of the list of results.
56 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.
57 {table}
58
59 1.1.1.1 Example
60
61 * Check out the example for class field values at [Class Field Example>DevGuide.AutoSuggestWidgetExample]
62
63
64
65 1.1.1 Suggest custom information
66
67 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.
68 For example, you can build a list of suggestions that contains the wiki page names within a certain space:
69 {code}
70
71 $!xwiki.jsx.use("DevGuide.AjaxSuggestCustomExample")
72 <form method="post" action="#">
73 <label for="myinput">Type the name of an example page from the *DevGuide* space and test the suggest list:</label>
74 <input id="myinput" size="20" type="text" value=""/>
75 </form>
76
77 {code}
78
79 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.
80
81 {code}
82 (function(){
83 document.observe('dom:loaded', function () {
84 if($('myinput')) {
85 Event.observe($('myinput'), "focus", function() {
86 new ajaxSuggest(this, {script: "$xwiki.getURL("DevGuide.SuggestService", "view", "xpage=plain&spacename=DevGuide")&", varname: "input", seps: " ,|", offsety: 13});
87 });
88 }
89 }); // end of doc observe
90 })();
91 {code}
92 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.
93 {code}
94 ##
95 ## Service to generate the suggest list of files from a certain space.
96 ## @spacename
97 ## @input
98 ##
99 #set($input = $request.get("input").toLowerCase())
100 #set($spacename = $request.get("spacename"))
101 $response.setContentType("text/xml") ## generate a xml file
102 ## select pages
103 #if("$!input" == "")
104 #set($query = "select doc.name from XWikiDocument doc where doc.space='$spacename' and doc.name<>'WebHome' and doc.name<>'WebPreferences' order by doc.date desc")
105 #else
106 #set($query = "select doc.name from XWikiDocument doc where doc.space='$spacename' and doc.name<>'WebHome' and doc.name<>'WebPreferences' and lower(doc.name) like '%" + $input + "%' order by doc.date desc")
107 #end
108 #set($searchresults = $xwiki.search($query))
109 <results space="$spacename">
110 #foreach($result in $searchresults)
111 <rs id="1" info="">$result</rs>
112 #end
113 </results>
114 {code}
115
116 #warning("You need programming for the code above to work in your wiki because the search method is part of the privileged API.")
117
118
119 1.1.1.1 Example
120
121 * Check out the example for custom information at [Custom Information Example>DevGuide.AjaxSuggestCustomExample]
122
123 1.1 Javascript parameters for the *ajaxsuggest* class
124
125 {table}
126 Parameter|Details
127 minchars|The minimum number of characters after which to trigger the suggest. Default value is 1.
128 get|The HTTP method for the AJAX request.
129 varname| The name of the request parameter holding the input stub. Default value is *input*.
130 className| The CSS classname of the suggest list. Default value is *ajaxsuggest*.
131 timeout|Default value is *2500*.
132 delay|Default value is *500*.
133 offsety|Default value is *-5*.
134 shownoresults|Display a "no results" message, or simply hide the suggest box when no suggestions are available.
135 noresults|Default displayed message is *No results!*.
136 maxheight|Default value is *250*.
137 cache|Default value is *false*.
138 seps|Default value is "".
139 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.
140 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.
141 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.
142 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.
143 parentContainer|The id of the element that will hold the suggest element. Default value is *body*.
144 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.
145 {table}
146
147
148 1.1 Tips
149
150 * Check out the Javascript code for more details: *{pre}http://localhost:8080/xwiki/resources/js/xwiki/suggest/ajaxSuggest.js {/pre}*.

Get Connected