Introduction

The search perspective  can be used to find files in the repository. The files can be searched for using an array of (custom defined) search criteria. You can find documents, which:

• match a certain property value, using arithmetic functions like =, >=, <, etc
• are in a specified repository folder
• contain one or more search strings. Search strings can be combined with logical operators like NOT, AND, OR.
• a combination of the above

The search components (search form & search results) are loaded into one iframe, which is placed inside the search standard perspective. The search perspective consists of two main parts: the search form and the layout , which is the part where the results of a search action are displayed. The image below presents all the configurable elements in the search perspective.

The search form

On the left, there is the search form. The search form consists of fieldset elements. A fieldset is a set of input fields / buttons. A fieldset can be configured to be visible by default, like the simple text search fieldset in the screenshot. Individual fields are identified by their IDs, which are used in e.g. the [filter configuration]. The following functional elements are allowed in a search form definition:

input fields

• textfield ; a simple text input field

• datefield ; a simple text input field with a date picker next to it

• radiofield ; speaks for itself. A group of radiofields have the same ID but different values.

• dropdown ; a select box. Can be configured with both static and dynamic lists;

• multiselect ; a multiselect input field. Can be configured with both static and dynamic lists
• item ; a child of a multiselect or dropdown field
• source ; a reference to a source defined in the sources configuration. Used to populate dropdown fields / multiselect boxes

actions

• action of type 'submit' ; translates to a button for submitting the search form

presentational elements

• fieldset ; a grouping of form elements. Is shown in the frontend as a collapsable box.

• grid ; translates to a table in the frontend; contains gridrows

• gridrow ; a row in the table ; contains cells

• cell ; a cell in a gridrow

• hbox ; a horizontal box ; translates to a div in the frontend

The layout (results)

The layout consists of the following configurable components:

• summary ; a summary of the search criteria entered by the user, in natural language
• header ; a row containing the column names
• paging ; cannot be configured, except the positioning of this component
• main ; contains the main information for each result item
• detailed ; the detailed information for each result item

Configuration

So how do you configure all these components? The starting point is a master configuration file, which can be put at

repository://configuration/search/config.xml

If this file is not present, a default configuration file is used, which is located at

site://search/config/defaultConfig.xml

The contents of this file:

<search>
  <configuration>
    <sources>
       <source id="typesxmlSources" type="nodetree" href="cocoon://search/typesxml2nodetree" />
    </sources>
    <include href="site://search/config/saved-reports.xml"/>
    <include href="site://search/config/properties.xml"/>
    <include href="site://search/config/advanced-search.xml"/>
    <include href="site://search/config/simple-search.xml"/>
    <include href="site://search/config/filters.xml"/>
    <include href="site://search/config/layouts.xml"/>
    <include href="site://search/config/scopes.xml"/>
    <include href="site://search/config/sorting.xml"/>
    <include href="site://search/config/fieldsets.xml"/>
  </configuration>
</search>

Because the total default configuration code is quite big, the configuration is split up into several files. These files are included into the 'master' configuration file. Inclusion of configuration files can only be done at the top level, for performance reasons. After inclusion of other configuration files you are left with this top xml structure:

<search>
  <configuration>
    <reports>..</reports>
    <Properties>..</Properties>
    <filters>..</filters>
    <layouts>..</layouts>
    <scopes>..</scopes>
    <sorting-schemes>..</sorting-schemes>
    <sources>..</sources>
    <businesslogic>..</businesslogic>
  </configuration>
</search>

What you see here, are several configuration groupings:

• reports ; a search action is always related to at most one report. Within a report you specify the components you want to use in the reports (filters, layouts, etc). Reports can share components by using globally defined components, and referencing them from the report.

• Properties ; defines the webdav properties which are used in the search configuration, e.g. DAV:modificationdate or cms:caption
• filters ; contains the logic for generation of the resulting WEBDAV Search request (DASL)
• layouts ; defines the presentation of results
• scopes ; defines which repository scopes to use
• sorting-schemes ; defines one or more ways in which to order the result, e.g. "DAV:modificationdate, descending" (which is default)
• sources ; defines 0 or more xml files which are used to populate.
  The sections below will further discuss these configurations.
