User Guide for CQL Search Table Macro

Introduction

Similar to https://akeles.jira.com/wiki/spaces/CQLC/overview?homepageId=2411692199#CQL-Search-Macro , this macro allows you to execute contextual searches with predefined CQL.

Results are displayed in a table with configurable columns.

Configuration

Field Name	Required	Default Value	Explanation	Additional Information
CQL			Enter a CQL statement with $$query$$ or $$query*$$ as the search term.	How to Search Content effectively with Titles How to limit search to a file type in Confluence Useful scenarios with Canned Search for Confluence Convenient Search with placeholders
Default Term			Enter a default query term to replace the $$query$$ in CQL. Search results will be preloaded if it is provided.	How to use CQL Macro to build a corporate encyclopedia
Search Type		Contains	The searching can done with three type searches. Exact Match – Find contents that contains the exact word Start With – Find contents that starts with the word Contains – Find contents that partially matches the word	Support different modes of searching
No. of Results per Page	10		Select the no. of results to be displayed: 5 — Pagination will occur if there are >5 search results 10 — Pagination will occur if there are >10 search results 50 — Pagination will occur if there are >50 search results 100 — Pagination will occur if there are >100 search results If there are more results than the selected no. of results to display, pagination will occur.	User Guide for CQL Search Macro \| Search-Results-—-with-pagination
Custom "No Results Found" message			Enter a customised message when no results are found.	How to Improve Feedback for Users when No Results are Found
Table Template		title, space, modified	Select the template to use for results table. s/n title space type created modified creator modifier labels version comments Separate template values using ",". See default value for example.	User Guide for CQL Search Table Macro \| Table-Template-for-customising-table-columns
Template Header			Enter customised headers to replace default template header. If not provided or provided incorrectly, specified header will not be applied.	User Guide for CQL Search Table Macro \| Template-Header-for-customising-table-headers
Search Bar		Show	Indicate whether to display the search bar	User Guide for CQL Search Table Macro \| Hidden-Search-Bar

Features

Hidden Search Bar

The search bar can be hidden to allow page owner to use the macro to create a listing which users can view-only.

Table Template for customising table columns

The available template are as follows:

Available Template Terms	Result
s/n	Index of the record
title	Shows title of file / page
space	Shows space where file / page is located
type	Indicate if item found is an attachment / page
created	Shows created date
modified	Shows last modified date
creator	Shows creator of page / file
modifier	Shows user who last modified page/ file
labels	Shows all labels on page
version	Shows latest available version for file / page
comments	Shows number of comments on page

When provided incorrectly, only correct templates will be used

E.g. For template “title, spaces, modified, labels”

“spaces” is incorrect (should be space)
Results will only show table with table headers “title, modified, labels”

E.g. For template “titles, spaces, label, types”

None of the template terms used is correct
Default template will be used to display results (“title, space, modified”)

Template Header for customising table headers

To allow users to customise table headers, a template header field is provided. Users can rename template values to a more suitable value for the results table they are creating.

In the example shown above, changes to template header are as follow:

Creator → Owner
Modified → Last Modified

Headers defined incorrectly will result in default template being used (over-defined / under-defined).

E.g. For the template “title, type, creator, modified” , if header “title, type, owner” is defined

Only 3 headers are defined for 4 template (under-defined)
Header defined will be ignored, template “title, type, creator, modified” will be used as header instead.

If no header is defined, template “title, type, creator, modified” will be used.