Working with GridJs Client Side

We developed GridJs client based on x-spreadsheet.

the main steps are:

create x_spreadsheet instance

xs = x_spreadsheet(id, options)
    // the parameters are:
    id:the html node id ,for example :'#gridjs-demo' for the html  <div id="gridjs-demo"></div>
    options: the load options
     

for example the below code init a gridjs_spreadsheet object.
	xs = x_spreadsheet('#gridjs-demo', {
			updateMode:'server',
			updateUrl:'/GridJs2/UpdateCell',
			mode: 'edit',
			showToolbar: true,
                        local: 'en',
			showContextmenu: true
			})

the parameters for load options:

Parameter	Description	Default Value	Optional
`allowSelectTextInTextBoxInReadMode`	Whether to allow text selection in TextBox controls when in read-only mode. The default value is `false`.	`false`	Yes
`checkSyntax`	Whether to perform syntax checking and spell correction for user input in text content. Works with `setSyntaxCheckUrl`. The default value is `false`.	`false`	Yes
`isCollaborative`	Whether to enable collaborative mode.	`false`	Yes
`loadingGif`	The URL of the loading GIF to display when loading images or shapes. The default value is `content/img/updating.gif`.	`content/img/updating.gif`	Yes
`local`	Sets localization information for menus and toolbars, supporting multiple languages. Possible values include: - `en`, `zh`, `es`, `pt`, `de`, `ru`, `nl` (for English, Chinese, Spanish, Portuguese, German, Russian, Dutch) - `ar`, `fr`, `id`, `it`, `ja` (for Arabic, French, Indonesian, Italian, Japanese) - `ko`, `th`, `tr`, `vi`, `cht` (for Korean, Thai, Turkish, Vietnamese, Traditional Chinese)	`en`	Yes
`mode`	Can be `read` or `edit`; `read` means a read-only spreadsheet, and `edit` means the spreadsheet can be edited.	None	No
`searchHighlightColor`	The highlight background color for search terms. The color must include an alpha channel for transparency.	`#dbe71338`	Yes
`showAutofilter`	Whether to show the AutoFilter button. The default value is `true`.	`true`	Yes
`showBottombarStats`	Whether to show the bottom bar statistics. The default value is `true`.	`true`	Yes
`showCheckSyntaxButton`	Whether to show syntax checking and spell correction buttons in the toolbar. The default value is `false`.	`false`	Yes
`showContextmenu`	Whether to show the context menu on right-clicking a cell. The default value is `true`.	`true`	Yes
`showFileName`	Whether to show the filename.	`true`	Yes
`showFormulaExplain`	Whether to show formula explanations applied to this cell when the mouse hovers over it. Works together with `setFormulaExplainUrl`. The default value is `false`.	`false`	Yes
`showFormulaTip`	Whether to show the existing formula applied to this cell when the mouse hovers over it. The default value is `false`.	`false`	Yes
`showNonEditableSymbolInCell`	Whether to show a client-side non-editable symbol in the cell. If set to `true`, after clicking the “Disable editing” option in the context menu, the selected area that disables editing will show the symbol. The default value is `false`.	`false`	Yes
`showRowAppenderToolbar`	Whether to show the batch row appender toolbar. The default value is `true`.	`true`	Yes
`showToolbar`	Whether to show the toolbar.	`true`	Yes
`token`	Sets the authentication token. When the token is not `null`, the `Authorization: Bearer {token}` header will be automatically added to the request headers. You can use `xs.refreshToken(token)` to set a new token.	None	Yes
`updateMode`	The update mode. Currently, only `server` is supported.	`server`	No
`updateUrl`	The server-side URL for update actions based on JSON.	None	No
`view`	Sets the view size for the sheet, e.g., `{width: () => 1000, height: () => 500}`. The default is `{width: () => document.documentElement.clientWidth, height: () => document.documentElement.clientHeight}`.	`{width: () => document.documentElement.clientWidth, height: () => document.documentElement.clientHeight }`	Yes

load with json data

xs.loadData(data)
// the parameters is:
	data: the json data which describ the data structure for the worksheets

set active sheet by sheetname

xs.setActiveSheetByName(sheetname)
// the parameters is:
	sheetname: the sheet name

set active sheet by id

xs.setActiveSheet(id)
// the parameters is:
	sheetname: the sheet id

set active cell

xs.setActiveCell(row,col);
// the parameters are:
	row: the cell row
	col: the cell column

set active for multiple instances

xs.setActiveForMultipleInstance(isacitve);
// the parameters are:
	isacitve: whether need to do edit operation at this xs instanse 
