README

带有JavaScript网格编辑器的Composer库

该库定义了一个JavaScript nettools.jsGridEditor 类，可以编辑以行和列存储的数据。

设置说明

要安装 net-tools/js-grid-editor 包，只需通过 composer 要求它：require net-tools/js-grid-editor:^1.0.0。

如何使用？

nettools.jsGridEditor 类构造函数期望以下参数

• 编辑器必须渲染的 HTMLElement 节点（通常是 DIV）
• 一个对象字面量，包含选项
  • columns：一个对象字面量数组，定义列（见下文）
  • data：一个对象字面量数组，包含数据（见下文）
  • editable：一个布尔值；如果设置为 false，则网格数据不能编辑
  • disableDblClick：一个布尔值；如果设置为 true，则双击不能将行切换到编辑模式
  • defaultValues：一个对象字面量，包含新行的默认值
  • dialog：一个继承自 nettools.jsGridEditor.Dialog 的对象，具有 alert 和 confirm 方法；默认情况下，使用 JavaScript 的 alert 和 confirm 函数
  • rowToStringColumns：一个事件，用于帮助将给定行的列值转换为字符串；如果给出数字（从0开始）或 'first'，则转换对应列的键=值字符串。如果给出 'all'，则转换返回所有键值，用逗号分隔
  • onRowValidate：在退出编辑模式之前调用以验证行数据的事件（rowData 可能在调用期间更新）；返回已解析的 Promise 以接受更改，或返回带有错误消息的拒绝 Promise 以拒绝更新
  • onRowToString：在获取行字符串值时调用的事件（默认事件的代码使用 rowToStringColumns 值来生成字符串）
  • onRowChange：在通知客户端行内容已更改时调用的事件；客户端代码必须返回已解析的 Promise 以确认更新，否则返回拒绝的 Promise
  • onRowDelete：在通知客户端已删除行时调用的事件；客户端代码必须确认删除并在完成后返回已解析的 Promise，或在发生错误时返回拒绝的 Promise
  • onRowInsert：在通知客户端已插入行时调用的事件；客户端代码在完成后必须返回 Promise，或在发生错误时返回拒绝的 Promise
  • onCellHtml：对于 'html' 列，调用以在 TD 节点中设置一些丰富的 GUI
  • onGetCellHtmlValue：在编辑模式中调用 'html' 列以获取要存储在数据集中的编辑值

columns 对象字面量数组定义所有列；列的允许参数（也请参阅下面的示例）

• id：列 ID 作为字符串；将在 data 参数中用作属性名称
• title：将出现在表头中的标题
• subTitle：表头中的列子标题
• type：定义列的类型（字符串、int、float、bool、list 或 html）
• required：强制列必填状态的布尔值
• hidden：隐藏列的布尔值
• format：用于验证列数据的正则表达式
• readonly : 列不能编辑
• readonlyEdit : 创建新行时，除了外，列不能编辑
• datalist : 如果 type 属性是 list，则定义一个字符串值数组，该数组作为可接受的值
• validator : 一个用于验证列值的自定义函数（如果值被接受则返回 true，如果值被拒绝则返回 false）

对象字面量数组 data 包含网格数据：每行一个对象字面量，每个对象属性是一个列值。请参阅下面的示例。

var grid = new nettools.jsGridEditor(document.getElementById('grid'),
	{
		// defining columns
		columns : [ 
			{ id : 'key', subTitle:'string(2)', format:/^[A-Z][A-Z0-9]$/, required : true, validator:function(v){ return v!='RU'; } },
			{ id : 'country', title : 'Country name', subTitle:'string', readonly : true }, 
			{ id : 'region', title : 'World area',  subTitle:'list', required : true, type:'list', datalist:['Europe', 'America', 'North-America', 'South-America', 'Asia', 'Africa'] },
			{ id : 'order', type : 'int', subTitle:'int'  },
            { id : 'english', title : 'Speak English ?',  subTitle:'bool(0/1)', required : true, type : 'bool' }
		],
	
		// data to edit
		data : [
			{ key : 'FR', country : 'France', region : 'Europe', order : 1, english : 0 },
			{ key : 'US', country : 'USA', region : 'North-America', order : 2, english : 1 },
			{ key : 'UK', country : 'United Kingdom', region : 'Europe', order : 3, english : 1 }
		],
	
		// grid is editable
		editable : true,
	
		// a row is converted to a string by return key=value for column 1 (second column)
		rowToStringColumns : 1,
	
		// default values for new lines
		defaultValues : {
			region : 'Asia',
			english : 1
		},
		
		// output in console values to validate
		onRowValidate : function(row, values)
			{
				console.log('Values to validate at row ' + row);
				console.log(values);
				return true;
			},
	
		// accepting updates in rows only for even one
		onRowChange : function(row, values)
			{
				console.log('Row changed at offset ' + row);
				console.log(values);
				
				if ( row % 2 == 0 )
					return Promise.resolve(row);
				else
					return Promise.reject('Row commit failed at row ' + row);
			},
	
		// processing deletion client-side ; if the user acknowledges deletion, the row is removed from dataset
		onRowDelete : function(row, values)
			{
				return new Promise(function(resolve, reject){
					if ( confirm('Confirm deletion has been processed client-side ?') )
						resolve(row);
					else
						reject('Deletion at row ' + row + ' denied');
				});
			},
	
		// procession new line ; if the user acknowledges insert, the row is inserted in the dataset
		onRowInsert : function(row, values)
			{
					return new Promise(function(resolve, reject){
						if ( confirm('Confirm insert has been processed client-side ?') )
							resolve(row);
						else
							reject('Insert at row ' + row + ' denied');
					});
			}
	}
);

可以调用几个对象方法

• setData : 如果在构造函数调用期间未设置 data 选项参数，则可以通过调用带有对象字面量数组的 setData 方法将数据分配给网格编辑器。
• isInserting : 如果编辑器当前正在插入新行，则返回 true
• insertRow : 将编辑器切换到插入模式，用提供的默认值填充空的新行
• editRow : 编辑参数中的偏移量所在行
• deleteRow : 删除参数中的偏移量所在行；会提示用户确认行删除；会调用 onRowDelete 事件以通知客户端

示例

在 /samples 子目录中有一个示例

• editor.html