Documentation Index

The available code has been documented as is on the following pages:

oPB.SummaryLinkStore
Describes the constructor to create a SummaryLinkStore and how an instance of SummaryLinkStore can be used.

oPB.SummaryLinkStore.SummaryLink
Describes the constructor to create a SummaryLink, and how an instance of a SummaryLink can be used. A SummaryLink should however be added to a SummaryLinkStore.

SummaryLinkCollection
Both the instance of SummaryLinkStore and the instance of SummaryLink (which could be a group header), have a property summaryLinks, which is a SummaryLinkCollection.

Build
Instances of SummaryLinkStore, SummaryLink and SummaryLinkCollection have a build function. This function can be used to help you parse the data into something specific (like a HTML representation of the data). How this works, is described here.

experimental code
Code described on this page should not be used in production. I'm experimenting with an API to allow more intuitive code (like typechecked properties that do not behave as functions). However this API is experimental, so I might change or remove this in any future version of the library.

Coding principles

Excluding the experimental code, I've tried to be consistent about a few things:
  • If a function starts with an uppercase character, it should be called as a constructor
  • Functions usually do not expect more than one argument. If multiple values need to be provided to a function, then an object is constructed to be able to provide named arguments.
  • Object properties have one accessor function. If no argument is provided, the value is returned. If an argument is provided, an error may be thrown if the value is not valid, otherwise the property will be set to the provided value.
  • Functions can act as a namespace to group other functions and properties, which are only relevant in association to that function.

Example

The code below does not represent all the SummaryLinkStore library can do, but it combines a few things in one code example which might help you to get started. The rest of the documentation is mainly written to describe individual functions and properties.

// This code snippet just provides a simplified example to help you get started

//For debugging purposes we want to show an alert for any unexpected situation that might occur (console.log would be less intrusive)
// Keep in mind that my code (often intentionally) might throw errors for unexpected situations as well. So you need to use try/catch blocks as well.
oPB.SummaryLinkStore.addErrorListener(function errorListener(message) {
	alert(message);
});

//This way we create an object that can represent a summary link value without setting the value just yet:
var myLinks = new oPB.SummaryLinkStore();

//This example shows how to register a function to manipulate the url value for serialization and deserialization.
// In this case we map the token ~sitecollection to the url https://summarylinkstore.codeplex.com
myLinks.addDeserializeUrlListener(function customUrlBehavior(options){
    if(options.params.processingInfo.serialize)
    {
        options.params.value = options.params.value.replace(/https:\/\/summarylinkstore\.codeplex\.com/img, "~sitecollection");
    }
    else
    {
        options.params.value = options.params.value.replace(/~sitecollection/img, "https://summarylinkstore.codeplex.com");
    }
});

//Next we deserialize our summary link value, note that we set replace to true, so any pre-existing items in myLinks will be cleared.
myLinks.deserialize({replace:true,value:'<div title="_schemaversion" id="_3"><div title="_links"><div title="_link"><span title="_title">summarylinkstore.codeplex.com</span><span title="_order">1</span><span title="_begincolumn">True</span><span title="_linkurl"><a href="https://summarylinkstore.codeplex.com/documentation">~sitecollection/documentation</a></span></div></div><div title="_view"><span title="_columns">1</span><span title="_linkstyle"></span><span title="_groupstyle"></span></div></div>'});

//Lets create a new link to be included in our summary link value:
var blogLink = new oPB.SummaryLinkStore.SummaryLink({title: "blog", linkUrl: "//thesharepoint.NL"});

//Lets add it to the summary link value:
myLinks.summaryLinks.add({item:blogLink});

//Does myLinks contain the blogLink instance? Lets find out: 
var result = myLinks.summaryLinks.find({id:blogLink.id()});
if(result.found)
{
	//result.item should be blog link, lets set a description:
    result.item.description("I hope my codeplex project, or my blog, is helpfull to you.");
}

//Serialize the Summary Link value back to the string that SharePoint understands:
var summaryLinkValue = myLinks.serialize(); //The XML value
var escapedSummaryLinkValue = myLinks + ""; //The XML value escaped to be inserted in other XML (like a web part definition).

//As a simplified example, we can use the build function to make an array of all the URLs
//First we create a context object that defines this behavior:
var buildContext = {
	urls:[],
	builder:function builder(params)
	{
		var context = this; //is the same as buildContext
		var instance = params.current;
		var phase = params.phase;
		//We only need to process SummaryLink instances, and only if they do not have any children:
		if((instance instanceof oPB.SummaryLinkStore.SummaryLink) && phase === "leaf")
		{
			//Lets add the url of this SummaryLink to our collection
			context.urls.push(instance.linkUrl());
		}
	}
};

//Lets execute the behavior we defined (iteratively);
myLinks.build(buildContext);

//Now we have our url collection:
alert(buildContext.urls.join('\n'));

Last edited Sep 16, 2015 at 3:15 PM by pbvansplunter, version 23