yv01p/Umbraco-CMS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

JsDocs comments on listviewhelper (U4-7185)

Browse Source
This commit is contained in:
Per Ploug
2016-04-14 11:36:24 +02:00
committed by Sebastiaan Janssen
parent bf70e208ad
commit fcaa4ad8d6
1 changed files with 221 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
src/Umbraco.Web.UI.Client/src/common/services/listviewhelper.service.js
View File

@@ -1,3 +1,47 @@
/**
@ngdoc service
* @name umbraco.services.listViewHelper
*
*
* @description
* Service for performing operations against items in the list view UI. Used by the built-in internal listviews
* as well as custom listview.
*
* A custom listview is always used inside a wrapper listview, so there are a number of inherited values on its
* scope by default:
*
* **$scope.selection**: Array containing all items currently selected in the listview
*
* **$scope.items**: Array containing all items currently displayed in the listview
*
* **$scope.folders**: Array containing all folders in the current listview (only for media)
*
* **$scope.options**: configuration object containing information such as pagesize, permissions, order direction etc.
*
* **$scope.model.config.layouts**: array of available layouts to apply to the listview (grid, list or custom layout)
*
* ##Usage##
* To use, inject listViewHelper into custom listview controller, listviewhelper expects you
* to pass in the full collection of items in the listview in several of its methods
* this collection is inherited from the parent controller and is available on $scope.selection
*
* <pre>
* angular.module("umbraco").controller("my.listVieweditor". function($scope, listViewHelper){
*
* //current items in the listview
* var items = $scope.items;
*
* //current selection
* var selection = $scope.selection;
*
* //deselect an item , $scope.selection is inherited, item is picked from inherited $scope.items
* listViewHelper.deselectItem(item, $scope.selection);
*
* //test if all items are selected, $scope.items + $scope.selection are inherited
* listViewhelper.isSelectedAll($scope.items, $scope.selection);
* });
* </pre>
*/
(function () {
'use strict';
@@ -6,6 +50,19 @@
var firstSelectedIndex = 0;
var localStorageKey = "umblistViewLayout";
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#getLayout
* @methodOf umbraco.services.listViewHelper
*
* @description
* Method for internal use, based on the collection of layouts passed, the method selects either
* any previous layout from local storage, or picks the first allowed layout
*
* @param {Number} nodeId The id of the current node displayed in the content editor
* @param {Array} availableLayouts Array of all allowed layouts, available from $scope.model.config.layouts
*/
function getLayout(nodeId, availableLayouts) {
var storedLayouts = [];
@@ -28,6 +85,19 @@
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#setLayout
* @methodOf umbraco.services.listViewHelper
*
* @description
* Changes the current layout used by the listview to the layout passed in. Stores selection in localstorage
*
* @param {Number} nodeID Id of the current node displayed in the content editor
* @param {Object} selectedLayout Layout selected as the layout to set as the current layout
* @param {Array} availableLayouts Array of all allowed layouts, available from $scope.model.config.layouts
*/
function setLayout(nodeId, selectedLayout, availableLayouts) {
var activeLayout = {};
@@ -54,6 +124,18 @@
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#saveLayoutInLocalStorage
* @methodOf umbraco.services.listViewHelper
*
* @description
* Stores a given layout as the current default selection in local storage
*
* @param {Number} nodeId Id of the current node displayed in the content editor
* @param {Object} selectedLayout Layout selected as the layout to set as the current layout
*/
function saveLayoutInLocalStorage(nodeId, selectedLayout) {
var layoutFound = false;
var storedLayouts = [];
@@ -84,6 +166,17 @@
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#getFirstAllowedLayout
* @methodOf umbraco.services.listViewHelper
*
* @description
* Returns currently selected layout, or alternatively the first layout in the available layouts collection
*
* @param {Array} layouts Array of all allowed layouts, available from $scope.model.config.layouts
*/
function getFirstAllowedLayout(layouts) {
var firstAllowedLayout = {};
@@ -99,6 +192,23 @@
return firstAllowedLayout;
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#selectHandler
* @methodOf umbraco.services.listViewHelper
*
* @description
* Helper method for working with item selection via a checkbox, internally it uses selectItem and deselectItem.
* Working with this method, requires its triggered via a checkbox which can then pass in its triggered $event
* When the checkbox is clicked, this method will toggle selection of the associated item so it matches the state of the checkbox
*
* @param {Object} selectedItem Item being selected or deselected by the checkbox
* @param {Number} selectedIndex Index of item being selected/deselected, usually passed as $index
* @param {Array} items All items in the current listview, available as $scope.items
* @param {Array} selection All selected items in the current listview, available as $scope.selection
* @param {Event} $event Event triggered by the checkbox being checked to select / deselect an item
*/
function selectHandler(selectedItem, selectedIndex, items, selection, $event) {
var start = 0;
@@ -143,6 +253,18 @@
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#selectItem
* @methodOf umbraco.services.listViewHelper
*
* @description
* Selects a given item to the listview selection array, requires you pass in the inherited $scope.selection collection
*
* @param {Object} item Item to select
* @param {Array} selection Listview selection, available as $scope.selection
*/
function selectItem(item, selection) {
var isSelected = false;
for (var i = 0; selection.length > i; i++) {
@@ -157,6 +279,18 @@
}
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#deselectItem
* @methodOf umbraco.services.listViewHelper
*
* @description
* Deselects a given item from the listviews selection array, requires you pass in the inherited $scope.selection collection
*
* @param {Object} item Item to deselect
* @param {Array} selection Listview selection, available as $scope.selection
*/
function deselectItem(item, selection) {
for (var i = 0; selection.length > i; i++) {
var selectedItem = selection[i];
@@ -167,6 +301,20 @@
}
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#clearSelection
* @methodOf umbraco.services.listViewHelper
*
* @description
* Removes a given number of items and folders from the listviews selection array
* Folders can only be passed in if the listview is used in the media section which has a concept of folders.
*
* @param {Array} items Items to remove, can be null
* @param {Array} folders Folders to remove, can be null
* @param {Array} selection Listview selection, available as $scope.selection
*/
function clearSelection(items, folders, selection) {
var i = 0;
@@ -180,7 +328,7 @@
}
}
if (angular.isArray(items)) {
if(angular.isArray(folders)) {
for (i = 0; folders.length > i; i++) {
var folder = folders[i];
folder.selected = false;
@@ -188,6 +336,20 @@
}
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#selectAllItems
* @methodOf umbraco.services.listViewHelper
*
* @description
* Helper method for toggling the select state on all items in the active listview
* Can only be used from a checkbox as a checkbox $event is required to pass in.
*
* @param {Array} items Items to toggle selection on, should be $scope.items
* @param {Array} selection Listview selection, available as $scope.selection
* @param {$event} $event Event passed from the checkbox being toggled
*/
function selectAllItems(items, selection, $event) {
var checkbox = $event.target;
@@ -219,6 +381,20 @@
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#isSelectedAll
* @methodOf umbraco.services.listViewHelper
*
* @description
* Method to determine if all items on the current page in the list has been selected
* Given the current items in the view, and the current selection, it will return true/false
*
* @param {Array} items Items to test if all are selected, should be $scope.items
* @param {Array} selection Listview selection, available as $scope.selection
* @returns {Boolean} boolean indicate if all items in the listview have been selected
*/
function isSelectedAll(items, selection) {
var numberOfSelectedItem = 0;
@@ -242,10 +418,35 @@
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#setSortingDirection
* @methodOf umbraco.services.listViewHelper
*
* @description
* *Internal* method for changing sort order icon
* @param {String} col Column alias to order after
* @param {String} direction Order direction `asc` or `desc`
* @param {Object} options object passed from the parent listview available as $scope.options
*/
function setSortingDirection(col, direction, options) {
return options.orderBy.toUpperCase() === col.toUpperCase() && options.orderDirection === direction;
}
/**
* @ngdoc method
* @name umbraco.services.listViewHelper#setSorting
* @methodOf umbraco.services.listViewHelper
*
* @description
* Method for setting the field on which the listview will order its items after.
*
* @param {String} field Field alias to order after
* @param {Boolean} allow Determines if the user is allowed to set this field, normally true
* @param {Object} options Options object passed from the parent listview available as $scope.options
*/
function setSorting(field, allow, options) {
if (allow) {
options.orderBy = field;
@@ -257,12 +458,12 @@
}
}
}
//This takes in a dictionary of Ids with Permissions and determines
// the intersect of all permissions to return an object representing the
// listview button permissions
function getButtonPermissions(unmergedPermissions, currentIdsWithPermissions) {
if (currentIdsWithPermissions == null) {
currentIdsWithPermissions = {};
}
@@ -286,26 +487,28 @@
canCopy: _.contains(intersectPermissions, 'O'), //Magic Char = O
canCreate: _.contains(intersectPermissions, 'C'), //Magic Char = C
canDelete: _.contains(intersectPermissions, 'D'), //Magic Char = D
canMove: _.contains(intersectPermissions, 'M'), //Magic Char = M
canMove: _.contains(intersectPermissions, 'M'), //Magic Char = M
canPublish: _.contains(intersectPermissions, 'U'), //Magic Char = U
canUnpublish: _.contains(intersectPermissions, 'U'), //Magic Char = Z (however UI says it can't be set, so if we can publish 'U' we can unpublish)
canUnpublish: _.contains(intersectPermissions, 'U'), //Magic Char = Z (however UI says it can't be set, so if we can publish 'U' we can unpublish)
};
}
var service = {
getLayout: getLayout,
getFirstAllowedLayout: getFirstAllowedLayout,
setLayout: setLayout,
saveLayoutInLocalStorage: saveLayoutInLocalStorage,
selectHandler: selectHandler,
selectItem: selectItem,
deselectItem: deselectItem,
clearSelection: clearSelection,
selectAllItems: selectAllItems,
isSelectedAll: isSelectedAll,
setSortingDirection: setSortingDirection,
setSorting: setSorting,
getButtonPermissions: getButtonPermissions
getLayout: getLayout,
getFirstAllowedLayout: getFirstAllowedLayout,
setLayout: setLayout,
saveLayoutInLocalStorage: saveLayoutInLocalStorage,
selectHandler: selectHandler,
selectItem: selectItem,
deselectItem: deselectItem,
clearSelection: clearSelection,
selectAllItems: selectAllItems,
isSelectedAll: isSelectedAll,
setSortingDirection: setSortingDirection,
setSorting: setSorting,
getButtonPermissions: getButtonPermissions
};
return service;