SummaryLinkCollection

Both the SummaryLinkStore and SummaryLink (if it is a group header) can contain a collection of SummaryLinks. To match the restrictions and behavior of the SharePoint summary link web part, these collections are internally managed by the SummaryLinkCollection.

Both instances of SummaryLinkStore and of SummaryLink have the property ".summaryLinks", which provides ways to access and manipulate the content of the collection (as described later on this page).

Through the build function you may be provided with an instance that would provide the following properties of the SummaryLinkCollection instance:
  • owner() - returns the object for which the .summaryLinks property is generated using this instance
  • canParent() - returns a boolean indicating if the collection can contain SummaryLinks.

oPB.SummaryLinkStore.isSummaryLinkCollection(instance); would return true, if the provided instance matches the instance described above.

.summaryLinks property

Both instances of oPB.SummaryLinkStore and oPB.SummaryLinkStore.SummaryLink have a property called "summaryLinks". It provides restricted access to a collection of instances of oPB.SummaryLinkStore.SummaryLink, managed by the SummaryLinkCollection.

If the summaryLink property is called as a getter, an array is returned with all the instances of oPB.SummaryLinkStore.SummaryLink that are contained by the owner of the summaryLink property. Note that you can not modify this data by modifying the returned array.

This function will not act as a setter. In fact you can provide arguments to filter the returned array by id or by title. Example:
var result = myInstance.summaryLinks({title: "SharePoint"});
"result" will only return SummaryLink instances that have the title "SharePoint".

The .summaryLinks property also acts as a namespace and this namespace allows you to manipulate the colledtion:
(undefined) add(options)
options is a required argument and needs a property named "item" which needs to be an instance of oPB.SummaryLinkStore.SummaryLink.
A SummaryLinkCollection can either contain a collection of links or a collection of group headers, but not a mix of the two. When adding a new item, the SummaryLinkCollection object makes sure the two do not get mixed:
If the item is a group header:
The SummaryLinkCollection updates it's knowledge about the group headers it contains. Also the group header is added to this collection. If there are items in this collection that are not group headers, then they are moved to this group header.

If the item is not a group header:
The provided summaryLink is removed from it's original container (if any), then it's added to the first group header in this SummaryLinkCollection if there is any. If there are no group headers in the collection, the SummaryLink is directly added to the collection.

(undefined) addEach(options)
options is a required argument, it needs a property named "items", which must be a JavaScript array.
Each instance in this array that is an instance of oPB.SummaryLinkStore.SummaryLink will be added using summaryLinks.add({item: instance}). If not all instances in the items array are of oPB.SummaryLinkStore.SummaryLink, then eventually an error is thrown. Valid instances are still added to the collections.

(undefined) build (options)
Even though the SummaryLinkCollection object is only a container, the instance will build. See build page for documentation.

(undefined) clear()
Makes SummaryLinkCollection forget about all it's content. Also all group headers in the collection will forget about all their content.

(number) count(options)
options argument is not required. It can have a boolean property named "recursive", if this is set to true, the instances in the group headers in this collection are counted too. Options can have a boolean property named "linksOnly", when set to true, items which are group headers are not counted.

It returns the number of items counted in the collection (and optionally recursive).

(result object) find(options)
options is a required argument, it needs a property named "id". This function will search for an item in the collection that has the provided id, if the collection contains group headers, then the content of those group headers is searched too.

This function returns a result object, with the boolean property named "found". This property tells if an item with the provided id was found. If this is the case, the result object will also have the named properties "item" and "owner". Item will have an instance of oPB.SummaryLinkStore.SummaryLink with the provided id. owner will refer to the instance of either oPB.SummaryLinkStore or oPB.SummaryLinkStore.SummaryLink (which is a group header), this instance will be the direct parent of the item.

Example:
var result = sls.summaryLinks.find({id: "00000000-0000-0000-0000-000000000000"});
if(result.found)
{
    alert("found " + result.item.title());
}

(number) groupHeaderCount()
Returns the number of group headers in the collection. This value is cached, so it is quick.

(Array) groups()
This function creates an array of groups which are directly in this collection, it returns this array.

Example:
if(sls.summaryLinks.groupHeaderCount() > 0)
{
    var groups = sls.summaryLinks.groups();
    //groups is now an array of group headers (instance of oPB.SummaryLinkStore.SummaryLink)
}

(string) newGroupName()
Returns a generated name for a group that should be unique. (for instance: "Group 4 00000000-0000-0000-0000-000000000000")

(result object)order(options)
Options is a required argument, it needs either a property named "item" that is an instance of oPB.SummaryLinkStore.SummaryLink, or it needs a property named "id". The properties named "order" and "newOrder" are both optional, but need to be numbers.

