SummaryLinkStore object

Namespace: oPB
Constructor: oPB.SummaryLinkStore(string)
since release 0.11
As of release 0.11 it is possible to directly provide the string value to deserialize to the constructor:
var instance = new oPB.SummaryLinkStore('<div title="_schemaversion" id="_3"><div title="_links"><div title="_link"><span title="_title">Codeplex project</span><span title="_order">1</span><span title="_begincolumn">True</span><span title="_linkurl"><a href="https:&#x2F;&#x2F;summarylinkstore.codeplex.com">https:&#x2F;&#x2F;summarylinkstore.codeplex.com</a></span></div></div><div title="_view"><span title="_columns">1</span><span title="_linkstyle"></span><span title="_groupstyle"></span></div></div>');

Alternatively you could use the original constructor:

Constructor: oPB.SummaryLinkStore(options)

Options is an optional argument to the constructor. It can be used to provide the constructor with initial values for properties on the instance that will be created. The following example shows all the properties which can be set this way, but each property is optional:
var instance = new oPB.SummaryLinkStore({
    schemaVersion: 3,
    columns: 1,
    linkStyle: "Default",
    groupStyle: "Default"
});

Properties

The SummaryLinkStore instance will have properties which can be accessed through accessor functions. If no argument is provided to the accessor, the property value is returned. If an argument is provided, that argument may be validated. If the argument is not a valid value for the property, the accessor may throw an error. If a valid value was provided, the property is set to that value.

schemaVersion
Validation: must be a number
Category: XML
Description:
Only schema version 3 is tested. (During deserialize, the code will try to understand the schema version, so this may change the property value. Before serialization, be advised to change this back to 3 if a different schema version was deserialized.)

columns
Validation: must be a number
Category: View
Description:
Only values 1 to 5 are tested.
IF the SummaryLinkStore has more than one group, the groups will be distributed over the amount of columns set here.
When changing this value "ViewListener" functions will be triggered if they where registered.

linkStyle
Validation: must be a string
Category: View
Description:
If a link style is not specified for an individual link in the SummaryLinkStore, this linkStyle value will be used in stead. Basically the link style refers to the item style template from the linked xsl file.
When changing this value "ViewListener" functions will be triggered if they where registered.

groupStyle
Validation: must be a string
Category: View
Description:
All the groups in the SummaryLinkStore will be presented in the header style referred by this property (given that the template for it is available in de header xsl file).
When changing this value "ViewListener" functions will be triggered if they where registered.

summaryLinks
Validation: collection is managed by the SummaryLinkCollection object.
Category: collection
Description: SummaryLinkCollection for details.

methods

With methods, I mean the functions on an instance which are not accessors to a property.

(undefined) addViewListener(options)
options is a required argument, it has one property: "listener", which is the function to be added as ViewListener. For example:
summaryLinkStoreInstance.addViewListener({
    listener: function viewChanged(options) {
        if(options.isInternalCall && options.params.propertyName === "columns"){
            //not a manually triggered event and columns property was changed
        }
    }
});
The listener is called when ever the columns, linkStyle or groupStyle properties change.

Since release 0.11: the listener can be passed on directly:
summaryLinkStoreInstance.addViewListener(function viewListener(options) {
        if(options.isInternalCall && options.params.propertyName === "columns"){
            //not a manually triggered event and columns property was changed
        }
    });

(undefined) forgetViewListeners(listener)
Since release: 0.11
A listener previously added with addViewListener, can be removed using forgetViewListener.

(undefined) fireViewListeners(params)
params is an optional argument, if provided by reference (object or function), the instance may be manipulated.
This function calls the listeners that where registered using addViewListener. The value of options.params in the listener will be the params value, but manipulated by the function. options.isInternalCall will be false when this function is called from outside the module.

(undefined) addDeserializeUrlListener(listener)
Since release: 0.11
The provided listener function will be fired during deserialization and serialization of the SummaryLinkStore object.
summaryLinkStoreInstance.addDeserializeUrlListener({
    listener: function customUrlValue(options) {
        if(options.params.direction === "deserialize")  {
            options.params.value = typeof options.params.value === "string" ? options.params.value.replace("~site", "/sites/example") : options.params.value;
        }
    }
});

This listener is called for every linkUrl and imageUrl property of every summary link in the summary link store, if the entire summary link store is serialized or deserialized. It helps to keep performance in mind when writing a listener for this "event".

The options argument in the listener will have the following structure:
options: {
    isInternalCall: true, //boolean value: will be true if the associated summary link is eigher being added by deserialization or (if serializing) has originally been added using deserialization. Editing a summary link with code will not affect this value.
    params: {
        schemaVersion: 3,
        propertyName: "imageUrl", //or linkUrl if that was the property for which the event fired
        direction: "serialize", //or deserialize, if that was the process triggering the event
        value: "https://example", //the value of the property (you might want to change this value)
        processingInfo: {
            initialValue: "~site/example", //only provided during serialization: the originally deserialized value.
            serialize: true //set during serialization, not set during deserialization (might be more effective to check for in stead of direction)
        }
    }
}

(undefined) forgetDeserializeUrlListener(listener)
Since release: 0.11
A listener previously added with addDeserializeUrlListener, can be removed using forgetDeserializeUrlListener.

(undefined) build (options)
Options is a required argument. It must have a property called "builder" with a function assigned to it.

The build function will call the provided builder function from each instance, usually multiple times. The goal is to allow the builder function to easily build a string that represents the structure of the data. This function can, for example, be useful to build HTML that represents the data.

(undefined) deserialize (options)
options is a requried argument. It can have two properties: value and replace. Replace is optional, but value is required.
summaryLinkStoreInstance.deserialize({
    replace: true, //optional, but advised
    value: "...summary link store property value read from web part..."
});

When you use JavaScript to read the SummaryLinkStore property from a Summary Link web part, the value will be returned as a string. Because the format of that string is not really useful for link manipulation, I wrote this whole module. So for value, you should provide the read property value from the web part. If the SummaryLinkStore instance already knows links and/or groups, you might want to replace them. In that case set replace to true. Otherwise the data from the provided value will be merged with existing links and groups. Because there are restrictions in place (for instance if groups are used or not), results may vary from the original data.

(string) serialize()
This will do the oposite of deserialize: it returns a string containing the xml that represents the data in the summary link store instance.

(string) toString()
This will deserialize the summary links tore and escape it for XML insertion. This can be handy, for instance when you are composing the content of a .webpart file.

Note that the toString function is automatically called for you when you try to cast the oPB.SummaryLinkStore instance to a string value. So the following example would result in valid XML:
webPartDefinition += '<property name="SummaryLinkStore" type="string">' + summaryLinkStoreInstance + '</property>';

Last edited Aug 30, 2015 at 2:41 PM by pbvansplunter, version 21