Ignite UI™ API Documentation

ui.igGridCellMerging

Merged cell feature of the igGrid allows you to combine cells in a column that are next to each other and have the same values. This is very useful after a column is sorted, because the cells that have the same values are merged.

The following code snippet demonstrates how to initialize the igGrid control.

Click here for more information on how to get started using this API. For details on how to reference the required scripts and themes for the igGrid control read, Using JavaScript Resources in Ignite UI and Styling and Theming Ignite UI.

Code Sample

<!doctype html>
<html>
<head>
    <!-- jQuery Core -->
    <script src="js/jquery.js" type="text/javascript"></script>
    <!-- jQuery Mobile -->
    <script src="js/jquery.mobile.js" type="text/javascript"></script>
    <!-- Moderznizr -->
    <script src="js/modernizr.js" type="text/javascript"></script>
    <!-- jQuery UI -->
    <script src="js/jquery-ui.js" type="text/javascript"></script>
    <!-- Infragistics Loader Script -->
    <script src="js/infragistics.loader.js" type="text/javascript"></script>    
    <!-- Infragistics Loader Initialization -->
    <script type="text/javascript">
        $.ig.loader({
            scriptPath: 'js/',
            cssPath: 'css/',
            resources: 'igGrid.CellMerging.Sorting.Updating'
        })
         
        var productData = [
            { "ProductID": "1", "UnitsInStock": "100", "ProductDescription": "Laptop", "UnitPrice": "$ 1000" , "DateAdded": new Date() },
            { "ProductID": "2", "UnitsInStock": "15", "ProductDescription": "Hamburger", "UnitPrice": "$ 10", "DateAdded": new Date() },
            { "ProductID": "3", "UnitsInStock": "4356", "ProductDescription": "Beer", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "4", "UnitsInStock": "32", "ProductDescription": "mobile phone", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "5", "UnitsInStock": "65", "ProductDescription": "trainers", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "6", "UnitsInStock": "25", "ProductDescription": "coffee cup", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "7", "UnitsInStock": "98", "ProductDescription": "BMW 323 CI", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "8", "UnitsInStock": "998", "ProductDescription": "mouse", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "9", "UnitsInStock": "43", "ProductDescription": "keyboard", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "10", "UnitsInStock": "69", "ProductDescription": "fish", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "11", "UnitsInStock": "100", "ProductDescription": "Laptop", "UnitPrice": "$ 1000" , "DateAdded": new Date() },
            { "ProductID": "12", "UnitsInStock": "15", "ProductDescription": "Hamburger", "UnitPrice": "$ 10", "DateAdded": new Date() },
            { "ProductID": "13", "UnitsInStock": "4356", "ProductDescription": "Beer", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "14", "UnitsInStock": "32", "ProductDescription": "mobile phone", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "15", "UnitsInStock": "65", "ProductDescription": "trainers", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "16", "UnitsInStock": "25", "ProductDescription": "coffee cup", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "17", "UnitsInStock": "98", "ProductDescription": "BMW 323 CI", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "18", "UnitsInStock": "998", "ProductDescription": "BMW 323 CI", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "19", "UnitsInStock": "43", "ProductDescription": "keyboard", "UnitPrice": "$ 1000", "DateAdded": new Date() },
            { "ProductID": "20", "UnitsInStock": "69", "ProductDescription": "fish", "UnitPrice": "$ 1000", "DateAdded": new Date() },
        ];
         
        $.ig.loader(function () {
            $("#grid1").igGrid({
                dataSource: productData,
                responseDataKey: "ProductID",
                fixedFooters: false,
                fixedHeaders: true,
                virtualization: false,
                autoGenerateColumns: false,
                width: 600,
                defaultColumnWidth: 140,
                columns: [
                    { headerText: "Product ID", key: "ProductID", dataType: "number", width: 100},
                    { headerText: "Units in Stock", key: "UnitsInStock", dataType: "number", width: 150},
                    { headerText: "Product Description", key: "ProductDescription", dataType: "string", width: 150},
                    { headerText: "Unit Price", key: "UnitPrice", dataType: "string", width: 150 }
                ],
                features: [
                    {
                        name: "CellMerging",
                        initialState: "merged"
                    },
                    {
                        name: "Sorting",
                        type: "local",
                        mode: "multiple"
                    }
                ]
            });
        });
    </script>
