Support Menu

Coveo component Matrix

Coveo Matrix Component (CoveoMatrix)

The Matrix component uses the values of two fields (row and column) to display the results of the specified computed field in a table.

The user specifies the values to use for the columns. An IGroupByRequest operation performed at the same time as the main query retrieves the values to use for the rows.

In a way that is similar to the Facet component, selecting a Matrix cell allows the end user to drill down inside the results by restricting the row field and the column field to match the values of the selected cell.

Index

Component Options

cellFontSize

cellFontSize: string

Specifies the font-size to use for displaying text inside the cells.

This option is mainly useful to prevent a Matrix containing many columns from cropping some of its values.

However, instead of using this option to solve this kind of issue, you could also remove some of the less important columns from your Matrix or modify the CSS of your page to allow the Matrix to occupy a larger space.

Default value is ''.

Markup configuration example(s) :
data-cell-font-size='foo'

columnField

columnField: IFieldOption

Specifies the field to use for the columns.

Specifying a value for this options is required for this component to work.

Markup configuration example(s) :
data-column-field='@foo'

columnFieldValues

columnFieldValues: Array<string>

Specifies the field values to use for each column.

See also Matrix.options.columnLabels.

Default value is [], which means that the Matrix will not generate any column (except the Total column, if Matrix.options.enableRowTotals is true).

Markup configuration example(s) :
data-column-field-values='foo,foo2'

columnHeader

columnHeader: string

Specifies the label for the first column on the left as a description of the Matrix.options.columnField.

Default value is undefined.

Markup configuration example(s) :
data-column-header='foo'

columnLabels

columnLabels: Array<string>

Specifies the label values to use for each column.

Default value is []. The array set for this options should match the Matrix.options.columnFieldValues.

Markup configuration example(s) :
data-column-labels='foo,foo2'

computedField

computedField: IFieldOption

Specifies the field whose computed values you want to display in the cells.

Specifying a value for this options is required for this component to work.

Markup configuration example(s) :
data-computed-field='@foo'

computedFieldFormat

computedFieldFormat: string

Specifies how to format the values resulting from a Matrix.options.computedFieldOperation.

The Globalize library defines all available formats (see Globalize).

The most commonly used formats are:

  • c0 - Formats the value as a currency.
  • n0 - Formats the value as an integer.
  • n2 - Formats the value as a floating point with 2 decimal digits.

Default value is c0.

Markup configuration example(s) :
data-computed-field-format='foo'

computedFieldOperation

computedFieldOperation: string

Specifies the type of aggregate operation to perform on the Matrix.options.computedField.

The possible values are:

  • sum - Computes the sum of the computed field values.
  • average - Computes the average of the computed field values.
  • minimum - Finds the minimum value of the computed field values.
  • maximum - Finds the maximum value of the computed field values.

Default value is sum.

Markup configuration example(s) :
data-computed-field-operation='foo'

enableColumnTotals

enableColumnTotals: boolean

Specifies whether to add a Total row containing the total of each column.

Default value is true

Markup configuration example(s) :
data-enable-column-totals='true'
data-enable-column-totals='false'

enableHoverPreview

enableHoverPreview: boolean

Specifies whether to show a preview popup of cell results when hovering over a cell.

See also Matrix.options.previewSortCriteria, Matrix.options.previewMaxWidth, Matrix.options.previewMinWidth, Matrix.options.previewDelay and Matrix.options.previewTemplate.

Default value is true.

Markup configuration example(s) :
data-enable-hover-preview='true'
data-enable-hover-preview='false'

enableRowTotals

enableRowTotals: boolean

Specifies whether to display a Total column containing the sum of each row.

Default value is true.

Markup configuration example(s) :
data-enable-row-totals='true'
data-enable-row-totals='false'

maximumNumberOfRows

maximumNumberOfRows: number

Specifies the maximum number of rows to display in the Matrix.

Default value is 10. Minimum value is 0.

Markup configuration example(s) :
data-maximum-number-of-rows='10'

maximumNumberOfValuesInGroupBy

maximumNumberOfValuesInGroupBy: number

Specifies the maximum number of results to include in the IGroupByRequest for the columns.

This value should always be greater than the Matrix.options.maximumNumberOfRows. If it is too small, some of the results will not be displayed in the Matrix.

Default value is 100. Minimum value is 0.

Markup configuration example(s) :
data-maximum-number-of-values-in-group-by='10'

previewDelay

previewDelay: number

If Matrix.options.enableHoverPreview is true, specifies the delay (in milliseconds) before sending the query to get the preview results.

Default value is 500.

Markup configuration example(s) :
data-preview-delay='10'

previewMaxWidth

previewMaxWidth: string

If Matrix.options.enableHoverPreview is true, specifies the maximum width (in pixels) of the preview popup.

Default value is 500px.

Markup configuration example(s) :
data-preview-max-width='foo'

previewMinWidth

previewMinWidth: string

If Matrix.options.enableHoverPreview is true, specifies the minimum width (in pixels) of the preview popup.

Default value is 0.

Markup configuration example(s) :
data-preview-min-width='foo'

previewSortCriteria

previewSortCriteria: string

If Matrix.options.enableHoverPreview is true, specifies the criteria to use for sorting the results of the hover preview.

The available sort criteria values are the same as those of the IQuery.

The possible values are:

  • relevancy: Uses all configured ranking weights and any specified ranking expressions to sort the results.
  • dateascending / datedescending: Sorts the results using the @date field value, which is typically the last modification date of an item in the index.
  • qre: Sorts the results using only the weights applied by ranking expressions. Using qre is much like using relevancy, except that qre does not compute automatic weights, such as weights based on keyword proximity.
  • nosort: Does not sort the results. Using nosort returns the items in an essentially random order.
  • fieldascending / fielddescending: Sorts the results using the value of a custom field.
  • fieldascending / fielddescending: Sorts the results using the value of a custom field.

