Hide last authors
author | version | line-number | content |
---|---|---|---|
1.1 | 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 | |||
14.1 | 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 | |||
7.1 | 23 | {image:suggest.png|document=DevGuide.AutoSuggestWidget} | |
1.1 | 24 | {code} | |
25 | |||
7.1 | 26 | $!xwiki.jsx.use("DevGuide.AutoSuggestWidgetExample") | |
1.1 | 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 | |||
7.1 | 34 | The *JavascriptExtension* object from the *DevGuide.AutoSuggestWidgetExample* page contains the Javascript code to enable the widget when focusing on the text field: | |
1.1 | 35 | ||
36 | {code} | ||
37 | (function(){ | ||
38 | document.observe('dom:loaded', function () { | ||
39 | if($('myinput')) { | ||
40 | Event.observe($('myinput'), "focus", function() { | ||
12.1 | 41 | new ajaxSuggest(this, {script: '$xwiki.getURL("${doc.space}.WebHome", "view")?xpage=suggest&classname=XWiki.TagClass&fieldname=tags&secCol=-&', varname: "input", seps: " ,|", offsety: 13}); | |
1.1 | 42 | }); | |
43 | } | ||
44 | }); // end of doc observe | ||
45 | })(); | ||
46 | {code} | ||
47 | |||
14.1 | 48 | 1.1.1 Suggest custom information | |
1.1 | 49 | ||
14.1 | 50 | 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. | |
51 | For example, you can build a list of suggestions that contains the wiki page names within a certain space: | ||
52 | {code} | ||
53 | |||
15.1 | 54 | $!xwiki.jsx.use("DevGuide.AjaxSuggestCustomExample") | |
14.1 | 55 | <form method="post" action="#"> | |
56 | <label for="myinput">Type the name of an example page from the **DevGuide** space and test the suggest list:</label> | ||
57 | <input id="myinput" size="20" type="text" value=""/> | ||
58 | </form> | ||
59 | |||
60 | {code} | ||
61 | |||
62 | 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. | ||
63 | |||
64 | {code} | ||
65 | (function(){ | ||
66 | document.observe('dom:loaded', function () { | ||
67 | if($('myinput')) { | ||
68 | Event.observe($('myinput'), "focus", function() { | ||
69 | new ajaxSuggest(this, {script: "$xwiki.getURL("DevGuide.SuggestService", "view", "xpage=plain&spacename=Tutorials")&", varname: "input", seps: " ,|", offsety: 13}); | ||
70 | }); | ||
71 | } | ||
72 | }); // end of doc observe | ||
73 | })(); | ||
74 | {code} | ||
75 | 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. | ||
76 | {code} | ||
77 | ## | ||
78 | ## Service to generate the suggest list of files from a certain space. | ||
79 | ## @spacename | ||
80 | ## @input | ||
81 | ## | ||
82 | #set($input = $request.get("input").toLowerCase()) | ||
83 | #set($spacename = $request.get("spacename")) | ||
84 | $response.setContentType("text/xml") ## generate a xml file | ||
85 | ## select pages | ||
86 | #if("$!input" == "") | ||
87 | #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") | ||
88 | #else | ||
89 | #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") | ||
90 | #end | ||
91 | #set($searchresults = $xwiki.search($query)) | ||
92 | <results space="$spacename"> | ||
93 | #foreach($result in $searchresults) | ||
94 | <rs id="1" info="">$result</rs> | ||
95 | #end | ||
96 | </results> | ||
97 | {code} | ||
1.1 | 98 | 1.1 Javascript parameters for the *ajaxsuggest* class | |
99 | |||
100 | {table} | ||
101 | Parameter|Details | ||
102 | minchars|The minimum number of characters after which to trigger the suggest. Default value is 1. | ||
103 | get|The HTTP method for the AJAX request. | ||
104 | varname| The name of the request parameter holding the input stub. Default value is *input*. | ||
105 | className| The CSS classname of the suggest list. Default value is *ajaxsuggest*. | ||
106 | timeout|Default value is *2500*. | ||
107 | delay|Default value is *500*. | ||
108 | offsety|Default value is *-5*. | ||
109 | shownoresults|Display a "no results" message, or simply hide the suggest box when no suggestions are available. | ||
110 | noresults|Default displayed message is *No results!*. | ||
111 | maxheight|Default value is *250*. | ||
112 | cache|Default value is *false*. | ||
113 | seps|Default value is "". | ||
114 | 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. | ||
115 | 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. | ||
116 | 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. | ||
117 | 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. | ||
118 | parentContainer|The id of the element that will hold the suggest element. Default value is *body*. | ||
14.1 | 119 | 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. | |
1.1 | 120 | {table} | |
121 | |||
122 | 1.1.1 Options for the *script* parameter: | ||
123 | |||
124 | {table} | ||
125 | Option|Details | ||
126 | xpage|Must use *xpage=suggest* because suggest.vm template is used to manage the request. | ||
127 | classname|The name of the class for the elements of the suggest list. | ||
128 | fieldname|The field name from the class considered for the suggest list. | ||
9.1 | 129 | firCol|First column of the list of results. | |
11.1 | 130 | 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. | |
1.1 | 131 | {table} | |
132 | |||
133 | |||
3.1 | 134 | 1.1 Live Example | |
1.1 | 135 | ||
3.1 | 136 | * Check out the example above at [Ajax Suggest Example>DevGuide.AutoSuggestWidgetExample] | |
1.1 | 137 | ||
138 | 1.1 Tips | ||
139 | |||
140 | * Check out the Javascript code for more details: *{pre}http://localhost:8080/xwiki/resources/js/xwiki/suggest/ajaxSuggest.js {/pre}*. |