Expand All

Basics

Formatting

Context menu

Drag n Drop

Spreadsheet

Tabs

Export

Layouts

RTL Layout

Rows

Paging

Big data

Columns

Cells

Inline editing

Row Grouping

Pivot

Sorting

Filter

Selections

Nesting / Row details

Tree grid

Charts

Angular

React React

Vue Vue

Knockout

;

Rich Objects

Overview

Introduced in v11.0.0, Rich Objects are plain objects used to define the behavior of rich content in cells— such as hyperlinks, images or rich media—throughout their lifecycle in PQGrid at a single place.

Rich Objects support the following key operations:

  • Rendering: Customize how the cell is visually displayed.
  • Editing: Define custom editors and retrieve data from them.
  • Clipboard Operations: Control copy-paste behavior for structured content.
  • Import/Export: Manage data exchange with external formats such as CSV, HTML, PDF, XLSX, etc.
  • Storage: Their instances can be persisted locally in browser or remotely in database.

Rich Objects are defined in the namespace pq.RichObjs. There are 2 inbuilt objects: pq.RichObjs.Link and pq.RichObjs.Pic

  • Inbuilt Rich Objects can be customized
  • New objects can be defined from scratch comforming to the interface and added to pq.RichObjs.

Instance Data Handling in Rich Objects (RO)

  • Render Object (RO) is a plain object composed mainly of static methods, so it doesn't store data for individual instances in itself.
  • Instead instance-specific data for each cell is stored in corresponding rowData.pq_cellprop[ dataIndx ]
  • This data is passed back and forth between the grid and RO methods during a cell lifecycle.

Interface API

A Rich object extends pq.RichObj and provides concrete implementations for these methods or properties to handle specific types of operations of a cell in PQGrid.

Rendering method

  1. render: Defines how the rich cell content is displayed, takes in same arguments and returns same value as column.render callback. 

    /**
* @method render
* @returns {string|Object} - Returns a plain string, HTML string or an object 
specifying styles, attributes, or classes.
*/
render( ui ) {}

Editing methods

  1. editor: Defines a custom editor, it uses and returns same properties as the column.editor in pqgrid.

    /**
* @property editor ( optional )
* @type {Object} - object specifying type of editor, initialization function, etc             
*/
editor = {
    type: '...',
    init: function( ui ){}
}

  2. getEditorVal: Extracts the Rich Object (RO) cell data from the custom editor in a standardized format.

    /**
 * @method getEditorVal (optional)
 * @param {Node} editor - The root container of the custom editor.
 * @returns {Object}
 */
getEditorVal(editor) {
    return {
        // Primitive value such as string, number, or boolean
        //stored in rowData[ dataIndx ]
        val: ...,
        // Additional data for the RO instance, passed as key-value pairs
        //stored in rowData.pq_cellprop[ dataIndx ]
        prop: { ... }
    };
}

Export to htm, csv, xlsx, pdf

  1. compareKeys: Name of properties which are used for comparison between cut and pasted cells.

    /**
* @property compareKeys
* @type {Array} - Name of properties which are compared while cut paste of cells.
*/
static compareKeys = []

  2. toExport: Prepares the cell content for export in different formats. This method can be either synchrnous or asynchronous. All the exported data is added to the cell object. 

    /**
* @method toExport (optional)     
* @param {Object} cell - cell to be exported as js workbook, or js object ( for other formats )
* @param {string} format - The target export format (e.g., 'wb', 'pdf', 'csv', 'htm', 'js', etc ).
*/    
async toExport(cell, format) {}

Copy to clibboard

  1. toHtml: Converts the class data into an HTML format for clipboard operations. This method can be either synchrnous or asynchronous. toString is used if this method is not implemented. 

    /**
* @method toHtml (optional)
* @returns {string} - Returns an HTML string
*/
async toHtml() {}

  2. toString: Defines string representation of the cell’s value, also used for clipboard operation if toHtml is not implemented. 

    /**
* @method toString
* @returns {string} - Returns string
*/
toString() {}

Import from js workbook / xlsx

  1. toImport: Converts imported cell from js workbook into a new instance of RenderCell.

    /**
* @method toImport ( optional)
* @param {Object} cell - The imported cell from a js workbook.
* @returns {RenderCell} - Returns a new Render Object populated from imported value.
*/
toImport( cell ) {}

Pasted cell to RO object instance

  1. toObject: Parses clipboard data cooresponding to a cell into a RenderCell instance.

    /**
* @method toObject (static, optional)
* @description 
* @param {string} val - cell data extracted from pasted clipboard data.
* @returns {RenderCell|undefined} - Returns a new instance if conversion is successful, otherwise undefined.
*/
static toObject(val) {}

Publish

After defining a Rich Object, it can be published for all grids by adding it to pq.RichObjs object

Use in grid cells

Rich objects can be used or added in grid cells in 2 ways:

  • directly define in rowData.pq_cellprop[ dataIndx ] of grid data 
        data[0][4] = 'Content/pics/cube.gif'
    data[0].pq_cellprop = {
        4: {
            inst: 'Pic',
            width: 100
        }                
    }

  • or add via grid.updateRow or grid.addRow method

    grid1.updateRow({
    newRow: {
        1: {
            val: 'ParamQuery API',
            style: {
                background: "#ff9999"
            },
            prop: {
                inst: 'Link', //Rich object
                link: '../api'
            }
        }
    },
    rowIndx: 1
})

Note: The prop.inst property marks a cell as a Rich Object. The value of prop.inst is used as a key to look up the corresponding definition in pq.RichObjs[name]. This allows the grid to associate the cell with a predefined rich object type and render it accordingly.