API-操作
Actions（操作）
Action
一个操作定义了从客户端向服务端的沟通方式。这里有四个操作类型：
- listAction：定义了如何获取列表数据。
- createAction：定义了如何提交一个创建表单。
- updateAction：定义了如何提交一个编辑表单。
- deleteAction：定义了如何删除一条记录。
一个操作必须定义在jTable选项里面的actions中：
...
actions: {
//Actions definitions come here
}
...
一个操作可以是字符串类型的URL，也可以是一个function（查看每一个操作的详细介绍）。
listAction URL string or function default: none
给listAction设置一个URL
如果你给listAction定义了一个字符串类型的URL，然后，当你使用load方法时，jTable会发送POST AJAX请求来获取列表记录数据。这个URL必须返回一个JSON object。下面是一个返回值案例：
{
"Result":"OK",
"Records":[
{"PersonId":1,"Name":"Benjamin Button","Age":17,"RecordDate":"\/Date(1320259705710)\/"},
{"PersonId":2,"Name":"Douglas Adams","Age":42,"RecordDate":"\/Date(1320259705710)\/"},
{"PersonId":3,"Name":"Isaac Asimov","Age":26,"RecordDate":"\/Date(1320259705710)\/"},
{"PersonId":4,"Name":"Thomas More","Age":65,"RecordDate":"\/Date(1320259705710)\/"}
]
}
Result属性可以是“OK”或者“ERROR”。如果是“OK”，Records属性必须是一个记录数组。如果是“ERROR”，必须包含一个Message属性，给用户展示一个错误的原因。
特别的，日期字段（在jTable和服务端传输）必须是下面格式中的一个：
- "/Date(...)/"
例如：/Date(1320259705710)/ (注意: Date(...)里面的数字是从01.01.1970传递的毫秒数) - "YYYY-MM-DD HH:MM:SS"
例如：2012-01-03 21:40:42 - "YYYY-MM-DD"
例如：2012-01-03
下面是 ASP.NET MVC服务端的案例代码，listAction：
[HttpPost]
public JsonResult PersonList()
{
try
{
List<Person> persons = _repository.PersonRepository.GetAllPeople();
return Json(new { Result = "OK", Records = persons });
}
catch (Exception ex)
{
return Json(new { Result = "ERROR", Message = ex.Message });
}
}
下载所有的案例。
Paging
如果开启了分页，jTable会在调用listAction的AJAX请求中发送两个参数：
- jtStartIndex：当前页面的记录开始索引。
- jtPageSize：预期记录总数的最大值
另外，服务器还需要返回一个附加信息：
- TotalRecordCount：所有记录的总条数。
Sorting
如果开启了排序，jTable会在调用listAction的AJAX请求中发送一个附加参数：
- jtSorting：一个字符串代表请求排序。它是由排序字段和排序方向组成的。例如，它可以是 'Name ASC', 'BirtDate DESC', 'Age ASC' ，或者是 'CityId DESC,Name ASC' （如果开启了multiSotring）。
下面是服务端的案例代码，paged and sorted listAction：
[HttpPost]
public JsonResult StudentList(int jtStartIndex = 0, int jtPageSize = 0, string jtSorting = null)
{
try
{
var studentCount = _repository.StudentRepository.GetStudentCount();
List<Student> students = _repository.StudentRepository.GetStudents(jtStartIndex, jtPageSize, jtSorting);
return Json(new { Result = "OK", Records = students, TotalRecordCount = studentCount });
}
catch (Exception ex)
{
return Json(new { Result = "ERROR", Message = ex.Message });
}
}
下载所有的案例。
给listAction设置一个function
你可以给这个action设置一个function。你的function可以返回下面中的其中一种：
- data（数据结果）。原文：The data (result) itself
- 一个promise来返回数据。原文：A promise (using jQuery.Deferred) to return the data (result)
为了返回数据本身，你可以这么定义action：
listAction: function (postData, jtParams) {
return {
"Result": "OK",
"Records": [
{ "StudentId": 39, "ContinentalId": 1, "CountryId": 18, "CityId": 55, "Name": "Agatha Garcia", "EmailAddress": "agatha.garcia@jtable.org", "Password": "123", "Gender": "F", "BirthDate": "\/Date(-1125111600000)\/", "About": "", "Education": 2, "IsActive": true, "RecordDate": "\/Date(1369083600000)\/" },
{ "StudentId": 61, "ContinentalId": 4, "CountryId": 1, "CityId": 1, "Name": "Agatha Lafore", "EmailAddress": "agatha.lafore@jtable.org", "Password": "123", "Gender": "F", "BirthDate": "\/Date(1017694800000)\/", "About": "", "Education": 3, "IsActive": true, "RecordDate": "\/Date(1393192800000)\/" }],
"TotalRecordCount": 2
};
}
直接返回数据可用于演示， 但这种场景并不常见。你大概想要通过ajax请求来向服务端获取数据。这种情况下，你可以使用 jQuery.Deferred 返回一个promise：
listAction: function (postData, jtParams) {
return $.Deferred(function ($dfd) {
$.ajax({
url: '/Demo/StudentList?jtStartIndex=' + jtParams.jtStartIndex + '&jtPageSize=' + jtParams.jtPageSize + '&jtSorting=' + jtParams.jtSorting,
type: 'POST',
dataType: 'json',
data: postData,
success: function (data) {
$dfd.resolve(data);
},
error: function () {
$dfd.reject();
}
});
});
}
这个函数接收一些参数：
- postData：如果你调用load方法并且传递一个post data，它就是你提供的data。
- jtParams：用于将jTable特定的参数作为对象传递。这个对象会有下面3个属性：
在这个function中，你可以在使用 $dfd.resolve(data) 返回之前修改返回数据的格式。数据必须格式化为jTable预期的格式。所以，在‘设置URL作为listAction’中写入的所有内容在这里也是有效的。
createAction URL string or function default: none
设置URL作为createAction
如果你定义一个URL作为createAction，然后，当你创建和保存一条记录的时候，jTable会发送一个POST AJAX请求到服务端来保存这条数据。
createAction是可选的。如果你没有定义，用户不能添加新纪录到表格中（表格中不显示‘+add new record’按钮）。这个URL必须返回一个JSON object，像下面一样：
{
"Result":"OK",
"Record":{"PersonId":5,"Name":"Dan Brown","Age":55,"RecordDate":"\/Date(1320262185197)\/"}
}
Result属性可以是“OK”或者“ERROR”。如果是“OK”，Record属性必须是新添加的那条记录。这是jTable需要添加到表格中的记录。如果Result是“ERROR”，返回结果中必须包含Message属性来向用户解释错误的原因。
下面是服务端的案例代码：
[HttpPost]
public JsonResult CreatePerson(Person person)
{
try
{
Person addedPerson = _repository.PersonRepository.AddPerson(person);
return Json(new { Result = "OK", Record = addedPerson });
}
catch (Exception ex)
{
return Json(new { Result = "ERROR", Message = ex.Message });
}
}
设置function作为createAction
你可以为action设置一个function。你的function可以返回下面中的任何一个：
- data（数据结果）。原文：The data (result) itself
- 一个promise来返回数据。原文：A promise (using jQuery.Deferred) to return the data (result)
由于它和listAction非常相似，在这里不在详细介绍。你可以看下案例。
updateAction URL string or function default: none
设置URL作为updateAction
当你编辑和保存一条记录的时候，jTable会发送一个POST AJAX请求到服务端来更新这条数据。
updateAction是可选的。如果没有定义，编辑（图片）按钮不会显示。这个URL必须返回一个JSON object。像下面一样：
{"Result":"OK"}
Result属性可以是“OK”或者“ERROR”。如果Result是“ERROR”，返回结果中必须包含Message属性来向用户解释错误的原因。
updateAction也可以返回一个Record记录（是可选的）。这条记录会覆盖以更新表中的记录。它并没有完全被覆盖，而是对应的字段被覆盖掉。所以，举个例子，如果你返回只有一个字段的记录，那么只有这个字段会被覆盖。
{
"Result":"OK",
"Record":{"Name":"Dan Brown","Age":55,"LastUpdateDate":"\/Date(1320262185197)\/"}
}
下面是服务端的案例代码，updateAction：
[HttpPost]
public JsonResult UpdatePerson(Person person)
{
try
{
_repository.PersonRepository.UpdatePerson(person);
return Json(new { Result = "OK" });
}
catch (Exception ex)
{
return Json(new { Result = "ERROR", Message = ex.Message });
}
}
设置function作为updateAction
你可以为action设置一个function。你的function可以返回下面中的任何一个：
- data（数据结果）。原文：The data (result) itself
- 一个promise来返回数据。原文：A promise (using jQuery.Deferred) to return the data (result)
由于它和listAction非常相似，在这里不在详细介绍。你可以看下案例。
deleteAction URL string or function default: none
设置URL作为deleteAction
当你删除一条记录的时候，jTable会发送一个POST AJAX请求到服务端来删除这条数据。
deleteAction是可选的。如果没有定义，删除（图片）按钮不会显示。这个URL必须返回一个JSON object。像下面一样：
{"Result":"OK"}
Result属性可以是“OK”或者“ERROR”。如果Result是“ERROR”，返回结果中必须包含Message属性来向用户解释错误的原因。
下面是服务端的案例代码，deleteAction：
[HttpPost]
public JsonResult DeletePerson(int personId)
{
try
{
_repository.PersonRepository.DeletePerson(personId);
return Json(new { Result = "OK" });
}
catch (Exception ex)
{
return Json(new { Result = "ERROR", Message = ex.Message });
}
}
设置function作为updateAction
你可以为action设置一个function。你的function可以返回下面中的任何一个：
- data（数据结果）。原文：The data (result) itself
- 一个promise来返回数据。原文：A promise (using jQuery.Deferred) to return the data (result)
由于它和listAction非常相似，在这里不在详细介绍。你可以看下案例。