// when there are more than one GridJs instances in one page, we need to call this method.
// we only support do edit operation for one instances at a page.
// for example,if we have two instances: xs1 and xs2 in one html page.
// if we need to keep edit operation in xs1,
// we shall call:
xs1.setActiveForMultipleInstance(true);
xs2.setActiveForMultipleInstance(false);

// if we need not do any edit operation for both,
// we shall call:
xs1.setActiveForMultipleInstance(false);
xs2.setActiveForMultipleInstance(false);

set custom toast

xs.customToast(customToastFunction);
// the parameter is:
	customToastFunction: user defined function to toast message,it shall have three parameters :title, content,callback
	if set to null,it will use the default build-in toast.
	 
    for example: 
            function myCustomToast(title, content, callback) {
	    //.....
	    }
            xs.customToast(myCustomToast);

set info for shape/images operation for server side action

xs.setImageInfo(imageGetActionUrl, imageAddByUploadActionUrl, imageAddByUrlActionUrl, imageCopyActionUrl, zindex, loadingGif);
// the parameters are:
	imageGetActionUrl: the get image action URL in the server side controller
	imageAddByUploadActionUrl: the upload image action  URL in the server side controller
	imageAddByUrlActionUrl: the add image from URL action  URL in the server side controller
	imageCopyActionUrl: the copy image action  URL in the server side controller
	zindex: the minimum zindex of the image in the canvas
	loadingGif: the loading gif url when loading the image/shape .it is optional,the default value is:content/img/updating.gif
    for example: 
            const imageurl = "/GridJs2/imageurl";
            const imageuploadurl1 = "/GridJs2/AddImage";
            const imageuploadurl2 = "/GridJs2/AddImageByURL";
            const imagecopyurl = "/GridJs2/CopyImage";  
            const basiczorder = 5678;
    xs.setImageInfo(imageurl, imageuploadurl1, imageuploadurl2, imagecopyurl, basiczorder);

set info for download operation for server side action

xs.setFileDownloadInfo(downloadActionUrl);
// the parameters are:
	downloadActionUrl: the get download file action URL in the server side controller
	 
    for example: 
            const fileDownloadUrl = "/GridJs2/Download";
            xs.setFileDownloadInfo(fileDownloadUrl);

set info for ole object operation for server side action

xs.setOleDownloadInfo(oleActionUrl);
// the parameters are:
	oleActionUrl: the ole object file action URL in the server side controller
    for example: 
            const oleDownloadUrl = "/GridJs2/Ole";
            xs.setOleDownloadInfo(oleDownloadUrl);

set info for syntax checking & spell correction operation for server side action

xs.setSyntaxCheckUrl(checkUrl);
// the parameters are:
	checkUrl: the  syntax checking & spell correction operation action URL in the server side controller
    for example: 
            const checkurl = "/GridJs2/CheckSyntax";
            xs.setSyntaxCheckUrl(checkurl);

set info for formula explanation for server side action

xs.setFormulaExplainUrl(formulaExplainUrl);
// the parameters are:
	formulaExplainUrl: the  formula explanation  action URL in the server side controller
    for example: 
            const formulaExplainUrl = "/GridJs2/FormulaExplain";
            xs.setFormulaExplainUrl(formulaExplainUrl);

other useful apis

Render the view

xs.reRender()

Get active sheet id

xs.getActiveSheet()

Add a new worksheet

xs.addSheet(name,isactive,tabcolor,fontcolor)
// the parameters are:
	name:the sheet name
	isactive:whether set this sheet as active sheet
	tabcolor:the background color for the sheet in the tab bottom menu
	fontcolor:the font color for the sheet name in the tab bottom menu
   for example:
    xs.addSheet('hello',true,'#12ee5b','#2c5d3b')

Modify the sheet name

xs.modifySheetName(oldName,newName)
// the parameters are:
	oldName:the sheet name
	newName:the new desired name
   for example:
     xs.modifySheetName('Sheet1','student');

Delete the sheet

xs.deleteSheet(name)
// the parameters is:
	name:the sheet name
   for example:
        xs.deleteSheet('Sheet1');

Set Zoom level

xs.setZoomLevel(zoom)
// the parameters is:
	zoom:the zoom level ,can be number ,for example 0.5 for zoom out, or 2 for zoom in

Set FileName

xs.setFileName(name)
// the parameters is:
	name:the file name with extension ,for example trip.xlsx

Set function call before save

xs.setBeforeSaveFunction(func)
// the parameters is:
	func:This function is called before the save action. If it returns true, the save will proceed; otherwise, the save will not proceed.
   for example:
	xs.setBeforeSaveFunction(()=>{console.log('hello before save');return true;});

