Advanced Search Plugin

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.4
Availability	Confluence v2.3-dr1 to v2.10
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Donate
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.4/
Download JAR	adaptavist-advanced-search-1.0.4.jar

This plugin now accessible through the Confluence Repository Client.

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.

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:

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.

{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.

See Also

• Search Fields