ABP-JavaScript API

1、AJAX

1，ABP採用的方式

ASP.NET Boilerplate經過用abp.ajax函數包裝AJAX調用來自動執行其中的一些步驟。 一個例子ajax調用：

var newPerson = {
    name: 'Dougles Adams',
    age: 42
};

abp.ajax({
    url: '/People/SavePerson',
    data: JSON.stringify(newPerson)
}).done(function(data) {
    abp.notify.success('created new person with id = ' + data.personId);
});

abp.ajax以一個對象做爲接收選項。你能夠傳遞任何在jQuery的$.ajax方法中有效的任何參數。這裏有一些 默認的值：dataType是‘json’，type是‘POST’，contentType是‘application/json’（所以，在發送到服務器以前，咱們能夠調用JSON.stringify將javascript對象轉成JSON字符串）。你能夠經過將選項傳給abp.ajax重寫默認值。

abp.ajax返回了promise。所以，你能夠寫done,fail,then等處理函數。上面的例子中，咱們向 PeopleController的SavePerson的action發送了簡單的Ajax請求。在 done處理函數中，咱們得到了新添加的person的數據庫Id，並且展現了一個成功的通知。讓咱們看一下該Ajax請求的 MVC控制器

public class PeopleController : AbpController
{
    [HttpPost]
    public JsonResult SavePerson(SavePersonModel person)
    {
        //TODO:將新的person保存到數據庫，並返回該person的Id
        return Json(new {PersonId = 42});
    }
}

SavePersonModel包含了Name和Age屬性。SavePerson標記有 HttpPost特性，由於abp.ajax默認的方法是POST。這裏經過返回一個匿名的對象簡化了方法的實現。

2，AJAX返回消息
即便咱們直接返回PersonId = 2的對象，ASP.NET Boilerplate也由MvcAjaxResponse對象包裝。 實際的AJAX響應是這樣的：

{
  "success": true,
  "result": {
    "personId": 42
  },
  "error": null,
  "targetUrl": null,
  "unAuthorizedRequest": false
}

這裏，全部的屬性都是camelCase的（由於在javascript中這是慣例），即便在服務端代碼中是PascalCased的。下面解釋一下全部的字段：

• success:一個布爾值，表示操做的成功狀態。若是是true，abp.ajax會解析該promise，並調用 done處理函數。若是是false（若是在方法調用中發生了異常），它會調用 fail處理函數並使用abp.message.error函數展現一個 error消息。
• result：控制器的action返回的實際值。若是success是true，並且服務器發送了一個返回值，它纔有效。
• error：若是success是false，那麼該字段是一個包含了 message和 detail字段的對象。
• targetUrl:這爲服務器提供了一種重定向客戶端到其餘Url的可能性。
• unAuthorizedRequest:這爲服務器提供了通知客戶端該操做沒有受權或者用戶沒有認證的可能性。若是該值是true，那麼abp.ajax會 從新加載當前的頁面。

經過從AbpController類中派生就能夠將返回值轉換成一個封裝的Ajax響應。 abp.ajax會識別並計算該響應。所以，它們成對工做。若是沒有發生錯誤的話，那麼abp.ajax的done處理函數會得到控制器返回的實際值（一個具備personId屬性的對象）。

當從AbpApiController類派生時，也會存在相同的機制。

3，處理錯誤

正如上面描述的，ABP會處理服務器中的全部異常，並返回一個具備錯誤信息的對象，以下所示：

{
  "targetUrl": null,
  "result": null,
  "success": false,
  "error": {
    "message": "An internal error occured during your request!",
    "details": "..."
  },
  "unAuthorizedRequest": false
}

能夠看到，success是false，result是null。abp.ajax處理該對象，並且使用abp.message.error函數展現一個錯誤信息給用戶。若是你的服務端代碼拋出了一個UserFriendlyException類型的異常，它會直接給用戶顯示異常信息。不然，它會隱藏實際的錯誤（將錯誤寫到日誌中），並展現一個標準的「服務器內部錯誤...」信息給用戶。全部的這些都是ABP自動處理的。

4，動態Web API層

雖然ABP提供了一種使得調用Ajax很簡單的機制，可是在真實世界的應用中，爲每一個Ajax調用編寫javascript函數是很經典的，好比：

//建立一個抽象了Ajax調用的function
var savePerson = function(person) {
    return abp.ajax({
        url: '/People/SavePerson',
        data: JSON.stringify(person)
    });
};

//建立一個新的 person
var newPerson = {
    name: 'Dougles Adams',
    age: 42
};

//保存該person
savePerson(newPerson).done(function(data) {
    abp.notify.success('created new person with id = ' + data.personId);
});

 

2、Notification

展現自動關閉的通知。

咱們喜歡一些事情發生時展現一些精緻的自動消失的通知，好比當保存一條記錄或者問題發生時。ABP爲這個定義了標準的APIs。

abp.notify.success('a message text', 'optional title');
abp.notify.info('a message text', 'optional title');
abp.notify.warn('a message text', 'optional title');
abp.notify.error('a message text', 'optional title');

通知API默認是使用toastr庫實現的。要使toastr生效，你應該引用toastr的css和javascript文件，而後再在頁面中包含abp.toastr.js做爲適配器。一個toastr成功通知以下所示：

 

你也能夠用你最喜歡的通知庫中實現通知。只須要在自定義javascript文件中重寫全部的函數，而後把它添加到頁面中而不是abp.toastr.js（你能夠檢查該文件看它是否實現，這個至關簡單）中。

 

3、Message

