RainerAtSpirit's blog

Testing Durandal apps made easy

2013-11-11T00:00:00-08:00

Hi there,

The today’s post is targeted to a very dedicated audience, so let’s see if the following is for you.

You belong to the growing number of Durandal developer?
You have a need to make your apps better?
You don’t know yet how to test a Durandal app?

If you answered one or multiple of these questions with a yes, read on.

Hey, even you answered the last two questions with a no read on to see if Grunt can make your life easier. When you haven’t heard of Grunt yet, head over to smashingmagazine for a nice Grunt intro.

Prerequisites

Clone the following repo https://github.com/RainerAtSpirit/HTMLStarterKitPro, which is the Grunt enabled version of the Durandal “HTML Starter kit” (at the time of this writing Durandal 2.0.1). Follow the steps in the readme, obviously skipping things you’ve already installed on your machine.

Quick start

install node from http://nodejs.org
install grunt using npm install -g grunt-cli
download/clone this repo
run npm install in repo’s root directory to install grunt’s dependencies
run grunt to run the default task, which opens the resultant _specrunner.html in the browser… and waits for you to write some tests

When everything runs smoothly you should see something like the following while running grunt.

 1     $ grunt
 2     Running "jshint:all" (jshint) task
 3     >> 8 files lint free.
 4 
 5     Running "jasmine:dev" (jasmine) task
 6     Testing jasmine specs via phantom
 7     ..............
 8     14 specs in 0.113s.
 9     >> 0 failures
10 
11     Running "connect:dev:livereload" (connect) task
12     Started connect web server on 127.0.0.1:8999.
13 
14     Running "open:dev" (open) task
15 
16     Running "watch:dev" (watch) task
17     Waiting...

Note: If you are seeing an error message like following instead…

1     $ grunt
2     Loading "Gruntfile.js" tasks...ERROR
3     >> Error: Cannot find module 'connect-livereload'
4     Warning: Task "default" not found. Use --force to continue.
5 Aborted due to warnings.

then reread the instructions, you probably missed step 4 ;-).

Ready for your first test? Time for some myth busting…

Durandal’s AMD modules are hard to grok

Hmh, not really. From a Durandal perspective an AMD module should either return a singleton or a constructor function. Here are two simple examples:

singleton.js

1 define(function () {
2     'use strict';
3 
4     return {
5        type: 'I\'m a singleton'
6     };
7 });

constructor.js

1 define(function () {
2     'use strict';
3 
4     return function(){
5        this.type =  'I\'m a constructor function';
6     };
7 });

On a side note When a module has dependencies than there are two ways to declare them.

singleton.js regular syntax

1 define(['knockout'], function (ko) {
2     'use strict';
3 
4     return {
5        type: 'I\'m a singleton',
6        observable: ko.observable('')
7     };
8 });

singleton.js sugar syntax

1 define(function (require) {
2     'use strict';
3     var ko = require('knockout');
4 
5     return {
6        type: 'I\'m a singleton',
7        observable: ko.observable('')
8     };
9 });

You’ll find both in the wild and it’s a question of personal style, which one to use. Before you ask, I tend to use the sugar syntax lately, but now back to the track.

When I say Durandal’s perspective I mean that the module gets loaded by using system.resolveObject, where Durandal differentiate between modules that return a function and … the rest. Of course Durandal wouldn’t be Durandal if this couldn’t be customized, but that’s another story and you have to read it on your own (see customizing system).

1 resolveObject: function(module) {
2     if (system.isFunction(module)) {
3         return new module();
4     } else {
5         return module;
6     }
7 },

Ok so how can we use our testing environment to figure out what is returned by our modules. Let’s face it just because I assume that one returns a constructor and the other a singleton doesn’t necessarily mean that it’s true.

Start by copying flickr.spec.js to singleton.spec.js and update the spec to the following.

 1 /*global jasmine, describe, beforeEach, it, expect, require */
 2 describe('viewmodels/singleton', function() {
 3     "use strict";
 4 
 5     var singleton = require('viewmodels/singleton');
 6 
 7     it('should have a "type" property', function() {
 8         expect(singleton.type).toBeDefined();
 9     });
10 
11 });

On save you’ll see the grunt watch task kicking in, running the specs updating the browser via livereload. Hopefully all is green, so let’s move on.

Copy singleton.spec.js to constructor.spec.js and update the spec so that it loads constructor.js instead:

 1 /*global jasmine, describe, beforeEach, it, expect, require */
 2 describe('viewmodels/constructor', function() {
 3     "use strict";
 4 
 5     var constructor = require('viewmodels/constructor');
 6 
 7     it('should have a "type" property', function() {
 8         expect(constructor.type).toBeDefined();
 9     });
10 
11 });

This time you should see a nice red warning message at the command prompt telling you that’s something wrong.

 1 >> File "test\specs\dev\constructor.spec.js" changed.
 2 
 3 Running "jasmine:dev" (jasmine) task
 4 Testing jasmine specs via phantom
 5 x...............
 6 viewmodels/constructor:: should have a "type" property: failed
 7   Expected undefined to be defined. (1)
 8 16 specs in 0.011s.
 9 >> 1 failures
10 Warning: Task "jasmine:dev" failed. Use --force to continue.
11 
12 Aborted due to warnings.

Now having a browser that allows us investigating what’s going on becomes pretty handy. Luckily in our case we don’t even need that. We already know that constructor.js returns a constructor function and not an object, so let’s rewrite the test to take that into account, which should bring us back to “all green”.

 1 describe('viewmodels/constructor', function() {
 2     "use strict";
 3 
 4     var Constructor = require('viewmodels/constructor'),
 5         instance = new Constructor();
 6 
 7     it('should be a Constructor function', function() {
 8           var a = new Constructor();
 9           expect(a.constructor).toEqual(Constructor);
10       });
11 
12     it('should have a "type" property', function() {
13         expect(instance.type).toBeDefined();
14     });
15 
16 });

That’s it for today, pretty straight forward, so it can be easily applied/adapted to your own Durandal projects. It’s the first post in the “Catch fish” category, hopefully more to come.

Give a man a fish, and you feed him for a day; show him how to catch fish, and you feed him for a lifetime.

Let me know what kind of fish you can come up with.

Durandal SP3: Developing SharePoint SPAs made easy

2013-04-08T00:00:00-07:00

Hi there,

In the last post I introduced you to Durandal a SPA Framework, which can be used to create SPAs on top of the SharePoint infrastructure. This time we’re going to leverage Marc Anderson’s SPServices as a data service for our SPA.

The obvious advantage is that web services are around for a long time, so one SPA (same code base) runs in SharePoint (2003), 2007, 2010 and 2013.

The obvious disadvantage is that web services are deprecated in 2013, so they might go away with the next major release. If you are already running on 2010/2013 and don’t have to support older browser versions you might want looking into using REST services with JayData or Breeze instead… but that’s worth another story.

Seeing is believing so here a couple of screen shots using IE versions that roughly matches the SP release time.

SharePoint 2013 | IE 10:

SharePoint 2010 | IE 8:

SharePoint 2007 | IE 7:

In SP2007 you’ll notice some issues with the CSS that is used in the SPA otherwise it’s fully functional. That is less an issue with IE7, but more with SP2007 that is running pages in Quirks mode. A quick workaround would be to apply a DOCTYPE to the pages that host your SPA.

SharePoint 2003 | IE 6:

Sorry, I’m out of historic SharePoint VMs. Please give me a shot if somebody has still access to a SP2003 environment. I’d love to add the missing screen shot.

Now, after hopefully getting you excited, here’s the bad news. The demo is using the alpha release 2013.01ALPHA5 of SPServices, so I won’t make the demo code available through Github as usual. I’ll update this post once the next official version of SPServices has been released and tested with Durandal SP3.

Update 2013/06/04: And here’s the link to the github repo

The good news is that there are two public available pages that allows you to go hands-on. Both are best viewed with your favorite console open.

Without going into the details lets see what the Promises demo app is doing when you activate the list route (/#lists).

Retrieve information about the lists in the current site via SPServices GetListCollection method (with caching)
Retrieve detail information about the selected list via SPServices GetList method and build a mapping that can be used in SPServices SPXmlToJson method (with caching)
Retrieve item information via SPServices GetListItems (NO caching)

Update 2013/04/11: The live demo was updated based on some feedback I got. The list overview now produces a configurable row view of lists with meta information like ItemCount and Last Modified. Step 2 and 3 are performed once you select a list.

By opening up the optimized build and filtering the network tab for XHR you can see the three POST requests to lists.asmx nicely lined up. Once you start selecting other lists, you’ll noticed that the number of XHR requests decrease as more and more cached information becomes available.

The development version on the other side shows far more details via the console. That allows you to get familiar with Durandal’s application life cycle and to inspect the Json result of some spdata methods.

After reading so far and hopefully seen the Promises demo in action by yourself, I hope that you share my excitement of the upcoming promise support in SPServices. Once it’s part of an official release SPServices will become a perfect fit for Durandal’s life cycle methods.

Update 2013/04/16 Marc Anderson reposted this article as SPServices story and added a bunch of additional, valuable information. Do not miss to check it out.

Durandal meets SharePoint 2013

2013-02-21T00:00:00-08:00

One of the benefits of the new SharePoint 2013 app model is that we are nowadays allowed to live on the cutting edge of technology. At least if you build Autohosted or Providerhosted apps. If that what you’re doing make sure to read Scott’s Announcing release of ASP.NET and Web Tools 2012.2 Update, install the bits and then explore some of the new MVC4 templates.

Next step would be to look at Ananu’s blog aanuwizard as it has step-by-step instructions for you how to add a MVC4 project to your SharePoint 2013 apps.

But how can you survive building single page application (SPA) in SharePoint if you are

still running on SharePoint 2010 or
creating SharePoint-hosted SharePoint 2013 apps

Let me introduce you to Durandal, a pretty young SPA framework, which is named after a famous French sword. As it states on the web site

Your search for a SPA framework ends here.

Durandal claims to be comfortable

We didn’t try to re-invent the wheel. Durandal is built on libs you know and love like jQuery, Knockout and RequireJS. There’s little to learn and building apps feels comfortable and familiar. Dive in and enjoy.

Durandal claims to run Anyone and Everyone

In the end, Durandal is just a collection of JavaScript libraries, so you don’t need anything special to use it. Hop on over to our github repo and fork away. You can just grab the contents of the App folder and use it to kickstart your own project.

Alright let’s test these statements by throwing Durandal into a SharePoint-hosted SharePoint 2013 app and see how it goes.

Before we start here’s a screen shot of the final result as teaser. There’s an online version as well and the VS template can be forked from github.

We are starting by opening up the MVC4 Durandal starter template and creating an OOTB SharePoint 2013 app of type SharePoint-hosted. Files in the MVC Content and Script folder can be copied straight away, because there are already corresponded modules in the SP template. Create a new module named App, copy all App files from MVC4 app and make sure to exclude App/Durandal/amd/optimizer.exe from the project. By default SP won’t allow upload of .exe files. Do NOT delete that file, we’ll need it later.

In the next step we’re copying the necessary bits from Index.cshtml and _splash.cshtml into our Default.aspx and adjust them to the aspx syntax.

In order to substitute the MVC4 BundleConfig settings for CSS and JavaScript files you must have Web Essentials 2012 installed. If not, this is a good time to install it otherwise the next step won’t work.

Hit F5, wait till the upload has finished and you should see something similar like this.

Not that bad for a first stab I’d say, you’ve reached Durandal’s development mode. All AMD files will be served individually and in addition we are getting a whole amount of logging messages in the console. That’s the place where later down the road you’d spend most of your time, so make yourself familiar. Today we simply heading forward to production, but before we do that let’s make a small adjustment to Durandal’s navigation bar because at the moment it’s overlaying the default SharePoint top nav. If you are already familiar with Durandal’s app structure the next two steps are obvious. If not here are some readings that get you started:

In order to address the positioning of the navbar remove the navbar-fixed-top class in views/shell.html.

And now a scary moment. Let’s create an optimized version of our app by going down to a command line and run optimizer.exe. Remember, that was the file that we excluded earlier in the process from our project, but of course it’s still sitting in the file system. As long as you stick with Durandal’s defaults this tool will help you creating an optimized main-built.js file.

In the last step comment|uncomment the appropriate parts in default.aspx that are responsible for loading main-build.js and you should be good to go.

Looks like we accomplished our mission for today and from my first impressions I’d say that Durandal can fulfill the promise of Your search for a SPA framework ends here. In one of the upcoming posts I’ll add my trusted data access tool JayData that allows us to work with native SharePoint list and libraries through OData and see how it fits into the Durandal SPA framework.

Here’s a final word of warning. Before diving deeper into this new and mighty thing called Durandal, remember it’s young. So weigh the risks and don’t miss to dig up the story of Durandal’s eponym. You’ll see that at the end the hero Roland is dead, only the sword survived ;-).

