Access Keys:
Skip to content (Access Key - 0)
Name Advanced Search
Vendor Adaptavist (Website)
Authors Dan Hardiker
Homepage http://confluence.atlassian.com/display/CONFEXT/Advanced+Search+Plugin
Issue Management
Continuous Integration n/a
Categories Confluence Content
Most Recent Version 1.0.6
Availability confluence v2.9.2 to v3.1.2
State Stable
Support By: Adaptavist
License Freeware / Open Source (BSD)
Price Free
Release Docs
Java API Docs n/a
Download Source https://studio.plugins.atlassian.com/source/browse/SRCH/tags/1.0.6/
Download JAR 18683
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.6 (#18) 09 Feb 2010 Stable Freeware / Open Source (BSD) Free

Release Notes

SRCH-6 added confluence 3.x support

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.

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

  • Dan Hardiker — Contributor

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

  • Dan Hardiker — Contributor

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

  • Dan Hardiker — Contributor

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

  • Dan Hardiker — Contributor

Show description 1.0 (#10) 20 Sep 2006 Stable Freeware / Open Source (BSD) Free

Release Notes
The inital public release.

Contributors

  • Dan Hardiker — Contributor

Toggle Sidebar

Get Support

Adaptavist provide commercial support to help resolve any problems you may have using our open source Confluence plugins Find out more...

Need Hosting?

Adaptavist can host your Confluence wiki and open source plugins Find out more....

Author

Pinned Pages

  • No pinned pages.

Popular Pages

Browse

  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, 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

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

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

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

  3. Mar 23

    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

    1. Mar 23

      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)}
      1. Mar 23

        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

        1. Mar 23

          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)}
          1. Mar 23

            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

  4. Apr 05

    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.

Adaptavist Theme Builder Powered by Atlassian Confluence