• businesslogic ; TODO

reports

The reports element contains one or more report elements, each uniquely identified by an id . Within the report element, you specify several components:

• form ; contains fieldsets (collapsable field groups), which can contain presentational, field and action elements.
• filters, scopes, sorting-schemes; you can refer to globally defined filters/scopes/sorting-schemes. E.g. for the "generalTextSearchfilter" :

  <report id="sampleReport">
    <filters>
      <filter ref="generalTextSearch"/>
   </filters>
  </report>

Alternatively, you can write out the whole filter definition in the reports element. In the default configuration however, references to global elements are used to prevent the report configuration becoming to bloated.

The form element contains the total configuration needed for presenting the search form. An excerpt of the default search form configuration is shown below:

<form>
      <hbox class="searchToolbar">
        <action id="submit" i18n:attr="label" label="search.form.advanced.submit"/>
      </hbox>
      <fieldset visible="true" i18n:attr="label" label="Simple Text Search">
        <grid class="form_table1">
          <gridrow>
            <cell>
              Search string
            </cell>
            <cell colspan="2" class="fieldContent1">
              <textfield id="simpleSearch" class="input156"/>&#160;
            </cell>
          </gridrow>
        </grid>
      </fieldset>
         ..
    </form>

The presentational elements are shown in normal text, the functional elements are shown in bold. The set of presentational elements is very limited:

• fieldset ; a collapsable box grouping together elements logically belonging together; this element cannot be styled

• hbox : a horizontal box containing other presentational elements
• grid / gridrow / cell ; translates directly to table / tr / td in HTML;

hboxes, grids, gridrows and cells can be styled by adding attributes like class, colspan, etc.

The functional element set contains the following elements:

• textfield ; a simple text input field

• datefield ; a simple text input field with a date picker next to it

• radiofield ; speak for itself. A group of radiofields have the same ID but different values. The values can be used in the filter configuration to make choices.

• dropdown ; a select box. Can be configured with both static and dynamic lists;

• multiselect ; a multiselect input field. Can be configured with both static and dynamic lists
• item ; a child of a multiselect or dropdown field
• source ; a reference to a source defined in the sources configuration. Is used to populate dropdown fields / multiselect boxes

Like the presentational elements, the input fields can be styled as well using the class attribute. You can specify a custom CSS in the repository, see [overview of custom configurations]

Properties

The Properties element contains the definitions of the webdav properties displayed are searched on by the search. An excerpt of the default configuration:

<Properties xmlns:i18n="http://apache.org/cocoon/i18n/2.1">
  <Property>
    <Name>modificationdate</Name>
    <DisplayName><i18n:text>search.result.header.date</i18n:text></DisplayName>
    <Namespace>DAV:</Namespace>
    <NamespacePrefix>dav</NamespacePrefix>
    <Datatype>date</Datatype>
    <Format>yyyy-MM-dd</Format>
    <DefaultSortOrder>descending</DefaultSortOrder>
  </Property>
 ..
  <Property>
    <Name>lastModifiedBy</Name>
    <DisplayName><i18n:text>explorer.properties.cms.lastModifiedBy</i18n:text></DisplayName>
    <Namespace>http://hippo.nl/cms/1.0</Namespace>
    <NamespacePrefix>cms</NamespacePrefix>
    <Datatype>string</Datatype>
    <DefaultSortOrder>ascending</DefaultSortOrder>
  </Property>
</Properties>

First, notice that all the element names are in capital letters. This due to backward compatibility with another property definition file used in the CMS.
The definition is very basic. Name is the element name of the property. DisplayName defines which text to use for a label. Namespace is the property's namespace .e.g. "http://hippo.nl/cms/1.0",which is the default hippo property namespace. NamespacePrefix is important; when referring to property definitions in e.g. the filters configuration, the following syntax is used: cms_caption . In this case cms is the NamespacePrefix , and caption is the Name defined in the Properties configuration for the Hippo caption property. Datatype can be either string or date. If the property is of datatype date, you also need to specify the Format element, so the search engine knows how to convert given input dates to the correct output dates. Finally, the DefaultSortOrder value is used to determine the default ordering method in the presentation of results.
The default properties configuration contains properties that should always be present in a release of Hippo CMS.