More about REST in SharePoint 2010/2013

2013-01-19T00:00:00-08:00

Hi there,

It’s been a while since the last post about SharePoint 2013 and why you should use REST when talking to it. I’m still convinced that this holds true in the long run, but you should be aware of a couple of facts that I’ve learned in the meantime.

At the time of this writing SharePoint 2013 only supports OData V2. How comes? During beta phase I got the impression that /_api acts as an OData V3 provider, but in the release version Microsoft pulled the plug and removed $metadata support. You can read more about that in this thread, but here’s the relevant paragraph from the specs.

OData services MUST expose a Metadata Document which defines all data exposed by the service. The Metadata Document URL SHOULD be the root URL of the service with “/$metadata” appended. To retrieve this document a client issues a GET request to the Metadata Document URL.

If you read a MUST in the specs you know that without it (whatever else your service delivers) it’s definitively not an OData v3 provider. What makes that so disappointing is that JayData won’t work without having the $metadata information exposed to it.

If you’re like me and want to give JayData a try for abstracting the access to the underlying data provider, you should be aware of another limiting factor. Like jQuery 2.0 that was just announced, JayData is targeted to work with modern (mobile) browser. IE8 and below definitively doesn’t belong into that group and for JayData there’s no way to shim the missing required capabilities in.

Not a big deal you say, IE8 is outdated anyway and nobody in my org is using it any longer. Lucky you, go ahead and give the OData v2/JayData combo a try. If on the other hand you want to create an app and put it in the app store…

Guess what one of the MUST have criteria is that allows it to be placed in the app store is? You guessed right IE8 support! Read more about this requirement and some other pitfalls you might encounter in this post by Aidan Garnish.

Hopefully Microsoft will deliver two things in the near future:

1. provide $metadata for _api -> this will make _api a real OData v3 provider

2. lift the requirements for the app store. Come on guys IE8 is outdated and you’ve already got two newer releases out there!

but regardless if Microsoft will fulfill my small wish list or not, luckily you can get JayData running on SharePoint 2010 and SharePoint 2013 by using _vti_bin/listdata.svc as of today.

Update:: As Thomas pointed out since the Feb. 5th update to the validation policies IE8 is no longer a requirement for SharePoint app.

In order to get you started here are links to two example sites that will allow you to get hands-on. Both require that you know your way around in a browser console :), so pick up your favorite one and give it a try.

JavaScript language query playground

This is a live version of the JSLQ101 document that will allow you to work with a public OData v2 endpoint using JayData. Note that everything that you can do with the public OData v2 endpoint can be done using _vti_bin/listdata.svc in SharePoint 2010/2013.

JSQL SharePoint 2013 app

UserName: odatademo@spirit2013preview.onmicrosoft.com

Password: OData!Demo

This is a SharePoint-hosted app that allows you to use CRUD operation against the app web. The list structure is described in more detail by Chris O’Brien and consists of a simple project list and a custom time tracking list that has a lookup to the project list. Make yourself familiar with this setup by reading this post from Chris.

Note even if this is an SharePoint hosted app running on SharePoint 2013, because it’s using _vti_bin/listdata.svc this would work on SP2010 as well.

SharePoint 2013 apps: CSOM vs. REST?

2012-10-05T00:00:00-07:00

Hi there,

Have your seen Microsoft’s TypeScript preview already? Are you curious how that will help you building SharePoint 2013 apps? Eager to get your hands dirty? So the good news is that by simply following the steps outlined in the last blog, this time using the TypeScript ToDoMVC example as your a la carte selection, you will be up and running in minutes.

Great starting point, but what’s next? How can we access data that is stored inside SharePoint? No server side code is allowed in the app model, so your options are CSOM or REST. Which one is the better approach? Does the type of App you build has an influence? Just to recap you can choose between SharePoint-hosted, Autohosted and Provider-hosted. Other than the typical consultant answer it depends ;-) here are some reasons why I’m always using REST.

On the server side:

SharePoint 2010 already provides listdata.svc (OData v2) -> Start building list-based CRUD solutions today
SharePoint 2013 adds the new OData v3 _api endpoint -> Function support in OData v3 allows Microsoft to expose the whole range of CSOM functionality via REST
You can control access to external OData services by using Business Connectivity Services
VS2012 makes it easier than ever to produce OData v2/v3 services based on your own data sources
LightSwitch eases the creation of server side mash-ups and expose them via OData
OData ecosystem provides access to data outside of the SharePoint context
Earlier this year Microsoft announced that OData becomes an OASIS Standard

On the client side:

HTML5/JavaScript apps are extremely popular nowadays and languages that compile into JavaScript like CoffeeScript and TypeScript help to transition from server side languages to JavaScript

CoffeeScript is to Ruby as TypeScript is to Java/C#/C++.

Luke Hoban (co-creator of TypeScript)
SPAs are the perfect fit for mobile application
Client side libraries like data.js or jaydata.js provide an abstraction layer for OData, so you don’t have to deal with the OData URI Conventions on your own.

So at the end of the day you learn OData and a couple of client side app pattern once, and then you can reuse this knowledge over and over again… even outside of SharePoint.

With that said, we still need to figure out how to access data that is stored in SharePoint from our remote hosted web, don’t we?

The following drawing summarizes what’s going on when you run an Autohosted or Provider-hosted app.

You end up with three places where data can be stored.

In the remote web
In the app web
In the host web

In a client-only application direct accessing data in the app web (2.) and host web (3.) from your remote app (1.) is prohibited by cross-site-script restrictions. That where Microsoft’s SP.RequestExecutor.js library comes into play. As you can see in the drawing under the hood the system creates an IFrame in the remote web to a specific page in the app/host web (AppWebProxy.aspx), so in effect you’re “remote call” is a local call that tunnels through the IFrame to the remote site.

Accessing data in the host web is further secured by OAuth, so in order to access information in the host web your application has to be configured correctly using the AppManifest.xml file. Last but not least you are allowed to configure the App authorization policy type e.g. if you app needs elevated privileges.

In the default App for SharePoint 2013 Autohosted and Provider-hosted templates, Microsoft provides the Tokenhelper.cs file to deal with the whole App authentication and authorization process. Good news is, you don’t even have to deal with that if you are creating a client side only app. Once you’ve access to the app web you can use the SP.AppContextSite(@hostweb)/ _api function to access information from the host web. SP.AppContextSite() will then ensure that you are accessing the host data in compliance to the permissions you’ve configured.

Here’s some minimalistic code that retrieves information from the app web and the host web and logs title and url on success.

 1 function execCrossDomainRequest() {
 2     // executor: The RequestExecutor object
 3     // Initialize the RequestExecutor with the app web URL.
 4     var executor = new SP.RequestExecutor(appweburl);
 5 
 6     // Retrieve information from the app web
 7     executor.executeAsync(
 8       {
 9           url:
10               appweburl +
11               "/_api/web",
12           method: "GET",
13           headers: { "Accept": "application/json; odata=verbose" },
14           success: successHandler,
15           error: errorHandler
16       }
17     );
18 
19     // Retrieve information from the host web
20     executor.executeAsync(
21         {
22             url:
23                 appweburl +
24                 "/_api/SP.AppContextSite(@hostweb)/web/?@hostweb='" + hostweburl + "'",
25             method: "GET",
26             headers: { "Accept": "application/json; odata=verbose" },
27             success: successHandler,
28             error: errorHandler
29         }
30     );
31 }
32 
33 function successHandler(data) {
34     var result = JSON.parse(data.body).d;
35     console.log('Title: ' + result.Title + ' Url: ' + result.Url);
36 }

Trying to run this code using an OOTB template won’t work and the various error messages you might see can be tracked down to the fact that the appweburl is undefined.

How comes? By default the Autohosted or Provider-hosted template have an empty app web. If the app web is empty SharePoint doesn’t create the app web for you. But as you can see in the diagram above without an app web, there’s no way to retrieve information for a client side solution. An NO, replacing appweburl through hostweburlto bypass the app web completely like in the following code example won’t work.

Instead the system returns the following error message.

How to mitigate? The solution is as simple as adding an Empty Element to the app web. This will force SharePoint to create the app web and you’ve got your missing stepping stone into the host web.

Mission accomplished and for those of you who made it till the end here’s the link for today’s github repro.

MV* SharePoint 2013 Apps a la carte

2012-09-08T00:00:00-07:00

Hey there,

Welcome to our small SharePoint App restaurant, where we serve the best client side MV* crossover SharePoint apps worldwide. So what make us so special and what do I mean when saying MV* crossover app?

As you already know you can use the Visual studio 2012 App for SharePoint 2013 template to create app flavors like SharePoint-hosted, Autohosted or Provider-hosted, which can be used as starting point for creating your own apps. And there is this world of client side single page application (SPA) that can be easily mixed into it. If you’ve ever have written some SPA before, you’ll know that you’re in the need to structure your apps real soon, otherwise you’ll start writing unmaintainable Spaghetti code.

That’s where Model View Controller, Model View Presenter, Model View View Model or short MV* libraries like Knockout, backbone.js… or frameworks like dojo, yui… come into play. They help you, and I’m going to quote John Papa’s words here:

Turn your code from Spaghetti to Ravioli.

With that said without further hassle, here’s what we are going to serve today. Even better find all background information needed to help you get started when cooking your own.

If you haven’t made up your mind yet, which MV* style is the right one for you, drop by http://todomvc.com/.

Developers these days are spoiled with choice when it comes to selecting an MV* framework for structuring and organizing their JavaScript web apps.

Backbone, Ember, AngularJS, Spine… the list of new and stable solutions continues to grow, but just how do you decide on which to use in a sea of so many options?

To help solve this problem, we created TodoMVC - a project which offers the same Todo application implemented using MV* concepts in most of the popular JavaScript MV* frameworks of today.

Want to find out what makes it a framework or library and if one or another better suits your needs? Make sure that you don’t miss Stephen Sanderson’s the Seven Frameworks post.

Enough theory let’s get hands-on to see What needs to be done. Each todo below has some instructions and screen shots, but I won’t dig into too much code today. Don’t worry though, because

The ToDoMVC example is available at github, so clone it and use it as starting point for your own apps
Each todo has an associated git tag that let you checkout the example at this specific point
Links to git diffs are available, whenever there’s a need for some details

Todo 1: Create SharePoint 2013 Autohosted app

Let’s start by creating an App for SharePoint 2013 in Visual Studio 2012 and use Autohosted for the hosting type.

Todo 2: Clean the stage

The defaults above don’t do us any good as we are going to create a client side SPA. Let’s get rid of all Properties and References, and then delete the Pages directory and the TokenHelper.cs file. This will leave us with a really clean stage, which we can build on. Please note that at this point the example isn’t doing anything.

Todo 3: Select from the ToDoMV* menu

Picking something from the ToDoMV* menu is completely up to your personal taste, but it probably helps if you already have some experience with the library/framework you chose.

If you’ve seen/read The Ferrari meets JayData, you’re probably not astonished why my pick for today is the Knockout + RequireJS example from the labs section.

Regardless of what you’ve picked, here are the steps to get it working.

Step 1: Choose from the menu.

Step2: Copy the files into the web project.

Step3: Copy the asset directory that holds common files for all todo examples.

Step4: Update the appmanifest.xml so that it points to your index.html (or whatever start page you’ve created/copied).

Step 5: When done press F5 start the app and enjoy the results.

Please note: If you are seeing a 405.0 error instead, make sure to apply the settings described in this post SharePoint 2013 App HTTP Error 405.0

Todo 4: Add the chrome control

Adding the chrome control is a two-step process.

Step 1: Add the chrome_ctrl_placeholder div to index.html Todo 4 Step Diff 1

Step 2: Add the required chrome control JavaScript to your code. Todo 4 Step Diff 2

Depending on the example you’ve picked, running this right away might lead to some error messages, which needs to be resolved before moving on. With the Knockout + RequireJS example I’m running into this.

Reason is that this example doesn’t use jQuery at all… up till now. So let’s add it following the RequireJS way and while on it let’s make sure that we try loading from a CDN first before serving our own local copy.

Todo 5: Cosmetic changes

There are only a couple of minor tweaks left like adding an AppIcon, changing the body and/or chrome-control width before we’re satisfied with the result.

That’s it for today, you’ve just cooked your first MV* SharePoint 2013 app.

Is there more to it? Sure! Here are a couple of suggestions that you might want to try out:

Store todos in a SharePoint list instead of local storage
Store todos in SQL azure
Store todos in your own provider-hosted data-store
… fill in the blanks with your own ideas

As long as you like cooking/coding/building/architecting, I don’t see any shortcoming of opportunities while SharePoint 2013 is making it to the market.

SharePoint 2013 and the notorious disclaimer

2012-09-05T00:00:00-07:00

At the time of this writing you’ve probably seen something like the below, while browsing SharePoint 2013 blogs or the documentation on MSDN.

