jsAppWebPart for SharePoint 2010 – one more way to craft js/CSOM based apps, part 1

SharePoint 2010 introduced CSOM as a new way to create client side application. It was a quite nice step forward which allows creating “light” client side applications and minimize farm downtime. With the latest SharePoint 2013 trends – html/js apps – it is worth to utilize CSOM even more intensively for your “old” SharePoint 2010 projects. However, some common routines to deploy and deliver your js-based/CSOM app to SharePoint are still required. Here are some ideas how it could be addressed

The purpose and the goal of the jsAppWebPart

So, making js based app with CSOM for SharePoint 2010 has some routines. Even if you get the right js/html/css files done, you still need to deploy it to SharePoint. To address that, there are several options – from adding CEWP on the page to developing custom web part. As far as we want to provide some settings for the end users, custom web part seems to be the most preferable way to implement and deliver your solution. In turn, it requires web part creating, some server side coding, some modules, receivers and the rest.

In my personal experience, I’ve done quite much js/html coding for different projects. All the time I had to create a few js/html files, maybe css and, finally, wrap it up into web part to provide a nice deployment/setup end user experience. At some point, implementing SharePoint infrastructure (modules, web part, wsp and the rest) could even require more time than implementing js/CSOM app. This isn’t very enjoyable and, to be honest, quite boring.

So, the idea is to create a common infrastructure to avoid most of the SharePoint related coding (especially server side one), to provide a standardized way to create, deploy and manage your js/CSOM apps. That’s exactly where jsAppWebPart for SharePoint 2010 come.

Getting started with jsAppWebPart

Simply saying, jsAppWebPart is a sandboxed web part which allows you to pick and set up the js based application from the app repository. There is a nice end user experience for that, and there is a standardized way to develop/deliver js apps from the developers’ perspective.

Currently, you can download the latest version from https://jsappwebpart.codeplex.com/

End User Experience

Firstly, let’s see the end user experience. As it is just a web part, move your page in the edit mode and select “jsAppWebPart” from the web part gallery:

Image may be NSFW.
Clik here to view.

Next, edit the web part propertied and select the target application you want to get on your page:

Image may be NSFW.
Clik here to view.

Basically, that’s it. Fast and simply. Save the page, enjoy the result. Next, let’s see the developers’ experience with jsAppWebPart.

Hey, there is app settings/properties?

The most coolest thing about web parts is that the end user could modify/adjust web part properties. In a nutshell, it requires a server side coding which is exactly what we try to avoid.

Currently, jsAppWebPart does not allow to setup the js application setting yet. It is the early proof-of-concept, so keep in touch to see how we will do that later via json/js/client side development.

Developer experience

To provide a common way to deploy your js apps, jsAppWebPart creates a new library at the root site called “jsAppsLib”. There are several folders inside that library:

• sys
• apps
• cdn

The “sys” folder is meant to store some scripts required by jsAppWebPart itself. You will not need  to work with that folder ever. It is the place where some special scripts for the jsAppWebPart are stored.

Next, the “apps” folder is meant to store the js apps. Simply. There is a name conventions for the app structure (it is described later, in “Making an app” paragraph) which is used to create an application picker experience and search.

Finally, there is a “cdn” folder to store reusable scripts such as jQuery, Knockout and the rest. If you have any script to be shared by different js applications, this is the right place to store those scripts. Out of the box, jsAppWebPart ships with several popular scripts (the actual list id defined at the end of the post).

Okay, let’s create a new js app for jsAppWebPart!

Making an app for jsAppWebPart: SharePoint designer approach

To start fast or prototype, SharePoint Designer could be used. Open “jsAppsLib” in SharePoint Designer and go to “apps” folder.  Create a new folder called “Hello world app” and fill it with that structure:

• /Hello world app
• /Hello world app/app.meta.html
• /Hello world app/app.meta.png
• /Hello world app/1.0.0.0/app.htm
• /Hello world app/1.0.0.0/app.js
• /Hello world app/1.0.0.0/app.css

So, this is a structure which is utilized by jsAppWebPart to create an application picker experience. Also, every app could contain different versions of itself. You can and need to do so by creating a folder with the actual version of your js app such as “1.0.0.0″ or “1.0.0.10″. jsAppWebPart automatically pick up the latest version of the js app from the eldest folder.

