Advanced Query Page (AQP)

The Advanced Query Page is a Conversant page type designed for two purposes, to allow visitors to submit searches to locate information in your conversation, or to create flexibly formatted pages that display information about messages in your conversation based on stored queries.

Creating an Advanced Query Page

To create a new Advanced Query Page, go to the structure editor of your site: "/yourSite/admin/conversations/yourSite/structure", and select the folder in which you want to create the page.

In this folder's properties editor, scroll the window all the way down, until you get the "New File Or Folder" form. Type the name you want to give to your page in "Navigation Title". Set "Page Type" to "Advanced Query Page" and click on "Create New File".

The page will reload and show you a confirmation that the new object has been created. Locate this object in the structure listing and click on it. This will open the properties editor for your new page.

Editing Properties

The Advanced Query Page has a variety of properties that allow you to control the appearance and behavior of the page. Here is a brief description of those properties:

Query Options

Allow search arg overrides? (Yes/No) : If Yes, the page will allow search values to be altered based on the contents of the search arguments in the URL submitted to the page. This property must be "Yes" if your page shows a query form, and you wish your users to be able to submit their own searches using this form. Default: Yes.

Run query on load? (Yes/No) : If yes, a query based on the query default properties will be run when the page is first loaded. You should set this property to "Yes" if you will not display a query form to your users, or no results will be shown. Default: No.

Show only bound URLs? (Yes/No) : If yes, the results returned will from the query will only return messages that are bound to URLs within the site. This is very useful if you have a site with a private discussion group, but you still wish to provide search capabilities to your guests. If you choose this option, and wish the result to link directly to the bound URLs, you should alter the message template property to use the <!--#msgBoundURL--> in place of the <!--#msgURL--> macro. Default: No.

Show only Top level Topics? (Yes/No) : If yes, the results returned will from the query will only return messages that are top level discussion topics, ie, not replies to another message.

Show only first message in each thread? (Yes/No) : If yes, only the first message in each thread will be returned. When used in combination with relative msgNum attributes in template Message Macros, this feature can be used to create lists of most recently active topics, etc.

Query's Timezone : This property specifies the timezone to use for date ranges when submitting the query. You may select a specific timezone if you wish your stored queries to appear the same for all visitors, or you may allow the page to use the user's timezone. Default: User's Timezone.

Query Defaults

Properties under this tab allow the specification of a default query for the page. Depending on selections under the "Query Options" tab, this may be the only query for the page and may be run at page load time. All basic discussion group fields are supported, as well as any custom fields in the conversation. To better under configuring date ranges, read Advanced Query Page - Date Specifications

Form Settings

These properties control some aspects of the appearance of the query form. Not that more complete control can be accomplished through editing the query form template, in the templates section below.

Show form? (Yes/No) : Toggle the appearance of the query form in the page. If you are running a stored query (Run query on load? Yes), you may not wish the form to be presented to users.

Query Fields Width (number) : Control the size of the text box presented for the subject and body in the query form. This property can also be set via macro attributes in the query form template.

Query Select Height (number) : Control the number rows present in the "posted by" and "modified by" boxes in the form. This property can also be set via macro attributes in the query form template.

Sort Keys : Specify which fields should be offered as options in the #querySortBy popup menu in the query form.

Result Settings

Items per page (number) : Number of results to return at one time. If more than this number of messages are found, the results will be divided into multiple result pages.

Previous/Next Link Text (string) : Text to use when linking to previous and next result pages in the result set.

Templates

These templates control the appearance of different sections of the page contents.

Page Content Template : This is the top level page template. It support to special macros, <!--#queryForm--> and <!--#queryResults--> which control the positioning in the page of the query form, and query results, respectively.

Query Form Template : Controls the appearance of the query form. You may remove items that you do not wish to be present without effecting the page. Special macros in this template:

• <!--#queryFormTag--> (required): opening html form tag.

  Optional attributes:

  • action="url to query page": Defaults to current page within an advanced query page, when the macro is used to build query forms to display on other pages.
  • name="any form name": Defaults to "query"
  • class="CSS class": Defaults is empty, which omits the class attribute from the form tag
  • onSubmit="any javascript": Default is empty, which omits the onSubmit attribute from the form tag
  • onReset="any javascript": Default is empty, which omits the onReset attribute from the form tag

• <!--#queryHidden--> (required): hidden html form elements.