Disclaimer MONTH DAY 2012: SharePoint 2013 is in preview at this stage, so some specifics and user experiences may change slightly between now and release time.

With that in mind we expect having some fun time while trying to get things working using the documentation/examples that are out there. To make things even more exciting Visual studio 2012 and Windows 8 were just released lately. In contrast most examples have been written using prerelease software.

Once you get started with SharePoint apps, you will be in need for examples and you know that officeapps is a great starting point. Me, I’m primarily interested in SharePoint 2013 apps that use client side REST calls to access server side data. Luckily there are already a couple of examples at officeapps that cover that area.

Unfortunately most of them fall under the above Disclaimer category and therefore need some tweaking before they work to my liking.

Before moving on

Notorious disclaimer September 05 2012: I’m running the example in a VMWare instance of Win8 plus VS2012, both RTM. Your experience may wary, but that’s expected.

Sorry couldn’t resist :). With that said let’s take a specific example like Use the chrome control and the cross-domain library (REST) and see what might happen while you testing it out.

Issue 1: HTTPS/HTTP Mixed content

Step 1: Download the example, open in Visual studio 2012 and add your SiteURL

Step 2: Run the example and launch the app

Step 3: If you see an error messages in VS, hit continue

Step 4: Switch to IE and confirm “Show all content”

Step 5: Finally: Success!

What’s the problem? Based on the IE message we see that we have a mixed bag of https and http content on our page, which is prevented by the default IE settings. Glancing through the html code reveals that we are loading files from a CDN via http while the web site is running on https.

1     <script
2         src="http://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"
3         type="text/javascript">
4     </script>
5     <script
6         type="text/javascript"
7         src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
8     </script>

How to mitigate: Instead of simply changing the src attribute to src="https://ajax...", which would reintroduce the issue if we later switch the web site protocol from https: to http:, let’s get rid of the protocol all together so that it reads: src="//ajax...". If that syntax doesn’t look familiar to you, check out 3 reasons why you should let Google host jQuery for you to learn more about it.

Issue 2: Chrome control prevents scroll bar

What’s the problem? The chrome control dynamically loads some additional CSS from the host web. So it’s not your CSS that causes the issues, it’s the remote CSS.

How to mitigate: The chrome control injects a link id="... element inside the <head> section, which ensures that this CSS is evaluated first (see issue 4 for details). That allows us to overwrite conflicting styles in our own CSS file. Let’s create an app.css file and include it in the html file(s). While on it you might want to clean up a little and get rid of the script element that loads MicrosoftAjax.js. Neither the example nor the chrome control and cross-domain library rely on it.

1 <head>
2    <title>Chrome control host page</title>
3    <link rel="stylesheet" type="text/css" href="app.css" />
4    <script 
5        type="text/javascript" 
6        src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
7    </script>
8    ...
9 </head>

app.css:

1 body {
2     overflow-y: scroll
3 }

Issue 3: Houston, We’ve Got a Problem

Step 1: Realize that we have a problem.

What’s the problem? Do we really have a problem here? After the modification done above the example is working and therefore allows grasping the essence of it:

This code sample includes a remote webpage that hosts the chrome control and retrieves information from the host web using the cross domain library and Representational State Transfer (REST) in SharePoint 2013 Preview.

So again. What’s the problem? If you are an experienced HTML5/CSS/JavaScript developer there’s probably none. You’d see that there are a couple of issues with the example like

leaking globals
script elements in header
waiting for $(document).ready before code execution

but you’d simply ignore them and make a mental note to fix them in your own code. You grasped the essence of it and that’s what count.

Chances are that you’re coming from a different angle, let’s say you’re an experienced .NET or even SharePoint developer and HTML5/CSS/JavaScript is not your prime area of expertise. You make the example work and grasp the essence of it. But because you don’t know what you don’t know, you will start replicating the code base… including the issues.

But hey, we got the notorious disclaimer, so Microsoft may change things later down the road. Maybe they start updating the examples closer to the release date. Yes maybe they do, but we better don’t wait for || rely on it.

How to mitigate: Let’s apply some JavaScript best practice rules and refactor the example. The goal is not to bend it too much, just making it living to the rules without losing the essence.

Step 1: Move declared global vars and named functions inside $(document).ready. Catchword: Declared and implied globals.

Before:

 1 var hostweburl;
 2 var appweburl;
 3 
 4 // Load the required SharePoint libraries
 5 $(document).ready(function () {
 6 ...
 7 });
 8 
 9 // Function to prepare and issue the request to get
10 //  SharePoint data
11 function execCrossDomainRequest() {
12 ..

After:

 1 // Load the required SharePoint libraries
 2 $(document).ready(function () {
 3 var hostweburl;
 4 var appweburl;
 5 ...
 6 // Function to prepare and issue the request to get
 7 //  SharePoint data
 8 function execCrossDomainRequest() {
 9 ..
10 
11 });

Step 2: Load scripts at the bottom of your html. Catchword: High Performance Web Sites: Rule 6

 1 <!DOCTYPE html>
 2 <html xmlns="http://www.w3.org/1999/xhtml">
 3 <head>
 4     <title>Chrome control host page</title>
 5     <link rel="stylesheet" type="text/css" href="app.css" />
 6 </head>
 7 <body>
 8 
 9     <!-- Chrome control placeholder -->
10     <div id="chrome_ctrl_placeholder"></div>
11     <h1 class="ms-accentText">Main content</h1>
12 
13     <!-- This is the placeholder for the announcements -->
14     <div id="renderAnnouncements"></div>
15 
16     <!-- Script tags moved to bottom -->
17     <script type="text/javascript" src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js"></script>
18     <script type="text/javascript" src="ChromeLoader.js"></script>
19     <script type="text/javascript" src="CrossDomainExec.js"></script>
20 </body>
21 </html>

Step 3: By loading scripts at the bottom, the need to wait for $(document).ready before we can kick off our code vanishes away, so we can speed up load time by switching to an Immediately-Invoked Function Expression IIFE instead.

Before:

1 $(document).ready(function () {
2 ...
3 });

After:

1 (function () {
2 ...
3 })();

There are probably other things that you might want to improve, but with those minor tweaks above, we already covered a lot of ground.

Further readings: The Essentials of Writing High Quality JavaScript, IIFE and Okay, Houston, we've had a problem here

Issue 4: Preventing flash of unstyled content

What’s the problem? Loading the chrome control happens asynchronously using $.getScript() with renderChrome() as callback. Within renderChrome you first configure the control and then kick it off via nav.setVisible(true) . This will add the dynamic link element that finally loads the remote CSS. So there’s a time frame after document.ready in which our static HTML content will not be aware of the remote CSS.

1    ...
2    // Load the js file and continue to the
3     //   success handler
4     $.getScript(scriptbase + "SP.UI.Controls.js", renderChrome)
5 });
6 
7 //Function to prepare the options and render the control
8 function renderChrome() {
9 ...

How to mitigate: Switching from SP.UI.Controls.js to SP.UI.Controls.debug.js let step us into nav .setVisible(true), where we see how MS constructs the link to defaultcss.ashx and sets up an event listener to determine when the CSS is loaded.

 1 ...
 2 if (visible && !this.$s_0) {
 3             var $v_0 = (document.getElementsByTagName('head'))[0];
 4             var $v_1 = document.createElement('link');
 5 
 6             $v_1.setAttribute('id', SP.UI.Controls.Navigation.$2 + SP.UI.Controls.Navigation.$12);
 7             $v_1.setAttribute('rel', 'stylesheet');
 8             $v_1.setAttribute('type', 'text/css');
 9             $v_1.setAttribute('href', this.$3_0 + SP.UI.Controls.Navigation.getVersionedLayoutsUrl('defaultcss.ashx'));
10 
11             if ($v_1.addEventListener) {
12                         var $$t_5 = this;
13 
14                         $v_1.addEventListener('load', function() {
15                             SP.UI.Controls.Navigation.$z($$t_5, visible);
16                         }, false);
17                     }
18 ...

What’s good for MS is good for us, so we add a style="display: none" to the body tag and add our own event handler that changes the style attribute to display: block when the CSS is loaded. As we are already using jQuery this is pretty straight forward.

1 ...
2     nav.setVisible(true);
3     $('#chromeControl_stylesheet').on('load', function (event) {
4         $('body').show();
5     })

That’s it for today and as a benefit for people who really made it till the end of this TL;DR, here’s a link to github, where the code for today’s post is available. While there take a look at the commit history and you’ll see that for every issue described above there’s a commit available.

Feel free to clone and send me a pull request if you find other issues.

You are working on another example, but find applying the above modifications beneficial? Good, make sure to share. I’m using the shortened URL from officeapps as git repository name. Create a git repro using this naming convention and link to your repro from the officeapps example Q&A section.

SharePoint 2013 App HTTP Error 405.0

2012-09-03T00:00:00-07:00

Hi there!

Today’s post is just a short one about an HTTP Error 405.0 that I was seeing when trying to get an Autohosted SharePoint app working with static files. If you’re not sure what a SharePoint App is or what it’s good for read Ted Pattison’s blog My first weekend in Napa and the Apps for Office and SharePoint blog to get you started.

So what happened? I wanted to replace the default files in an Autohosted template with files coming from my favorite HTML5 framework: Zurb foundation.

If you don’t trust screenshots ;-) here are the steps to follow along:

Step 1: Create an App for SharePoint

Step 2: Choose Autohosted for hosting type

Step 3: Get rid of the defaults files, references and properties

Step 4: Copy/paste you static HTML files and adjust AppManifest

Step 5: Run the app, trust it and … HTTP Error 405.0

I’m pretty sure you’ve been to http://code.msdn.microsoft.com/office before and seen many SharePoint 2013 examples with the following troubleshooting message.

Unfortunately after applying the additional verbs to my applicationhost.config file I still got the same error :(.

For further troubleshooting I’ve added a new handler StaticHTML for *.html files, which while leading to the same error at least proved that the new handler with all correctly configured verbs was used by the system.

1  ..
2  <handlers>
3     ..
4     <add name="StaticHTML" path="*.html" verb="GET,HEAD,POST,DEBUG,TRACE" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
5     <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
6  </handlers>
7

After a moment of frustation Google-fu came to the rescue: this post talks about some intrinic of the StaticFileHandler and why static sometimes is not static enough. After following the recommendation of adding an AspNetStaticFileHandler everything was working as expected.

1  ..
2  <handlers>
3     ...
4     <add name="AspNetStaticFileHandler" path="*" verb="*" type="System.Web.StaticFileHandler" />
5     <add name="StaticHTML" path="*.html" verb="GET,HEAD,POST,DEBUG,TRACE" modules="StaticFileModule" resourceType="File" requireAccess="Read" />
6     <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
7  </handlers>
8

Finally: SharePoint Autohosted App meets Zurb foundation

Update 09/09: Ready to deploy to Azure? Make sure to add the handlers to web.config otherwise you’ll be presented with a similiar error 405.0 when trying to launch your app on azure.

Nappa apps and Chrome Control

2012-08-28T00:00:00-07:00

Let’s assume you’ve

a) read Ted Pattison’s blog My first weekend in Napa and got Microsoft’s invite

But then I think about this new breed of SharePoint developer that Mike Morton described to me. A developer that’s never never used SharePoint before and has never seen a SharePoint dinosaur like me (except maybe in a museum). This developers has a very high IQ and has tons of experience with things like .NET, C#, JavaScript and jQuery

b) seen my previous post that turned the OOTB Nappa masterpage template into an easier to handle HTML5 template

Just to recap. In the template we removed the reference to the masterpage, which is normally responsible to load the chrome for Nappa apps, because we didn’t like the overhead that comes with it. According to the invite you’ve never seen SharePoint before (feel free to read on even if you have) and you’re wondering if you’re now supposed to turn the minimalistic Nappa template (see below) into something that looks like a SharePoint app on your own.

Don’t wonder any longer, you don’t ;-) and even better there are just a few changes necessary. Without the masterpage reference our current Nappa template behaves more like a hosted HTML5 app and for that kind of SharePoint app Microsoft already offers the client chrome control.

For the eager of you here are the 5 steps that provide you access to a clean Nappa template that uses the client chrome control:

Step 1: Create a new Nappa app Step 2: Replace default.aspx content with this default.aspx content Step 3: Replace apps.js content with this app.js content Step 4: Change permission to allow read access to web Step 5: . Trust the app Step 6: Party time: A clean Nappa App template with client chrome control

The chrome configuration is done in the renderChrome() function and is following the settings in this MSDN the client chrome control article. Please note that the MSDN settings assume that you create a couple of additional pages otherwise the links won’t work.

One minor issue that I’ve noticed it that without further modifications the MSDN version might lead to some flash of unstyled content (fouc). One way to prevent that is to change our HTML in default.aspx to <div id="message" style="display: none"> to hide our message div by default. In our code we then bind to the load event of the dynamically injected stylesheet and leverage $('#message').show(); to show the message.