Callback function for email sending feature.

xs.setEmailSendCallFunction(callback)
// the parameters is:
	callback: the callback function to handle email sending, receives a mailObj parameter
		callback: function(mailObj) {
			// mailObj properties:
			// mailObj.receiver: the email address of the receiver, e.g., 'example@gmail.com'
			// mailObj.type: the format of the file to be sent, can be 'html', 'xlsx', or 'pdf'
		}

whether to enable window key event for GridJs

xs.enableKeyEvent(isenable)
// the parameters is:
	isenable:whether the window key event is active for GridJs
//when has other controls in the same page, you may want to ignore the key event in GridJs

unbind all events attached to GridJs,including window key event and window resize event.

xs.destroy()

setup the collaborative settings in collaborative mode,make sure setCollaborativeSetting before setUniqueId

xs.setCollaborativeSetting(url,wsendpoint,wsapp,wsuser,wstopic)
    //the parameters are:
         url: the basic action URL in the server side controller to get history messages ,the default is '/GridJs2/msg'
	 wsendpoint: the websocket endpoint in the server side , the default is '/ws'
	 wsapp: the websocket destinations prefixed with "/app", the default is '/app/opr'
	 wsuser: the websocket for user-specific queues prefixed with "/usr", the default is '/user/queue'
	 wstopic: the websocket destinations prefixed with "/topic", the default is '/topic/opr'

set visible filter for image/shape

xs.setVisibleFilter((sheet,s) =>{})
    //  to set a function which return true(for visible) or false(for invisible) for the visible filter with the below parameters :
	sheet:the sheet instance
	s:the image or shape instance
    for example: 
	//this will make visible for image/shape in sheet with name 'Sheet3' and 'Sheet1' except for the 'Rectangle' type
		xs.setVisibleFilter((sheet,s) => { if (sheet.data.name==='Sheet3'||sheet.data.name==='Sheet1') return s.type!=='Rectangle';  return false; })
	//this will make visible for image/shape in sheet with name  'Sheet1' 
		xs.setVisibleFilter((sheet,s) => { if (sheet.data.name==='Sheet1') return true;  return false; })
	//this will make invisible for image/shape in all sheets 
		xs.setVisibleFilter((sheet,s) => {  return false; })
	//if all the image/shape is already loaded and you want to change the visible filter at runtime,you can call the below code to trigger a reload for image/shape
		xs.reRender()

Get the selected image/shape,if nothing select will return null

xs.sheet.selector.getObj()

Show or hide an HTML node at a specified cell position

xs.sheet.showHtmlAtCell(isShow, html, ri, ci, deltaX, deltaY)

    //the parameters are:
      isShow: Boolean value indicating whether to show or hide the HTML content.
      html: The HTML string to be displayed.
      ri: Row index of the target cell.
      ci: Column index of the target cell.
      deltaX: (Optional) Relative X-position adjustment from the top-left corner of the cell.
      deltaY: (Optional) Relative Y-position adjustment from the top-left corner of the cell.

    for example: 
    // Show HTML at cell A1
    xs.sheet.showHtmlAtCell(true, "<span>html span</span><input length='30' id='myinput'>test</input>", 0, 0);

    // Hide the HTML node
    xs.sheet.showHtmlAtCell(false);

    // Note: When an HTML node is shown, the default GridJS event handling is disabled to allow interaction with the HTML content.
    // This means you cannot select any cells or perform edit operations until the HTML node is hidden.

Set the selectable state for image/shape

const shape=xs.sheet.selector.getObj();
shape.setControlable(isenable)
     // the parameter is:
      isenable: when set to true,the image or shape can be selectable and movable/resizeable

Insert rows

xs.sheet.insertRows(start, n)
    // the parameters are:
	start: start row id 
	n:how many rows will be inserted

Insert columns

xs.sheet.insertColumns(start, n)
    // the parameters are:
	start: start column id
	n:how many columns will be inserted

Delete rows

xs.sheet.deleteRows(start, n)
    // the parameters are:
	start: start row id 
	n:how many rows will be deleted

Delete columns

xs.sheet.deleteColumns(start, n)
    // the parameters are:
	start: start column id 
	n:how many columns will be deleted

Set the freeze pane

xs.sheet.freeze(ri,ci)
    // the parameters are:
	ri:row index 
	ci:column index

Unfreeze pane

xs.sheet.freeze(0,0)

Set editable/readonly range

xs.sheet.setEditableRange(range,isenable)
    // the parameters are:
	range:the cell range ,etc. {sri:0,sci:0,eri:2,eci:2} reprensents range start from cell A1 to C3
	isenable:when set to true,the range is editable.other wise,the range is readonly.