• <!--#queryStartDate-->, <!--#queryEndDate--> : Date entry elements for specifying a range of message creation dates.

  Optional attributes supported:

  • size="[number]" : size of fields
  • class="[string]", id="[string]", style="[string]" : CSS attributes
  • onfocus="[string]", onblur="[string]", onchange="[string]" : Javascript attributes
  • toLabel="[string]", fromLabel="[string]" : text used to label the date ranges

• <!--#queryModStartDate-->, <!--#queryModEndDate--> : Date entry elements for specifying a range of message modification dates.

  Optional attributes supported:

  • size="[number]" : size of fields
  • class="[string]", id="[string]", style="[string]" : CSS attributes
  • onfocus="[string]", onblur="[string]", onchange="[string]" : Javascript attributes
  • toLabel="[string]", fromLabel="[string]" : text used to label the date ranges

• <!--#querySimple--> : special text input field that searches across multiple text fields (like subject and body).

  optional attributes supported:

  • fields="[string,list]" : a comma- or space-separated list of field names to search, defaulting to "subject,body"
  • size="[number]" : size of field
  • maxlength="[number]" : max number of characters to accept
  • class="[string]", id="[string]", style="[string]" : CSS attributes
  • onfocus="[string]", onblur="[string]", onchange="[string]" : Javascript attributes

  Notes

  • if the 'fields' attribute is omitted, then the subject and body fields will be used
  • any item in the fields list which is NOT the name of a text field (including custom fields) will be ignored
  • any field included in the 'fields' attribute will be ignored. So if your simple query field is supposed to search the subject and body, don't *also* have a separate subject field in your form, because it will be ignored.

• <!--#querySubject-->,
  <!--#queryBody--> : text input fields for subject and body content.

  Optional attributes supported:

  • size="[number]" : size of fields
  • maxlength="[number]" : max number of characters to accept
  • class="[string]", id="[string]", style="[string]" : CSS attributes
  • onfocus="[string]", onblur="[string]", onchange="[string]" : Javascript attributes

• <!--#queryLabel-->, <!--#queryPostedBy-->, <!--#queryModifiedBy--> : Selection boxes for label, creator and modifier of the messages.

  Optional attributes supported:

  • size="[number]" : size of fields
  • maxlength="[number]" : max number of characters to accept
  • class="[string]", id="[string]", style="[string]" : CSS attributes
  • onfocus="[string]", onblur="[string]", onselect="[string]" : Javascript attributes

• <!--#querySortBy-->, <!--#querySortDir--> : Elements to specify the sorting key and sorting direction.

• <!--#queryCustomField name="[fieldName]"--> : Used to add a selection/entry widget for specifying query values for a custom field in the query form. The widget that comes out will be appropriate to the data type of the custom field. Most attributes listed in the other #query macros will work as appropriate to the type -- ie, a "Short Text" type field will look similar to a #querySubject macro, and support the same attributes.

• <!--#querySubmitButton--> : Form submit button.

  Optional attributes supported:

  • class="[string]", id="[string]", style="[string]" : CSS attributes
  • onfocus="[string]", onblur="[string]", onclick="[string]" : Javascript attributes

Query Result Template : Container template for query result items. Used to specify column headers and footers.

• <!--#querySortLink sortBy="[field to sort by]" sortDir="[asc/des]" label="[string]"--> : This macro is used to build a hyperlink to the current query results sorted by the field specified in the required "sortBy" attribute. Valid "sortBy" values can be the familiar or actual field names, or the name of a custom field, preferred values are: msgNum, creationDate, modificationDate, creatorAddress, modifierAddress, subject, label. This macro supercede the older sort macros, which still work but are not recommended...They are: <!--#queryResultNumLink-->, <!--#queryResultDateLink-->, <!--#queryResultSubjectLink-->, <!--#queryResultPostedLink-->.

• <!--#queryResultFoundLine--> :

  This will be replaced with the line that indicates how many messages were found and how many are displayed.

• <!--#queryResultPrevLink--> :

  This will be replaced with a link to the page that displays the previous found messages. The text used to display the link can be set in the query page properties

• <!--#queryResultNextLink--> :

  This will be replaced with a link to the page that displays the next found messages.

• <!--#queryResultPageLinks--> :

  This will be replaced with a link to each page of found messages.

Message Template : Controls the appearance of each message result line item in the query results. This template can use all standard Message Macros.

Empty Result Template : Allows you to specify the text to return in the case a query find no matching messages.

Process Error Template : Allows you to specify the appearance of the text returned when a query could not be processed dues to some error...typically invalid data submitted to the page. This template has one special macro, <!--#queryErrors--> which returns the list of errors encountered.