1 var nav = new SP.UI.Controls.Navigation(
2                         "chrome_ctrl_placeholder",
3                         options
4                   );
5 nav.setVisible(true);
6 $('#chromeControl_stylesheet').on('load', function (event) {
7     $('#message').show();
8 })

With those modification you should have a nice clean starting template for your HTML5 Nappa apps.

Let’s party!

Goodbye Ferrari, hello Napa?

2012-08-24T00:00:00-07:00

Hey there!

If you’ve seen my series about the SharePoint DVWP in Ferrari mode (Part 1, Part 2, Part 3) you remember that we ended up with a small HTML5/CSS3/JavaScript app that is running on SP 2010 and SP 2013.

Today we take some of our lessons learned and try to apply them into the brave new world of SP 2013 apps or to be more precise into the world of Napa apps. Please note that I’m not going to cover the whole SharePoint 2013 App Model, but if you want to learn more about it, spend an hour and watch Jeremy Thake’s screencast about that topic.

Why should we talk about Napa apps in the first place? One reason is that Napa apps are the lowest hanging fruits in SP2013 development at least in terms of required infrastructure. You don’t need to setup an on premise SP2013 development environment and you’re not required to have Visual studio 2012 installed.

With that said if you want to follow along and haven’t Napa yet, this Office 365 Developer page will get you started.

Just to get our feet wet let’s create an OOTB app called ‘SharePointApp1’ and run the project without further modification.

Step 1 Add a new project Step 2 Choose App for SharePoint and give it a name Step 3 Press the Run project button and see how the system is doing its job to package, deploy and launch your app Step 4 Be impressed with the results of all your hard work :)

Take a quick glance at the HTML source of our impressive app. I say impressive because even though the payload is just the User Name it has 644 lines of code. The reason is that our small ‘payload’ is nicely embedded into SP2013, which comes with a price.

 1 <%-- The following 4 lines are ASP.NET directives needed when using SharePoint components --%>
 2 <%@ Page Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" MasterPageFile="~masterurl/default.master" language="C#" %>
 3 <%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
 4 <%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
 5 <%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
 6 
 7 <%-- The markup and script in the following Content element will be placed in the <head> of the page --%>
 8 <asp:Content ContentPlaceHolderId="PlaceHolderAdditionalPageHead" runat="server">
 9     <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.6.2.min.js" type="text/javascript"></script>
10 
11     <!-- Add your CSS styles to the following file -->
12     <link rel="Stylesheet" type="text/css" href="../Content/App.css" />
13 
14     <!-- Add your JavaScript to the following file -->
15     <script type="text/javascript" src="../Scripts/App.js"></script>
16 </asp:Content>
17 
18 <%-- The markup and script in the following Content element will be placed in the <body> of the page --%>
19 <asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
20 
21     <div>
22         <p id="message">
23             <!-- The following content will be replaced with the user name when you run the app - see App.js -->
24             initializing...
25         </p>
26     </div>
27 
28 </asp:Content>

Within the Source we see some familiar ASP.NET directives with a link to a masterpage and then two <asp:Content> blocks.The PlaceHolderAdditionalPageHead is used to load your app specific CSS and JavaScript. The CSS is of no interest for us at the moment so let’s take a look at App.js instead.

 1 var context;
 2 var web;
 3 var user;
 4 
 5 // This code runs when the DOM is ready. It ensures the SharePoint
 6 // script file sp.js is loaded and then executes sharePointReady()
 7 $(document).ready(function () {
 8     SP.SOD.executeFunc('sp.js', 'SP.ClientContext', sharePointReady);
 9 });
10 
11 // This function creates a context object which is needed to use the SharePoint object model
12 function sharePointReady() {
13     context = new SP.ClientContext.get_current();
14     web = context.get_web();
15 
16     getUserName();
17 }
18 
19 // This function prepares, loads, and then executes a SharePoint query to get the current users information
20 function getUserName() {
21     user = web.get_currentUser();
22     context.load(user);
23     context.executeQueryAsync(onGetUserNameSuccess, onGetUserNameFail);
24 }
25 
26 // This function is executed if the above call is successful
27 // It replaces the contents of the 'helloString' element with the user name
28 function onGetUserNameSuccess() {
29     $('#message').text('Hello ' + user.get_title());
30 }
31 
32 // This function is executed if the above call fails
33 function onGetUserNameFail(sender, args) {
34     alert('Failed to get user name. Error:' + args.get_message());
35 }

Beside the fact that the small code leaks more than half a dozen globals, which makes some of us laugh and some of us cry, we see that getUserName() retrieves the user information from the app web via CSOM and finally onGetUserNameSuccess() renders the Hello username message.

Checkpoint So far everything was nice and easy I’d say and you shouldn’t have an issue if you follow along.

Now let’s switch gears by first getting rid of the SharePoint chrome. Simply copy Source2 and replace your existing default.aspx content in Napa. Running the app will show that the HTML source2 for the page is down to 18 lines.

By glancing through Source2 you see that we are still using some ASP.NET directives, just the reference to the masterpage has gone. In addition the <asp:Content> blocks have been replaced by some standard HTML5. In Part 1 we stripped down the DVWP in a similar manner, so we might call this mode the Naparari :-).

Please note that at this time the JavaScript won’t work as some required CSOM files are loaded via the masterpage we just removed.

 1 <%-- The following 5 lines are ASP.NET directives needed when using SharePoint components --%>
 2 
 3 <%@ Page Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Language="C#" %>
 4 
 5 <%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
 6 <%@ Import Namespace="Microsoft.SharePoint" %>
 7 <%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
 8 <%@ Register TagPrefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
 9 
10 <!DOCTYPE HTML>
11 <html>
12 <head>
13     <title>
14         <SharePoint:ProjectProperty Property="Title" runat="server" />
15     </title>
16     <!-- Add your CSS styles to the following file -->
17     <link rel="Stylesheet" type="text/css" href="../Content/App.css" />
18 </head>
19 <body>
20     <div id="message">
21         <!-- The following content will be replaced with the user name when you run the app - see App.js -->
22         initializing...
23     </div>
24     <script src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.0.min.js" type="text/javascript"></script>
25     <script type="text/javascript" src="../Scripts/App.js"></script>
26 </body>
27 </html>

Second let’s make some modification to app.js.

Goal: In addition to the username we want to retrieve the web title from the host web
Goal: Instead of adding the required CSOM files, we are switching to OData
Goal: While on it let’s get rid of the globals ;-).

Napa apps like other SharePoint Apps enforces a clear separation between the host web, the web where you install your app, and the app web, the place where your code is actually running.

As an example take a look at my host web URL: https://spirit2013preview.sharepoint.com/sites/dev/

Whenever a Napa app is launched it runs at an app web URL similiar to

https://spirit2013preview-b0204c96e900db.sharepoint.com/sites/dev/GoodbyeFerrariHelloNapa/Pages/Default.aspx

You see that an app specific GUID like -b0204c96e900db is added to the host header, so for our JavaScript code that is running in the app web there’s NO way to access information directly in the host web due to cross site scripting restriction.

Let’s see how our goals can be accomplished in the JavaScript below, which is based on code from MSDN. If you’re not familiar with the cross-domain library SP.RequestExecutor.js please check it out first.

Goal 1 and 2: The answer to both goals live in the execCrossDomainRequest() function. As you can see we are executing a call against the local SPAppWebUrl /_api/SP.AppContextSite(@target)/ OData endpoint and passing in SPHostUrl as @target. Effectivily this will provide us access to the remote SPHostUrl/_api endpoint (through the cross-domain library).

Beside the cross-domain library specific you can now use the same OData syntax that you would use locally e.g. here /web?$expand=CurrentUser is used to retrieve web and at the same time CurrentUser information.

Goal 3: There’s more than one way to accomplish that, but to be close to the origal version let’s wrap our code in an Immediately-Invoked Function Expression IIFE, which you might know as self-executing anonymous function as well.

 1 (function () {
 2     var params = getParams(),
 3         scriptbase = params.SPHostUrl + "/_layouts/15/";
 4 
 5 
 6     // Load the js file and continue to the
 7     //   success event handler.
 8     $.getScript(scriptbase + "SP.RequestExecutor.js", execCrossDomainRequest);
 9 
10 
11     // Function to prepare and issue the request to get
12     //  SharePoint data.
13     function execCrossDomainRequest() {
14         var executor = new SP.RequestExecutor(params.SPAppWebUrl);
15 
16         // Issue the call against the host web.
17         // To get the title using REST we can hit the endpoint:
18         //      app_web_url/_api/SP.AppContextSite(@target)/web/title?@target='siteUrl'
19         // The response formats the data in the JSON format.
20         // The functions successHandler and errorHandler attend the
21         //      success and error events respectively.
22         executor.executeAsync(
23             {
24                 url:
25                     params.SPAppWebUrl +
26                     "/_api/SP.AppContextSite(@target)/web?$expand=CurrentUser&@target='" +
27                     params.SPHostUrl + "'",
28                 method: "GET",
29                 headers: { "Accept": "application/json; odata=verbose" },
30                 success: successHandler,
31                 error: errorHandler
32             }
33         );
34     }
35 
36     // Function to handle the success event.
37     // Prints the host web's title to the page.
38     function successHandler(data) {
39         var jsonObject = JSON.parse(data.body);
40         $('#message').html(jsonObject.d.CurrentUser.Title  +
41                     '<br/>host web: <b>' + jsonObject.d.Title + '</b>');
42     }
43 
44     // Function to handle the error event.
45     // Prints the error message to the page.
46     function errorHandler(data, errorCode, errorMessage) {
47         $('#message').html("Could not complete cross-domain call: " + errorMessage);
48     }
49 
50 
51     // Returning the params object
52     function getParams() {
53         var params = {};
54         location.search.split('?')[1].split('&').forEach(function (param) {
55             var key = param.split('=')[0],
56                 val = decodeURIComponent(param.split('=')[1]);
57             params[key] = val;
58         });
59         return params;
60     }
61 
62 })();

After all that hard work here’s the Punchline:

Running the example right away won’t work!

The reason is that we missed the most important configuration part for SP 2013 apps. Whenever your app requires acccessing information in the host web you have to configure the appropriate permissions. In addition whenever a site admin installs an app, they have to decide if they trust your app or not.

It will be interesting to see how this new concept (new to SharePoint, you’re probably familiar with it from mobile apps) will pay off in the real world.

For Napa apps there’s just one additional step required as developer, so let’s walk trough that process quickly.

Step 1 As a developer you have to explicitly ask for permission for your app Step 2 As site admin you have to trust the app Step 3 Finally the desired result: No chrome, user name and (Host)web title.

That’s it for today and I’m leaving you with this example, which -while visually not as impressive as the first version- under the hood is clean as hell and hopefully well understood ;-). Take it a starting point for your own Napa apps and let me know how it goes.

One question though: How do you feel about SP apps and the SP marketplace in general? Are you already sold (can’t wait for it to open, so that you can get rich) or do you have some concerns compared to traditional farm or sandbox solutions?

The Ferrari meets JayData

2012-08-01T00:00:00-07:00

Good morning, good afternoon, good evening to you.

Welcome back to a new episode in the Ferrari series. For those of you who remember what I call the Ferrari read on; all other please make yourself familiar with Part 1 and Part 2 in this series before moving on.

In Part 2 we ended up with a HTML5 app that shows a nice metro style tile view of SharePoint lists and libraries. This time we want to enhance the solutions so that it retrieves items through SharePoint’s OData service. Sorry SP2007 we’ve to leave you behind as this service was first introduced in SP2010. Don’t worry too much though; using REST is forward thinking as SP2013 will expose a whole new REST API that will greatly expanding the existing capabilities.

In the simplest form you could make XHR calls to the service endpoint at _vti_bin/listdata.svc, but we’re not going down that route. Instead we’re using JayData for doing the heavy lifting. While being relatively new to the market JayData brings an astonishing range of capabilities to the table, one of them is the abstracting of underlying storage provider. Yes, you heard me right; OData is just one of the supported storage provider, see JayData provider for a full list. Once you learned a little bit about JSLQ the JavaScript Query Language you will (probably) never go back talking to any storage provider on your own.

After settling on JayData the next choice is about a client framework that helps us building our dynamic UI. JayData comes with a bunch of modules that offers integration into various third party frameworks and knockout is one of them. A word of warning take everything that you see me doing with knockout with some grain of salt, as I haven’t worked with it before. The last piece of software that I want to bring to the table is of course RequireJS. We are going to build a JavaScript app and based on my experience there’s simply no way of writing one without it.

So without further hassle we are now going to build a pretty straight forward three tier navigation, which BTW will align us nicely with the Metro-style design guides; and nah, we won’t do Metro style left <-> right scrolling, this is still a web app not Window 8 Metro ;-). For the eager of you here are the links to the live demos:

