 | Redirection Notice This page should redirect to http://www.adaptavist.com/display/Plugins/Advanced+Search. |
| Confluence v2.2.x concatonates query terms using OR, where as Confluence v2.3.x and beyond uses AND. The effect for you is that if you have multiple label/metadata fields, they will be ANDed together now and not ORed. So where before if you had 3 labels passed over, it would return things matching any – now it only returns things matching them all. |
Description
This plugin provides a set of macros utilising DWR (AJAX) searching capabilities. These macros center around providing a form-based interface for building search queries, the output is dynamically sortable and can be customised.
The data from the fields form generate a search query which is then processed by lucene via the Confluence API, with all the terms (each field) being AND'ed together (so all terms must match, not any). There is no paging on the results, and the results can show the rating of each blog / page - however showing the rating column will slow down the showing of the results somewhat. The rating is based on the rate macro.
You can find a full list of search fields on Atlassian's website.
Automatic running queries is also possible so that the search form submits the default values and returns the results automatically. The search form can also be hidden, if desired.
Usage
Only a single {search-form} and {search-results} can be used on a page in any order. Both must be present to operate properly.
{search-form}
This defines the seach criteria part of the page, which can optionally be hidden. It has a body that encapsulates the {search-input}, {search-select} and {search-submit} macros which define any number of search criteria or filters.
| Parameter | Description | Type | Default | Required |
|---|---|---|---|---|
| autoSubmit | Submit the form as soon as the page loads (providing default results) | boolean | false |  |
| hidden | Hide the form from view (only useful with autoSubmit) | boolean | false | |
So, let's take a look at the macros that go in the body of the search-form (an example is shown lower down this page)...
{search-input}
This provides an input field synonymous to a HTML input field and has no body.
| Parameter | Description | Value | Default | Required |
|---|---|---|---|---|
| match | Type of Search Field | string (label, metadata, query) | none |  |
| metadataKey | Metadata Key - only valid for match=metadata | string | none | unless match=metadata, then |
| type | Type of Field | string (text / checkbox / hidden) | none | |
| value | Value of the Field | string | none | |
| checked | Inital State - only valid for type=checkbox | boolean | false | |
As you can see, you can create hidden fields - this is really useful if there is a filter you always want to apply to the search form but don't want users to see.
{search-select}
This provides an select field (drop-down list) synonymous to a HTML select field, with options defined in it's body by the {search-option} macro.
| Parameter | Description | Value | Default | Required |
|---|---|---|---|---|
| match | Type of Search Field | string (label, metadata, query) | none | |
| metadataKey | Metadata Key - only valid for match=metadata | string | none | unless match=metadata, then |
| nullLabel | Label of the "unanswered" option | string | no "unanswered" option | |
{search-option}
This provides an option field synonymous to a HTML option field, its body is wiki rendered and is the outputted label for the option.
| Parameter | Description | Value | Default | Required |
|---|---|---|---|---|
| value | Value of the Field | string | empty | |
| selected | Is this Option Selected | boolean | false | |
{search-submit}
You MUST include a search-submit within the search-form if you wish your users to be able to manually submit the search. If you hide the search form and set it to auto submit, then this is not needed.
This provides a submit button. You need one of these for the form to work!
| Parameter | Description | Value | Default | Required |
|---|---|---|---|---|
| default | Label for the Button | string | Submit | |
{search-results}
This provides the target for search results to goto, it also configures how the search results are displayed.
- Types - There are 4 content types you can search for currently. You specify them as a comma separated list and any of the specified content types are included in the results. The 4 content types are: page, blogpost, userinfo and spacedesc.
- Fields - There are 6 fields, and can be displayed in any order - however title must always be display. They can also be renamed:
rating,title!My Title,author
That would put the fields in that order, renaming the title field to "My Title".
- Excerpts - If shown, the contents of the {excerpt} macro are used first and then it falls back on the the content excerpt used in the standard search results.
- Ratings - If the rate macro is use (or has been in the past) and the page has ratings, then an average is found. If the rateThreashold (defaulting at 5) isn't met (i.e. if there haven't been 5 people rating this content) then it uses 0. If there isn't any rate data then it defaults to 0 as well. NOTE: If the content has been rated in the past, and the rate macro is then removed - the rating data will sill remain and will still be used by this plugin. This can be worked around by detecting the presence of a {rate} macro first in the content - however this work around isnt in effect yet. Please let me know if this is needed.
| Parameter | Description | Value | Default | Required |
|---|---|---|---|---|
| fields | The selection, order and naming of the fields | string | title!Resource,rating,creation,modified,author,space!Partner | |
| types | The content types to search for | string | page,blogpost | |
| showExcerpts | Should I show excerpts? | boolean | true | |
| sortField | The fields to sort on initially. | string (a field from fields) | title | |
| sortDir | The direction to sort on initially. | string (asc / desc) | asc | |
| maxResults | How many results should I truncate to? (users will be warned in the case of more results than shown) | int | 20 | |
| rateThreshold | How many ratings are needed before the average is used? | int | 5 | |
| debug | Should I show the query I generated for debugging? | boolean | false | |
Tutorial
To begin with you are going to want to have a basic search form:
{search-form}
{search-input:type=text|match=query}
{search-submit:Search}
{search-form}
{search-results}
This about as basic as it gets, pretty much emulating what the normal Confluence search does - except limiting results to pages and blog posts. From here we can built up the search so that it is tailored to our needs. I now have the following criteria:
- I want to set the default value of the query to repository plugin, as if that was typed into the search engine.
- I want to only return content that has the searchable label - but this shouldn't be displayed as an option.
- I want the search to be run automatically with the defaults above.
{search-form:autoSubmit=true}
{search-input:type=text|match=query|value=repository plugin}
{search-input:type=hidden|match=label|value=searchable}
{search-submit:Search}
{search-form}
{search-results}
Great! I would like to customise the results though, so that it shows the rating, author, title, then space. I want to sort by rating descendingly. I also want the title column to be called Content Title instead.
{search-results:fields=rating,author,title!Content Title,space|sortField=rating|sortDir=desc}
Advanced Example
The following provides a general search term box, with checkboxes for searching for different preset keywords as well as an advanced one for searching for one label but not another.
Comments (41)
Nov 03, 2008
Noel Estabrook says:
Using Theme Builder in Confluence 2.9, this plugin doesn't work, as there appear...Using Theme Builder in Confluence 2.9, this plugin doesn't work, as there appears to be an error with the WikiStyleRenderer. Any ideas on how to fix this issue?
Feb 02, 2009
Keith Brophy says:
Hi Noel, Can you retest with the latest released version (1.0.5)? This version ...Hi Noel,
Can you retest with the latest released version (1.0.5)? This version should address issues with Confluence 2.9 compatibility.
Please let us know if you encounter any issues.
Regards,
Keith
Jan 22, 2010
Ben McGuire says:
Are there any plans to make this plug in compatible with Confluence 3.1? If so w...Are there any plans to make this plug in compatible with Confluence 3.1? If so what is the time frame.
Could you please let me know either way.
Thanks
Ben McGuire
Jan 29, 2010
Jonas Lindström says:
Second this question. We've made a central search tool around this plugin and ar...Second this question. We've made a central search tool around this plugin and are eager to upgrade to Confluence 3.1. Any idea on the timeframe on this one?
Feb 09, 2010
Jonathan Mort says:
Version 1.0.6 has just been released which adds support for Confluence 3.1. See...Version 1.0.6 has just been released which adds support for Confluence 3.1.
See the announcement for more details.
Mar 23, 2010
james lyons says:
I'm having trouble with the syntax to exclude a single label from the search. so...I'm having trouble with the syntax to exclude a single label from the search. so far i've got:
{search-input:type=hidden|match=query|value=label:(+cases?) NOT label:(+cases?noindex)}the plan is to exclude everything with the label noindex from the search results, but the above just kills all results. as does:
{search-input:type=hidden|match=query|value=label:NOT label:noindex}and
{search-input:type=hidden|match=query|value=Not label:noindex}and numerous other things i've tried. I can kind of see why they don't work, kind of. The label is unique to the space and i just want to skip it in results, just can't see how.
any help would be greatly appreciated.
j
Mar 23, 2010
Jonas Lindström says:
Hi James, Looks like you need to modify your labels: {search-input:type=hidde...Hi James,
Looks like you need to modify your labels:
{search-input:type=hidden|match=query|value=label:(+cases?) NOT label:(+cases?noindex)}Instead, try:
{search-input:type=hidden|match=query|value=label:(+global?cases) NOT label:(+global?noindex)}Mar 23, 2010
james lyons says:
I think i see what you're saying but the markup you suggest still kills all sear...I think i see what you're saying but the markup you suggest still kills all searches.
The label noindex is global, i get the second bracketed part but the first part:
(+global?cases)
i don't get (actually not sure i get the second one on reflection). i thought the text after the ? would be the label, there is no cases label. The logic (As it seems to me) is:
match a label from ANY labels globally but NOT the label noindex
or, in english
if it has the label noindex ignore it
I appreciate your help, and it seems as if it should be doable (it's done in the examples with a check box), i just can't work out the syntax.
cheers,
j
Mar 23, 2010
Jonas Lindström says:
Ah! In that case, just don't specify an include-label, just the exclude-label. C...Ah! In that case, just don't specify an include-label, just the exclude-label. Code:
{search-input:type=hidden|match=query|value=NOT label:(+global?noindex)}Mar 23, 2010
james lyons says:
I see what you've done there, i think i tried something similar a little while a...I see what you've done there, i think i tried something similar a little while ago, still kills all searches. Here's the whole thing:
{search-form} {search-input:type=text|match=query} {search-input:type=hidden|match=query|value=NOT label:(+cases?noindex)} {search-submit:Search}{search-form}(i do have search results further down the page).
It soooo looks like it should work.
Thanks again for your help.
james
Apr 05, 2010
Jonathan Hudson says:
Is there any way to get a numbered total of the search result rows? I have trie...Is there any way to get a numbered total of the search result rows? I have tried a number of things without success.
Sep 22, 2010
Francis Martens says:
Is version 1.0.6 compatible with Confluence 3.2 (and higher) ? It is currently n...Is version 1.0.6 compatible with Confluence 3.2 (and higher) ?
It is currently not available on the repository, so I assume there is some problem with its compatibility.
Sep 22, 2010
Jonas Lindström says:
We have used it with Confluence 3.2.1_01 and are using it with Confluence 3.3.1....We have used it with Confluence 3.2.1_01 and are using it with Confluence 3.3.1. I think the compatibility setting just hasn't been updated.
Sep 22, 2010
Francis Martens says:
Jonas - thanks ! It does work fine on 3.2.1_01Jonas - thanks !
It does work fine on 3.2.1_01
Sep 28, 2010
Sam Kenny says:
Hi, I am not sure if I am doing something wrong or if this is a bug but the sea...Hi,
I am not sure if I am doing something wrong or if this is a bug but the search does not seem to work if I set the sortField to be modified.
For example, in the code below I get no results. If I change the sortField to be, say, author, everything works fine.
{table:align=center} {tr:align=center} {td:align=center} {search-form:autoSubmit=true} {search-input:type=text|match=query} {search-input:type=hidden|match=label|value=searchable} {search-submit:Search} {search-form} {search-results:fields=title,creation,modified,author|sortField=modified}I am running Theme Builder 4.1.3 and Confluence 3.3
Oct 04, 2010
Mark Earlam says:
We aware of a few bugs within the advanced search plugin and we hope to solve th...We aware of a few bugs within the advanced search plugin and we hope to solve these issues and release a new plugin shortly.
Oct 19, 2010
Sam Kenny says:
Thank you. Do you have an ETA? This month? November? 2011? Just trying to g...Thank you. Do you have an ETA? This month? November? 2011? Just trying to gauge when I might be able to leverage it. Happy to beta test if that helps.
Oct 20, 2010
Keith Brophy says:
Hi Sam, We have completed most of this work, but further testing is required. W...Hi Sam,
We have completed most of this work, but further testing is required. We are tentatively aiming at releasing this plugin (and others) by the end of November.
Regards,
Keith
Oct 20, 2010
Sam Kenny says:
Thanks for getting back to me. This is good to know.Thanks for getting back to me. This is good to know.
Dec 09, 2010
Keith Brophy says:
Hi Sam, While we have addressed a bug where label and metadata queries were not...Hi Sam,
While we have addressed a bug where label and metadata queries were not executed correctly, we have yet to make a new release available. Unfortunately, I do not have a concrete plan as to when this release will be made - I now expect it to be in the new year. We shall update this page as soon as the release is made.
Regards,
Keith
Dec 22, 2010
Robert Lillywhite says:
I have found two problems with 3.0.5 while testing prior to ugrading to Confluen...I have found two problems with 3.0.5 while testing prior to ugrading to Confluence 3.4.5...
1. The maxresults option does not work.
2. {search-input:type=hidden|match=query|value=spacekey:SPACEKEY} causes the search to totally fail and error to the atlassian.log.
Are there any plans for a bug fix release as I have had to roll back to 1.0.6?
Cheers,
Rob
Jan 06, 2011
Samael Bate says:
Hi Robert, I am looking into the maxresults issue. The second point you raised...Hi Robert,
I am looking into the maxresults issue. The second point you raised may be due to the markup being used. try changing it to the following:
{search-input:type=hidden|match=query|value=spacekey:(ds)}
Edit: I have also been unable to get the maxresults option to work and have found another report of a similar problem. I have raised a bug report for this internally so that it can be resolved in a future update.
Jan 10, 2011
Robert Lillywhite says:
Hi Samael, I have actually encountered another issue while testing your suggest...Hi Samael,
I have actually encountered another issue while testing your suggested syntax for the spacekey (which unfortunately still didn't work).
I have the following at the top of my search...
{search-input:type=hidden|match=label|value=my_label}
...but this is being ignored.
I tried modifying it to...
{search-input:type=hidden|match=query|value=my_label}
...but this caused nothing to be returned.
Also, I have several search-select boxes which match against metadata stored using the Scaffolding plugin but using these doesn't seem to be filering the results... this might be partly due to the other issues I am not sure.
Thanks,
Rob
Jan 10, 2011
Samael Bate says:
When I tested it I used: {search-form} {search-input:type=hidden|match=que...When I tested it I used:
{search-form} {search-input:type=hidden|match=query|value=spacekey:(SPACEKEY)} {search-input:type=hidden|match=label|value=MYLABEL} {search-input:type=text|match=query} {search-submit:Search} {search-form} {search-results}That worked as expected. If you could supply all the markup being used I'll try testing with that. Please use the {code} macro when adding example markup to a comment.
Jan 11, 2011
Robert Lillywhite says:
Hi Samael, I created a new page with the markup you tried (substituting my own ...Hi Samael,
I created a new page with the markup you tried (substituting my own spacekey and label) and found that the spacekey worked but the label was being ignored and if the search box was left blank then the search did nothing.
I tried using * in the search field but this also failed. In both cases (using * or a blank box) it errors in the atlassian log.
Let me know if there is any other information you need.
Cheers,
Rob
Jan 11, 2011
Samael Bate says:
It looks for labels when I test it but it does return pages without labels also....It looks for labels when I test it but it does return pages without labels also. I put in a feature request for adding a new parameter so that a search input can be set as "required".
I did find that there is sometimes no results shown when trying to use either the fields or sortField parameter in the {search-results} macro if there are pages without these values being indexed. eg: using modified with pages that have no modified value.
I can't comment to the errors in your log without seeing the error messages you are referring to. There are a few bugs reports raised now in regards to parameters in the {search-results} so until these are resolved in a future release it may be best to use the defaults.
Jan 11, 2011
Robert Lillywhite says:
Hi Samael, It looks for labels when I test it but it does return pages without...Hi Samael,
I have just tested again and I can confirm that I get pages returned that have labels but not the label defined in the search-input macto.
The other problem is that if the search-input is blank the search does not work and it errors to the atlassian log (I can provide logs if you can tell me where to send them).
For example, if I use this...
{search-form} {search-input:type=hidden|match=query|value=spacekey:(spacekey)} {search-input:type=text|match=query} {search-submit:Search} {search-form} {search-results}... but run a search without entering anything in the search-input field then it fails. This seems to only happen in conjunction when using the spacekey search.
In version 1.0.6 this worked to match anything and is vital to the way we use this plug-in.
I am happy to provide any information you require but I am not sure this is the place to put it.
Thanks,
Rob
Jan 12, 2011
Samael Bate says:
Hi Robert, In regards to the entries in your log file it is probably best to r...Hi Robert,
In regards to the entries in your log file it is probably best to raise a bug report for it on studio.plugins.atlassian.com, the Advanced Search project can be found here. Although we monitor both the comments here on the site and the issues raised on studio.plugins.atlassian.com, for a more in-depth, timely investigation of issues such this I recommend the Adaptavist Support Service. If this is something you would like to discuss further please use this contact page.
Jan 12, 2011
Robert Lillywhite says:
Hi Samael, There are two issues (I think). 1. match=label no longer works. To...Hi Samael,
There are two issues (I think).
1. match=label no longer works. To match against labels you now have to use:
{search-input:type=hidden|match=query|value=label:(+global?MyLabel)}2. You cannot search with a blank input where there is more than one match=query present in the search. You get this (and more) in the atlassian log:
This is quite a big problem for me as I have a page which offers several drop-downs (some of which use query) and a search box.
Do you have any suggestions?
Thanks,
Rob
Jan 13, 2011
Samael Bate says:
Thank you for supplying the error message in your log file. I've included a lin...Thank you for supplying the error message in your log file. I've included a link to your comment in the internal Jira issue so that you can be notified when a fix has been done.
Feb 11, 2011
Karim El Alaili says:
Hello, The Advanced Search Plugin is listed as Open Source on this page but the...Hello,
The Advanced Search Plugin is listed as Open Source on this page but there is no link to the source code. Would it be possible to have access to it somehow ?
I am currently implementing JIRA and Confluence for my company and customizing various aspects of Confluence to meet our demands (look & feel, plugin development, etc.). Thus, I would like to customize the Advanced Search Plugin, mainly to add extra columns to the search results table (added to the lucene search index with one of my plugins).
I have tried extending the appropriate classes with no success. If it's not possible to supply the source code, what would you advise in order to achieve the desired result ?
Thank you,
Karim El Alaili
Feb 21, 2011
Keith Brophy says:
Hi Karim, We have actually moved to a closed source model with the latest relea...Hi Karim,
We have actually moved to a closed source model with the latest releases of our plugins. Unfortunately, limited community involvement and time constraints from other client commissioned work meant that our plugins were not updated in a timely fashion once a new Confluence version was released.
We are due to announce some new plans in relation to our plugins that hopefully addresses this situation - please keep an eye on our site for further details on this.
Should you wish to review the source as it was before we closed it, the code is still available here.
Regards,
Keith
Feb 12, 2011
Klaus Feldmann says:
Could not manage to get excerpts in search result (conf. 3.4.8 and Adv.Sear. 3.0...Could not manage to get excerpts in search result (conf. 3.4.8 and Adv.Sear. 3.05), with or without including parameter showExcerpts=true.
Is their something special to take care for?
Feb 17, 2011
james lyons says:
Hi, I recently rolled up to confluence 3.4.8 with advanced search 3.0.5. I don...Hi,
I recently rolled up to confluence 3.4.8 with advanced search 3.0.5. I don't want to some across as too negative about something so useful and FREE but after a few days of testing variations of re-writes i'd have to say it's broken. maxResult, searchOption, showExcerpts, spaceKey, some combinations give me limited valid results but not to the extent it ever has previously, I've just lost a huge chunk of space functionality which until now was used heavily on a daily basis. Is there any word on when we can expect a new release or for the documentation to be updated to reflect any changes (the documentation on studio.plugins.atlassian.com seems to reflect more accurately what's going on)?
Thanks,
j
Feb 21, 2011
Keith Brophy says:
Hi James, Klaus, Many thanks for these reports. We are aware of some issues wit...Hi James, Klaus,
Many thanks for these reports. We are aware of some issues with the Advanced Search plugin - it appears that some elements were not covered in our 3.4 compatibility testing cycle. We are currently reviewing a number of our plugins and we are hoping to make a new release for April.
Regards,
Keith
Feb 22, 2011
james lyons says:
Hi Keith, thanks for the info, I look forward to the next release cheers, j...Hi Keith, thanks for the info, I look forward to the next release
cheers,
james
Mar 28, 2011
james lyons says:
Hello, any word on advanced search 1.0.6 compatibility with confluence 3.5? Afr...Hello,
any word on advanced search 1.0.6 compatibility with confluence 3.5? Afraid i don't have testing server.
ta,
james
Mar 29, 2011
Sean Diggins says:
seems broken with 3.5 here, testing upgrade from 3.3.1 with Advanced Search 3.0....seems broken with 3.5 here, testing upgrade from 3.3.1 with Advanced Search 3.0.5
no matter what I try, searches return 0 results
3.0.5 works fine in Conf 3.3.1
Is a release still expected in April?
Mar 29, 2011
james lyons says:
I gave up with 3.0.5, had no joy with it. Have you tried 1.0.6 in 3.5? i'd be cu...I gave up with 3.0.5, had no joy with it. Have you tried 1.0.6 in 3.5? i'd be curious to know how you get on.
Mar 30, 2011
Sean Diggins says:
Reverting to 1.0.6 in Conf 3.5 seems to work. Thanks for the tip. The devil will...Reverting to 1.0.6 in Conf 3.5 seems to work. Thanks for the tip. The devil will be in the details I guess - we havent used 1.0.6 before, so maybe some issues will surface that arent obvious at first glance.
Mar 30, 2011
james lyons says:
Great, i'll try it out myself, i could never get 3.0.5 to work properly. cheers...Great, i'll try it out myself, i could never get 3.0.5 to work properly.
cheers,
j