filters

The filters element contains filter elements, which are uniquely identified by an id , and can be referenced within a report, or written out inside the report element.

A filter element defines a search criterium, and basically contains two required elements: one input-value and one operator . An input-value can be of type "fixed" or "user-specified". Fixed means that the input-value's value is constant and not resolved from the output of the search form. A user-specified input-value takes its value from the search form. In that case an id attribute is required, which should match an input field in the search form definition. An example:

<filter id="generalTextSearch">
    <input-value type="user-specified" id="simpleSearch"/>
    <operator name="contains"/>
  </filter>

The input-value with id simpleSearch uses the input field defined in the form definition:

<cell colspan="2" class="fieldContent1">
   <textfield id="simpleSearch" class="input156"/>&#160;
 </cell>

A filter element can also contain a conditional construct switch.. case .. default .. , e.g.:

<filter id="workflowStatus">
      <switch>
        <input-value type="user-specified" id="workflowstatus"/>
        <case match="published">
          <filter id="checkIfPublished">
            <operator name="exists" field="cms_publicationDate"/>
          </filter>
        </case>
        <case match="pending">
          <filter id="checkIfPending">
            <operator name="exists" field="cms_requestedPublicationDate"/>
          </filter>
        </case>
        <case match="not_published">
          <filter logical-operator="not" id="checkIfNotPublished">
            <operator name="exists" field="cms_publicationDate"/>
          </filter>
        </case>
      </switch>
</filter>

In this code the the case elements are matched to the value of the input-value defined in the switch element. If one case matches, the contents of the case match are resolved. The case element can contain other filter elements. If no case matches , the contents of the default element are resolved.
An operator element generates a comparative search criterium, using the property / element called field. The name attribute of the operator decides which comparative structure is generated:

• equals
• greater-than-or-equals
• greater-than

• less-than-or-equals
• less-than
• like ; checks whether a property value contains a value

• exists ; checks whether a property exists on a document

• contains ; looks for a text inside a document (no property has to be specified)

• contains-exact; looks for the exact text inside a document (no property has to be specified)
  For the operators in italics you need to specify a property identifier (e.g. cms_caption, where cms is the property's NamespacePrefix and caption is the property's Name).

Filters can be combined by using one of the logical operators  not, and, or. For this you need to specify an attribute logical-operator on the enclosing filter element:

<filter id="mainFilter" logical-operator="or">
<pre>  <filter id="subFilter1">..</filter>
  <filter id="subFilter2">..</filter>
</filter>

The filters subFilter1 and subFilter2 are OR'ed together.

scopes

The scopes element contains scope elements, which define the repository scope for the search, e.g. '/yournamespace/files/yournamespace.preview/content/bulk/news'. If no scope is defined in the report element, the scope with attribute default = true in the globally defined scopes is used.
Scope elements need a unique id attribute. The contents of a scope element consists of an input-value element or a conditional construct switch .. case .. default , which was described in the previous section. The input-values can have, again, derived values from the search form or fixed values.

sorting-schemes

The sorting-schemes element contains sorting-scheme element which defined the method of sorting the search uses. If no sorting-scheme is defined in the report element, a globally defined sorting-scheme with attribute default = true is used instead.

A sorting scheme consists of sort elements. Every sort element results in a sorting of the search results. The order in which they appear in the configuration determines the precedence.
A sort element basically includes one required element 'field' and one optional element 'order'. The field element defines which property to sort on. E.g.:

<sort>
      <field>
        <input-value type="fixed" value="dav_modificationdate"/>
      </field>
</sort>

As you can see, the sort property is determined by the input-value element, which can be of type 'fixed' or 'user-specified' as before.
The default order of the results is specified by the optional order element. If no value is specified, the value of defaultSortOrder from the properties file for this property will be taken. If this value is not specified, the value "descending" will be used.
Like in the filters and scopes configuration, you can also use the switch .. case .. default construct, e.g. to base the sorting method on values from the search form (see the default configuration for an example).