Live on SP 2010

Live on SP 2013

First tier: Entry screen consists of a Tile View (green) and a Login View (yellow). The whole page can be served anonymously, but in order to see the next tier you’ve to log on. You probably heard me saying that before “SharePoint OData service won’t work anonymously”.

The following HTML is used as by Knockout to produce the Tile View.

 1 <div class="row" id="tileVM">
 2     <div class="twelve columns tiles"
 3          data-bind="foreach: TileData, updateTilesOnce: true">
 4         <div class="live-tile" data-stops="100%" data-speed="750" data-delay="-1"
 5              data-bind="class: color + ' ' + size,
 6                         attr: {'data-mode': mode ? mode : '', 'data-direction': direction} ,
 7                         click: $root.goToDetail">
 8             <span class="tile-title" data-bind="text: title"></span>
 9             <span class="badge" data-bind="text: count"></span>
10 
11             <div>
12                 <img class="micon" data-bind="attr: {src: icon}"/>
13             </div>
14             <div>
15                 <h3 data-bind="text: backTitle"></h3>
16                 <span class="prettyDate" data-bind="attr: {title: prettyDate}"></span>
17             </div>
18         </div>
19     </div>
20 </div>

And here’s the TileViewModel as RequireJS module leveraging the revealing module pattern. I’ve seen John Papa mentioning this pattern more than once. BTW feel free to provide feedback about your favorite way to structure knockout apps.

 1 define (['knockout', 'helper'], function ( ko, fn ) {
 2     "use strict";
 3 
 4     return function () {
 5         // ko observables
 6         var userId = ko.observable ().subscribeTo ('userId'),
 7             selectedList = ko.observable ().subscribeTo ('selectedList'),
 8             TileData = ko.observableArray ([]),
 9         // functions
10             goToDetail;
11 
12         // end of var declaration
13 
14         goToDetail = function ( tile, event ) {
15             if ( userId () !== 'anonymous' ) {
16 
17                 selectedList (fn.cleanup (tile.title));
18                 location.hash = '/view/' + selectedList ();
19             }
20             else {
21                 alert (' Make sure to log on.');
22             }
23         };
24 
25         // Bootstrap
26         TileData (app.tilesData.tiles.tile);
27 
28 
29         // Return public methods
30         return{
31             userId : userId,
32             TileData : TileData,
33             goToDetail : goToDetail
34         };
35     };
36 });

Our trusted DVWP produces the required app.tilesData.tiles.tile array that is used to bootstrap the TileData observableArray. I’m not going to cover the required XSLT here as this is just a variation what we did in Part 2, but if you want to deep dive again take a look at this gist DVWP’s settings and XSLT.

Here’s the HTML for the login area and the related LogonViewModel.

 1  <div id="logonVM">
 2     <div data-bind="visible: userId() !== 'anonymous' " style="display: none;">
 3         You're logged on as: <span class="success label" data-bind="text: userId"></span>
 4     </div>
 5     <div data-bind="visible: userId() === 'anonymous' " style="display: none;">
 6         <a href="#" data-bind="attr: {href: loginURL}" class="button"> Sign
 7             in</a>
 8         with username: <span class="secondary label">ODataDemo</span> password: <span class="secondary label">OData!Demo</span>
 9     </div>
10 </div>

 1 define (['knockout'], function ( ko ) {
 2     "use strict";
 3 
 4     return function () {
 5         var userId = ko.observable (app.configMap.userId).publishOn ('userId'),
 6             loginURL;
 7 
 8         loginURL = ko.computed (function () {
 9             return '../_layouts/Authenticate.aspx?Source=' + encodeURIComponent (location.pathname) + location.hash;
10         });
11 
12         // Return public methods
13         return {
14             userId : userId,
15             loginURL : loginURL
16         }
17     }
18 });

Second tier: The Login View (yellow) will show your username once you’re logged in and by clicking on one of the tiles you’ll see 10 items of the chosen list or library. Bear in mind that this is a demo, but adding paging, sorting and filtering per data source in the UI would be a pretty straight forward as they are already implemented in the ListingViewModel.

Third tier: By clicking on one of the level 2 tiles you’ll see the full detail information on the right. One of the benefits of working with OData is that is allows you to get multiple related information in single call, which greatly simplifies your life as client side app developer.

From the OData website

A URI with a $expand System Query Option indicates that Entries associated with the Entry or Collection of Entries identified by the Resource Path section of the URI must be represented inline (i.e. eagerly loaded). For example, if you want to identify a category and its products, you could use two URIs (and execute two requests), one for /Categories(1) and one for /Categories(1)/Products. The ‘$expand’ option allows you to identify related Entries with a single URI such that a graph of Entries could be retrieved with a single HTTP request.

For this demo I haven’t separated the Listing and the Detail view and the Detail view is just an un-styled list of properties for the current item. For a larger application it would probably make sense to separate the views and work the detail view a little bit out ;-).

To see the full html and JS that is involved take a look at this gist, I’m going to concentrate on the parts that deal with the JayData configuration here.

