Skip to end of metadata
Go to start of metadata

This add-on has been retired.

Limited Support in line with our Support SLA will be provided for this add-on until your license expires or until August 2015 at most. If you have questions, please contact Adaptavist Support Team.

Read the announcement about the retirement of this add-on on our blog

A note for those upgrading to v5.x

In version 5 Advanced Search configuration scripts will need to be updated. Please read the guide to porting scripts in v5 before installing.

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

(error)

hidden

Hide the form from view (only useful with autoSubmit)

boolean

false

(error)

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

(tick)

metadataKey

Metadata Key – only valid for match=metadata

string

none

(error) unless match=metadata, then (tick)

type

Type of Field

string (text / checkbox / hidden)

none

(tick)

value

Value of the Field

string

none

(error)

checked

Inital State – only valid for type=checkbox

boolean

false

(error)

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

(tick)

metadataKey

Metadata Key – only valid for match=metadata

string

none

(error) unless match=metadata, then (tick)

nullLabel

Label of the "unanswered" option

string

no "unanswered" option

(error)

{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

(error)

selected

Is this Option Selected

boolean

false

(error)

{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

(error)

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

  • 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 isn't 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

(error)

types

The content types to search for

string

page,blogpost

(error)

sortField

The fields to sort on initially.

string (a field from fields)

title

(error)

sortDir

The direction to sort on initially.

string (asc / desc)

asc

(error)

maxResults

How many results should I truncate to? (users will be warned in the case of more results than shown)

int

20

(error)

rateThreshold

How many ratings are needed before the average is used?

int

5

(error)

debug

Should I show the query I generated for debugging?

boolean

false

(error)

 

 

Top of page

Recipes

How to create highly customisable lists in Confluence with Advanced Search plugin configs

Basic Search Form

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.

Second Search Form

 


 


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}

 

To restrict your search values to a specific space, use the following markup:

 

If you're searching on Team labels then use the following:

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.

{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|debug=true}

Example search configuration

The following configuration, when used with


on a Wiki page, will display just the blog posts with the label 'latest_blog'. For each blog found the title of the blog and name of its author is displayed, along with an excerpt of the blog cropped to a maximum of 50 characters.
The formatting of the configurations has to be exact – Download it in XML form to copy and paste.

<?xml version="1.0" encoding="UTF-8"?>
<config id="latest_blogs" title="Latest Blogs">
    <scripts>
        <preSearch><![CDATA[
import org.apache.lucene.search]]><![CDATA[
import com.adaptavist.confluence.advancedSearch.core]]><![CDATA[

labelSubQuery = searcher.buildStandardQuery(["labelText"], 'latest_blog')]]><![CDATA[
bean.getLuceneQuery().add( labelSubQuery, org.apache.lucene.search.BooleanClause.Occur.MUST )
]]><![CDATA[
        ]]></preSearch>
    </scripts>
    <query>
        <maxResults>5</maxResults>
        <pageSize>5</pageSize>
        <contentTypes>
            <type>blogpost</type>
        </contentTypes>
        <sort>
            <sortField reverse="true">created</sortField>
        </sort>
        <retrieveAllResults>false</retrieveAllResults>
    </query>
    <output>
        <columns>
            <column title="Title"/>
        </columns>
        <template><![CDATA[
<table class="confluenceTable">]]><![CDATA[
  <thead>]]><![CDATA[
    <tr>]]><![CDATA[
    #foreach ($column in $bean.columns)]]><![CDATA[
      <th class="confluenceTh">$column.title</th>]]><![CDATA[
    #end]]><![CDATA[
    </tr>]]><![CDATA[
  </thead>]]><![CDATA[
  <tbody>]]><![CDATA[
      #if ($bean.getPaginationSupport().getItems() && $bean.getPaginationSupport().getPage()
.size() > 0)]]>
<![CDATA[
        #foreach ($result in $bean.getPaginationSupport().getPage())]]><![CDATA[
          <tr>]]><![CDATA[
            <td class="confluenceTd">]]><![CDATA[
              #set($colCount = $velocityCount - 1)]]><![CDATA[
              <a href="$req.contextPath$result.get('urlPath')">$!result.get("title")</a> 
by <a href="${req.contextPath}/display/~$resu]]><![CDATA[lt.get('creatorName')">
$userInfoUtils.getFullName($result.get('creatorName'))</a>]]><![CDATA[
              <br />]]><![CDATA[
              #set($excerpt = $result.get('excerpt'))]]><![CDATA[
     ]]><![CDATA[         #if($excerpt && $excerpt.length() > 50)]]><![CDATA[
                $excerpt.substring(0, 50) ...]]><![CDATA[
              #else]]><![CDATA[
                $!]]><![CDATA[excerpt]]><![CDATA[
              #end]]><![CDATA[
            </td>]]><![CDATA[
          </tr>]]><![CDATA[
        #end]]><![CDATA[
      #else]]><![CDATA[
      <tr>]]><![CDATA[
        <td colspan="$bean.columns.size()">]]><![CDATA[
          There were no results for your search criteria.]]><![CDATA[
        </td>]]><![CDATA[
      </tr>]]><![CDATA[
      #end]]><![CDATA[
  </tbody>]]><![CDATA[
</table>]]><![CDATA[
    ]]></template>
    </output>
</config>

 

You can restrict this query to just personal spaces, by adding the following to the presearch, after the labelSubQuery:

personalSubQuery = searcher.buildStandardQuery(["space.type"], 'personal')
bean.getLuceneQuery().add( personalSubQuery, org.apache.lucene.search.BooleanClause.Occur.MUST )

 

Top of page

  • No labels