Each SummaryLink in the SummaryLinkStore should have a unique order value (the index value if you will). However, the SummaryLinkStore may contain several SummaryLinkCollections. For each group header has it's own collection.

The provided options.order value, is the order count up until the current SummaryLinkCollection (so this number will be added to the counter).

This order function helps to discover the order value for the provided item (or the item with the provided id), and if a newOrder value is provided, the item can be moved as well (provided it stays in the same container).

The function will return a result object that may have the following named properties:
  • (boolean) found: was the item found
  • (number) order: the order value for the item
  • (boolean) moved: was the item moved by the order function
  • (object) owner: the SummaryLinkStore or SummaryLink that contains the item
  • (number) ownerIndex: the index within the collection itself

(number) move(options)
The options argument is required and needs the string property named "direction", which should either be "down" or "up". It also needs either the property named "id", or the property named "item" which then should be an instance of oPB.SummaryLinkStore.SummaryLink. Optionally a property named "unbound" can be set to true, when this is a case, a SummaryLink can move one position by switching to the sibling group header parent (in the same way this happens when moving a link in the SharePoint UI).

This function will move the provided item (or the item with the provided id) either 1 position up or down (depending on the value of "direction"). However items will only move to a different group that way, if unbound was set to true. So if an item is the first in it's group header, it will not move up to be the last item in the previous group header in the SummaryLinkStore, unless unbound is set to true.

The function returns the index of the item within the collection after it has been moved. If the item could not be moved, the value -1 is returned. If the item was not found at all, the value -2 is returned. If the item was moved to a different group, the value -3 is returned.

(number) moveDown(options)
options is a required argument and needs either the property named "id" or the property named "item" which then should be an instance of oPB.SummaryLinkStore.SummaryLink. Optionally the property named "unbound" can be set to true, to allow the item to move to a different group header.

This function will attempt to move the provided item (or the item with the provided id) one position down. It will look in group headers as well, but the item will not move between collections (so it will not change group).

The function returns the index of the item within the collection after it has been moved. If the item could not be moved, the value -1 is returned. If the item was not found at all, the value -2 is returned. If the item was moved to a different group, the value -3 is returned.

(number) moveUp(options)
options is a required argument and needs either the property named "id" or the property named "item" which then should be an instance of oPB.SummaryLinkStore.SummaryLink. Optionally the property named "unbound" can be set to true, to allow the item to move to a different group header.

This function will attempt to move the provided item (or the item with the provided id) one position up. It will look in group headers as well, but the item will not move between collections (so it will not change group).

The function returns the index of the item within the collection after it has been moved. If the item could not be moved, the value -1 is returned. If the item was not found at all, the value -2 is returned. If the item was moved to a different group, the value -3 is returned.

(Array) remove(options)
options is a required argument and needs either the property named "id" or the property named "item" which then should be an instance of oPB.SummaryLinkStore.SummaryLink.

This function will remove the provided item (or the item with the provided id) from the current SummaryLinkCollection. If the item does not exist within the collection, it does check group headers and removes the item from the first group header that contains this item.

The returned object might not be an array in the future, but you can use the .length property to find out how many items have been removed.

(result object) serialize(options)
options is an optional argument, intended for internal use. This function is targeted for internal use as well, but it is available to you.

The result object will have a property called "strings", which will be an array. If you call result.strings.join(''); then you'll have an XML representation of the collection of SummaryLinks.

(undefined) sort(options)
options is an optional argument. It can have the boolean property named "descending".
since release 0.11: it can have the string property named "property", which by default is "title"

This function will sort the items in the collection by title (or by the specified string property) in ascending order (a, b c), unless the option descending was provided as true, then the items will be sorted in descending order (c, b, a).

(undefined) sort(function)
If sort is called with a function as argument, then that function will be used as the sort function. Sorting will behave similar to Array.prototype.sort, where both arguments will be instances of oPB.SummaryLinkStore.SummaryLink.

(undefined) ungroup(options)
options is a required argument and needs either the property named "id" or the property named "item" which then should be an instance of oPB.SummaryLinkStore.SummaryLink. Either way the id or the item should refer to a SummaryLink from within the collection that is a group header.

The content of the group header will be remembered (it's destination depends on if there are other group headers in the collection or not). The group header itself will be deleted.

(undefined) updateEach(options)
options is a required argument. It needs the string property named "property" and a property named "value".
This function will set the property value for each item in the SummaryLinkCollection, and for each item in the group headers in this collection.
Example:
summaryLinkStore.summaryLinks.updateEach({property:'style', value: 'Default'});


Last edited Aug 28, 2015 at 9:49 PM by pbvansplunter, version 14