給用戶展現消息對話框。

消息API用於給用戶展現消息或者得到用戶的確認。

消息API默認是使用sweetalert實現的。要讓sweetalert生效，你應該包含它的css和javascript文件，而後再頁面中添加 abp.sweet-alert.js的引用做爲適配器。

abp.message.info('some info message', 'some optional title');
abp.message.success('some success message', 'some optional title');
abp.message.warn('some warning message', 'some optional title');
abp.message.error('some error message', 'some optional title');

一個成功的消息以下所示：

 

abp.message.confirm(
    'User admin will be deleted.',
    'Are you sure?',
    function (isConfirmed) {
        if (isConfirmed) {
            //...刪除用戶
        }
    }
);

這裏的第二個參數（title）是可選的，所以，回調函數也能夠是第二個參數。

一個確認消息的例子以下所示：

 

ABP內部使用了Message API。好比，若是Ajax調用失敗了，那麼它會調用abp.message.error。

 

4、UI block和Busy API

使用一個區域（一個div，form，整個頁面等）阻塞用戶的輸入。此外，還使得一個區域處於繁忙狀態（具備一個繁忙的指示器，如‘loading...’）。

1，UI Block API

該API使用一個透明的塗層（transparent overlay）來阻塞整個頁面或者該頁面上的一個元素。這樣，用戶的點擊就無效了。當保存一個表單或者加載一個區域（一個div或者整個頁面）時這是頗有用的，好比：

abp.ui.block(); //阻塞整個頁面
abp.ui.block($('#MyDivElement')); //可使用jQuery 選擇器..
abp.ui.block('#MyDivElement'); //..或者直接使用選擇器
abp.ui.unblock(); //解除阻塞整個頁面
abp.ui.unblock('#MyDivElement'); //解除阻塞特定的元素

UI Block API默認使用jQuery的blockUI插件實現的。要是它生效，你應該包含它的javascript文件，而後在頁面中包含abp.blockUI.js做爲適配器。

2，UI Busy API

該API用於使得某些頁面或者元素處於繁忙狀態。好比，你可能想阻塞一個表單，而後當提交表單至服務器時展現一個繁忙的指示器。例子：

abp.ui.setBusy('#MyLoginForm');
abp.ui.clearBusy('#MyLoginForm');

該參數應該是一個選擇器（如‘#MyLoginForm’）或者jQuery選擇器（如$('#MyLoginForm')）。要使得整個頁面處於繁忙狀態，你能夠傳入null（或者'body'）做爲選擇器。

setBusy函數第二個參數接收一個promise（約定），當該約定完成時會自動清除繁忙的狀態。例子：

abp.ui.setBusy(
    $('#MyLoginForm'), 
    abp.ajax({ ... })   
);

由於abp.ajax返回promise，咱們能夠直接將它做爲promise傳入。要學習慣於promise更多的東西，查看jQuery的Deferred。

UI Busy API是使用spin.js實現的。要讓它生效，應該包含它的javascript文件，而後在頁面中包含abp.spin.js做爲適配器。

 

5、事件總線

用於註冊和觸發客戶端的全局事件。

Pub/sub事件模型普遍用於客戶端，ABP包含了一個簡單的全局事件總線來 註冊並 觸發事件。

1，註冊事件

可使用abp.event.on來註冊一個全局事件。一個註冊的例子：

abp.event.on('itemAddedToBasket', function (item) {
    console.log(item.name + ' is added to basket!');
});

第一個參數是事件的惟一名稱。第二個是回調函數，當特定事件被觸發時，會被調用。

可使用abp.event.off方法來從一個事件中取消註冊。注意：要取消註冊，要提供相同的函數。所以，對於上面的例子，你應該將回調函數設置爲一個變量，而後在on和off方法中使用它。

2，觸發事件

abp.event.trigger用於觸發一個全局事件。觸發一個已經註冊的事件的代碼以下：

abp.event.trigger('itemAddedToBasket', {
    id: 42,
    name: 'Acme Light MousePad'
});

第一個參數是該事件的惟一名稱。第二個是（可選的）事件參數。你能夠添加任何數量的參數，而且在回調方法中得到它們

 

6、日誌

在客戶端記錄日誌。

1，Javascript Logging API

當你想要在客戶端記錄一些簡單的日誌時，你可使用console.log('...')API，這你已經知道了。可是這種寫法不是全部的瀏覽器都支持的，並且可能會破壞你的腳本。所以，你應該首先檢查console是否可用，此外，你可能想在別的地方記錄日誌，甚至你想以某種級別記錄日誌。ABP定義了安全的日誌函數：

abp.log.debug('...');
abp.log.info('...');
abp.log.warn('...');
abp.log.error('...');
abp.log.fatal('...');

 

7、其餘工具技能

ABP提供了一些通用的工具功能。

1，abp.utils.createNamespace

用於當即建立更深的命名空間。假設咱們有一個基命名空間‘abp’，而後想要建立或者得到‘abp.utils.strings.formatting’命名空間

var formatting = abp.utils.createNamespace(abp, 'utils.strings.formatting';

//給該namespace添加一個function
formatting.format = function() { ... };

這樣就簡化了安全地建立深刻的命名空間了。注意，第一個參數是必須存在的根命名空間。

2，abp.utils.formatString

這個和C#中的string.Format()很類似。用法示例：

var str = abp.utils.formatString('Hello {0}!', 'World'); //str = 'Hello World!'
var str = abp.utils.formatString('{0} number is {1}.', 'Secret', 42); //str = 'Secret number is 42'