From version < 47.1 >
edited by Guillaume Delhumeau
on 2011/12/14
To version < 48.1 >
edited by Sergiu Dumitriu
on 2012/08/06
< >
Change comment: Document converted from syntax xwiki/1.0 to syntax xwiki/2.1

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.gdelhumeau
1 +XWiki.Sergiu
Syntax
... ... @@ -1,1 +1,1 @@
1 -XWiki 1.0
1 +XWiki 2.1
Content
... ... @@ -1,3 +1,5 @@
1 +{{velocity filter="none"}}
2 +{{html clean="false" wiki="true"}}
1 1  ##
2 2  ## TODO:
3 3  ## - Document the REST usage of the suggest (this is the recommanded way of using the suggest now - when possible)
... ... @@ -5,36 +5,35 @@
5 5  ## - Migrate this page to syntax 2.0
6 6  ##
7 7  #startfloatingbox()
8 -*Contents*
9 -#toc ("2" "2" "")
10 +**Contents**
11 +
12 +{{toc start="2" depth="2" numbered=""/}}
10 10  #endfloatingbox()
14 +<p/>
15 +{{info}}This is a Javascript widget bundled by default with the XWiki platform.{{/info}}
11 11  
12 -#info("This is a Javascript widget bundled by default with the XWiki platform.")
17 +== Usage ==
13 13  
14 -
15 -1.1 Usage
16 -
17 17  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.
18 18  
19 -1.1.1 Suggest fields from a class defined in the wiki
21 +=== Suggest fields from a class defined in the wiki ===
20 20  
21 -Use information from a predefined class in your wiki (e.g. *XWiki.TagClass*, *XWiki.XWikiUsers*, etc.) or from a class defined by yourself.
22 -For example, use *XWiki.TagClass* to suggest tags from the wiki tag cloud:
23 +Use information from a predefined class in your wiki (e.g. **XWiki.TagClass**, **XWiki.XWikiUsers**, etc.) or from a class defined by yourself.
24 +For example, use **XWiki.TagClass** to suggest tags from the wiki tag cloud:
25 +<p/>
26 +[[image:[email protected]]]
23 23  
24 -{image:suggest.png|document=DevGuide.AutoSuggestWidget}
25 -{code}
26 -
28 +{{code}}
27 27  $!xwiki.jsx.use("DevGuide.AutoSuggestWidgetExample")
28 28  <form method="post" action="#">
29 29   <label for="myinput">Type the name of a tag and test the suggest list:</label>
30 30   <input id="myinput" size="20" type="text" value=""/>
31 31  </form>
34 +{{/code}}
32 32  
33 -{code}
36 +The **JavascriptExtension** object from the **DevGuide.AutoSuggestWidgetExample** page contains the Javascript code to enable the widget when focusing on the text field:
34 34  
35 -The *JavascriptExtension* object from the *DevGuide.AutoSuggestWidgetExample* page contains the Javascript code to enable the widget when focusing on the text field:
36 -
37 -{code}
38 +{{code}}
38 38  (function(){
39 39   document.observe('dom:loaded', function () {
40 40   if($('myinput')) {
... ... @@ -49,32 +49,29 @@
49 49   }
50 50   }); // end of doc observe
51 51  })();
52 -{code}
53 +{{/code}}
53 53  
54 -1.1.1.1 Options used in the *suggest.vm* template:
55 +==== Options used in the **suggest.vm** template: ====
55 55  
56 -{table}
57 -Option|Details
58 -xpage|Must use *xpage=suggest* because suggest.vm template is used to manage the request.
59 -classname|The name of the class for the elements of the suggest list.
60 -fieldname|The field name from the class considered for the suggest list.
61 -firCol|First column of the list of results.
62 -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.
63 -{table}
57 +|=Option|=Details
58 +|xpage|Must use **xpage=suggest** because suggest.vm template is used to manage the request.
59 +|classname|The name of the class for the elements of the suggest list.
60 +|fieldname|The field name from the class considered for the suggest list.
61 +|firCol|First column of the list of results.
62 +|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.
64 64  
65 -1.1.1.1 Example
64 +==== Example ====
66 66  
67 -* Check out the example for class field values at [Class Field Example>DevGuide.AutoSuggestWidgetExample]
66 +* Check out the example for class field values at [[Class Field Example>>DevGuide.AutoSuggestWidgetExample]]
68 68  
69 -1.1.1 Suggest custom information
68 +=== Suggest custom information ===
70 70  
71 -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.
70 +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.
72 72  For example, you can build a list of suggestions that contains the wiki page names within a certain space:
72 +<p/>
73 +[[image:[email protected]]]
73 73  
74 -{image:customsuggest.png|document=DevGuide.AutoSuggestWidget}
75 -
76 -{code}
77 -
75 +{{code}}
78 78  $!xwiki.jsx.use("DevGuide.AjaxSuggestCustomExample")
79 79  <form method="post" action="#">
80 80   <label for="myinput">Type the name of an example page from the *DevGuide* space and test the suggest list:</label>
... ... @@ -82,12 +82,11 @@
82 82   <input id="myinput" type="hidden" />
83 83   <input id="mybutton" type="button" value="Go" /><br/>
84 84  </form>
83 +{{/code}}
85 85  
86 -{code}
85 +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.
87 87  
88 -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.
89 -
90 -{code}
87 +{{code}}
91 91  (function(){
92 92   document.observe('dom:loaded', function () {
93 93   if($('myinput_suggest')) {
... ... @@ -103,9 +103,11 @@
103 103   }
104 104   }); // end of doc observe
105 105  })();
106 -{code}
107 -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.
108 -{code}
103 +{{/code}}
104 +
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 +
107 +{{code}}
109 109  ##
110 110  ## Service to generate the suggest list of files from a certain space.
111 111  ## @spacename
... ... @@ -129,13 +129,13 @@
129 129   <rs id="1" info="$resultDocURL">$resultDocName</rs>
130 130   #end
131 131  </results>
132 -{code}
131 +{{/code}}
133 133  
134 134  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.
135 -
134 +<p/>
136 136  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.
137 137  
138 -{code}
137 +{{code}}
139 139  (function(){
140 140   document.observe('dom:loaded', function () {
141 141   myForm = document.getElementById('inline').elements;
... ... @@ -161,31 +161,31 @@
161 161   });
162 162   }
163 163  }
164 -{code}
163 +{{/code}}
165 165  
166 -1.1.1.1 Example
165 +==== Example ====
167 167  
168 -* Check out the example for custom information at [Custom Information Example>DevGuide.AjaxSuggestCustomExample]
167 +* Check out the example for custom information at [[Custom Information Example>>DevGuide.AjaxSuggestCustomExample]]
169 169  
170 -1.1.1 Suggest Users or Groups from the wiki
169 +=== Suggest Users or Groups from the wiki ===
171 171  
172 -Local or global users and groups from the wiki can be suggested using the *uorgsuggest.vm* template.
173 -
171 +Local or global users and groups from the wiki can be suggested using the **uorgsuggest.vm** template.
172 +<p/>
174 174  Example:
175 -
174 +<p/>
176 176  $xwiki.jsx.use("$doc.fullName")##
177 177  
178 178  <input name="userInput" id="userInput" value="" type="text"/>
179 -
178 +<p/>
180 180  Here is the code that made the suggestion of global users from the wiki possible:
181 181  
182 -{code}
181 +{{code}}
183 183  ...
184 184  <input name="userInput" id="userInput" value="" type="text"/>
185 185  ...
186 -{code}
185 +{{/code}}
187 187  
188 -{code}
187 +{{code}}
189 189  (function(){
190 190   document.observe('dom:loaded', function () {
191 191   if($('userInput')) {
... ... @@ -202,44 +202,48 @@
202 202   }
203 203   }); // end of doc observe
204 204  })();
205 -{code}
204 +{{/code}}
206 206  
207 -1.1 Javascript parameters for the *ajaxsuggest* class
206 +== Javascript parameters for the **ajaxsuggest** class ==
208 208  
209 -{table}
210 -Parameter|Details
211 -minchars|The minimum number of characters after which to trigger the suggest. Default value is 1.
212 -get|The HTTP method for the AJAX request.
213 -varname| The name of the request parameter holding the input stub. Default value is *input*.
214 -className| The CSS classname of the suggest list. Default value is *ajaxsuggest*.
215 -timeout|Default value is *2500*.
216 -delay|Default value is *500*.
217 -offsety|Default value is *-5*.
218 -shownoresults|Display a "no results" message, or simply hide the suggest box when no suggestions are available.
219 -noresults|Default displayed message is *No results!*.
220 -maxheight|Default value is *250*.
221 -cache|Default value is *false*.
222 -seps|Default value is "".
223 -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.
224 -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.
225 -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.
226 -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.
227 -parentContainer|The id of the element that will hold the suggest element. Default value is *body*.
228 -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.
229 -{table}
208 +|=Parameter|=Details
209 +|minchars|The minimum number of characters after which to trigger the suggest. Default value is 1.
210 +|get|The HTTP method for the AJAX request.
211 +|varname|The name of the request parameter holding the input stub. Default value is **input**.
212 +|className|The CSS classname of the suggest list. Default value is **ajaxsuggest**.
213 +|timeout|Default value is **2500**.
214 +|delay|Default value is **500**.
215 +|offsety|Default value is **-5**.
216 +|shownoresults|Display a "no results" message, or simply hide the suggest box when no suggestions are available.
217 +|noresults|Default displayed message is **No results!**.
218 +|maxheight|Default value is **250**.
219 +|cache|Default value is **false**.
220 +|seps|Default value is "".
221 +|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.
222 +|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.
223 +|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.
224 +|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.
225 +|parentContainer|The id of the element that will hold the suggest element. Default value is **body**.
226 +|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.
230 230  
228 +== Tips ==
231 231  
232 -1.1 Tips
230 +* Suggest event: **xwiki:suggest:selected**
233 233  
234 -* Suggest event: *xwiki:suggest:selected*
235 -{code}
236 - Event.observe($('myInput'), "xwiki:suggest:selected", function(event) {
232 +{{code}}
233 +Event.observe($('myInput'), "xwiki:suggest:selected", function(event) {
237 237   // do something with event.memo.value or event.memo.id or event.memo.info ...
238 238   });
239 -{code}
236 +{{/code}}
237 +
240 240  * Check out the code:
241 -** for your wiki instance: *{pre}http://localhost:8080/xwiki/resources/js/xwiki/suggest/ajaxSuggest.js {/pre}*.
242 -** the suggest resources on svn(for exemple tag xwiki-web-2.2): [http://svn.xwiki.org/svnroot/xwiki/platform/web/tags/xwiki-web-2.2/standard/src/main/webapp/resources/js/xwiki/suggest/]
243 -1.1 Bugs we know about
239 +** for your wiki instance: **{{{http://localhost:8080/xwiki/resources/js/xwiki/suggest/ajaxSuggest.js}}}**.
240 +** the suggest resources on svn(for exemple tag xwiki-web-2.2): [[http://svn.xwiki.org/svnroot/xwiki/platform/web/tags/xwiki-web-2.2/standard/src/main/webapp/resources/js/xwiki/suggest/]]
244 244  
245 -* The suggest feature will not work if the page called by the widget is not saved with programming rights: see details on [http://jira.xwiki.org/jira/browse/XE-539].
242 +== Bugs we know about ==
243 +
244 +* The suggest feature will not work if the page called by the widget is not saved with programming rights: see details on [[http://jira.xwiki.org/jira/browse/XE-539]].
245 +<p/>
246 +
247 +{{/html}}
248 +{{/velocity}}
XWiki.JavaScriptExtension[0]
Code
... ... @@ -1,16 +1,1 @@
1 -(function(){
2 - document.observe('dom:loaded', function () {
3 - if($('userInput')) {
4 - Event.observe($('userInput'), "focus", function() {
5 - new XWiki.widgets.Suggest(this, {
6 - script: '$xwiki.getURL("${doc.fullName}", "view")?xpage=uorgsuggest&classname=XWiki.XWikiUsers&wiki=global&uorg=user&',
7 - varname: "input",
8 - seps: " ,|",
9 - delay : 200,
10 - timeout: 5000,
11 - offsety: 13
12 - });
13 - });
14 - }
15 - }); // end of doc observe
16 -})();
1 +(function(){ document.observe('dom:loaded', function () { if($('userInput')) { Event.observe($('userInput'), "focus", function() { new XWiki.widgets.Suggest(this, { script: '{{velocity filter="none"}}{{html clean="false" wiki="true"}}$xwiki.getURL("${doc.fullName}", "view"){{/html}}{{/velocity}}?xpage=uorgsuggest&classname=XWiki.XWikiUsers&wiki=global&uorg=user&', varname: "input", seps: " ,|", delay : 200, timeout: 5000, offsety: 13 }); }); } }); ~/~/ end of doc observe })();

Get Connected