But before we can do that, we need to take quick look how all the various VMs are integrated by RequireJS. As in almost every standard RequireJS app there’s a main.js file that allows you to configure various aspects and then kick off your app.

 1 require.config({
 2    //By default load any module IDs from js/lib
 3     baseUrl : 'libs',
 4     paths : {
 5        // Try loading from CDN first
 6        ...
 7 
 8 require(['app'], function (app) {
 9     // we can safely kick of the app even before document.ready
10     app.init();
11 });

Within app.js we define dependencies on the various VMs that you’ve seen earlier and within the init method we use ko.applyBindings() to bind them to the corresponding element in the DOM. As said I’m new to knockout, so I leave it to the experts if that’s a recommend pattern or not. At least it’s working, so it can’t be totally wrong ;-). Path.js is used as a light alternative to sammy.js in order to setup some URL rules. As you can see Ryan Niemeyer’s excellent postbox -a native ko pubsub sytem- is used to notify subscribers whenever changes occur.

 1 define (['jquery', 'knockout', 'LogonVM', 'TileVM', 'ListingVM', 'postbox', 'path', 'appData', 'kocBH' ],
 2     function ( $, ko, LogonVM, TileVM, ListingVM, postbox ) {
 3         "use strict";
 4 
 5         var init = function () {
 6 
 7             // Exposing ko as global
 8             window.ko = window.ko || ko;
 9             var $tileContainer = $ ('#tileVM');
10 
11             // Configuring JayData to use current site's Odata service
12             app.context = new app.MetroStyleDataContext ({ name : 'oData', oDataServiceHost : '../_vti_bin/listdata.svc' });
13 
14             // binding ko to the appropriate container
15             ko.applyBindings (new TileVM (), document.getElementById ('tileVM'));
16             ko.applyBindings (new LogonVM (), document.getElementById ('logonVM'));
17             ko.applyBindings (new ListingVM (), document.getElementById ('listingVM'));
18 
19             // Client-side routes. Path exposed as global via shim configuration
20             function toggleTiles() {
21                 var isVisible = $tileContainer.css ('display') === 'block';
22                 isVisible ? $tileContainer.slideUp (300) : $tileContainer.slideDown (300);
23             }
24 
25             Path.map ("#/view/:list").to (function () {
26                 postbox.publish ('selectedList', this.params.list);
27             }).enter (toggleTiles);
28 
29             Path.map ("(#)").to (function () {
30                 postbox.publish ('selectedList', '');
31             }).enter (toggleTiles);
32 
33             Path.listen ();
34         };
35 
36         return {
37             init : init
38         }
39 
40     });

Boy, Rainer! All those talk about RequireJS and knockout basics. I’m already familiar with it, so where’s the beef? You promised to tell us about JayData, didn’t you?

Yes I did and here you go.

Part 1: Retrieving ListingView date via OData service.

 1  postbox.subscribe ("selectedList", function ( newValue ) {
 2     if ( app.configMap.userId === 'anonymous' ) {
 3         return alert ('Make sure to log on.');
 4     }
 5     if ( newValue !== '' ) {
 6         // Clean out existing itemDetail
 7         itemDetail ([]);
 8         var base = app.context[newValue],
 9             myBase = _.extend ({}, base),
10             sortExp = 'it.' + orderBy ();
11 
12         if ( orderAsc () ) {
13             _.extend (myBase, myBase.orderBy (sortExp));
14         }
15         else {
16             _.extend (myBase, myBase.orderByDescending (sortExp));
17         }
18         _.each (includeArray (), function ( inc ) {
19             _.extend (myBase, myBase.include (inc));
20         });
21         myBase.map (chooseMap (newValue))
22             .take (take ())
23             .toArray (allItems);
24     }
25     else {
26         // Clean out existing allItems
27         allItems ([]);
28         // Clean out existing itemDetail
29         itemDetail ([]);
30     }
31 });

Within ListingViewModel.js you find the above postbox.subscriber that listen to any change in the selectedList channel. After checking if there’s a non empty value and that the user is already logged in JayData takes over.

app.context knows about all lists and libraries, so here we use base to select a specific one var base = app.context[newValue]
orderBy() or orderByDescending() are using the default sorting criteria . This can be modified during runtime by updating the OrderAsc and OrderBy observables.
include() in OData terms maps to the OData $expand verb. Default settings here are CreatedBy and ModifiedBy. There’s a includeArray() observabelArray that is used to store the ones you’re interested in.
map() mapping or projection is another important feature that allows you to select specific fields instead of retrieving all information. The chooseMap() method is used to retrieve a small set of fields based on their availability e.g. Title vs. Name vs URL.
take() allows you to restrict the number of items returned by the system. Again a observable is used to store the default.
toArray() and finally this method is used to update the allItems observableArray. For those of you that are curious how that works under the cover, take a look at the following blog post.

Part 2: Retrieving the Detail View data for a selected item.

 1  showDetails = function (currItem) {
 2     var currentList = selectedList();
 3 
 4     app.context[currentList]
 5         .single(function (item) {
 6             return item.Id == this.Id
 7         },
 8         {Id : currItem.Id},
 9         function (item) {
10             var keyValue = [];
11             _.each(item.toJSON(), function (val, key) {
12                 keyValue.push({"key" : key, "val" : val});
13             });
14             itemDetail([]);
15             ko.utils.arrayPushAll(itemDetail(), keyValue);
16             itemDetail.valueHasMutated();
17         });
18 };

Come on, that’s almost too easy isn’t it? This time we’re using JSLQ`s .single method to retrieve ONE item based on a unique criteria, here the currItem.Id. Whenever the system returns the information it’s converted to JSON. Underscore’s each method allows us to push the returned key/value pairs into the keyValue array. Whenever done we use ko.utils.arrayPushAll to update the itemDetails() observable and valueHasMutated() to notify it about the changes.

As you can see, we haven’t dealt a bit with the native OData protocol and when you take a look at what’s going over the wire you’ll be surprised how complex it can get. But luckily that is of no concern for us any longer as we only have to deal with JSLQ.

That’s it for today, but before you ask I wanna cover two questions that I feel coming up:

Would you choose JayData for another project?

That’s a clear YES. JayData is something that’s better than sliced bread. Luckily it’s already invented.

Would you choose knockout for another project?

Yes… most likely. After reading some of the stuff over at the knockout site itself, but more important over at Ryan Niemeyer’s blog, I found it pretty straight forward to work with. By being the only overall framework that JayData supports as module at the moment, it’s the natural choice for the time being. With that said, there are already Sencha and Titanium modules out there, so maybe there’s a JayData backbone module one day… at that point feel free to ask me that question again.

One last thing, you can find the code for the 2010 demo site on github. You have to update the appdata.js in order to work in your environment. Checkout this post that guides you through the required steps with JaySvcUtil.

The SharePoint DVWP in Ferrari mode strikes again

2012-07-20T00:00:00-07:00

In the last post we dissected the SharePoint DVWP up till the point where it delivered clean HTML5. If you remember I call this mode the Ferrari. Now the bad news: For those who like to cut things down to the bare bones, that’s it. You can’t dissect the DVWP any further.

Now the good news: For those who think that this would be great starting point to build something new, read on. In this post I’m going to show you my way of driving the Ferrari. Of course this is not the only way, so feel free to do something completely different… and give me your success stories.

First let’s ask ourselves some question:

What are we going to build?
Which technologies are we going to use?
How to effectively use our Ferrari in that scenario?

Answer to Q1: Let’s build a new version of the Metro style menu web part, that was initially build by Peter Collins. Hey Rainer, why would you do that? It’s already build, isn’t it? Yeah, you’re right, but we are going to add some visual effects and some configuration options to the picture, which wasn’t in the first version. Simply think of our version as V2.0.

Answer to Q2: A Ferrari needs to be driven in adequate places like the Nürburgring in Germany, so let’s try to find a technology stack that can cope with that ideal ;-).

Technologies:

Accessing SharePoint data: DVWP in ferrari mode
Providing a modern HTML5/CSS3/JavaScript Framework Zurb Foundation 3
Metro styled live tiles by Drew Greenwell MetroJS
Alternative for SergoiUI (the metro font) Open Sans Condensed
Metro like icons by IconShock Free Metro Icons

The reasoning behind each selection is simple: I like them. I know that there are alternatives at each level, but as said earlier it’s your decision entirely… when you build your solution. Now without further hesitation lets present two screenshots of the live demo. Thanks to some feedback I got on twitter from Marc D Anderson the second screenshot shows an optimized version for iPhones.

Source, Live

I encourage you to take a look at the live version first to see the live tiles in action. All kudos to Drew Greenwell’s MetroJS project.

Now let’s dive a little deeper into the code by looking at the Source. As you can see it’s almost the same minimal HTML5 that was introduced last time, enhanced by the files required by Zurb Foundation 3 and MetroJS.

Somewhere in the middle you see this div <div id="metroTiles">...</div>, where the DVWP is instantiated. If you are looking very closely, you spot some differences from where we left it last time. This time the web part properties are stripped down to the bare minimum and by using <XslLink>XSLT/ListsAsTiles.xslt</XslLink> we are allowed to store the XSLT in an external file. As in the Peter Collin’s version the DataSourceMode is set to ListOfLists in which the server returns information about all lists/libraries of the current site.

 1     <div id="metroTiles" class="twelve columns tiles">
 2         <!-- DVWP with DataSourceMode="ListOfLists" -->
 3         <WebPartPages:DataFormWebPart runat="server" AsyncRefresh="False" FrameType="None" SuppressWebPartChrome="True">
 4             <ParameterBindings></ParameterBindings>
 5             <DataFields></DataFields>
 6             <XslLink>XSLT/ListsAsTiles.xslt</XslLink>
 7             <Xsl></Xsl>
 8             <DataSources>
 9                 <SharePoint:SPDataSource runat="server" DataSourceMode="ListOfLists" SelectCommand=""
10                                          ID="dsLists"></SharePoint:SPDataSource>
11             </DataSources>
12         </WebPartPages:DataFormWebPart>
13         <!-- DVWP with DataSourceMode="ListOfLists" -->
14     </div>

I’m not going to talk about the Zurb Foundation 3 specific configurations here (sass and compass based), but from my first impression I can say at least so much: ”It’s hot! Real hot!”. A quantum leap compared to other prominent HTML5 frameworks. Don’t take my word on it, check it out on your own and let me know what you think.

Answer to Q3: This one is pretty short: Know your XSLT.

Checkpoint: Up till now you should have a rough understanding how the various pieces of the solution fits together. While it’s certainly not rocket science it’s nothing for beginners either. But now we are coming to the heart of the solution. We have to fine tune the Ferrari, so that it can deliver its best performance. You asked for it, so here it is:

A word of warning: I don’t want to waste your time, so there’s no need to read on, if you most likely never work with XSLT at all.

XSLT deep dive

XSLT might not be everybody’s darling, but let’s face it, you can do a lot of smart things in SharePoint with it that otherwise would require either third party tools or custom .Net development.

You have access to the complete XSLT at github and I’m going to provide some background information about the various pieces below. Of course that code only reflects my coding style. If you pick up one or another XSLT trick that you find useful, good. If not, there’s certainly more than one way to skin a cat, so I’d glad to hear from you about you’re tackling things instead.

BTW before you ask: My favorite book ever on that topic is Jenni Tennison’s XSLT and XPath On the edge.

With that here’s what makes the Ferrari engine tick. After the usual <xsl:stylesheet ..> declaration we start by defining a $Rows variable. It’s used to filter out list/libaries that you don’t want to render e.g. like those with (@__spHidden = 'True' and …

1 <xsl:variable name="Rows" select="/dsQueryResponse/Rows/Row[not(@__spHidden = 'True') and not(contains
2 (@__spDefaultViewUrl, '_catalogs')) and @__spTitle != 'ServiceFiles']"/>

One goal for the solution was to make it configurable. One of the easiest way to accomplish that is by defining a variable and access it via msxsl:node-set($VariableName). Here I’m using the global element to store global configuration options and tiles to store configuration options based on the BaseTemplate e.g. Contacts, DocumentLibrary and so on. As you can see there are options for color and icon, which control the visual appearance, but also options like data-mode and data-direction that will be used by MetroJS to provide the slide and flip animations.

In a fully fledged solution you’d store those somewhere externally and then bring them in either via Linked Data source, cookies, querystrings etc.

 1 <!-- configMap allows configuration per BaseTemplate -->
 2 <xsl:variable name="configMap">
 3     <global>
 4         <maxTiles>12</maxTiles>
 5         <wideTiles>3</wideTiles>
 6         <backTileTitle>Last updated</backTileTitle>
 7     </global>
 8     <tiles>
 9         <item BaseTemplate="Contacts" color="lime" icon="images/48/bomb.png"/>
10         <item BaseTemplate="DocumentLibrary" color="teal" icon="images/48/file.png" data-mode="slide"
11               data-direction="vertical"/>
12         <item BaseTemplate="GenericList" color="green" icon="images/48/inventory2.png" data-mode="flip"
13               data-direction="vertical"/>
14         <item BaseTemplate="Tasks" color="red" icon="images/48/bomb.png" data-mode="flip"
15               data-direction="horizontal"/>
16         <item BaseTemplate="GanttTasks" color="purple" icon="images/48/hand_thumbsup.png"/>
17         <item BaseTemplate="IssueTracking" color="pink" icon="images/48/clipboard.png" data-mode="slide"
18               data-direction="vertical"/>
19         <item BaseTemplate="Links" color="lime" icon="images/48/link.png"/>
20         <item BaseTemplate="WebPageLibrary" color="brown" icon="images/48/clipboard.png"/>
21         <item BaseTemplate="Events" color="mango" icon="images/48/clipboard.png"/>
22         <item BaseTemplate="unknown" color="blue" icon="images/48/smiley_sad.png"/>
23     </tiles>
24 </xsl:variable>
25 
26 <!-- shortcuts to globalConfig and tilesConfig -->
27 <xsl:variable name="globalConfig" select="msxsl:node-set($configMap)/global"/>
28 <xsl:variable name="tilesConfig" select="msxsl:node-set($configMap)/tiles"/>

The next variable $itemInList stores a result set that it sorted descending by @__spItemCount. This in combination with $globalConfig/wideTiles will be used to show wide tiles based on the number of items in a given list or library e.g. $wideTiles = 3 would show the 3 lists with the most items as wide tile.

1 <!-- itemsInList sorted by @__spItemCount descending. Used to distinguish between normal and wide tiles  -->
2 <xsl:variable name="itemsInList">
3     <xsl:for-each select="$Rows">
4         <xsl:sort select="@__spItemCount" order="descending" data-type="number"/>
5         <item id="{@__spID}" count="{@__spItemCount}" pos="{position()}"/>
6     </xsl:for-each>
7 </xsl:variable>

The above variables are all globally defined, so they can be accessed throughout the code in every template. Next comes the root template and you can see that the result set is sorted by a heavy XPath expression. All we want to do here is having the lists/libraries sorted by the time they were last modified, but unfortunately the system buries the only reliable UTC date somewhere down in the @__spPropertiesXml attribute. I leave it up to you to digest this XPath and figure out what it’s exactly doing.

By checking <xsl:if test="position() <= $globalConfig/maxTiles"> before we call the Tile template we restrict the number of rendered tiles to whatever is configured, nothing fancy here.

 1 <xsl:template match="/">
 2     <xsl:for-each select="$Rows">
 3         <!-- This complex sort criteria is required because __spModified is localized. Using information inside __spPropertiesXml instead -->
 4         <xsl:sort
 5                 select="translate(substring-before(substring-after(@__spPropertiesXml, 'Modified=&quot;'), '&quot; LastDeleted'), ' :', '')"
 6                 order="descending" data-type="number"/>
 7         <xsl:if test="position() &lt;= $globalConfig/maxTiles">
 8             <xsl:call-template name="Tile"/>
 9         </xsl:if>
10     </xsl:for-each>
11 </xsl:template>

The Tile template is responsible for building up the tile html, but as you can see this is divided into multiple separate templates. I simply follow common sense here that mixing structure and logic will become unmaintainable very soon. So we build up a helper variable $t using the MetaData template (logic), which is passed to the TileTemplate (html). Think of this template as your dispenser: logic -> left, structure ->right.

 1 <xsl:template name="Tile">
 2     <!-- Mashup of $configMap and $ itemsInList for the current item -->
 3     <xsl:variable name="coreMetaData">
 4         <xsl:call-template name="MetaData">
 5             <xsl:with-param name="baseTemplate" select="@__spBaseTemplate"/>
 6             <xsl:with-param name="spID" select="@__spID"/>
 7             <xsl:with-param name="spPropertiesXml" select="@__spPropertiesXml"/>
 8         </xsl:call-template>
 9     </xsl:variable>
10     <!-- shortcut for accessing $coreMetaData -->
11     <xsl:variable name="t" select="msxsl:node-set($coreMetaData)"/>
12 
13     <xsl:call-template name="TileTemplate">
14         <xsl:with-param name="t" select="$t" />
15     </xsl:call-template>
16 </xsl:template>

Alright prime time; we are building the required html that represents one tile. We start by copying the tile html from the MetroJS page. There are multipe variable that you can access here.

$Rows attributes can be accessed directly e.g. <xsl:value-of select="@__spItemCount"/> or data-target="{@__spDefaultViewUrl}".
Meta data can be accessed through $t with the same ease as e.g. <div class="live-tile {$t/item/@color} {$t/size}" or <img src="{$t/item/@icon}" class="micon"/>.
You’ve access to everything that was globally defined like e.g $globalConfig.

 1 <xsl:template name="TileTemplate">
 2     <xsl:param name="t" />
 3     <div class="live-tile {$t/item/@color} {$t/size}"
 4          data-stops="100%"
 5          data-speed="750"
 6          data-delay="-1"
 7          data-mode="{$t/item/@data-mode}"
 8          data-direction="{$t/item/@data-direction}"
 9          data-target="{@__spDefaultViewUrl}"
10          data-baseTemplate="{@__spBaseTemplate}">
11         <span class="tile-title">
12             <xsl:value-of select="@__spTitle"/>
13             <span class="badge right">
14                 <xsl:value-of select="@__spItemCount"/>
15             </span>
16         </span>
17         <div>
18             <img src="{$t/item/@icon}" class="micon"/>
19         </div>
20         <div>
21             <h3>
22                <xsl:value-of select="$globalConfig/backTileTitle" />
23             </h3>
24             <span class="prettyDate" title="{$t/prettyDate}">
25                 <xsl:value-of select="$t/prettyDate"/>
26             </span>
27         </div>
28     </div>
29 </xsl:template>

The last template builds a mashup based on the current item’s $tilesConfig. Think of it as multiple tables that are joined by some common keys e.g. $tilesConfig/item[@BaseTemplate = $baseTemplate]. Here we use the @__spBaseTemplate attribute of the current Row, which was passed in as baseTemplate param as the join criteria for $tilesConfig/item/@BaseTemplate. If there’s a match we make a copy of the matched $tilesConfig/item if not we copy $tilesConfig/item[@BaseTemplate = 'unknown'] instead.

Everything that needs to be calculated like <size> and <prettyDate> goes in this template as well. If the logic for a given calculation would become to complex you should factor it out of course.

 1 <xsl:template name="MetaData">
 2     <xsl:param name="spID"/>
 3     <xsl:param name="baseTemplate"/>
 4     <xsl:param name="spPropertiesXml"/>
 5     <!-- accessible via $t/item/@XXXX. Available attributes see $configMap/tiles/item/@XXXX -->
 6     <xsl:choose>
 7         <xsl:when test="$tilesConfig/item[@BaseTemplate = $baseTemplate]">
 8             <xsl:copy-of select="$tilesConfig/item[@BaseTemplate = $baseTemplate]"/>
 9         </xsl:when>
10         <xsl:otherwise>
11             <xsl:copy-of select="$tilesConfig/item[@BaseTemplate = 'unknown']"/>
12         </xsl:otherwise>
13     </xsl:choose>
14     <!-- accessible via $t/size -->
15     <size>
16         <xsl:choose>
17             <xsl:when test="msxsl:node-set($itemsInList)/item[@id = $spID]/@pos &lt;= $globalConfig/wideTiles">
18                 <xsl:text>wide</xsl:text>
19             </xsl:when>
20             <xsl:otherwise/>
21         </xsl:choose>
22     </size>
23     <prettyDate>
24         <xsl:variable name="DateRaw"
25                       select="translate(substring-before(substring-after($spPropertiesXml, 'Modified=&quot;'), '&quot; LastDeleted'), ' ', 'T')"/>
26         <xsl:value-of
27                 select="concat(substring($DateRaw, 1, 4), '-', substring($DateRaw, 5, 2), '-', substring($DateRaw, 7,2), substring($DateRaw, 9), 'Z')"/>
28     </prettyDate>
29 </xsl:template>

That’s it, you made it. You’ve seen how to build a modern HTML5/CSS3/JavaScript solution in SharePoint 2007/2010/(2013?) using the good old DVWP. And you know that at its core it’s powered by 134 lines of XSLT.

As always feedback welcome and bye for now.

SharePoint DVWP: from workhorse to Ferrari in 7 steps

2012-07-15T00:00:00-07:00

This is going to be intense and this is going to be fun…, if you are willing to follow till the end. I’m going to take the good old Data Form Web Part, better known as DVWP, and turn the standard HTML, which is delivered by this reliable workhorse, in some highly optimized HTML5 code: I call it the Ferrari version.

But before we even start, here are some prerequisites:

you worked with the DVWP before
you’re familiar with XML/XSLT
you know who Marc D Anderson is and know his posts about the DVWP inside out
you are familiar with SharePoint Designer, but you are not afraid using a text editor. Notepad will do, but some kind of syntax checking and highlighting would be beneficial. Before you ask: I’m using WebStorm for overall web development and Altova XML Spy for complex XML/XSLT.

Let’s get started with something the DVWP was build for:

accessing data via a data source
(just to recap: Database, SOAP, REST, XML Files and Linked Data source are supported)
converting the data using XSLT
and finally display the result as part of a SharePoint page.

Go ahead and:

create a new site using the blank site template
create a document library called servicefiles that is used to store our pages
create a subfolder servicefiles/xml
and finally create a helloworld.xml file with the following content

1 <?xml version="1.0" encoding="utf-8" ?>
2 <root>
3 	<title>Hello World</title>
4 </root>

Nothing fancy so far, so let’s move on:

Let’s created a XML data source for this file
create a web part page called WebPartPage.aspx
Place a DVWP on it show us the standard content.

Checkpoint: As said, I assume that you know the DVWP inside out. But if not or you’d prefer not following along right now, don’t worry. Each of the steps below can be accessed online, so sit back, relax and enjoy the ride. If you wanna get your hands dirty later, you find the source code at github.

Ok, let’s move on. By default SPD uses some baked in XSLT to perform the XML/XSLT conversion, which is clearly not the best starting point for us, so let’s replace the xsl:stylesheet by our own.

1 <xsl:stylesheet version="1.0" exclude-result-prefixes="xsl msxsl ddwrt" xmlns:ddwrt="http://schemas.microsoft.com/WebParts/v2/DataView/runtime" xmlns:asp="http://schemas.microsoft.com/ASPNET/20" xmlns:__designer="http://schemas.microsoft.com/WebParts/v2/DataView/designer" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:SharePoint="Microsoft.SharePoint.WebControls" xmlns:ddwrt2="urn:frontpage:internal">
2     <xsl:output method="html" indent="no"/>
3     <xsl:template match="/" xmlns:asp="http://schemas.microsoft.com/ASPNET/20" xmlns:__designer="http://schemas.microsoft.com/WebParts/v2/DataView/designer" xmlns:SharePoint="Microsoft.SharePoint.WebControls">
4         <h1><xsl:value-of select="root/title" /></h1>
5     </xsl:template>
6 </xsl:stylesheet>

Assuming nothing went wrong, you should see something like this in your browser.

For your convenience you have access to the Source, see the rendered result Live and what’s more important you can see the HTML source of that page; and yes, right click on the rendered result, view source will work as well.

The size of HTML source will act as our baseline, and a quick look reveals that there are 772 lines of code, which includes our payload of <h1>Hello world</h1>. You can see that our payload is nicely integrated into a fully-fledged SharePoint theme. As said above this scenario is exactly, what the DVWP was built for.

Checkpoint In a series of small step-by-step modifications this starting point now undergoes optimization, with the goal of creating a slick HTML5 version that uses the same payload.

Ready?
3
2
1
go…

Step 1 Create an empty aspx page in the same folder (hint: right click is your friend) call it step_1.aspx and copy/paste the existing DVWP from WebPartPage.aspx into it.

Source, Live, HTML source

By placing the DVWP onto it’s own empty aspx page we a) removed almost all visible SharePoint chrome and b) reduced the HTML source size to 160 lines. Make a copy of the current page (step_1.aspx) and save as next page (step_2 .aspx); repeat the same process for the following steps.

Step 2 Getting rid of the Web part properties bar is straight forward and frankly could have been done in our original page as well. Simply open the web part properties and change the Chrome Type to none, which will bring us down to 154 lines.

Source, Live, HTML source

Step 3 After that easy passage in step 2 let’s get a little bit more aggressive by getting rid of the asp:ScriptManager tag. You can either delete it in the code view or in design view. If the latter, make sure that you’ve turned on Visual Aids otherwise you won’t see it.

You should test this modification immediately in the browser and you’ll see this error message.

Source, Live

How comes? The page looks still good in SPD, doesn’t it? Somehow the web part seems to have a dependency on the asp:ScriptManager that only shows up in the browser. Being at this point before, you remember that the ScriptManager is responsible for loading all kind of JavaScript files, some of them Async in nature. So by carefully exploring the DVWP settings, you come across the following AsyncRefresh=True property. Modifying this to AsyncRefresh=False will ensure that the error message goes away and brings the html down to 124 lines.

Source, Live, HTML source

Checkpoint Up till now we’ve used SPD to make modifications, but from this point on SPD is no longer your best friend for dealing with the DVWP. This is not the fault of SPD though; we are simply driving the DVWP behind the point that’s supported inside SPD. Therefore I’d suggest that you now grab your favorite XML/XSLT HTML editor and make further modifications directly in the source code.

One additional warning By making modifications beyond this point, you will no longer be able to save your site as a site template and create new sites from it, at least not reliable. Most of the time this is not an issue, remember we are going to build a Ferrari and you probably just need one not thousands ;-). But if there’s ever a need to move your Ferrari around, you can still manually copy the aspx pages or turn them into a Visual studio feature.

Step 4 Looking at the source code of the result in step 3 will immediately trigger our attention to the next optimization target. There is that huge input that hosts the viewstate. All nice and well if you are doing server side stuff, but we don’t want that, so simply remove the <form ...>and </forms> tags in the source.

Yeah, I know that might sound a little bit drastic, but give it a try before you judge; and you’ll be rewarded by seeing the HTML source cutting down to 51 lines.

Source, Live, HTML source

Step 5 Let’s see if we can still use some SharePoint controls at the server side after our drastic step 4; and in addition let’s cleanup the current header.

change the static title to a dynamic one (see below)
update the doctype <!DOCTYPE html> and <html> tag
remove existing <style> tag

1 <title><SharePoint:ListItemProperty Property="BaseName" maxlength="40" runat="server"/></title>`

As you can see below the <title> information is correctly showing the current’s page name; and by cleaning up we are down to 20 lines.

Source, Live, HTML source

Step 6 Now have a look at the HTML5 source after all the optimization. Not too bad I’d say, but still there’s room for improvement. See the highlighted namespaces in the payload. This will be our next target.

Truth told, we might have tackled those namespaces earlier, but now that our HTML becomes smaller, it is far easier to spot that they are not required.

This one is pretty straight forward, just modify the XSLT slightly. Here’s the reformatted version that defines all exclude-result-prefixes correctly and removes the namespaces in <xsl:template match="/".

 1 <xsl:stylesheet version="1.0"
 2 exclude-result-prefixes="ddwrt asp __designer xsl msxsl SharePoint ddwrt2"
 3 xmlns:ddwrt="http://schemas.microsoft.com/WebParts/v2/DataView/runtime"
 4 xmlns:asp="http://schemas.microsoft.com/ASPNET/20"
 5 xmlns:__designer="http://schemas.microsoft.com/WebParts/v2/DataView/designer"
 6 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 7 xmlns:msxsl="urn:schemas-microsoft-com:xslt"
 8 xmlns:SharePoint="Microsoft.SharePoint.WebControls"
 9 xmlns:ddwrt2="urn:frontpage:internal">
10     <xsl:output method="html" indent="no"/>
11     <xsl:template match="/">
12         <h1><xsl:value-of select="root/title" /></h1>
13     </xsl:template>
14 </xsl:stylesheet>

Source, Live, HTML source

Step 7 Not much room for optimization left, correct? But there’s one thing that annoys me most, when looking at the current state of things. Take a look at our XSLT stylesheet above, there’s clearly NO <table class"....></table> in there, this code is injected by the DVWP instead.

The not that well known property SuppressWebPartChrome (see MSDN) will help us getting rid of this extra WebPartChrome. Please note that this only works if the DVWP lives outside a web part zone, so you can’t use this for standard implemenations like our initial WebPartPage.aspx.

You reach the finishing line by adding SuppressWebPartChrome="True" to the web part properties, which brings us to

16 lines of clean HTML5 code or The Ferrari version

Source, Live, HTML source

Boy, that was probably just another TL;DR, but if you made it till here, you might have picked up one or two things about the DVWP that you’d consider ‘Good to know’.

I’d be glad to hear from you about the experiences you make, while testing this out.

BTW if you are looking for inspiration, where to go from here, take a look at this Metro demo, which is a HTML5 client app that was build using two DVWPs…, but’s that’s worth another story, so stay tuned!

Live

Metro JavaScript App - strongly typed?

2012-07-13T00:00:00-07:00

Let’s face it, even when I choose to build Metro style apps with HTML5, JavaScript and CSS because I love the dynamic nature of this environment, there are times when I’m a little bit jealous of that strong typed stuff that you get in that boring C#/XAML world ;-).

Let see if we can take an existing application like Jeremy Foster’s excellent A Metro Netflix browser in HTML/JS - The Hub page, add some magic (JayData) to it and see if that helps reducing my jealousy .

Start by downloading Jeremy’s code that is attached to the blog. While on it don’t miss to download and install Fiddler 4 and the Windows 8 AppContainer Loopback Utility.

Simply follow the Jeremy’s instructions, fire up fiddler and run the code.

Checkpoint: Make sure that you see some titles coming back from Netflix.

Looking at fiddler you should see something like the above. Notice the response size of about 740K. At the moment we are not leveraging OData to its full extend. I know that if you’re an OData expert you already spoted a way to reduce the response by using server side projection. But wait, maybe there are others that aren’t experts yet, so we come back to this a little later.

Next download the latest version of JayData and JaySvcUtil from the download area. Extract both files into two separate directories, we don’t want all of them lingering around in our projcect directory, we cherry pick instead the bare minimum.

So from the JayData directory add the following files into the project’s js directory

JayData-vsdoc.js
JayData.js
datajs-1.0.2.js

Open up your preferred command line and navigate to the JaySvcUtil directory. JaySvcUtil.exe is command line utility that allows converting OData $metada information into a strongly typed JavaScript object. While it has several switches for fine tuning, we only require three of them.

-m $metadata url of your service e.g http://odata.netflix.com/catalog/$metadata
-n Namespace e.g. here Netflix
-o output file e.g. Netflix.js

Rainer@METRORP ~/Downloads/JaySvcUtil
$ JaySvcUtil.exe -m 'http://odata.netflix.com/catalog/$metadata' -o Netflix.js -n 'Netflix'

If everything went smoothly the system should have generated your ‘Netflix.js’ file. Depending on the complexity of your service you might receive a couple of warning messages, which - most of the time - can safely be ignored. Please add the newly created ‘YourOutputFile.js’ to the project’s js directory as well.

Your default.html should now look like this:

 1 <!DOCTYPE html>
 2 <html>
 3 <head>
 4     <meta charset="utf-8" />
 5     <title>NetflixBrowser</title>
 6 
 7     <!-- WinJS references -->
 8     <link href="//Microsoft.WinJS.1.0.RC/css/ui-dark.css" rel="stylesheet" />
 9     <script src="//Microsoft.WinJS.1.0.RC/js/base.js"></script>
10     <script src="//Microsoft.WinJS.1.0.RC/js/ui.js"></script>
11 
12     <!-- NetflixBrowser references -->
13     <link href="/css/default.css" rel="stylesheet" />
14     <script src="/js/default.js"></script>
15     <script src="/js/navigator.js"></script>
16 
17     <!-- JayData references -->
18     <script src="/js/datajs-1.0.2.js"></script>
19     <script src="/js/JayData.js"></script>
20     <script src="/js/netflix.js"></script>
21 
22 </head>
23 <body>
24     <div id="contenthost" data-win-control="Application.PageControlNavigator" data-win-options="{home: '/pages/home/home.html'}"></div>
25     <!-- <div id="appbar" data-win-control="WinJS.UI.AppBar">
26         <button data-win-control="WinJS.UI.AppBarCommand" data-win-options="{id:'cmd', label:'Command', icon:'placeholder'}"></button>
27     </div> -->
28 </body>
29 </html>

Checkpoint: Run the app just to see if all files can be loaded and no error occurs.

While doing that in my case Visual studio was complaining about some errors in Netflix.js and right so. You can see that there are a couple of mistyped ..., params : , ... in the code begining at line 166. If that the case for you as well go ahead and remove them. Not quite sure if that’s Netflix or an JayData issue, but it’s reported to JayData.

Alright almost done with the setup phase. Let’s open up js/home.js and

get rid of the current WinJS.xhr call
add some references to the JayData files to get Intellisense support.

You’re home.js should look like below. Remember that you need to compile once to get Intellisense picking up the changes.

 1 /// <reference path="/js/jaydata.js" />
 2 /// <reference path="/js/jaydata-vsdoc.js" />
 3 /// <reference path="/js/netflix.js" />
 4 (function () {
 5  "use strict";
 6 
 7  WinJS.UI.Pages.define("/pages/home/home.html", {
 8      // This function is called whenever a user navigates to this page. It
 9      // populates the page elements with the app's data.
10      ready: function (element, options) {
11 
12          var titlesListGrouped = new WinJS.Binding.List().createGrouped(
13              function (i) { return i.title.charAt(0).toUpperCase(); },
14              function (i) { return { firstLetter: i.title.charAt(0).toUpperCase() }; }
15          );
16 
17          var list = q("#list").winControl;
18          list.itemDataSource = titlesListGrouped.dataSource;
19          list.itemTemplate = q("#template");
20          list.groupDataSource = titlesListGrouped.groups.dataSource;
21          list.groupHeaderTemplate = q("#headertemplate");
22 
23      }
24  });
25 })();

Now, roll drum… here’s the magic moment :), type in Netflix.context. and you should see Intellisene kicking in. Before we move on let’s celebrate by leaving the computer and doing whatever you prefer to do when you celebrate.

Alright, back to work! Your first goal would be to come up with an equivalent of the original WinJS.xhr call

 1 WinJS.xhr({ url: "http://odata.netflix.com/Catalog/Titles?$format=json&$top=200" })
 2     .then(function (xhr) {
 3         var titles = JSON.parse(xhr.response).d;
 4         titles.forEach(function (i) {
 5             titlesListGrouped.push({
 6                 title: i.ShortName,
 7                 imageUrl: i.BoxArt.LargeUrl
 8             });
 9         });
10     });

Converting this is pretty straight forward. Netflix.context is already aware of the URL and JayData will add the appropriate Request-Header, so that the Odata service returns Json. That leaves us with teaching the system that we would like to retrieve 200 Titles. By looking at the available methods for Netflix.context.Titles we notice the take()method, which probably sounds familiar to many of you. There are several other methods like include(), filter(), orderBy(), skip(), map() and forEach that are all part of the JavaScript Language Query. If you never heard of any of those or want to learn more about it check them out at (JSLQ) 101 and come back later.

The last thing we need to do is reusing the logic of the original forEach loop to push the results into titlesListGrouped.

1 Netflix.context.Titles
2     .take(200)
3     .forEach(function(item) {
4         titlesListGrouped.push({
5             title: item.title,
6             imageUrl: item.BoxArt.LargeUrl
7         });
8     })

Please note that at the time of this writing, while there is an JayData deferred.js adapter available for jQuery there’s NO WinJS aware adapter… yet. So at the moment you won’t be able to create promises and use .then() or .done().

Checkpoint: Run the code and make sure that you still see titles coming back from Netflix. Alright how does that feel so far? Without being an OData expert you just conducted an OData query, without leaving the comfort zone of Visual Studio and its Intellisene. Not too shabby I’d say. But we’ll take it even a step further and try making our OData request a little bit more precise.

Can we do that? Of course we can by leveraging the .map method; and you’ll see, which benefits that brings in just a moment. Please note that I couldn’t bring Intellisense to show available properties for item, but when you look at the Json returned by the service in Fiddler, you can see that we map title: item.ShortName and BoxArt: item.BoxArt and return that as an anonymous object. So in the forEach loop we access those as item.title and item.BoxArt.

 1 Netflix.context.Titles
 2     .map(function(item) {
 3         return {
 4             title: item.ShortName,
 5             BoxArt: item.BoxArt
 6         };
 7     })
 8     .take(200)
 9     .forEach(function(item) {
10         titlesListGrouped.push({
11             title: item.title,
12             imageUrl: item.BoxArt.LargeUrl
13         });
14     })

If you are now running the application and watch Fiddler you see that the return set is way smaller than before. We are down from 740K to about 140K. So by using the strongly typed Netflix object you not only gained the benefit of Intellisense support, you somehow became an OData expert as well ;-). Closer watching the URL in Fiddler reveals that there’s a new $select=ShortName,BoxArt parameter that was added by JayData, so now the projection is accomplished at the server side and no longer at the client.

