ui.igGridCellMerging

ui.igGridCellMerging_image

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

Related Topics

Dependencies

jquery-1.9.1.js
jquery.ui.core.js
jquery.ui.widget.js
infragistics.util.js
infragistics.ui.widget.js
infragistics.datasource.js
infragistics.ui.grid.framework.js
infragistics.ui.shared.js

Inherits

  • 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

        • owner
          Type: Object

          Gets reference to igGridCellMerging.

        • owner.grid
          Type: Object

          Gets a reference to the igGrid the igGridCellMerging are initialized for.

        • row
          Type: jQuery

          Gets a reference to the row the merged group starts in if available in the DOM.

        • rowIndex
          Type: Number

          Gets the data index of the row the merged group starts in.

        • rowId
          Type: Unknown

          Gets the PK of the row the merged group starts in if available.

        • columnKey
          Type: String

          Gets the column key the merge is being executed for.

        • firstRecord
          Type: Object

          Gets the first record in the merging chain that the merge is executed for.

        • record
          Type: Object

          Gets the last record in the merging chain that the merge is executed for.

        • count
          Type: Number

          Gets the total count of cells that were merged.

    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

        • owner
          Type: Object

          Gets reference to igGridCellMerging.

        • owner.grid
          Type: Object

          Gets a reference to the igGrid the igGridCellMerging are initialized for.

        • row
          Type: jQuery

          Gets a reference to the row the merged group starts in if available in the DOM.

        • rowIndex
          Type: Number

          Gets the data index of the row the merged group starts in.

        • rowId
          Type: Unknown

          Gets the PK of the row the merged group starts in if available.

        • columnKey
          Type: String

          Gets the column key the merge is being executed for.

        • firstRecord
          Type: Object

          Gets the first record in the merging chain that the merge is executed for.

        • record
          Type: Object

          Gets the next record in the merging chain that the merge is executed for.

    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){ ... }
    						}
    					]
    				});
    			 
  • 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.

Copyright © 1996 - 2019 Infragistics, Inc. All rights reserved.