Dynamically registering JavaScript from within a sandbox web part

Question

I am mid-way through development of a corporate intranet that will be hosted in SharePoint Online. For this reason, we are restricted to using sandbox solutions. One of the last "gotchas" that I need to resolve however, is how to dynamically register JavaScript files from within my web parts.

After a lot of research, there seems to be three decent ways of achieving this which I've outlined below, each with their own list of pro's and con's. Can anyone assist in guiding me down the best path here? This approach will be used across a dozens of web parts within our system, so it's important we get this stuff right first time.

Note: There are certainly more ways to dynamically inject files into the page from within a sandboxed web part, but the methods below are the only ones that I'm aware of that reslove the issue whereby if there are multiple instances of the same web part on the page, then the JavaScipt or CSS depenedies will still only be loaded once.

1. CustomAction's ScriptLocation property

   Info: http://blog.voyta.net/2010/09/12/referencing-javascript-files-using-customaction-in-sharepoint-2010-sandboxed-solutions/

   Pro's:

   • Uses pure OOTB functionality :)
   • Approach can be used for both CSS and JavaScript files

   Con's:

   • UPDATE 5-Nov: Registers the script on every page in the site (not just the page where the web part has been added)

2. ECMA Script

   Info: http://blog.mastykarz.nl/dynamically-loading-javascript-sandbox/

   Pro's:

   • Uses pure OOTB functionality :)
   • Waldek (the author) is a noted "big player" on the SahrePoint scene -- I'd basically trust the guy no matter what he told me to do!

   Con's:

   • Can't be used for registering CSS (ideally, I'd like to use the same approach for all my dependencies -- regardless of their file type)
   • It seems the most difficult and complex of the three solutions to implement (this could give a lot of room for error when there are lots of developers working on a project)

3. AJAX Script Loader

   Info: http://lightningtools.com/sharepoint_2010/add-javascript-files-once-to-a-page-sharepoint-sandbox-solutions/

   Pro's:

   • Uses code written by Microsoft (therefore it can be treated as "tested and trusted")

   Con's:

   • Can't be used for CSS
   • It seems a bit leftfield, i.e. it is a single piece of an AJAX library in beta that actually targets .NET 4.0 and doesn't come packaged OOTB with SharePoint :(

4. UPDATE 5-Nov: Custom JavaScript Function

   Info: http://github.com/eirikb/sppreload -- kudos to @eirikb for adding this suggestion. It uses the CustomAction's ScriptLocation property to call a custom JavaScript function (passing in the URL of the .js or .css file you want to load). The function determines if the file has already been loaded, and only if not, then it dynamically creates the node in the page head element.

   Pro's:

   • Can be used for CSS and JavaScript

   Con's:

   • Doesn't leverage any OOTB functionality, so there's no assurance against bugs etc.

And to pre-empt the flood of answers that won't take into consideration the limitations of the sandbox, please be aware that the use of delegate controls is forbidden, as are the ScriptLink and CssRegistration controls and the Page.RegisterClientScriptBlock method. Also, the CustomAction.ScriptSrc property is hard-wired to retrieve scripts from the _layouts directory which we unfortunately don't have have access to.

Thanks in advance for your help!

Answer 1

CustomAction-ScriptSrc is the way to go, and it does not limit scripts to layouts - there are delimiters for site collection- and site-referenced files. I've used this lots of times in sandbox scenarios.

<CustomAction 
    ScriptSrc="~SiteCollection/Style Library/js/jquery-1.4.3.js"
    Location="ScriptLink"
    Sequence="10">

Note that this will load the script throughout the site whether the page has your web parts or not. This will be handy if you have multiple web parts on the page and want to avoid double-loading your files. The Sequence attribute allows you to specify an order - a bigger numbers means it will load later.

Answer 2

For those playing at home, since I originally posted this question I have implemented and evaluated all four possible solutions. Ultimately, I eneded up using option #2 (which uses the built in ECMA script model to dynamically load JavaScript files; more details are available at http://blog.mastykarz.nl/dynamically-loading-javascript-sandbox/)

The main deal-breaker for me with the other methods was the fact they they used the custom action's ScriptLink property to load JavaScript files. What I didn't realise originally, was that this mechanism will in fact register your web parts' scripts on every page in your site -- even those where the web part has not been added. In my case (where the SharePoint application in question is a corporate intranet with a huge number of web parts deployed to it and where the entire intranet comprises a single site collection) the page size of evry page in the site almost instantly bloated out of control.

As for using the built-in ECMA scripts to dynamically load your web parts' scripts, the only real drawback here is that there's a bit of development overhead involved in converting all your existing scripts to "on demand" scripts. All the details are provided in the link above, but in short, you need to add an "okay, I've finished loading" command to the bottom of each of your scripts, plus also register any inter-script dependencies that you may have. Doing so means that if a particular function is called, then the ECMA scripts methods will not only go off and load the necessary script (if it hasn;t been loaded already of course!), but it will also load the jQuery library and any other libraries that it might need or depend on. As you can see, once this has all been set up, it's a very neat and reusable pattern :)

And as previously stated in the original question, this method also can't be used for CSS files. This means that if your page contains multiple copies of a custom web part, then you'll still have multiple copies of the web part's CSS files being loaded by the browser. This however, is less of an issue than it sounds... Luckily, CSS is not only fast and lightweight, but it's built on the concept of inheritance, and so regardless of how many copies of the stylesheet have been loaded, it won't affect the appearance of the web part in any way (as the stylesheet rules will simply all override one another). So apart from the slightly increased page bloat, there really is no functional risk to this situation. JavaScript on the other hand is very different -- having multiple copies of the same script on the same page will cause the browser to wet its pants as soon as the first function is called.

I hope this helps someone out there...

Answer 3

Or, you could always put your <script> tags directly into the master page, along with your css links.