Wiki source code of AutoSuggestWidget
Version 42.1 by Oana Florea on 2010/09/13
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | ## | ||
| 2 | ## TODO: | ||
| 3 | ## - Document the REST usage of the suggest (this is the recommanded way of using the suggest now - when possible) | ||
| 4 | ## - Merge the example document in this one (why are there 2 documents ?) | ||
| 5 | ## - Migrate this page to syntax 2.0 | ||
| 6 | ## | ||
| 7 | 1 AutoSuggest Widget | ||
| 8 | |||
| 9 | #startfloatingbox() | ||
| 10 | *Contents* | ||
| 11 | #toc ("2" "2" "") | ||
| 12 | #endfloatingbox() | ||
| 13 | |||
| 14 | #info("This is a Javascript widget bundled by default with the XWiki platform.") | ||
| 15 | |||
| 16 | |||
| 17 | 1.1 Usage | ||
| 18 | |||
| 19 | 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. | ||
| 20 | |||
| 21 | 1.1.1 Suggest fields from a class defined in the wiki | ||
| 22 | |||
| 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 | |||
| 26 | {image:suggest.png|document=DevGuide.AutoSuggestWidget} | ||
| 27 | {code} | ||
| 28 | |||
| 29 | $!xwiki.jsx.use("DevGuide.AutoSuggestWidgetExample") | ||
| 30 | <form method="post" action="#"> | ||
| 31 | <label for="myinput">Type the name of a tag and test the suggest list:</label> | ||
| 32 | <input id="myinput" size="20" type="text" value=""/> | ||
| 33 | </form> | ||
| 34 | |||
| 35 | {code} | ||
| 36 | |||
| 37 | The *JavascriptExtension* object from the *DevGuide.AutoSuggestWidgetExample* page contains the Javascript code to enable the widget when focusing on the text field: | ||
| 38 | |||
| 39 | {code} | ||
| 40 | (function(){ | ||
| 41 | document.observe('dom:loaded', function () { | ||
| 42 | if($('myinput')) { | ||
| 43 | Event.observe($('myinput'), "focus", function() { | ||
| 44 | new XWiki.widgets.Suggest(this, { | ||
| 45 | script: '$xwiki.getURL("${doc.space}.WebHome", "view")?xpage=suggest&classname=XWiki.TagClass&fieldname=tags&secCol=-&', | ||
| 46 | varname: "input", | ||
| 47 | seps: " ,|", | ||
| 48 | offsety: 13 | ||
| 49 | }); | ||
| 50 | }); | ||
| 51 | } | ||
| 52 | }); // end of doc observe | ||
| 53 | })(); | ||
| 54 | {code} | ||
| 55 | |||
| 56 | 1.1.1.1 Options used in the *suggest.vm* template: | ||
| 57 | |||
| 58 | {table} | ||
| 59 | Option|Details | ||
| 60 | xpage|Must use *xpage=suggest* because suggest.vm template is used to manage the request. | ||
| 61 | classname|The name of the class for the elements of the suggest list. | ||
| 62 | fieldname|The field name from the class considered for the suggest list. | ||
| 63 | firCol|First column of the list of results. | ||
| 64 | 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. | ||
| 65 | {table} | ||
| 66 | |||
| 67 | 1.1.1.1 Example | ||
| 68 | |||
| 69 | * Check out the example for class field values at [Class Field Example>DevGuide.AutoSuggestWidgetExample] | ||
| 70 | |||
| 71 | 1.1.1 Suggest custom information | ||
| 72 | |||
| 73 | 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. | ||
| 74 | For example, you can build a list of suggestions that contains the wiki page names within a certain space: | ||
| 75 | |||
| 76 | {image:customsuggest.png|document=DevGuide.AutoSuggestWidget} | ||
| 77 | |||
| 78 | {code} | ||
| 79 | |||
| 80 | $!xwiki.jsx.use("DevGuide.AjaxSuggestCustomExample") | ||
| 81 | <form method="post" action="#"> | ||
| 82 | <label for="myinput">Type the name of an example page from the *DevGuide* space and test the suggest list:</label> | ||
| 83 | <input id="myinput_suggest" size="20" type="text" value=""/> | ||
| 84 | <input id="myinput" type="hidden" /> | ||
| 85 | <input id="mybutton" type="button" value="Go" /><br/> | ||
| 86 | </form> | ||
| 87 | |||
| 88 | {code} | ||
| 89 | |||
| 90 | 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. | ||
| 91 | |||
| 92 | {code} | ||
| 93 | (function(){ | ||
| 94 | document.observe('dom:loaded', function () { | ||
| 95 | if($('myinput_suggest')) { | ||
| 96 | Event.observe($('myinput_suggest'), "focus", function() { | ||
| 97 | new XWiki.widgets.Suggest(this, { | ||
| 98 | script: "$xwiki.getURL("DevGuide.SuggestService", "view", "xpage=plain&spacename=DevGuide")&", | ||
| 99 | varname: "input", | ||
| 100 | seps: " ,|", | ||
| 101 | offsety: 13, | ||
| 102 | minchars: 3 | ||
| 103 | }); | ||
| 104 | }); | ||
| 105 | } | ||
| 106 | }); // end of doc observe | ||
| 107 | })(); | ||
| 108 | {code} | ||
| 109 | 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. | ||
| 110 | {code} | ||
| 111 | ## | ||
| 112 | ## Service to generate the suggest list of files from a certain space. | ||
| 113 | ## @spacename | ||
| 114 | ## @input | ||
| 115 | ## | ||
| 116 | #set($input = $request.get("input").toLowerCase()) | ||
| 117 | #set($spacename = $request.get("spacename")) | ||
| 118 | $response.setContentType("text/xml") ## generate a xml file | ||
| 119 | ## select pages | ||
| 120 | #if("$!input" == "") | ||
| 121 | #set($query = "where doc.space='$spacename' and doc.name<>'WebHome' and doc.name<>'WebPreferences' order by doc.date desc") | ||
| 122 | #else | ||
| 123 | #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") | ||
| 124 | #end | ||
| 125 | #set($searchresults = $xwiki.searchDocuments($query, 30, 0)) | ||
| 126 | <results space="$spacename"> | ||
| 127 | #foreach($result in $searchresults) | ||
| 128 | #set($resultDoc = $xwiki.getDocument($result)) | ||
| 129 | #set($resultDocName = $resultDoc.name) | ||
| 130 | #set($resultDocURL = $resultDoc.getURL()) | ||
| 131 | <rs id="1" info="$resultDocURL">$resultDocName</rs> | ||
| 132 | #end | ||
| 133 | </results> | ||
| 134 | {code} | ||
| 135 | |||
| 136 | |||
| 137 | 1.1.1.1 Example | ||
| 138 | |||
| 139 | * Check out the example for custom information at [Custom Information Example>DevGuide.AjaxSuggestCustomExample] | ||
| 140 | |||
| 141 | 1.1.1 Suggest Users or Groups from the wiki | ||
| 142 | |||
| 143 | Local or global users and groups from the wiki can be suggested using the *uorgsuggest.vm* template. | ||
| 144 | |||
| 145 | Example: | ||
| 146 | |||
| 147 | $xwiki.jsx.use("$doc.fullName")## | ||
| 148 | |||
| 149 | <input name="userInput" id="userInput" value="" type="text"/> | ||
| 150 | |||
| 151 | Here is the code that made this happen: | ||
| 152 | |||
| 153 | {code} | ||
| 154 | ... | ||
| 155 | <input name="userInput" id="userInput" value="" type="text"/> | ||
| 156 | ... | ||
| 157 | {code} | ||
| 158 | |||
| 159 | {code} | ||
| 160 | (function(){ | ||
| 161 | document.observe('dom:loaded', function () { | ||
| 162 | if($('userInput')) { | ||
| 163 | Event.observe($('userInput'), "focus", function() { | ||
| 164 | new XWiki.widgets.Suggest(this, { | ||
| 165 | script: '$xwiki.getURL("${doc.fullName}", "view")?xpage=uorgsuggest&classname=XWiki.XWikiUsers&wiki=local&uorg=user&', | ||
| 166 | varname: "input", | ||
| 167 | seps: " ,|", | ||
| 168 | delay : 200, | ||
| 169 | timeout: 5000, | ||
| 170 | offsety: 13 | ||
| 171 | }); | ||
| 172 | }); | ||
| 173 | } | ||
| 174 | }); // end of doc observe | ||
| 175 | })(); | ||
| 176 | {code} | ||
| 177 | |||
| 178 | 1.1 Javascript parameters for the *ajaxsuggest* class | ||
| 179 | |||
| 180 | {table} | ||
| 181 | Parameter|Details | ||
| 182 | minchars|The minimum number of characters after which to trigger the suggest. Default value is 1. | ||
| 183 | get|The HTTP method for the AJAX request. | ||
| 184 | varname| The name of the request parameter holding the input stub. Default value is *input*. | ||
| 185 | className| The CSS classname of the suggest list. Default value is *ajaxsuggest*. | ||
| 186 | timeout|Default value is *2500*. | ||
| 187 | delay|Default value is *500*. | ||
| 188 | offsety|Default value is *-5*. | ||
| 189 | shownoresults|Display a "no results" message, or simply hide the suggest box when no suggestions are available. | ||
| 190 | noresults|Default displayed message is *No results!*. | ||
| 191 | maxheight|Default value is *250*. | ||
| 192 | cache|Default value is *false*. | ||
| 193 | seps|Default value is "". | ||
| 194 | 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. | ||
| 195 | 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. | ||
| 196 | 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. | ||
| 197 | 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. | ||
| 198 | parentContainer|The id of the element that will hold the suggest element. Default value is *body*. | ||
| 199 | 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. | ||
| 200 | {table} | ||
| 201 | |||
| 202 | |||
| 203 | 1.1 Tips | ||
| 204 | |||
| 205 | * Check out the code: | ||
| 206 | ** for your wiki instance: *{pre}http://localhost:8080/xwiki/resources/js/xwiki/suggest/ajaxSuggest.js {/pre}*. | ||
| 207 | ** 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/] | ||
| 208 | 1.1 Bugs we know about | ||
| 209 | |||
| 210 | * 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]. |