sources

The sources element contains source elements. Sources are XML files containing values that will be used to populate input fields. The sources element must be put in the customized config.xml under configuration and must not be included from a separate file. An example configuration:

<search>
	<configuration>
		<sources>
			<source id="authors" type="list" href="repository://content/meta/authors.xml"/>
			<source id="languages" type="nodetree" href="repository://search/config/languages.xml"/>
		</sources>
		<!-- other configurations -->
	</configuration>
</search>

The id attribute should be unqiue within the sources configuration. The type attribute specifies the XML format of the input source. Two types are currently allowed: nodetree and list.
The XSDs for nodetree and list files are located in the /search/config/xsd folder in the CMS. The nodetree format supports infinitely deep nested nodes with id/value pairs, while the list type is flatlist with values.

Note: Using 'list' is currently not recommended because it is reported the search criteria might possibly be deselected when using paging.

Finally, the href attribute points to the source where the file is located , e.g. repository://.. or cocoon://.. , ..

layouts

The layouts element contains layout elements, which contain all the configuration needed to present the search results. If a report does not contain a specified layout or a referenced layout, a globally defined layout with attribute default=true is used as default layout.

A layout contains 4 main elements:

• summary ; generates a short summary of the search criteria in natural language

• header ; generates a header row with column names (property names)

• paging (1+) ; the paging navigational element, can be specified more than one time, e.g. at the top and bottom.

• results ; the actual search results

The summary

The optional summary element is made up of a header and 0 or more item elements.  The summary is resolved  to one line of text and is shown in the top of the search screen, unless there are no valid item elements. How does this work? Each item element contains text nodes and optional input-value elements. an item is not included in the output if it contains one ore more item elements,which 1) have an attribute required = true and 2) its value is empty. Otherwise, the item is included and thus the summary is shown. An example:

<layout id="sampleLayout" default="true">
    <summary>
      <header>You searched for documents </header>
      <item>containg the text <input-value type="user-specified" id="textsearch.all" required="true"/></item>
    </summary>
     ...
</layout>

will result in (if the user searched for the text "Hippo":

You searched for documents containing the text Hippo

Finally,within a an item, you can use the switch .. case .. default construct. See the CMS' default search configuration for more elaborate examples.

The header

The header element contains the column (property) names for the main search results. The layout of the header can be configured to meet your wishes, using the presentational elements grid, gridrow, cell and hbox (the use is similar to the use in the search form). You can use the element fieldlabel to print out the label for a property. E.g.:

<field-label ref="dav_modificationdate" sortable="true"/>

The ref attribute refers the modificationdate property in the properties configuration. The DisplayName value of the property is used as label. The optional sortable property enables sorting by clicking on a coulmn header in the GUI. If a column header with sortable = true is clicked, the DefaultSortOrder of the corresponding property is used to determine the sortorder (ascending / descending).

Paging

The paging element can be inserted one or more times anywhere in the layout as a direct child of the layout element. This will result in the paging navigation being shown in the search screen. Currently, the paging element cannot be styled.

Results

The results element configures the presentation of the search result rows and the collapsable boxes containg details per result row. The results element contains two elements: a main element containing the main information per resulting row, and a detailed element which configures the collapsable details box per result row.

The main element contains 1 or more field elements which define which property values to show per result row. The ref attribute refers to a property defined in the [properties configuration]. The field can be styled using a class attribute.

The layout of the detailed element can be, in contrast to the main element, freely configured. That means you can use the familiar grid, gridrow, etc elements, like in the search form configuration. A property value can be printed by including a field element , similar as in the previously described main element.

businesslogic

features (not fully tested yet):

• event listener capability for search form input fields
• automatic update (using Ajax) of list elements, when a master field value changes.

Overview of custom configurations

• repository://configuration/search/config.xml ; master configuration file.
• repository://configuration/search/translations/** ; contains custom i18n catalogues, e.g. messages_en.xml

• repository://configuration/search/css/custom.css ; custom CSS file