Tuesday, December 31, 2013

How to include User Custom Actions and Scriptlink using SharePoint JSOM

This is a very fast article about creating and manage User Custom Action with SharePoint JavaScript Object Model (JSOM).

This article describes how you can include Custom Actions, global JS files "ScriptLink" using ECMAScript code in a very easy way without Visual Studio.

A lot of SharePoint Administrator don't allow to add SharePoint WSP (Farm, Sandbox) solutions or SharePoint Designer "Allow you to add  User Custom Action in Lists" for maintenance and upgrade issues, this JSOM method will avoid the installation of SharePoint solutions and will support your Custom solutions.

PS: This requires a good management of the existing "User Custom Action" of the Site using the objects SP.Web and SP.List.
Please document everything on detail to dont get suprises.

For more information about a Tool to Manage this Custom Actions please access the following link:
SharePoint App Processlynx Custom Action and Ribbon Manager Launch
There is also a free version in the office store:
Free Custom Action and Ribbon Manager

I also would like to share the following articles regarding this topic.
Manage User Custom Actions SharePoint 2013 App and Sandbox - JSOM
http://aaclage.blogspot.ch/2014/01/manage-user-custom-actions-sharepoint.html
PnP Manage User Custom Actions
https://github.com/OfficeDev/PnP/tree/master/Samples/Core.ManageUserCustomAction 
and

Examples of Ribbons Customization in SharePoint 2013

http://aaclage.blogspot.ch/2014/04/examples-of-customization-of-ribbons-in.html

This option avoid install WSP solutions "Farm, Sandbox" using declarative in the elements.xml file.



The SP.UserCustomAction object provide methods to include Custom Actions to support our Client Side solution.
Example of our final output.



This give us also the ability to include Custom Javascript actions that will be executed in all Site Pages, including hive folder Pages.
Example:
Site Settings
Url: "https://[Site]/_layouts/15/settings.aspx".


Add the Support Files

The first thing you should do is include JS files "alert.JS and Jquery*.JS" in Assets Library. This files will support our solution.



Go to a SharePoint Page and include a new Script Editor Web Part

Add a embedded Script Editor Web Part and include the code to add a button that create our User Custom Action.

The Page with the Script will add a new button, this option will create the reference in the header to the new SharePoint Files.

Example ECMAScript code to create CustomAction reference to Jquery.js and alert.js files:









function AddCustomActions() { var clientContext = new SP.ClientContext(); var site = clientContext.get_web(); var UserCustomActions = site.get_userCustomActions(); var newUserCustomAction = UserCustomActions.add(); newUserCustomAction.set_location('ScriptLink'); newUserCustomAction.set_scriptSrc('~SiteCollection/SiteAssets/jquery-1.9.1.js'); newUserCustomAction.set_sequence(9); newUserCustomAction.set_title('Jquery'); newUserCustomAction.set_description('Global Jquery'); newUserCustomAction.update(); newUserCustomAction = UserCustomActions.add(); newUserCustomAction.set_location('ScriptLink'); newUserCustomAction.set_scriptSrc('~SiteCollection/SiteAssets/Alert.js'); newUserCustomAction.set_sequence(10); newUserCustomAction.set_title('New Alert'); newUserCustomAction.set_description('Global Alert'); newUserCustomAction.update(); clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed)); } function onQuerySucceeded(sender, args) { alert('New Support files added to Site.\n\nRefresh the page.'); } function onQueryFailed(sender, args) { alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace()); } AddCustomActions()
After you include the code, execute the button "Add CustomAction" and a confirmation alert will appear and refresh the page.


If you access to your Internet Explorer > Source Code the 2 files will be included and the alert should appear.
PS: Be careful with the order of the JS files.


Get UserCustomActions Properties from Web Object

You can use the same Script Editor Web Part to include a new option to retrive the User CustomActions from the Site.


Example ECMAScript code to return CustomAction reference to SP.Web Object:







function Getproperties() { var clientContext = new SP.ClientContext(); var site = clientContext.get_web(); UserCustomActions = site.get_userCustomActions(); clientContext.load(UserCustomActions); clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed)); } function onQuerySucceeded(sender, args) { var listInfo = ''; var listEnumerator = UserCustomActions.getEnumerator(); while (listEnumerator.moveNext()) { var oList = listEnumerator.get_current(); listInfo += 'Location: ' + oList.get_location() + '\n' + 'Description:' + oList.get_description() + '\n'+ 'scriptSrc:' + oList.get_scriptSrc() + '\n'; } alert(listInfo); } function onQueryFailed(sender, args) { alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace()); } Getproperties()
Example of the output:
If you access to Fiddler you can get the details of the JSON output:



Include new Custom Actions

The same way the other 2 User Custom Actions were created, you can include in the SharePoint Out of the Box Menu new options.

After this code is executed a new option is created "New Site" this option will redirect to new Site Creation Page.


Here is the code example:






function runCode() { var clientContext = new SP.ClientContext(); var site = clientContext.get_web(); var UserCustomActions = site.get_userCustomActions(); var newUserCustomAction = UserCustomActions.add(); newUserCustomAction.set_location('Microsoft.SharePoint.StandardMenu'); newUserCustomAction.set_group('SiteActions'); newUserCustomAction.set_sequence(2000); newUserCustomAction.set_title('New Site'); newUserCustomAction.set_imageUrl('/_layouts/images/myIcon.jpg'); newUserCustomAction.set_description('Menu item added via ECMAScript'); newUserCustomAction.set_url('/_layouts/15/newsbweb.aspx'); newUserCustomAction.update(); clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed)); } function onQuerySucceeded(sender, args) { alert('New menu item added to Site Actions menu.\n\nTo view the new menu item, refresh the page.'); } function onQueryFailed(sender, args) { alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace()); }
If you need to monitor the UserCustomActions you can use REST Call to display the Web Objects, for this example the UserCustomActions options.

Access to UserCustomActions using REST Call 
https:/(Site)/_api/web/UserCustomActions

This rest call retrieves the Feed XML associated with UserCustomActions associated with Web Object.



Here is a solution "SharePoint 2013: Manage User Custom Actions App and Sandbox" about this topic.
for more information about this Tool and new version please access the following link:
SharePoint App Processlynx Custom Action and Ribbon Manager Launch

Support Links:
SP.UserCustomAction object (sp.js)
SP.UserCustomActionCollection.add() Method


Hope you like and happy New Year, :)
Kind regards,
Andre Lage