Hide rows

xs.sheet.hideRows(sri,eri)
    // the parameters are:
	sri:the start row index 
	eri:the end row index

Unhide rows

xs.sheet.unhideRows(sri,eri)
    // the parameters are:
	sri:the start row index 
	eri:the end row index

Hide columns

xs.sheet.hideColumns(sci,eci)
    // the parameters are:
	sci:the start column index 
	eci:the end column index

Unhide columns

xs.sheet.unhideColumns(sci,eci)
    // the parameters are:
	sci:the start column index 
	eci:the end column index

Set the height for the row

xs.sheet.setRowHeight(ri,height)
    // the parameters are:
	ri:row index
	height:the height for the row

Set the height for the rows

xs.sheet.setRowsHeight(sri,eri,height)
    // the parameters are:
	sri:start row index
	eri:end row index
	height:the height for the rows

Set the height for all the rows

xs.sheet.setAllRowsHeight(height)
    // the parameters are:
	height:the height for the rows

Set the width for the column

xs.sheet.setColWidth(ci,width)
    // the parameters are:
	ci:column index
	width:the width for the column

Set the width for the columns

xs.sheet.setColsWidth(sci,eci,width)
    // the parameters are:
	sci:the start column index
	eci:the end column index
	width:the width for the column

Set the width for all the columns

xs.sheet.setAllColsWidth(width)
    // the parameters are:
	width:the width for the columns

Set the comment at the cell

xs.sheet.setComment(ri,ci,author,note)
    // the parameters are:
	ri:row index of the cell
	ci:column index of the cell
	author:the author for the comment
	note:the content for the comment

Remove the comment at the cell

xs.sheet.removeComment(ri,ci)
    // the parameters are:
	ri:row index of the cell
	ci:column index of the cell

Get the cell object

xs.sheet.data.getCell(ri,ci)
    // the parameters are:
	ri:row index 
	ci:column index

Get the cell style

xs.sheet.data.getCellStyle(ri,ci)
    // the parameters are:
	ri:row index 
	ci:column index

Set the cell value

xs.sheet.data.setCellText(ri,ci,value,state)
    // the parameters are:
	ri:row index 
	ci:column index
	value:the cell value
	state: input | finished ,if finished ,it will do update action to servside

Get/Set the selected cell range

xs.sheet.data.selector.range

Set the cell value for the selected cell or cell area

xs.sheet.data.setSelectedCellText(value)
    // the parameters are:
	value:the  value for the cell

Set the style for the selected cell or cell area

xs.sheet.data.setSelectedCellAttr(attributename,value)
    // the parameters are:
	attributename:font-name | font-bold | font-italic | font-size  | format|border|merge|formula |strike|textwrap |underline |align |valign |color|bgcolor|pattern
	value:the  value for the attribute

Set the style for the desired cell area

xs.sheet.data.setRangeAttr(range,attributename,value)
    // the parameters are:
        range:the cell range ,etc. {sri:0,sci:0,eri:2,eci:2} reprensents range start from cell A1 to C3
	attributename:font-name | font-bold | font-italic | font-size  | format|border|merge|formula |strike|textwrap |underline |align |valign |color|bgcolor|pattern
	value:the  value for the attribute
   for example:
        xs.sheet.data.setRangeAttr({sri:0,sci:0,eri:2,eci:2},'bgcolor','#11ee2a');

Merge the selected cell area

xs.sheet.data.merge()

Unmerge the selected cell area

xs.sheet.data.unmerge()

Delete the cell content or clear the style at the selected cell

xs.sheet.data.deleteCell(type)
    // the parameters are:
	type:all|format  all: means delete the cell and clear the style ;format means delete the cell value and keep the cell style

Delete the cell content or clear the style at the desired cell area

xs.sheet.data.deleteRange(range,type)
    // the parameters are:
        range:the cell range ,etc. {sri:0,sci:0,eri:2,eci:2} reprensents range start from cell A1 to C3
	type:all|format  all: means delete the cell and clear the style ;format means delete the cell value and keep the cell style

Get the width for the column

xs.sheet.data.cols.sumWidth(min,max)
    // the parameters are:
	min:the start column index
	max:the end column index,not include

Get the height for the row

xs.sheet.data.rows.sumHeight(min,max)
    // the parameters are:
	min:the start row index
	max:the end row index,not include

Get/Set the display direction

xs.sheet.data.displayRight2Left

Event call back

