Access Keys:
Skip to content (Access Key - 0)

Advanced Search
Name Advanced Search
Vendor Adaptavist.com Ltd (Website)
Authors Dan Hardiker, Guy Fraser
Homepage http://confluence.atlassian.com/display/CONFEXT/Advanced+Search+Plugin
Issue Management n/a
Continuous Integration n/a
Categories Content Macros
Most Recent Version 1.0.5
Availability Confluence v2.9 to v2.10.3
State Stable
Support By: Adaptavist Community Support
Website: http://www.adaptavist.com/display/free/Support
License Freeware / Open Source (BSD)
Price Free
Release Docs http://confluence.atlassian.com/display/CONFEXT/Advanced+Search+Plugin
Java API Docs n/a
Download Source http://svn.atlassian.com/svn/public/contrib/confluence/advanced-search-plugin/tags/1.0.5/
Download JAR adaptavist-advanced-search-1.0.5.jar
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:

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:

  1. I want to set the default value of the query to repository plugin, as if that was typed into the search engine.
  2. I want to only return content that has the searchable label - but this shouldn't be displayed as an option.
  3. I want the search to be run automatically with the defaults above.
Second Search Form
{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.

Modified Search Results
{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.

Click to view example

Version History

Version Date State License Price
Show description 1.0 (#10) 20 Sep 2006 Stable Freeware / Open Source (BSD) Free

Release Notes
The inital public release.

Contributors

Show description 1.0.1 (#11) 29 Sep 2006 Stable Freeware / Open Source (BSD) Free

Release Notes
Fixed a bug with null pointer exceptions when users / spaces are deleted after the content has been indexed.

Contributors

Show description 1.0.2 (#12) 19 Oct 2006 Stable Freeware / Open Source (BSD) Free

Release Notes

  • Fixed a null pointer bug caused by an unset component.
  • Added better space resolution where possible.

Contributors

Show description 1.0.3 (#15) 14 Jul 2007 Stable Freeware / Open Source (BSD) Free

Release Notes

  • Removing old Maven 1 build files
  • Adding Maven 2 build file
  • Configuring atlassian-plugin.xml to pull data from Maven 2
  • Fixing Confluence API changes to packages and method signatures
  • Counter-acting the default concat mode for queries from OR to AND by explicitly stating OR between entity type terms (they can never be multiple and elicit zero results).

Contributors

Show description 1.0.4 (#16) 22 Jul 2007 Stable Freeware / Open Source (BSD) Free

Release Notes

  • Missed some files from the build and the check in! Oops.

Contributors

Show description 1.0.5 (#17) 02 Feb 2009 Stable Freeware / Open Source (BSD) Free

Release Notes

Updated version for Confluence 2.9/2.10 compatibility.

Contributors

Toggle Sidebar

Browse

Pinned Pages

Popular Pages
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (2)

 

  1. 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?

    1. Feb 02

      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
Adaptavist Theme Builder Powered by Atlassian Confluence