</head>
<body>
    <table id="grid1"></table>
</body>

Related Samples

Cell Merging (igGrid)

columnSettings

Type:: array
Default:: []
Elements Type:: object

A list of column settings that specifies hiding options on a per column basis.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            columnSettings: [
                { columnKey: "ProductID", mergeOn: "always" }
            ]
        }
    ]
});
//Get
var columnSettings = $(".selector").igGridCellMerging("option", "columnSettings");

columnIndex

Type:: number
Default:: -1

Column index. This is a required property in every column setting if columnKey is not set.

Code Sample

//Initialize
$(".selector").({
    features: [
        {
            name: "CellMerging",
            columnSettings: [
                { columnIndex: 0, mergeOn: "always" }
            ]
        }
    ]
});

columnKey

Type:: string
Default:: null

Column key. This is a required property in every column setting if columnIndex is not set.

Code Sample

//Initialize
$(".selector").({
    features: [
        {
            name: "CellMerging",
            columnSettings: [
                { columnKey: "ProductID", mergeOn: "always" }
            ]
        }
    ]
});

mergeOn

Type:: enumeration
Default:: sorting

Defines when merging should be applied.

Members

sorting
Type:string
The column will only be merged when sorted.
always
Type:string
The column will always be merged.
never
Type:string
No merging will be applied.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            columnSettings: [
                { columnKey: "ProductID", mergeOn: "always" }
            ]
        }
    ]
});

mergeStrategy

Type:

enumeration

Default:

duplicate
Defines the rules merging is based on.
Members
- duplicate
- Type:string
- Duplicate values in the column will be merged together.
- null
- Type:string
- Merging will be applied for each subsequent null value after a non-null value.
- function
- type="function|string" Merging will be applied based on the provided function (either by reference or by name in which case it should be available as property of window). The function takes arguments 'prevRecord' (the previous record in the chain), 'curRecord' (the current record in the chain) and 'columnKey' which is the key of the column the merging is currently being executed for.
Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            mergeOn: "always"
        }
    ]
});;

inherit

Type:

bool

Default:

false

Enables/disables feature inheritance for the child layouts. NOTE: It only applies for igHierarchicalGrid.

language
Inherited

Type:: string
Default:: "en"

Set/Get the locale language setting for the widget.

Code Sample

    //Initialize
$(".selector").igGridCellMerging({
    language: "ja"
});
 
// Get
var language = $(".selector").igGridCellMerging("option", "language");
 
// Set
$(".selector").igGridCellMerging("option", "language", "ja");

locale
Inherited

Type:: object
Default:: null

Set/Get the locale setting for the widget.

Code Sample

    //Initialize
$(".selector").igGridCellMerging({
    locale: {}
});
 
// Get
var locale = $(".selector").igGridCellMerging("option", "locale");
 
// Set
$(".selector").igGridCellMerging("option", "locale", {});

mergeOn

Type:: enumeration
Default:: sorting

Defines when merging should be applied.

Members

sorting
Type:string
Only sorted columns will have merging applied.
always
Type:string
Merging will be applied to all columns always.
never
Type:string
No merging will be applied.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            mergeOn: "always"
        }
    ]
});
//Get
var mergeOn = $(".selector").igGridCellMerging("option", "mergeOn");
//Set
$(".selector").igGridCellMerging("option", "mergeOn", "always");

mergeRows

Type:: enumeration
Default:: false

Defines the whether the rows will be merged or not.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            mergeRows: true
        }
    ]
});
//Get
var mergeRows = $(".selector").igGridCellMerging("option", "mergeRows");
//Set
$(".selector").igGridCellMerging("option", "mergeRows", false);