We can track the below events

 xs.on('cell-selected', (cell, ri, ci) => {
                console.log('cell selected:', cell, ', ri:', ri, ', ci:', ci);
                if (ci === -1) {
                    console.log('ci === -1 means a row selected ',ri);
                }
                if (ri === -1) {
                    console.log('ri === -1 means a column selected',ci);
                }
            }).on('cells-selected', (cell, range) => {
                console.log('range   selected:', cell, ', rang:', range);
            }).on('object-selected', (shapeOrImageObj) => {
                console.log('shape or image selected id:', shapeOrImageObj.id, ', type: ', shapeOrImageObj.type);
            }).on('sheet-selected', (id,name) => {
                console.log('sheet selected id:', id, ', name: ',name);
            }).on('sheet-loaded', (id,name) => {
                console.log('sheet load finished:', id, ', name: ',name);
            }).on('cell-edited', (text, ri, ci) => {
	        //just edit the cell
                console.log('text:', text, ', ri: ', ri, ', ci:', ci);
            }).on('cells-updated', (name, cells) => {
	       //cell value got updated
                console.log('cells updated for sheet name:', name);
                cells.forEach((acell, index, array) => {
                console.log('acell got updated:', acell);
            })
            }).on('cells-deleted', (range) => {
                console.log('cells deleted :', range);
            }).on('rows-deleted', (ri, n) => {
                console.log('rows-deleted :', ri, ",size", n);

            }).on('columns-deleted', (ci, n) => {
                console.log('columns-deleted :', ci, ",size", n);

            }).on('rows-inserted', (ri, n) => {
                console.log('rows-inserted :', ri, ",size", n);

            }).on('columns-inserted', (ci, n) => {
                console.log('columns-inserted :', ci, ",size", n);

            }).on('vertical-scrolled', (ri) => {
                console.log('vertical-scrolled,start row is:', ri);

            }).on('horizontal-scrolled', (ci) => {
                console.log('horizontal-scrolled,start column is:', ci);

            });

Pre-Check event if return false,the insert/delete operation will not go on.

  xs.checkRowInsert = (ri, size) => { if (ri % 2 == 1) return true; else return false; };
  xs.checkColumnInsert = (ci, size) => { if (ci % 2 == 1) return true; else return false; };
  xs.checkRowDelete = (ri, size) => { if (ri % 2 == 1) return true; else return false; };
  xs.checkColumnDelete = (ci, size) => { if (ci % 2 == 1) return true; else return false; };

Customization

Set home icon and link

xs.sheet.menubar.icon.setHomeIcon(iconUrl,targetUrl)
    // the parameters are:
	iconUrl:the home icon URL
	targetUrl:the target link URL
	for example ,the below code will set the new logo and with link to google.com
	xs.sheet.menubar.icon.setHomeIcon('https://forum.aspose.com/letter_avatar_proxy/v4/letter/y/3e96dc/45.png','https://www.google.com')

Show the menu bar

xs.sheet.menubar.show()

Hide the menu bar

xs.sheet.menubar.hide()

APIs for shape object

Change background color for shape object

    setBackgroundColor(color)
    // the parameters are:
        color: the html color value in hex string value
    //for example,we assume shape 0 existed,this will set the background color to Yellow 
     const ashape=xs.sheet.data.shapes[0];
     ashape.setBackgroundColor('#FFFF00');

APIs for TextBox object

TextBox is a special kind of shape which type property is :“TextBox”, for example: the below code will show which shape is textbox

for (let shape of xs.sheet.data.shapes) {
    if (shape.type === 'TextBox') {
        console.log(shape.id + ' is a textbox');
    }
}

Apply font settings for textbox object

    setFont(fontsettings)
    // the parameter is:
        fontsettings:   {'name':'Arial', 'size':12, 'bold':true, 'color':'#FFFF00', 'italic':true} ,the properties are 'name', 'size', 'bold', 'color', 'italic',they are all optional.
    //for example,we assume shape 0 is a textbox object,this will set the font color to Yellow ,and font size to 12pt,and bold the font. 
     const textbox=xs.sheet.data.shapes[0];
     const fontsettings= {'name':'Arial', 'size':12, 'bold':true, 'color':'#FFFF00'}; 
     textbox.setFont(fontsettings);

Auto change the background color and text color to get a visual active effect

    setActiveEffect(boolvalue)
    // the parameters are:
        boolvalue: if true,will change background color and the text color of the textbox object;if false,restore to original appearence

Hide/unhide the text content in the textbox object

    hideText(boolvalue)
    // the parameters are:
        boolvalue: if true,will not display the text in the textbox object;if false,restore to original appearence

for detail info ,you can check the example here https://github.com/aspose-cells/Aspose.Cells.Grid-for-Java/tree/main/Examples.GridJs

How to Print how to build a collaborative Excel editor with GridJs