From b607c9cd87330fc91eaf84155abca084ea82147d Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 10 Aug 2017 16:14:11 +0200 Subject: [PATCH] add documentation to users.resource --- .../src/common/resources/users.resource.js | 211 +++++++++++++++++- 1 file changed, 210 insertions(+), 1 deletion(-) diff --git a/src/Umbraco.Web.UI.Client/src/common/resources/users.resource.js b/src/Umbraco.Web.UI.Client/src/common/resources/users.resource.js index 55a8636bdd..72564398c0 100644 --- a/src/Umbraco.Web.UI.Client/src/common/resources/users.resource.js +++ b/src/Umbraco.Web.UI.Client/src/common/resources/users.resource.js @@ -4,13 +4,33 @@ * @function * * @description - * Used by the users section to get users and send requests to create, invite, delete, etc. users. + * Used by the users section to get users and send requests to create, invite, disable, etc. users. */ (function () { 'use strict'; function usersResource($http, umbRequestHelper, $q, umbDataFormatter) { + /** + * @ngdoc method + * @name umbraco.resources.usersResource#clearAvatar + * @methodOf umbraco.resources.usersResource + * + * @description + * Deletes the user avatar + * + * ##usage + * 
+          * usersResource.clearAvatar(1)
+          *    .then(function() {
+          *        alert("avatar is gone");
+          *    });
+          *
+ * + * @param {Array} id id of user. + * @returns {Promise} resourcePromise object. + * + */ function clearAvatar(userId) { return umbRequestHelper.resourcePromise( @@ -22,6 +42,26 @@ 'Failed to clear the user avatar ' + userId); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#disableUsers + * @methodOf umbraco.resources.usersResource + * + * @description + * Disables a collection of users + * + * ##usage + * 
+          * usersResource.disableUsers([1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were disabled");
+          *    });
+          *
+ * + * @param {Array} ids ids of users to disable. + * @returns {Promise} resourcePromise object. + * + */ function disableUsers(userIds) { if (!userIds) { throw "userIds not specified"; @@ -39,6 +79,26 @@ 'Failed to disable the users ' + userIds.join(",")); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#enableUsers + * @methodOf umbraco.resources.usersResource + * + * @description + * Enables a collection of users + * + * ##usage + * 
+          * usersResource.enableUsers([1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were enabled");
+          *    });
+          *
+ * + * @param {Array} ids ids of users to enable. + * @returns {Promise} resourcePromise object. + * + */ function enableUsers(userIds) { if (!userIds) { throw "userIds not specified"; @@ -55,6 +115,26 @@ 'Failed to enable the users ' + userIds.join(",")); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#unlockUsers + * @methodOf umbraco.resources.usersResource + * + * @description + * Unlocks a collection of users + * + * ##usage + * 
+          * usersResource.unlockUsers([1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were unlocked");
+          *    });
+          *
+ * + * @param {Array} ids ids of users to unlock. + * @returns {Promise} resourcePromise object. + * + */ function unlockUsers(userIds) { if (!userIds) { throw "userIds not specified"; @@ -71,6 +151,27 @@ 'Failed to enable the users ' + userIds.join(",")); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#setUserGroupsOnUsers + * @methodOf umbraco.resources.usersResource + * + * @description + * Overwrites the existing user groups on a collection of users + * + * ##usage + * 
+          * usersResource.setUserGroupsOnUsers(['admin', 'editor'], [1, 2, 3, 4, 5])
+          *    .then(function() {
+          *        alert("users were updated");
+          *    });
+          *
+ * + * @param {Array} userGroupAliases aliases of user groups. + * @param {Array} ids ids of users to update. + * @returns {Promise} resourcePromise object. + * + */ function setUserGroupsOnUsers(userGroups, userIds) { var userGroupAliases = userGroups.map(function(o) { return o.alias; }); var query = "userGroupAliases=" + userGroupAliases.join("&userGroupAliases=") + "&userIds=" + userIds.join("&userIds="); @@ -83,6 +184,34 @@ 'Failed to set user groups ' + userGroupAliases.join(",") + ' on the users ' + userIds.join(",")); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#getPagedResults + * @methodOf umbraco.resources.usersResource + * + * @description + * Get users + * + * ##usage + * 
+          * usersResource.getPagedResults({pageSize: 10, pageNumber: 2})
+          *    .then(function(data) {
+          *        var users = data.items;
+          *        alert('they are here!');
+          *    });
+          *
+ * + * @param {Object} options optional options object + * @param {Int} options.pageSize if paging data, number of users per page, default = 25 + * @param {Int} options.pageNumber if paging data, current page index, default = 1 + * @param {String} options.filter if provided, query will only return those with names matching the filter + * @param {String} options.orderDirection can be `Ascending` or `Descending` - Default: `Ascending` + * @param {String} options.orderBy property to order users by, default: `Username` + * @param {Array} options.userGroups property to filter users by user group + * @param {Array} options.userStates property to filter users by user state + * @returns {Promise} resourcePromise object containing an array of content items. + * + */ function getPagedResults(options) { var defaults = { pageSize: 25, @@ -135,6 +264,26 @@ 'Failed to retrieve users paged result'); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#getUser + * @methodOf umbraco.resources.usersResource + * + * @description + * Gets a user + * + * ##usage + * 
+          * usersResource.getUser(1)
+          *    .then(function(user) {
+          *        alert("It's here");
+          *    });
+          *
+ * + * @param {Array} id user id. + * @returns {Promise} resourcePromise object containing the user. + * + */ function getUser(userId) { return umbRequestHelper.resourcePromise( @@ -146,6 +295,26 @@ "Failed to retrieve data for user " + userId); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#createUser + * @methodOf umbraco.resources.usersResource + * + * @description + * Creates a new user + * + * ##usage + * 
+          * usersResource.createUser(user)
+          *    .then(function(newUser) {
+          *        alert("It's here");
+          *    });
+          *
+ * + * @param {Object} user user to create + * @returns {Promise} resourcePromise object containing the new user. + * + */ function createUser(user) { if (!user) { throw "user not specified"; @@ -163,6 +332,26 @@ "Failed to save user"); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#inviteUser + * @methodOf umbraco.resources.usersResource + * + * @description + * Creates and sends an email invitation to a new user + * + * ##usage + * 
+          * usersResource.inviteUser(user)
+          *    .then(function(newUser) {
+          *        alert("It's here");
+          *    });
+          *
+ * + * @param {Object} user user to invite + * @returns {Promise} resourcePromise object containing the new user. + * + */ function inviteUser(user) { if (!user) { throw "user not specified"; @@ -180,6 +369,26 @@ "Failed to invite user"); } + /** + * @ngdoc method + * @name umbraco.resources.usersResource#saveUser + * @methodOf umbraco.resources.usersResource + * + * @description + * Saves a user + * + * ##usage + * 
+          * usersResource.saveUser(user)
+          *    .then(function(updatedUser) {
+          *        alert("It's here");
+          *    });
+          *
+ * + * @param {Object} user object to save + * @returns {Promise} resourcePromise object containing the updated user. + * + */ function saveUser(user) { if (!user) { throw "user not specified";