mergeStrategy

Type:: enumeration
Default:: duplicate

Defines the rules merging is based on.

Members

duplicate
Type:string
Duplicate values in the column will be merged together.
null
Type:string
Merging will be applied for each subsequent null value after a non-null value.

function
type="function|string" Merging will be applied based on the provided function (either by reference or by name in which case it should be available as property of window). The function takes arguments 'prevRecord' (the previous record in the chain), 'curRecord' (the current record in the chain) and 'columnKey' which is the key of the column the merging is currently being executed for.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            mergeStrategy: "null"
        }
    ]
});
//Get
var mergeStrategy = $(".selector").igGridCellMerging("option", "mergeStrategy");
//Set
$(".selector").igGridCellMerging("option", "mergeStrategy", "null");

mergeType

Type:: enumeration
Default:: visual

Defines the type of merging.

Members

visual
Type:string
the grid cells will be merged only visually.
physical
Type:string
the grid cell will be merged physically throughout rowspan.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            mergeType: "physical"
        }
    ]
});
//Get
var mergeType = $(".selector").igGridCellMerging("option", "mergeType");

regional
Inherited

Type:: enumeration
Default:: defaults

Set/Get the regional setting for the widget.

Code Sample

//Initialize
$(".selector").igGridCellMerging({
    regional: "ja"
});
// Get
var regional = $(".selector").igGridCellMerging("option", "regional");
// Set
$(".selector").igGridCellMerging("option", "regional", "ja");

rowMergeStrategy

Type:: enumeration
Default:: duplicate

Defines the rules merging is based on.

Members

duplicate
Type:string
Duplicate values in the column will be merged together.
null
Type:string
Merging will be applied for each subsequent null value after a non-null value.

function
type="function|string" Merging will be applied based on the provided function (either by reference or by name in which case it should be available as property of window). The function takes arguments 'columnKey1' (the column key of the first cell), 'columnKey2' (the column key of the second cell) and 'record' which is the current record for which the merge is being executed.

Code Sample

//Initialize
$(".selector").({
    features : [
        {
            name : "CellMerging",
            rowMergeStrategy: "null"
        }
    ]
});
//Get
var rowMergeStrategy = $(".selector").igGridCellMerging("option", "rowMergeStrategy");
//Set
$(".selector").igGridCellMerging("option", "rowMergeStrategy", "null");

For more information on how to interact with the Ignite UI controls' events, refer to
Using Events in Ignite UI.

Note: Calling API methods programmatically does not raise events related to their operation unless specifically stated otherwise by the corresponding API documentation; those events are only raised by their respective user interaction.

Show Details

cellsMerged

Cancellable:: false

evt
Type: Event

JQuery event object.
ui
Type: Object

Code Sample

//Bind after initialization
$(document).on("iggridcellmergingcellsmerged", ".selector", function (evt, ui) {
    //return the triggered event
    evt;
 
    // Gets reference to the igGridCellMerging widget.
    ui.owner;
 
    // Gets reference to the igGrid the igGridCellMerging is initialized for.
    ui.owner.grid;
 
    // Gets a reference to the row the merged group starts in if available in the DOM.
    ui.row;
 
    // Gets the data index of the row the merged group starts in.
    ui.rowIndex;
 
    // Gets the PK of the row the merged group starts in if available.
    ui.rowId;
 
    // Gets the column key the merge is being executed for.
    ui.columnKey;
 
    // Gets the first record in the merging chain that the merge is executed for (only for vertical merging).
    ui.firstRecord;
 
    // Gets the column key of the first column, where the merging starts (only for horizontal merging).
    ui.firstColumnKey;
 
    // Gets the last record in the merging chain that the merge is executed for.
    ui.record;
 
    // Get the total count of cells that were merged.
    ui.count;
 
    // Gets the type of merging that is executed
    ui.orientation;
 
});
 
//Initialize
$(".selector").igGrid({
    features : [
        {
            name : "CellMerging",
            cellsMerged: function(evt, ui){ ... }
        }
    ]
});

