SummaryLinkStore.js

If you want to create summary link data using JavaScript and found out that the required format is a bit complex, then I might be able to help you here.
On Codeplex I’ve shared a JavaScript module called SummaryLinkStore.js. It enables developers to create or edit SummaryLink data in SharePoint using JavaScript.

Introduction

You can find SummaryLink data at a few places in SharePoint. It is a field type, typically used on the welcome page of a publishing site, and it’s a property on the Summary Link web part. The datatype allows you to configure a collection of links practically in any way you need. You can group them, sort them, style them (using XSL), and configure other properties.

Unfortunately, you may have found out that the same field does not work really well with other platforms. Server side you can use the SummaryLinkFieldValue object to manage this data. However, when the SummaryLink value is read, you get the deserialized value of the SummaryLinkFieldValue instance. This XML value quickly becomes too large to export to Excel and to manipulate it, without the actual serialized SummaryLinkFieldValue available, requires a lot of coding and investigation into what the XML the format actually means.

Here my library comes in. It is capable of serializing the SummaryLink value into an object structure that you can use my functions on to manipulate the data. Similarly you can deserialize the value back so you can store your new or modified value into the field.

For example, if you read a SummaryLink field in SharePoint that only has one link, it would return the following string in JavaScript (this is about as simple as a SummaryLinks value can be):

With SummaryLinkStore.js, you do not need to worry so much about the behavior of group headers, columns, XSL styles and other settings, because the module will read and write the xml value for you:

The above code will search for a link with the title “codeplex” and assigns the first match to the codeplexLink variable. From this link the url is retrieved by using the linkUrl accessor. codeplexUrl will get the value ‘https://summarylinkstore.codeplex.com/documentation’, which is indeed the url of the link with the title ‘codeplex’ in stringValue.

We could go further by changing the title of the link we found into ‘SummaryLinkStore.js documentation’ and then getting the string value to store in the SummaryLinks field:

If you would store stringValue back in the field it came from, you would see that the title of the link has been updated.

Using web part property value

If you wish to use the data from an existing web part on the page. You can use JavaScript to read the web part properties, as you would for any other web part. What you need for oPB.SummaryLinkStore is the property named “SummaryLinkStore”:

The example above shows how you can deserialize the string data from the web part into JavaScript objects. This basically means that the summaryLinkStore variable will have references to objects and functions that help you understand and manipulate this data.

When you call summaryLinkStore.serialize();, you’ll notice the exact same string should be returned. Or if the original input could not be interpreted as such, the serialized string would represent what the module understood from it. And this should be similar, within reason, to the behavior of the Summary Link web part.

Often if you wish to write this data to a web part, you would compose the webpart xml file to import using the LimitedWebPartManager. If this is the case, you might want to escape the summaryLinkStore value for XML insertion. This will be done for you, if you cast the oPB.SummaryLinkStore instance back to a string:

 

Demonstration

To explain how the oPB.SummaryLinkStore module can be useful, I’ve made a simple demonstration for this blog. Obviously it does not showcase the full potential, but I hope it will help you understand and inspire you to use it creatively.

Import your data into this demo

If you have no SummaryLinkStore value ready to paste, you can generate your own data using the form further down below. Otherwise, you can paste a SummaryLinkStore string value into the text area below. Then make sure the onchange event is fired by blurring the field (clicking outside of the field):

A text area should appear here

The onchange event will trigger the deserialize function that was explained earlier. This demonstration uses one instance of oPB.SummaryLinkStore, so the same data will be used in the rest of the demo.

The user interface is written for this demonstration, oPB.SummaryLinkStore empowers you to write your own user interface, but does not come with any user interface by itself.

Building a User Interface

The instance of oPB.SummaryLinkStore has a function called “build”. You can provide this build function with a builder function. In the builder function you can compose a string to represent the data in the SummaryLinkStore. The build function will iterate over this data and call the builder function whenever that might be relevant.

So if you wish to build a HTML representation of the SummaryLinkStore data, you need to write a builder function that can compose this HTML. The builder function should take an object as an argument. This object will have two properties: “current” and “phase”.

The oPB.SummaryLinkStore build function will then iterate over the data and call the builder function for each data “node” once or twice. Based on the provided values for “current” and “phase”, the builder function should be able to append the appropriate html to the result.

I can imagine that I’ve lost you here, so let me clarify this with an example:

As you can see, “current” is the instance representing a “node” in the data hierarchy, while phase is a string explaining what part of the object should be added to the string representation. phase can be one of three values: “open”, “close” or “leaf”.

The example above, should result in the following HTML (corresponding to the SummaryLinkStore data you pasted in the text area above, or created using the form further down below):

The HTML representation of the data should be inserted here

To go further with this example, we can build HTML that outputs controls to interact with the same data from which the HTML is generated. I’ve not included the sourcecode for the example below, but the idea is similar to the code for the previous example:

A more elabovate HTML representation of the data should be inserted here

To use generated HTML, is of course just one of the options to interact with the data. A more sober, but effective approach would be to just add a static form:

A form to add more data should be inserted here

After using the example above to manipulate the data, the result can be found here:

A text area should appear here

 

To get the data, escaped for XML insertion, all you need to do is cast the SummaryLinkStore object to a string. If you do not want to escape the XML for insertion into for instance a web part definition, then you can call the serialize function.

Catching Errors

I throw errors (exceptions) intentionally, for example: when I need to protect my code from doing something unexpected otherwise. So you need to catch my errors, to ensure stability, especially if user input is involved.

When you are troubleshooting the library, typically you’d want to have a little bit more information about what is happening. The following line of script can help with that (to some extend):

 Finally

The example in this blog is just to get you started. There are functions available to you to do all kinds of things. So for the full documentation, have a look at https://summarylinkstore.codeplex.com/documentation.

I’d like to hear what you think! (related to this blog and JavaScript module I mean)


Leave a Reply

Your email address will not be published. Required fields are marked *