See also Matrix.options.previewSortField.

Default value is FieldDescending.

Markup configuration example(s) :
data-preview-sort-criteria='foo'

previewSortField

previewSortField: IFieldOption

If Matrix.options.previewSortCriteria is fieldascending or fielddescending, specifies the field to use for sorting the results of the hover preview.

Default value is the value of Matrix.options.computedField.

Markup configuration example(s) :
data-preview-sort-field='@foo'

previewTemplate

previewTemplate: Template

If Matrix.options.enableHoverPreview is true, specifies the template ID or CSS selector of the template to use to render the results of the hover preview.

You must use either data-template-id or data-template-selector in the markup to specify a value for this option.

Examples:

Specifying what template to use by referring to its template ID:

<div class='CoveoMatrix' data-template-id='TemplateId'></div>

Specifying what template to use by referring to its CSS selector:

<div class='CoveoMatrix' data-template-selector='.templateSelector'></div>

rowField

rowField: IFieldOption

Specifies the field to use for the rows.

Specifying a value for this options is required for this component to work.

Markup configuration example(s) :
data-row-field='@foo'

sortCriteria

sortCriteria: string

Specifies the criteria to use for sorting the rows.

See IGroupByRequest.sortCriteria for the list of possible values.

Default value is ComputedFieldDescending.

Markup configuration example(s) :
data-sort-criteria='foo'

title

title: string

Specifies the text to display at the top of the Matrix.

Markup configuration example(s) :
data-title='foo'

Methods

debugInfo

  • debugInfo(): any

disable

  • disable(): void
  • Disable the component. Normally this means that the component will not execute handlers for the framework events (query events, for example). Component are enabled by default on creation.

    Returns void

enable

  • enable(): void
  • Enable the component. Normally this means that the component will execute handlers for the framework events (query events, for example). Components are enabled by default on creation.

    Returns void

getBindings

getCellElement

  • getCellElement(rowNumber: number, columnNumber: number): HTMLElement
  • Gets the HTMLElement associated to a cell.

    Parameters

    • rowNumber: number

      The row number of the cell.

    • columnNumber: number

      The column number of the cell.

    Returns HTMLElement

    The associated HTMLElement.

getCellValue

  • getCellValue(rowNumber: number, columnNumber: number): string
  • Gets the string associated to a cell.

    Parameters

    • rowNumber: number

      The row number of the cell.

    • columnNumber: number

      The column number of the cell.

    Returns string

    The associated string.

getSelectedColumnValue

  • getSelectedColumnValue(): string

getSelectedRowValue

  • getSelectedRowValue(): string

selectCell

  • selectCell(rowNumber: number, columnNumber: number): void
  • Selects a cell by its row and column number. Does not execute a query.

    Parameters

    • rowNumber: number

      The row number of the cell to select.

    • columnNumber: number

      The column number of the cell to select.

    Returns void

Static get

  • get(element: HTMLElement, componentClass?: any, noThrow?: boolean): BaseComponent
  • Get the bound component to the given HTMLElement. Throws an assert if the HTMLElement has no component bound, unless using the noThrow argument.
    If there is multiple component bound to the current HTMLElement, you must specify the component class.

    Parameters

    • element: HTMLElement

      HTMLElement for which to get the bound component.

    • Optional componentClass: any

      Optional component class. If the HTMLElement has multiple components bound, you must specify which one you are targeting.

    • Optional noThrow: boolean

      Boolean option to tell the method to not throw on error.

    Returns BaseComponent

Properties

bind

Allows the component to bind events and execute them only when it is enabled.

type

{Coveo.ComponentEvents}

componentOptionsModel

componentOptionsModel: ComponentOptionsModel

Contains the state of options for differents component. Mainly used by ResultLink.

componentStateModel

componentStateModel: ComponentStateModel

Contains the state of different component (enabled vs disabled). Allows to get/set values. Trigger component state event when modified. Each component can listen to those events.

data

data: Cell[]

Holds the data for the Matrix.

disabled

disabled: boolean

A disabled component will not participate in the query, or listen to ComponentEvents.

type

{boolean}

logger

logger: Logger

Allows component to log in the dev console.

queryController

queryController: QueryController

Contains the singleton that allows to trigger queries.

queryStateModel

queryStateModel: QueryStateModel

Contains the state of the query. Allows to get/set values. Trigger query state event when modified. Each component can listen to those events.

root

root: HTMLElement

A reference to the root HTMLElement (the SearchInterface).

searchInterface

searchInterface: SearchInterface

A reference to the root of every component, the SearchInterface.

selectedColumnValue

selectedColumnValue: any

The currently selected column value, or undefined if nothing is selected.

selectedRowValue

selectedRowValue: string

The currently selected row value, or undefined if nothing is selected.

usageAnalytics

usageAnalytics: IAnalyticsClient

A reference to the Analytics.client.

Static ID

ID: string

The static ID that each component need to be identified.
For example, SearchButton -> static ID : SearchButton -> className : CoveoSearchButton

Constructors

constructor

  • Creates a new Matrix. Also verifies whether options are valid and coherent. Binds query events.

    Parameters

    • element: HTMLElement

      The HTMLElement on which to instantiate the component.

    • Optional options: IMatrixOptions

      The options for the Matrix component.

    • Optional bindings: IComponentBindings

      The bindings that the component requires to function normally. If not set, these will be automatically resolved (with a slower execution time).

    Returns Matrix