That’s it for today and truth told I feel my jealousy about strongly typed C#/XAML fading away and my excitement about JavaScript grow. But everybody’s different, so here are two choices if you want to move on with Jeremy’s Metro app:

You can get rid of all JayData files you’ve added and apply the knowledge about the $select parameter to enhance the original WinJS code manually. You will see the same performance benefits that we got here.

Just so that you know, there’s nothing wrong with this approach, really.
But maybe you want to stay a little with JayData and see how it pays off.

For those of you, who are on the fence line, it might be good to know that JayData supports a couple of other formats that can be all accessed using the same JSQL you started getting familiar with.

Facebook Query Language, SqlLite, Yahoo Open Data Tables, InMemoryDB, WebSQL, IndexedDb

and there are more in the pipeline

I’d be glad to hear from you about your decission and the reasoning behind it.

PS: For the impatient ones that wants to start immediately with JayData version of Jeremy’s Metro example feel free to clone this repo.

Dynamic search in a static world

2012-07-09T00:00:00-07:00

While adding search to a new blog might not be the most important thing to do, it gave me perfect excuse to work a little with Jekyll liquid and AngularJS. There was no need to reinvent the wheel as Edward Hotchkiss already implemented something pretty similiar. Therefore here are just the major differences, I expect that you’re familiar with Edward’s post, if not please read it first. The implementation is based on AngularJS v1.0.1 and by using a small liquid condition scripts are only loaded on the search page.

