每一個WEB應用程序都有導航菜單,Abp也為用戶提供了通用的創建和顯示菜單方式。
創建菜單
一個應用程序可能包含不同的模塊,而每個模塊都可能有它自己的菜單項。在Abp中,需要創建一個派生自NavigationProvider的類來定義一個菜單項。
假設我們有一個這樣的主菜單:
由上可知,Administration菜單項有兩個子菜單項。對應的生成方法如下:
public class SimpleTaskSystemNavigationProvider : NavigationProvider { public override void SetNavigation(INavigationProviderContext context) { context.Manager.MainMenu .AddItem( new MenuItemDefinition( "Tasks", new LocalizableString("Tasks", "SimpleTaskSystem"), url: "/Tasks", icon: "fa fa-tasks" ) ).AddItem( new MenuItemDefinition( "Reports", new LocalizableString("Reports", "SimpleTaskSystem"), url: "/Reports", icon: "fa fa-bar-chart" ) ).AddItem( new MenuItemDefinition( "Administration", new LocalizableString("Administration", "SimpleTaskSystem"), icon: "fa fa-cogs" ).AddItem( new MenuItemDefinition( "UserManagement", new LocalizableString("UserManagement", "SimpleTaskSystem"), url: "/Administration/Users", icon: "fa fa-users", requiredPermissionName: "SimpleTaskSystem.Permissions.UserManagement" ) ).AddItem( new MenuItemDefinition( "RoleManagement", new LocalizableString("RoleManagement", "SimpleTaskSystem"), url: "/Administration/Roles", icon: "fa fa-star", requiredPermissionName: "SimpleTaskSystem.Permissions.RoleManagement" ) ) ); } }
MenuItemDefinition可以有一個唯一的名字,一個用於本地化顯示的名字,一個url和一個icon,此外,菜單項可能需要與特定用戶權限相結合(相關權限系統正在開發,暫時還沒有說明文檔)。
InavigationProviderContext方法能夠獲取現有的菜單項、添加菜單或菜單項。因此,不同的模塊可以添加各自的菜單。
創建完成導航後,還需要在對應模塊預初始化時注冊到Abp配置文件中:
Configuration.Navigation.Providers.Add<SimpleTaskSystemNavigationProvider>();
顯示菜單
IuserNavigationManager可以注入、獲取和顯示菜單。可以在服務器端創建菜單。
Abp自動生成的javascript API使得用戶能夠在客戶端獲取菜單,對應的方法和對象在命名空間abp.nav中。例如,在客戶端使用abp.nav.menus.MainMenu可以用來獲取主菜單。
下面我們就來看一下JavaScript的相關方面。
Ajax
現代的應用經常會使用AJAX,尤其是單頁應用,幾乎是和服務器通信的唯一手段,執行AJAX通常會有以下步驟:
在客戶端,你需要提供一個URL,選擇一個和服務器通信的方法(GET,POST,PUT,DELETE)。在請求完成後執行回調函數,請求結果可更是成功或失敗,失敗時你需要給出提示,成功時你需要根據返回值執行操作。通常情況下,在請求開始時,你需要給出類似正在處理或者相關的繁忙等待信息(如頁面遮蓋),請求完成後恢復。
服務端接收到請求後,對請求參數進行驗證,執行服務端代碼,如果發生錯誤或者驗證失敗,應給出具體的原因,成功時返回客戶端想要的數據。
ABP服務端支持標准的ajax的請求/輸出。建議大家使用abp.jquery.js中提供的ajax請求方法,這個方法基於jquery的ajax方法,可以自動處理服務端的異常信息,當然,如果你對js很熟練的話,也可以根據自己的需要寫ajax。
ASP.NET Boilerplate的ajax請求實例:
//構建要傳輸的參數對象 var newPerson = { name: 'Dougles Adams', age: 42 }; //調用abp的ajax方法 abp.ajax({ url: '/People/SavePerson', data: JSON.stringify(newPerson) //轉換成json字符串 }).done(function(data) { abp.notify.success('created new person with id = ' + data.personId); });
你也可以使用jquery的ajax方法調用,但是需要設置一下默認請求參數,dataType 設置為 'json', type 設置為 'POST' and contentType 設置為 'application/json,在發送請求時需要將js對象轉換成json字符串,和$.ajax一樣,你也可以傳遞參數覆蓋abp.ajax的默認參數abp.ajax返回一個promise類型,你可以鏈式編程寫如下的方法:
.done() //成功, .fail() //失敗, .then() //回調嵌套。
下面的一個簡單的例子展示ajax請求PeopleController的SavePerson方法,在.done()中可以獲取到服務端創建記錄成功後返回的記錄id。
public class PeopleController : AbpController { [HttpPost] public JsonResult SavePerson(SavePersonModel person) { //TODO: save new person to database and return new person's id //TODO: 創建一個新的person記錄並返回此記錄的id return Json(new {PersonId = 42}); } }
SavePersonModel 包含name,age等屬性. SavePerson 上標記了 HttpPost 特性 abp.ajax默認以 POST 方式請求. 返回值被簡化成了一個匿名對象。
SavePersonModel 包含name,age等屬性. SavePerson 上標記了 HttpPost 特性 abp.ajax默認以 POST 方式請求. 返回值被簡化成了一個匿名對象。
AJAX 返回值(AJAX return messages)
我們直接返回了一個匿名對象, ABP 通過 MvcAjaxResponse 類型包裝了返回值. 實際的返回值類型如下:
{ "success": true, //正確處理標志 "result": { "personId": 42 //返回的數據 }, "error": null, //如果發生錯誤,result為null,此處為錯誤信息的對象,包含message和details兩個屬性 "targetUrl": null, //可以提供一個url供客戶端重定向,例如自動構建下一頁的url "unAuthorizedRequest": false //是否通過了授權,如果返回true,客戶端應重新登錄 }
如果你繼承了AbpController,Json方法返回的對象總會被這樣包裝,如果未發生錯誤,你在abp.ajax的done(function(result,data){})中,第一個參數result是{"personId": 42}對象,data是原始對象,WebApi中繼承AbpApiController也是同樣的機制。
錯誤處理(Handling errors)
返回值如下:
{ "targetUrl": null, "result": null, "success": false, //代表出現異常 "error": { "message": "An internal error occured during your request!", //未捕捉到的異常,通常為系統異常,會自動記錄日志,具體提示信息在配置文件配置,可以搜索一下,如果是業務拋出的UserFriendlyException異常,message為具體的錯誤信息 "details": "..." //發生異常時默認會調用abp.message.error函數,你可以在abp.jquery.js修改,統一處理錯誤信息。 }, "unAuthorizedRequest": false }
動態WebAPI(Dynamic Web API Layer)
此處會根據Services動態生成WebAPI調用函數:
//通常我們使用ajax會按照如下寫法,做一個簡單的封裝來重用ajax,此處框架可以幫你生成簡單的調用方法 var savePerson = function(person) { return abp.ajax({ url: '/People/SavePerson', data: JSON.stringify(person) }); }; //調用時你需要構建參數 var newPerson = { name: 'Dougles Adams', age: 42 }; //直接調用方法,如何生成上面的調用方法可以參考源碼中的Abp.Web.Api項目中/ WebApi/ Controllers/ Scripting/ jQuery下的實現 savePerson(newPerson).done(function(data) { abp.notify.success('created new person with id = ' + data.personId); });