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:

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.

Click to view example

{search-form:autoSubmit=true}{search-input:type=text|match=query}

{search-input:type=checkbox|match=query|value=label:( +global?agency-home ) NOT label:( +global?hidden )} Normal label "agency-home" but not "hidden" label
{search-input:type=checkbox|match=query|value=Nordic Scandinavia "Northern Europe" Denmark Finland Iceland Norway Sweden} Nordic States
{search-input:type=checkbox|match=query|value="European Union" Germany France "United Kingdom" UK Italy Spain Poland Romania Netherlands Greece Portugal Belgium Czech "Czech Republic" Hungary Sweden Austria Bulgaria Slovakia Denmark Finland Ireland Lithuania Latvia Slovenia Estonia Cyprus Luxembourg Malta} European Union
{search-input:type=checkbox|match=query|value=Germany Switzerland Liechtenstein Slovakia Poland Czech "Czech Republic" Austria Hungary Slovenia} Central Europe
{search-input:type=checkbox|match=query|value=Burundi Comoros Djibouti Eritrea Ethiopia Kenya Madagascar Malawi Mauritius Mozambique Réunion Reunion Rwanda Seychelles Somalia Uganda "United Republic of Tanzania" Tanzania Zambia Zimbabwe|checked=true} Eastern Africa
{search-submit:Search}
{search-form}

{search-results:types=page,blogpost,userinfo,spacedesc|rateThreshold=0|maxResults=50|fields=space!Bubble,title,rating,author|sortField=rating|sortDir=desc|showExcerpts=true|debug=true}

Version History

Version	Date	State	License	Price
1.0.6 (#18)	09 Feb 2010	Stable	Freeware / Open Source (BSD)	Free
Release Notes SRCH-6 added confluence 3.x support
1.0.5 (#17)	02 Feb 2009	Stable	Freeware / Open Source (BSD)	Free
Release Notes Updated version for Confluence 2.9/2.10 compatibility.
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 Dan Hardiker — Contributor
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 Dan Hardiker — Contributor
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 Dan Hardiker — Contributor
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 Dan Hardiker — Contributor
1.0 (#10)	20 Sep 2006	Stable	Freeware / Open Source (BSD)	Free
Release Notes The inital public release. Contributors Dan Hardiker — Contributor