Here’s the relevant excerpt from default.html.

1 {% if page.title == 'Search' %}
2     <script type="text/javascript" src="http://code.angularjs.org/angular-1.0.1.min.js"></script>
3     <script type="text/javascript" src="/js/JekyllApp.js"></script>
4 {% endif %}

Edward Hotchkiss is making an XHR call to retrieve the RSS-feed feed.xml and then parses the xml. This is a pretty straight forward implementation, but I wanted to omit this extra XHR call and ‘bootstrap’ the information into the initial page. Therefore a liquid helper is used to create an JavaScript array with the relevant post information. This has the additional advantage that you can leverage liquid filter like strip_html | truncate : 120 (on the server side!) to clean up and cut down potentially large information.

One goal was to having a search box on every page. The Controller was enhanced so that the $scope .searchText = '' can now be passed in via querystring as well.

BTW: You can give it a try on all blog pages, to see it in action.

 1 /**
 2  * Setup Module with `highlight` filter
 3  */
 4 
 5 var JekyllApp = angular.module('JekyllApp', [], function ($routeProvider, $locationProvider) {
 6     $locationProvider.html5Mode(false);
 7 });
 8 
 9 JekyllApp.filter('highlight', function () {
10     return function (text, filter) {
11         if (filter === '') {
12             return text;
13         }
14         else {
15             return text.replace(new RegExp(filter, 'gi'), '<span class="match">$&</span>');
16         }
17     };
18 });
19 
20 /**
21  * Inject required $objects into our Controller
22  */
23 
24 JekyllSearchController.$inject = ['$scope', '$location', '$window'];
25 
26 function JekyllSearchController($scope, $location, $window) {
27     // Optionally passing in a search term via q=XXX
28     // $location.search won't work without html5Mode false using window.location.search instead
29     // $scope.searchText =  $location.search().q || "";
30     // Todo: Consider switching back to $location.search once it supports html5Mode false
31     $scope.searchText = '';
32     var search = window.location.search;
33     if (search.indexOf('?q=') > -1 || search.indexOf('&q=') > -1) {
34         var params = {};
35         angular.forEach(search.split('?')[1].split('&'), function (param) {
36             params[param.split('=')[0]] = param.split('=')[1];
37         });
38         $scope.searchText = params.q || '';
39     }
40 
41     $scope.externalLink = function () {
42         // Todo: Figure out the correct AngularJS way for a page reload on href click
43         // https://github.com/angular/angular.js/issues/1102
44         $window.location.href = this.post.url;
45     };
46     $scope.posts = JekyllApp.posts;
47 }

There are a couple of things that I didn’t grasp fully at the moment I’ve to admit, like

why $location.search() only works with $locationProvider.html5mode(true) or
why AngularJS doesn’t have an easy (to discover) method that allows a full page reload on href click

so I’d be happy if somebody could fill the gaps. In the meantime workarounds are used, so querystring q is determined in a good old fashioned way and there’s a thread on the angular groups that discusses page reload.

 1 <script type="text/javascript">
 2    // Using liquid to populate JeykllApp.posts array
 3    JekyllApp.posts = {% include Helper/JekyllAppPosts %}
 4 </script>
 5 
 6 <div id="search-container" class="entrance" ng-app="JekyllApp" ng-controller="JekyllSearchController">
 7   <div class="entrance-item">
 8     <p><input id="searchText" type="search" placeholder="Live Search Posts..." ng-model-instant ng-model="searchText" />
 9   </div>
10   <div class="entrance-item">
11     <ul>
12       <li ng-repeat="post in posts | filter:searchText">
13          <span ng-bind-html-unsafe="post.date | date:'MMM d, y' | highlight:searchText"></span> &raquo;
14         <a ng-href="{{ post.url }}" ng-click="externalLink()"
15            ng-bind-html-unsafe="post.title | highlight:searchText"></a>
16           <div class="preview" ng-bind-html-unsafe="post.content | highlight:searchText"></div>
17       </li>
18     </ul>
19   </div>
20 </div>

So where’s that magic include Helper/JekyllAppPosts coming from? This is where my very first liquid expression :) kicks in and returns an array with title, url, date and content information.

1 [{% for post in site.posts %}
2 {"title" : "{{ post.title }}",
3 "url" : "{{ post.url }}",
4 "date" : "{{ post.date | date_to_string }}",
5 "content" : "{{ post.content |  strip_html | truncate : 120 }}"}{% if forloop.rindex0 != 0 %},{% endif %}
6 {% endfor %}
7 ];

All in all the implementation was pretty straight forward, even when there were a couple of gotchas.

On very last gotcha I run into and that I’d like to share, is that on my local box jekyll is running with liquid 2.3 whatever, which allows you to use {% raw %}, while github is using liquid 2.2 whatever and therefore the older {% literal %} expression is used. After being hit by that one I finally understood Edward’s LeftCurley setting in _config.yml and I feel his pain.

Anyway as a rule of thumb, don’t use those tags for the time being and rewrite the code instead. There are some instructions from Khaja Minhajuddin that doesn’t require plug-ins.

WinJS.Namespace.define gotcha

2012-07-06T00:00:00-07:00

So you are following MS best practice and started namespacing your Metro JavaScript projects nicely already. Good :). Now here’s the challenge: spot the issue with the following code:

Problematic version: using WinJS.Namespace.define

WinJS.Namespace.define('MyApp', {
    version : '0.0.1'
});

WinJS.Namespace.define('Myapp.Helper', {
    think: function(input) {
        // do something
    }
});

console.log(typeof MyApp.Helper.think);  // -> 0x800a138f - JavaScript runtime error: Unable to get property 'think' of
undefined or null reference

Yeah, I know you spotted the mistyped namespace Myapp.Helper immediately. But what if Myapp.Helper would have been defined in another file, maybe by another coder? You might have been suprised a little, at least I was, when first faced with it;-).

Better version: using WinJS.Namespace.defineWithParent

WinJS.Namespace.define('MyApp', {
    version : '0.0.1'
});

WinJS.Namespace.defineWithParent(MyApp, 'Helper', {
    think: function (input) {
        // do something
    }
});

console.log(typeof MyApp.Helper.think); // -> "function"

Using defineWithParent won’t have that issue as you are passing in the parent object as first parameter, so VS immediately starts yelling if this object doesn’t exist. Probably worth making a rule like only using define for root namespaces and from that point on using defineWithParent.

Love to hear about your experiences with WinJS.Namespace.

First steps

2012-07-05T00:00:00-07:00

The obvious challenge: Where and how to start blogging. The answer: After deciding to use github pages and jekyll to host a static blog this blog here brought me up to speed. I’m especially glad about finding the_program theme, which provides a great responsive design without looking like ‘twitter bootstrap’ at all ;-).