Finally, there are a few files called “app.meta.html” and “app.meta.png” at the app root folder. These files are meant to provide the description/image from your app in the application picker.

So, fill out the “app.htm” file with following content:

<div class="hello-world">Hello world app!</div>

Fill “app.meta.html” with any description you want, such as:

<div>This is a "Hello world" app.</div>

Then, add a nice png  file (“app.meta.png”) to be used as an icon of your app in app picker. At the end, you should the something like this: Image may be NSFW.
Clik here to view. Next, add the “jsAppWebPart” on the page and select your app from the catalog: Image may be NSFW.
Clik here to view. Enjoy the result on the page! Again, quite simply, huh? Let’s move forward and add some css and js magic. Image may be NSFW.
Clik here to view.

Js tokens

Surely, static html is not exactly what we want. So, let’s see how js files/scripts could be utilized in our app. First of all, change “app.htm” to  include the “app.js”:

<script type="text/ecmascript" src="~app/app.js"></script>
<div class="hello-world">Hello world app!</div>

Here is the trick. As we really don’t know where our app will be used, the correct path to any js script is really unknown. So, there are several tokens to be used instead. jsApWebPart takes care about them and calculates the correct paths in runtime. Here is the list of the tokens supported at the moment:

Let’s add some logic to “app.js” as following:

window.helloWorldApp = window.helloWorldApp || {};

(function (app) {

	app.HelloApp = function () {

	};

	app.HelloApp.prototype.run = function(containerId) {

		var appContainer = document.getElementById(containerId);

		appContainer.innerHTML = "This text was added by Hello App.";
		appContainer.innerHTML += "";
		appContainer.innerHTML += "containerId: [" + containerId + "]";
	};

})(window.helloWorldApp);

SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("app.js");

Finally, let’s init our js app instance from “app.htm”. Here is another one trick – the correct “scoping” to allow multiple applications work correctly at the same page. We just define unique id which comes as a part of the web part ClientId.

<script type="text/javascript">
if (LoadSodByKey('helloapp', null) == Sods.missing)
	RegisterSod('helloapp', '~app/app.js');

 SP.SOD.executeFunc("helloapp", null, function () {

       var app = new helloWorldApp.HelloApp();
       app.run("~js-app-id");
 });

<div id="~js-app-id" class="hello-world">Hello world app!</div>

Okay, let’s see what we’ve got. Refresh the page and enjoy the first app created for jsAppWebpart with SharePoint designer.

Image may be NSFW.
Clik here to view.

Adding css

Adding the css is as east as js scripts. Just utilize the “link” tag with “~app” token:

<script type="text/javascript">
if (LoadSodByKey('helloapp', null) == Sods.missing)
    RegisterSod('helloapp', '~app/app.js');

 SP.SOD.executeFunc("helloapp", null, function () {

       var app = new helloWorldApp.HelloApp();
       app.run("~js-app-id");
 });
<div id="~js-app-id" class="hello-world">Hello world app!</div>

However, it is much better to make up a “dynamic” css loading to avoid multiple including via static link tag with in the app. It is something what will be solved in the future.

What’s next?

The next post, “jsAppWebPart for SharePoint 2010 – one more way to craft js/CSOM based apps, part 2, covers the Visual studio/wsp package approach to create a repeatable and smooth experience with deployment and delivering apps for the jsAppWebPart. Stay turned, make some feedback and share your ideas on that!

Links

• jsAppWebPart for SharePoint 2010 at codeplex
• jsAppWebPart for SharePoint 2010 – one more way to craft js/CSOM based apps, part 1
• jsAppWebPart for SharePoint 2010 – one more way to craft js/CSOM based apps, part 2

Conclusion

CSOM, sandboxed solutions in SharePoint 2010 and the “new apps” model in SP2013 are really nice things to be explored and utilized. Making client side apps with html/js/css has a lot of benefits such as simplified development and deployment, maintability and minimal impact/downtime on the target SharePoint farm.

However, it still might require some SharePoint related coding – web parts, modules, feature receivers and the rest. To minimize these activities, some common infrastructure could be done. It could be “generic web part” which implements some routine functions, it could be set of js/html/css scripts or file, or it could be even bigger projects like jsAppWebpart.