Adds documentation for missing resource methods

This commit is contained in:
perploug
2013-11-19 21:56:35 +01:00
parent 23d5d117e7
commit 56e9d0a602
12 changed files with 564 additions and 34 deletions

View File

@@ -565,10 +565,57 @@ function contentResource($q, $http, umbDataFormatter, umbRequestHelper) {
return saveContentItem(content, "publish" + (isNew ? "New" : ""), files);
},
/**
* @ngdoc method
* @name umbraco.resources.contentResource#sendToPublish
* @methodOf umbraco.resources.contentResource
*
* @description
* Saves changes made to a content item, and notifies any subscribers about a pending publication
*
* ##usage
* <pre>
* contentResource.getById(1234)
* .then(function(content) {
* content.name = "I want a new name, and be published!";
* contentResource.sendToPublish(content, false)
* .then(function(content){
* alert("Retrieved, updated and notication send off");
* });
* });
* </pre>
*
* @param {Object} content The content item object with changes applied
* @param {Bool} isNew set to true to create a new item or to update an existing
* @param {Array} files collection of files for the document
* @returns {Promise} resourcePromise object containing the saved content item.
*
*/
sendToPublish: function (content, isNew, files) {
return saveContentItem(content, "sendPublish" + (isNew ? "New" : ""), files);
},
/**
* @ngdoc method
* @name umbraco.resources.contentResource#publishByid
* @methodOf umbraco.resources.contentResource
*
* @description
* Publishes a content item with a given ID
*
* ##usage
* <pre>
* contentResource.publishById(1234)
* .then(function(content) {
* alert("published");
* });
* </pre>
*
* @param {Int} id The ID of the conten to publish
* @returns {Promise} resourcePromise object containing the published content item.
*
*/
publishById: function(id){
if (!id) {

View File

@@ -7,7 +7,25 @@ function contentTypeResource($q, $http, umbRequestHelper) {
return {
//return a content type with a given ID
/**
* @ngdoc method
* @name umbraco.resources.contentTypeResource#getContentType
* @methodOf umbraco.resources.contentTypeResource
*
* @description
* Returns a content type with a given ID
*
* ##usage
* <pre>
* contentTypeResource.getContentType(1234)
* .then(function(type) {
* $scope.type = type;
* });
* </pre>
* @param {Int} id id of the content type to retrieve
* @returns {Promise} resourcePromise object.
*
*/
getContentType: function (id) {
var deferred = $q.defer();
@@ -22,7 +40,25 @@ function contentTypeResource($q, $http, umbRequestHelper) {
return deferred.promise;
},
//return all types allowed under given document
/**
* @ngdoc method
* @name umbraco.resources.contentTypeResource#getAllowedTypes
* @methodOf umbraco.resources.contentTypeResource
*
* @description
* Returns a list of allowed content types underneath a content item with a given ID
*
* ##usage
* <pre>
* contentTypeResource.getAllowedTypes(1234)
* .then(function(array) {
* $scope.type = type;
* });
* </pre>
* @param {Int} contentId id of the content item to retrive allowed child types for
* @returns {Promise} resourcePromise object.
*
*/
getAllowedTypes: function (contentId) {
return umbRequestHelper.resourcePromise(

View File

@@ -6,6 +6,19 @@
function dashboardResource($q, $http, umbRequestHelper) {
//the factory object returned
return {
/**
* @ngdoc method
* @name umbraco.resources.dashboardResource#getDashboard
* @methodOf umbraco.resources.dashboardResource
*
* @description
* Retrieves the dashboard configuration for a given section
*
* @param {string} section Alias of section to retrieve dashboard configuraton for
* @returns {Promise} resourcePromise object containing the user array.
*
*/
getDashboard: function (section) {
return umbRequestHelper.resourcePromise(

View File

@@ -7,7 +7,28 @@ function dataTypeResource($q, $http, umbDataFormatter, umbRequestHelper) {
return {
getPreValues: function (editorId, dataTypeId) {
/**
* @ngdoc method
* @name umbraco.resources.dataTypeResource#getPreValues
* @methodOf umbraco.resources.dataTypeResource
*
* @description
* Retrieves available prevalues for a given data type + editor
*
* ##usage
* <pre>
* dataTypeResource.getPrevalyes("Umbraco.MediaPicker", 1234)
* .then(function(prevalues) {
* alert('its gone!');
* });
* </pre>
*
* @param {String} editorAlias string alias of editor type to retrive prevalues configuration for
* @param {Int} id id of datatype to retrieve prevalues for
* @returns {Promise} resourcePromise object.
*
*/
getPreValues: function (editorAlias, dataTypeId) {
if (!dataTypeId) {
dataTypeId = -1;
@@ -18,10 +39,30 @@ function dataTypeResource($q, $http, umbDataFormatter, umbRequestHelper) {
umbRequestHelper.getApiUrl(
"dataTypeApiBaseUrl",
"GetPreValues",
[{ editorAlias: editorId }, { dataTypeId: dataTypeId }])),
[{ editorAlias: editorAlias }, { dataTypeId: dataTypeId }])),
'Failed to retreive pre values for editor id ' + editorId);
},
/**
* @ngdoc method
* @name umbraco.resources.dataTypeResource#getById
* @methodOf umbraco.resources.dataTypeResource
*
* @description
* Gets a data type item with a given id
*
* ##usage
* <pre>
* dataTypeResource.getById(1234)
* .then(function() {
* alert('its gone!');
* });
* </pre>
*
* @param {Int} id id of data type to retrieve
* @returns {Promise} resourcePromise object.
*
*/
getById: function (id) {
return umbRequestHelper.resourcePromise(
@@ -39,21 +80,45 @@ function dataTypeResource($q, $http, umbDataFormatter, umbRequestHelper) {
$http.get(
umbRequestHelper.getApiUrl(
"dataTypeApiBaseUrl",
"GetAll",
[{ id: id }])),
'Failed to retreive data for data type id ' + id);
"GetAll")),
'Failed to retreive data');
},
/** returns an empty content object which can be persistent on the content service
requires the parent id and the alias of the content type to base the scaffold on */
getScaffold: function (parentId, alias) {
/**
* @ngdoc method
* @name umbraco.resources.contentResource#getScaffold
* @methodOf umbraco.resources.contentResource
*
* @description
* Returns a scaffold of an empty data type item
*
* The scaffold is used to build editors for data types that has not yet been populated with data.
*
* ##usage
* <pre>
* dataTypeResource.getScaffold()
* .then(function(scaffold) {
* var myType = scaffold;
* myType.name = "My new data type";
*
* dataTypeResource.save(myType, myType.preValues, true)
* .then(function(type){
* alert("Retrieved, updated and saved again");
* });
* });
* </pre>
*
* @returns {Promise} resourcePromise object containing the data type scaffold.
*
*/
getScaffold: function () {
return umbRequestHelper.resourcePromise(
$http.get(
umbRequestHelper.getApiUrl(
"dataTypeApiBaseUrl",
"GetEmpty")),
'Failed to retreive data for empty datatype ' + alias);
'Failed to retreive data for empty datatype');
},
/**
* @ngdoc method
@@ -61,7 +126,7 @@ function dataTypeResource($q, $http, umbDataFormatter, umbRequestHelper) {
* @methodOf umbraco.resources.dataTypeResource
*
* @description
* Deletes a content item with a given id
* Deletes a data type with a given id
*
* ##usage
* <pre>
@@ -84,7 +149,33 @@ function dataTypeResource($q, $http, umbDataFormatter, umbRequestHelper) {
[{ id: id }])),
'Failed to delete item ' + id);
},
/** saves or updates a data type object */
/**
* @ngdoc method
* @name umbraco.resources.dataTypeResource#deleteById
* @methodOf umbraco.resources.dataTypeResource
*
* @description
* Saves or update a data typw
*
* ##usage
* <pre>
* dataTypeResource.getById(1234)
* .then(function(type) {
* type.name ="hibba";
*
* dataTypeResource.save(type, type.preValues, false).then(function(type){
* alert('its done!');
* }):
* });
* </pre>
*
* @param {Object} dataType data type object to create/update
* @param {Array} preValues collection of prevalues on the datatype
* @param {Bool} isNew set to true if type should be create instead of updated
* @returns {Promise} resourcePromise object.
*
*/
save: function (dataType, preValues, isNew) {
var saveModel = umbDataFormatter.formatDataTypePostData(dataType, preValues, "save" + (isNew ? "New" : ""));

View File

@@ -264,6 +264,28 @@ function entityResource($q, $http, umbRequestHelper) {
'Failed to retreive entity data for query ' + query);
},
/**
* @ngdoc method
* @name umbraco.resources.entityResource#searchAll
* @methodOf umbraco.resources.entityResource
*
* @description
* Gets an array of entities from all available search indexes, given a lucene query
*
* ##usage
* <pre>
* entityResource.searchAll("bob")
* .then(function(array) {
* var myDoc = array;
* alert('they are here!');
* });
* </pre>
*
* @param {String} Query search query
* @returns {Promise} resourcePromise object containing the entity array.
*
*/
searchAll: function (query) {
return umbRequestHelper.resourcePromise(

View File

@@ -329,12 +329,59 @@ function mediaResource($q, $http, umbDataFormatter, umbRequestHelper) {
'Failed to retreive children for media item ' + parentId);
},
/** saves or updates a media object */
/**
* @ngdoc method
* @name umbraco.resources.mediaResource#save
* @methodOf umbraco.resources.mediaResource
*
* @description
* Saves changes made to a media item, if the media item is new, the isNew paramater must be passed to force creation
* if the media item needs to have files attached, they must be provided as the files param and passed seperately
*
*
* ##usage
* <pre>
* mediaResource.getById(1234)
* .then(function(media) {
* media.name = "I want a new name!";
* mediaResource.save(media, false)
* .then(function(media){
* alert("Retrieved, updated and saved again");
* });
* });
* </pre>
*
* @param {Object} media The media item object with changes applied
* @param {Bool} isNew set to true to create a new item or to update an existing
* @param {Array} files collection of files for the media item
* @returns {Promise} resourcePromise object containing the saved media item.
*
*/
save: function (media, isNew, files) {
return saveMediaItem(media, "save" + (isNew ? "New" : ""), files);
},
//** shorthand for creating a new folder under a given parent **/
/**
* @ngdoc method
* @name umbraco.resources.mediaResource#addFolder
* @methodOf umbraco.resources.mediaResource
*
* @description
* Shorthand for adding a media item of the type "Folder" under a given parent ID
*
* ##usage
* <pre>
* mediaResource.addFolder("My gallery", 1234)
* .then(function(folder) {
* alert('New folder');
* });
* </pre>
*
* @param {string} name Name of the folder to create
* @param {int} parentId Id of the media item to create the folder underneath
* @returns {Promise} resourcePromise object.
*
*/
addFolder: function(name, parentId){
return umbRequestHelper.resourcePromise(
$http.post(umbRequestHelper

View File

@@ -7,16 +7,34 @@ function mediaTypeResource($q, $http, umbRequestHelper) {
return {
//return all types allowed under given document
getAllowedTypes: function (contentId) {
/**
* @ngdoc method
* @name umbraco.resources.mediaTypeResource#getAllowedTypes
* @methodOf umbraco.resources.mdiaTypeResource
*
* @description
* Returns a list of allowed media types underneath a media item with a given ID
*
* ##usage
* <pre>
* mediaTypeResource.getAllowedTypes(1234)
* .then(function(array) {
* $scope.type = type;
* });
* </pre>
* @param {Int} mediaId id of the media item to retrive allowed child types for
* @returns {Promise} resourcePromise object.
*
*/
getAllowedTypes: function (mediaId) {
return umbRequestHelper.resourcePromise(
$http.get(
umbRequestHelper.getApiUrl(
"mediaTypeApiBaseUrl",
"GetAllowedChildren",
[{ contentId: contentId }])),
'Failed to retreive data for media id ' + contentId);
[{ contentId: mediaId }])),
'Failed to retreive data for media id ' + mediaId);
}
};

View File

@@ -138,7 +138,34 @@ function memberResource($q, $http, umbDataFormatter, umbRequestHelper) {
},
/** saves or updates a member object */
/**
* @ngdoc method
* @name umbraco.resources.memberResource#save
* @methodOf umbraco.resources.memberResource
*
* @description
* Saves changes made to a member, if the member is new, the isNew paramater must be passed to force creation
* if the member needs to have files attached, they must be provided as the files param and passed seperately
*
*
* ##usage
* <pre>
* memberResource.getBykey("23234-sd8djsd-3h8d3j-sdh8d")
* .then(function(member) {
* member.name = "Bob";
* memberResource.save(member, false)
* .then(function(member){
* alert("Retrieved, updated and saved again");
* });
* });
* </pre>
*
* @param {Object} media The member item object with changes applied
* @param {Bool} isNew set to true to create a new item or to update an existing
* @param {Array} files collection of files for the media item
* @returns {Promise} resourcePromise object containing the saved media item.
*
*/
save: function (member, isNew, files) {
return saveMember(member, "save" + (isNew ? "New" : ""), files);
}

View File

@@ -38,24 +38,61 @@ function stylesheetResource($q, $http, umbRequestHelper) {
'Failed to retreive stylesheets ');
},
/**
* @ngdoc method
* @name umbraco.resources.stylesheetResource#getRules
* @methodOf umbraco.resources.stylesheetResource
*
* @description
* Returns all defined child rules for a stylesheet with a given ID
*
* ##usage
* <pre>
* stylesheetResource.getRules(2345)
* .then(function(rules) {
* alert('its here!');
* });
* </pre>
*
* @returns {Promise} resourcePromise object containing the rules.
*
*/
getRules: function (id) {
return umbRequestHelper.resourcePromise(
$http.get(
umbRequestHelper.getApiUrl(
"stylesheetApiBaseUrl",
"GetRules",
[{ id: id }]
) +"&rnd=" + Math.floor(Math.random()*1001), {cache: false}),
[{ id: id }]) +"&rnd=" + Math.floor(Math.random()*1001), {cache: false}),
'Failed to retreive stylesheets ');
},
/**
* @ngdoc method
* @name umbraco.resources.stylesheetResource#getRulesByName
* @methodOf umbraco.resources.stylesheetResource
*
* @description
* Returns all defined child rules for a stylesheet with a given name
*
* ##usage
* <pre>
* stylesheetResource.getRulesByName("ie7stylesheet")
* .then(function(rules) {
* alert('its here!');
* });
* </pre>
*
* @returns {Promise} resourcePromise object containing the rules.
*
*/
getRulesByName: function (name) {
return umbRequestHelper.resourcePromise(
$http.get(
umbRequestHelper.getApiUrl(
"stylesheetApiBaseUrl",
"GetRulesByName",
[{ name: name }])),
[{ name: name }]) +"&rnd=" + Math.floor(Math.random()*1001), {cache: false}),
'Failed to retreive stylesheets ');
}
};

View File

@@ -1,3 +1,25 @@
/**
* @ngdoc service
* @name umbraco.services.searchService
*
*
* @description
* Service for handling the main application search, can currently search content, media and members
*
* ##usage
* To use, simply inject the searchService into any controller that needs it, and make
* sure the umbraco.services module is accesible - which it should be by default.
*
* <pre>
* searchService.searchMembers({term: 'bob'}).then(function(results){
* angular.forEach(results, function(result){
* //returns:
* {name: "name", id: 1234, menuUrl: "url", editorPath: "url", metaData: {}, subtitle: "/path/etc" }
* })
* var result =
* })
* </pre>
*/
angular.module('umbraco.services')
.factory('searchService', function ($q, $log, entityResource, contentResource, umbRequestHelper) {
@@ -23,6 +45,18 @@ angular.module('umbraco.services')
}
return {
/**
* @ngdoc method
* @name umbraco.services.searchService#searchMembers
* @methodOf umbraco.services.searchService
*
* @description
* Searches the default member search index
* @param {Object} args argument object
* @param {String} args.term seach term
* @returns {Promise} returns promise containing all matching members
*/
searchMembers: function(args) {
if (!args.term) {
@@ -36,6 +70,18 @@ angular.module('umbraco.services')
return data;
});
},
/**
* @ngdoc method
* @name umbraco.services.searchService#searchContent
* @methodOf umbraco.services.searchService
*
* @description
* Searches the default internal content search index
* @param {Object} args argument object
* @param {String} args.term seach term
* @returns {Promise} returns promise containing all matching content items
*/
searchContent: function(args) {
if (!args.term) {
@@ -49,6 +95,18 @@ angular.module('umbraco.services')
return data;
});
},
/**
* @ngdoc method
* @name umbraco.services.searchService#searchMedia
* @methodOf umbraco.services.searchService
*
* @description
* Searches the default media search index
* @param {Object} args argument object
* @param {String} args.term seach term
* @returns {Promise} returns promise containing all matching media items
*/
searchMedia: function(args) {
if (!args.term) {
@@ -62,6 +120,18 @@ angular.module('umbraco.services')
return data;
});
},
/**
* @ngdoc method
* @name umbraco.services.searchService#searchAll
* @methodOf umbraco.services.searchService
*
* @description
* Searches all available indexes and returns all results in one collection
* @param {Object} args argument object
* @param {String} args.term seach term
* @returns {Promise} returns promise containing all matching items
*/
searchAll: function (args) {
if (!args.term) {

View File

@@ -121,7 +121,20 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
return undefined;
},
/** clears the tree cache - with optional cacheKey, optional section or optional filter */
/**
* @ngdoc method
* @name umbraco.services.treeService#clearCache
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Clears the tree cache - with optional cacheKey, optional section or optional filter.
*
* @param {Object} args arguments
* @param {String} args.cacheKey optional cachekey - this is used to clear specific trees in dialogs
* @param {String} args.section optional section alias - clear tree for a given section
* @param {String} args.childrenOf optional parent ID - only clear the cache below a specific node
*/
clearCache: function (args) {
//clear all if not specified
if (!args) {
@@ -252,7 +265,16 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
},
/** Removes a given tree node from the tree */
/**
* @ngdoc method
* @name umbraco.services.treeService#removeNode
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Removes a given node from the tree
* @param {object} treeNode the node to remove
*/
removeNode: function(treeNode) {
if (treeNode.parent() == null) {
throw "Cannot remove a node that doesn't have a parent";
@@ -261,14 +283,33 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
treeNode.parent().children.splice(treeNode.parent().children.indexOf(treeNode), 1);
},
/** Removes all child nodes from a given tree node */
/**
* @ngdoc method
* @name umbraco.services.treeService#removeChildNodes
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Removes all child nodes from a given tree node
* @param {object} treeNode the node to remove children from
*/
removeChildNodes : function(treeNode) {
treeNode.expanded = false;
treeNode.children = [];
treeNode.hasChildren = false;
},
/** Gets a child node by id */
/**
* @ngdoc method
* @name umbraco.services.treeService#getChildNode
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Gets a child node with a given ID, from a specific treeNode
* @param {object} treeNode to retrive child node from
* @param {int} id id of child node
*/
getChildNode: function (treeNode, id) {
if (!treeNode.children) {
return null;
@@ -279,7 +320,18 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
return found === undefined ? null : found;
},
/** Gets a descendant node by id */
/**
* @ngdoc method
* @name umbraco.services.treeService#getDescendantNode
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Gets a descendant node by id
* @param {object} treeNode to retrive descendant node from
* @param {int} id id of descendant node
* @param {string} treeAlias - optional tree alias, if fetching descendant node from a child of a listview document
*/
getDescendantNode: function(treeNode, id, treeAlias) {
//validate if it is a section container since we'll need a treeAlias if it is one
@@ -332,7 +384,16 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
return found === undefined ? null : found;
},
/** Gets the root node of the current tree type for a given tree node */
/**
* @ngdoc method
* @name umbraco.services.treeService#getTreeRoot
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Gets the root node of the current tree type for a given tree node
* @param {object} treeNode to retrive tree root node from
*/
getTreeRoot: function (treeNode) {
if (!treeNode) {
throw "treeNode cannot be null";
@@ -354,6 +415,16 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
},
/** Gets the node's tree alias, this is done by looking up the meta-data of the current node's root node */
/**
* @ngdoc method
* @name umbraco.services.treeService#getTreeAlias
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Gets the node's tree alias, this is done by looking up the meta-data of the current node's root node
* @param {object} treeNode to retrive tree alias from
*/
getTreeAlias : function(treeNode) {
var root = this.getTreeRoot(treeNode);
if (root) {
@@ -362,7 +433,18 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
return "";
},
/** gets the tree, returns a promise */
/**
* @ngdoc method
* @name umbraco.services.treeService#getTree
* @methodOf umbraco.services.treeService
* @function
*
* @description
* gets the tree, returns a promise
* @param {object} args Arguments
* @param {string} args.section Section alias
* @param {string} args.cacheKey Optional cachekey
*/
getTree: function (args) {
var deferred = $q.defer();
@@ -409,6 +491,17 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
return deferred.promise;
},
/**
* @ngdoc method
* @name umbraco.services.treeService#getMenu
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Returns available menu actions for a given tree node
* @param {object} args Arguments
* @param {string} args.treeNode tree node object to retrieve the menu for
*/
getMenu: function (args) {
if (!args) {
@@ -428,7 +521,18 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
});
},
/** Gets the children from the server for a given node */
/**
* @ngdoc method
* @name umbraco.services.treeService#getChildren
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Gets the children from the server for a given node
* @param {object} args Arguments
* @param {object} args.node tree node object to retrieve the children for
* @param {string} args.section current section alias
*/
getChildren: function (args) {
if (!args) {
@@ -451,7 +555,16 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
});
},
/** This re-loads the single node from the server */
/**
* @ngdoc method
* @name umbraco.services.treeService#reloadNode
* @methodOf umbraco.services.treeService
* @function
*
* @description
* Re-loads the single node from the server
* @param {object} node Tree node to reload
*/
reloadNode: function(node) {
if (!node) {
throw "node cannot be null";
@@ -495,7 +608,16 @@ function treeService($q, treeResource, iconHelper, notificationsService, $rootSc
return deferred.promise;
},
/** This will return the current node's path by walking up the tree */
/**
* @ngdoc method
* @name umbraco.services.treeService#getPath
* @methodOf umbraco.services.treeService
* @function
*
* @description
* This will return the current node's path by walking up the tree
* @param {object} node Tree node to retrieve path for
*/
getPath: function(node) {
if (!node) {
throw "node cannot be null";

View File

@@ -46,7 +46,7 @@ function DataTypeEditController($scope, $routeParams, $location, appState, navig
if ($routeParams.create) {
//we are creating so get an empty data type item
dataTypeResource.getScaffold($routeParams.id)
dataTypeResource.getScaffold()
.then(function(data) {
$scope.loaded = true;
$scope.preValuesLoaded = true;