ASP.NET MVC: DataSource на JavaScript для работы с Web API или снова про JsSite
Сайтостроение | создано: 13.07.2013 | опубликовано: 14.07.2013 | обновлено: 07.02.2024 | просмотров: 7617
Web API очень удобный фрэймворк, который существенно упрощает создание HTTP-сервисов доступных большому число клиентских программ включая браузеры и мобильные устройства. Цель данной статьи описать контрол DataSource, который является JavaScript-оберткой для Web API сервис в концепции ASP.NET MVC.
Описание и предназначение
DataSource – контрол написанный на языке JavaScript. Библиотека JsSite включает в себя, на мой взгляд, полезный js-контрол, который может очень просто отобразить на странице сущности полученные с Web API. При этом разбитие на странице осуществляется автоматически, а также в нем уже присутствует функционал по добавлении, удалению и редактированию сущностей в списке. Помимо того что DataSource “умеет” получать данные постранично, добавлять, удалять, обновлять сущности, еще “умеет” использовать параметризированные запросы к сервису Web API.
Конструктор
DataSource находится в пространстве имен site.controls библиотеки JsSite.
site.controls.DataSource = function (options, queryParams, aggr) {...}
Конструктор принимает по умолчанию следующие параметры:
Наименование параметра | Тип | Значение |
---|---|---|
options | JSON | для расширения или переопределения настроек контрола, которые применяются по умолчанию. См. описание ниже. |
queryParams | JSON | Универсальный класс параметров запросов. Об этом классе будет рассказано в другой статье. |
aggr | JSON | Json-объект, который призван пока не используется, но планируется для хранения вычисляемых агрегирующих значений “по столбцам” всего набора данных. Об этом классе будет рассказано в другой статье. |
JSON-объект Options, как параметр настройки DataSource
Опции для настройки контрола DataSource помогут предопределить его поведение, в том числе и заданное по умолчанию.
Наименование параметра | тип | Значение по умолчанию | Описание |
---|---|---|---|
index | number | 0 | Индекс страницы запрашиваемый на сервера. |
size | number | 10 | Размер страницы (количество возвращаемых объектов) в запросе. |
groupSize | number | 15 | Количество кнопок страниц в пейджере. |
service | string | null | JavaScript “обертка” на Web API сервис. Смотри раздел “Сервис для DataSource” |
items | Array, [] | null | Коллекция объектов, которые требуется разбить на страницы и/или использовать для выборки (select) |
autoLoad | boolean | true | Запускает получение данных с Web API сразу после инициализации контрола. |
optionsCaption | JSON | null | Если DataSource используется для связывания с контролом <select>, то это свойство должно задавать объект для первого <option>, которое может быть использовано для выборки объектов с типом nullable. |
pager | JSON | Объект переопределяет настройки внутреннего контрола для настройки страниц. |
JSON-объект Pager
Наименование параметра | Тип | Значение по умолчанию | Описание |
---|---|---|---|
prev | JSON | { text: “<<”, css: “”} | Текст надписи на кнопке “назад” и CSS стиль для этой кнопки. |
current | JSON | { css: “active”} | CSS стиль для выбранной кнопки. |
next | JSON | { text: “<<”, css: “”} | Текст надписи на кнопке “вперед” и CSS стиль для этой кнопки. |
Свойства DataSource
Описание свойств сведу в простую таблицы. Так как контрол продолжает обрастать новыми свойствами, данная таблица будет обновляться.
Наименование свойства | Тип | Значение по умолчанию | Описание |
---|---|---|---|
selectedItems | ko.observableArray | null | Выбранные объекты в наборе полученных данных. На данный момент используется для внутренних расчетов. Планируется реализация множественного выбора. |
queryParams | JSON | null | Специализированный объект, который является универсальным классом параметров для запроса. Объект содержится в пространстве имен site.controls библиотеки JsSite. |
execute | JSON | null | Объект для хранения (вызова) методов сервиса используемого в DataSource |
currentItem | ko.observable | null | Выбранный объект |
events | JSON | Смотри описание событий ниже. | |
aggregate | JSON | Зарезервированное свойство для обработки агрегирующих функций. (Реализация запланирована в следующий версии) | |
indicator | JSON | Объект BusyIndicator из пространства имен site.controls библиотеки JsSite используется для индикации процесса обработки запроса на сервис. | |
hasPages | boolean | false | После получения набора объектов принимает значение true, если количество страниц больше 1. |
hasItems | boolean | false | После получения набора объектов принимает значение true, если количество объектов для отображения больше 1. |
pages | ko.observableArray | null | Страницы сформированные контролом для отображения пейджера. |
items | ko.observableArray | null | Загруженные объекты |
Методы DataSource
Наименование метода | Описание |
---|---|
resetSelectedItem | Очищает выбранный объект, устанавливая его в значение null. |
postData | Выполняет отправку данных на сервис Web API используя сервис (site.services.имясущности.js). Тип отправляемого запроса POST. |
getData | Отправляет запрос на сервер Web API для получения данных. В параметре отправки используется Options. Тип отправляемого запроса GET. |
putData | Тип отправляемого запроса PUT. |
delData | Тип отправляемого запроса DELETE. |
select | Помечает объект в коллекции как “selected”, а также устанавливает свойство “currentItem” этот объект. |
remove | Удаляет из коллекции выбранный объект (без отправки запроса на сервис Web API) |
append | Добавляет в коллекцию объект (без отправки запроса на сервис Web API) |
reload | Перезагружает объект (currentItem) с сервера. Параметром также служить id объекта. |
clear | Очищает коллекцию объектов |
События Events контрола DataSource
Все события по умолчанию имеют значение null.
Наименование параметра | Описание |
---|---|
selectedHandler | Событие срабатывает после вызова метода select. |
getCompleteHandler | Событие срабатывает после получение коллекции сущностей. |
postCompleteHandler | Событие срабатывает после получение положительного результата при добавлении сущности (метод postData). |
deleteCompleteHandler | Событие срабатывает после получение положительного результата при удалении сущности (метод delData). |
Сервис для DataSource
Для того чтобы DataSource начал работу с Web API требуется наличие специализированного сервиса. Это, своего рода, “обертка” (wrapper) на GET, POST, PUT, DELETE методы Web API. Сервис прост до безобразия, и преследует всего лишь одну цель: все обращения к сервису Web API должны быть из одного места! У вас на представлении (View) может быть несколько DataSource-объектов, которые могут использовать один и тот же сервис. Наверное это всё немного сложно, лучше показать всё на примерах.
Ничего не может быть лучше хорошего примера, чем код сервиса:
(function (site) { site.services.documents = function () { var init = function () { site.amplify.request.define("getdocument", "ajax", { url: "/api/documentapi", dataType: "json", type: "GET", cache: false }); site.amplify.request.define("postdocument", "ajax", { url: "/api/documentapi", dataType: "json", contentType: "application/json; charset=utf-8", type: "POST", cache: false }); site.amplify.request.define("putdocument", "ajax", { url: "/api/documentapi", dataType: "json", contentType: "application/json; charset=utf-8", type: "PUT", cache: false }); site.amplify.request.define("deldocument", "ajax", { url: "/api/documentapi", dataType: "json", contentType: "application/json; charset=utf-8", type: "DELETE", cache: false }); }, mapItem = function (data) { return new site.m.Document(data); }, mapItems = function (data) { var mapped = []; site._.each(data, function (item) { mapped.push(mapItem(item)); }); return mapped; }, getData = function (params, back) { if (typeof back !== "function") throw new Error("callback not a function"); if (!params) throw new Error("queryParams notis null"); return site.amplify.request({ resourceId: "getdocument", data: { qp: ko.toJSON(params) }, success: function (json) { if (json) { if (json.success) { params.total(json.total); var result = mapItems(json.items); back(result); return; } if (json.warning) { site.logger.warning(json.warning); } if (json.error) { site.logger.error(json.error); } } back(); }, error: function () { site.logger.error("Ошибка загрузки сущности \"Документ\"); back(); } }); }, getDataById = function (params, back) { if (typeof back !== "function") throw new Error("callback not a function"); if (!params) throw new Error("queryParams notis null"); return site.amplify.request({ resourceId: "getdocument", data: { id: params }, success: function (json) { if (json) { if (json.success) { var result = mapItem(json.item); back(result); return; } if (json.warning) { site.logger.warning(json.warning); } if (json.error) { site.logger.error(json.error); } } back(); }, error: function () { site.logger.error("Ошибка загрузки сущности \"Должность\"); back(); } }); }, postData = function (params, back) { if (typeof back !== "function") throw new Error("callback not a function"); return site.amplify.request({ resourceId: "postdocument", data: ko.toJSON(params), success: function (json) { if (json) { if (json.success) { site.logger.success(json.success); back(new mapItem(json.item)); return; } if (json.warning) { site.logger.warning(json.warning); } if (json.error) { site.logger.error(json.error); } } back(); }, error: function () { site.logger.error("Ошибка сохранения сущности \"Документ\""); back(); } }); }, putData = function (params, back) { if (typeof back !== "function") throw new Error("callback not a function"); return site.amplify.request({ resourceId: "putdocument", data: ko.toJSON(params), success: function (json) { if (json) { if (json.success) { site.logger.success(json.success); back(new mapItem(json.item)); return; } if (json.warning) { site.logger.warning(json.warning); } if (json.error) { site.logger.error(json.error); } } back(); }, error: function () { site.logger.error("Ошибка обновления сущности \"Документ\"); back(); } }); }, delData = function (params, back) { if (typeof back !== "function") throw new Error("callback not a function"); return site.amplify.request({ resourceId: "deldocument", data: ko.toJSON(params), success: function (json) { if (json) { if (json.success) { site.logger.success(json.success); back(new mapItem(json.item)); return; } if (json.warning) { site.logger.warning(json.warning); } if (json.error) { site.logger.error(json.error); } } back(); }, error: function () { site.logger.error("Ошибка удаления сущности \"Документ\"); back(); } }); }; init(); return { getDataById: getDataById, postData: postData, getData: getData, putData: putData, delData: delData }; }(); })(site);
Прошу обратить ваше внимание на то, что у каждого сервиса, который должен быть использован в контроле DataSource должны быть обязательные методы. Все они перечислены в строках 186-190. Дополнительные методы Web API сервиса прописываются аналогичным образом, и так же публикуются в публичные свойства (litteral object). Вызов дополнительных методов производится через объект execute контрола DataSource.
Все сервисы размещены в пространстве имен site.services. Пример сервиса приведен в предыдущем листинге. Но более свежий пример всегда есть в файле site.services.js, который поставляется с nuget-пакетом JsSite.
Ссылки по теме
JsSite – nuget-пакет, в котором находится DataSource-контрол и все необходимые для работы контрола дополнения в виде утилит и вспомогательных классов.
В следующих статьях я, на примере простого приложения, покажу как используя этот незамысловатый контрол можно с легкостью реализовать Master – Details связку. К обеим частям прилагаются проект для экспериментов.