cellsMerging

Cancellable:: true

Event fired before a new merged cells group is created.

evt
Type: Event

JQuery event object.
ui
Type: Object

Code Sample

//Bind after initialization
$(document).on("iggridcellmergingcellsmerging", ".selector", function (evt, ui) {
    //return the triggered event
    evt;
 
    // Gets reference to the igGridCellMerging widget.
    ui.owner;
 
    // Gets reference to the igGrid the igGridCellMerging is initialized for.
    ui.owner.grid;
 
    // Gets a reference to the row the merged group starts in if available in the DOM.
    ui.row;
 
    // Gets the data index of the row the merged group starts in.
    ui.rowIndex;
 
    // Gets the PK of the row the merged group starts in if available.
    ui.rowId;
 
    // Gets the column key the merge is being executed for.
    ui.columnKey;
 
    // Gets the first record in the merging chain that the merge is executed for (only for vertical merging).
    ui.firstRecord;
 
    // Gets the column key of the first column, where the merging starts (only for horizontal merging).
    ui.firstColumnKey;
 
    // Gets the next record in the merging chain that the merge is executed for.
    ui.record;
 
    // Gets the type of merging that is executed
    ui.orientation;
 
});
 
//Initialize
$(".selector").igGrid({
    features : [
        {
            name : "CellMerging",
            cellsMerging: function(evt, ui){ ... }
        }
    ]
});

Show Details

changeLocale
Inherited

.igGridCellMerging( "changeLocale", $container:object );
Changes the all locales contained into a specified container to the language specified in options.language
Note that this method is for rare scenarios, use language or locale option setter.
- $container
- Type:object
- Optional parameter - if not set it would use the element of the widget as $container.
Code Sample

$(".selector").igGridCellMerging("changeLocale");
destroy

.igGridCellMerging( "destroy" );
Removes all igGridCellMerging UI changes and destroys the widget.
Code Sample

$(".selector").igGridCellMerging("destroy");
isMerged

.igGridCellMerging( "isMerged", column:object );

Return Type:

bool

Return Type Description:

Returns 'true' if the column is merged and 'false' otherwise.
Returns the merge state of a column.
- column
- Type:object
- The column index or column key to get the state for.
Code Sample

var isMerged = $(".selector").igGridCellMerging("isMerged", "ProductNumber");
mergeColumn

.igGridCellMerging( "mergeColumn", column:object, raiseEvents:bool );

Return Type:

jquery

Return Type Description:

Returns the widget element.
Merges the specified column unless it is already merged.
- column
- Type:object
- The column index or column key to merge.
- raiseEvents
- Type:bool
- Specifies if the operation should raise merging-related events.
Code Sample

$(".selector").igGridCellMerging("mergeColumn", "ProductNumber", false);
mergeRow

.igGridCellMerging( "mergeRow", id:object, fireEvents:object );
- id
- Type:object
- fireEvents
- Type:object
unmergeColumn

.igGridCellMerging( "unmergeColumn", column:object );

Return Type:

jquery

Return Type Description:

Returns the widget element.
Restores the column to its unmerged state. Does nothing if the column is not merged.
- column
- Type:object
- The column index or column key to unmerge.
Code Sample

$(".selector").igGridCellMerging("unmergeColumn", "ProductNumber");
unmergeRow

.igGridCellMerging( "unmergeRow", id:object, index:object );
- id
- Type:object
- index
- Type:object

ui-iggrid-mergedcell

Classes applied to every cell of a visually merged group.
ui-iggrid-mergedcellsbottom

Classes applied to the bottom cell of a visually merged group.
ui-iggrid-mergedcellstop

Classes applied to the top cell of a visually merged group.
ui-iggrid-physicalmergedcell

Classes applied to every cell of a physically merged group.

Ignite UI for jQuery | API Reference

ui.igGridCellMerging

Code Sample

Related Samples

Related Topics

Dependencies

Inherits