IQParts Design – Isolating AngularJS and Bootstrap

In the previous post I introduced AngularJS 1.4 and Bootstrap 3.3 Web Parts. You can get it using the Free SharePoint Add-Ins page in IQApp Central. This post is about how it all works.

Web Parts and Isolation

My goal was to make the solution as ideal as possible based on the 8 Characteristics of an Ideal SharePoint Customization. To state that a bit more succinctly, the customizations should be isolated but make good use of SharePoint without requiring custom master pages or ASP.Net page customizations. To meet this goals first requires a good container. Users need to be able to add the parts to pages and configure them in the browser. It makes sense therefore to start with one of the stock Web Parts. There are three possible candidates: the Page Viewer Web Part (PVWP), the Content Editor Web Part (CEWP), and the Script Editor Web part. The samples have examples using the PVWP and CEWP.

In either case we want to contain the custom functionality inside an iframe element for each part. The main difference between the two parts is that the CEWP requires an extra piece. The PVWP is therefore a bit easier. In terms of end user experience we weren’t able to tell a difference, but we included both part containers because theoretically the CEWP version is more flexible – you can customize the extra HTML file and the iframe.

Seriously? An iframe?

In the context of SharePoint 2013 the humble iframe has gotten a bad reputation because it is the basis of the App Part. The problem is that the App Part design requires the contents of the iframe to be in a different domain. This is done to prevent cross-site exploits and it works because by default a frame from an origin other than the parent page’s domain is isolated and can’t read the parent page or even the parent page’s URL. Many of the frustrations developers have with the app model stem from this. It makes everything far more complicated.

In this case we are using an iframe simply to load a page from the same site where the pages which contain the Web Parts are loaded. Because the parent Wiki or Web Part page is served from the same domain as the part container, the part can work with the parent window to resize itself, detect that the page is in edit mode, and read the parent’s URL and query string. It can also, if necessary, communicate with other IQParts on the same page. At the same time the frame gives us isolation so that Bootstrap and AngularJS can’t break anything outside the iframe.

SPABody.aspx

The iframe loads a file named SPABody.aspx which is the actual container for the app’s functionality. It loads the SharePoint object model, AngularJS, Bootstrap, and Angular-UI. Other dependencies are injected at runtime based on each app’s specific configuration.

Of special interest is this line:

<div
ng-include=”RootTemplate + ‘?m=’ + Modified”></div>

It uses Angular’s ng-include directive to load a partial html template based on the value of RootTemplate which is set during initialization.

Configurations.js and IQPart.js

SPABody.aspx directly contains two custom script files. The first, configurations.js, is generated on the fly when users configure the parts on a page. Configurations.js is an optimization to prevent the need to round trip to the SharePoint server for configuration data – more on this later. The second script, iqpart.js, implements the rest if the wrapper’s functionality.

IQPart.js is fairly long and so I am not including its source here. You can get it by installing the sample.

How the AngularJS Apps Work

Everything starts when a user adds the container Web Part to a page.

The Web Part points to SPABody.aspx which loads iqpart.js.

When iqpart.js loads, it looks for a configuration for the part. If it doesn’t find one it sets RootTemplate to default.html which is a partial located in the same folder as SPABody.aspx. If the page is in design mode, the part looks like this…

Otherwise it looks like this…

The selection dropdown displays all of the available apps. These are loaded by iterating the folders in /IQAppCore/SPAs.

If you select Create new AngularJS app… the part presents a form allowing you to name the app and give it a description.

Once you select Create New App, iqpart.js creates a new folder, in this case /IQPart/SPAs/My New Demo App, and copies the starter template files into the new folder. The default files are:

  • App.html – The RootTemplate of the new app
  • App.js – The AngularJS module and controller for the new app
  • App.css – The app’s custom styles
  • Config.html – The app’s configuration page
  • defaultConfig.js – The app’s default settings

The generated file looks like this:

//This is the default configuration for this app part
var p = window.iqPart; if (!!p && !!p.SetNewConfiguration) { 
    p.SetNewConfiguration( 
        {        
            //Add your custom properties here
            "SelectedDemo": "timer", 
            //Or overide defaults
            "Name": "My New Demo App", 
            "Description": "A nice description",
            "RootTemplate": "app.html",
            "Scripts": [ 
                "app.js" 
            ],
            "Styles": [
                "app.css"
            ],
            "Modules": [
                "iqAppPartModule"
            ]
        });
}

Based on the configuration, iqpart.js will load additional scripts and styles, and you can override the default module name. If you have installed the sample, compare the defaultConfig.js files for the six included samples.

The default Config.html looks like this…

You can add your own configuration values by altering this form. In this case the only setting is the demo mode and it is set to display a greeting. The other option is to display a timer. The html template is app.html and the script is app.js.

The greeting demo illustrates the use of SharePoint JSOM and makes use of a service wrapper that makes it easy to use JSOM with AngularJS.

Getting Started with AngularJS Samples

Three of the included samples come from the homepage of http://angularjs.org. They are Getting Started, Add Some Control, and Create Components. Each has a video!

Join us on Slack

Want to talk about this sample and the rest of the IQApp Central awesomeness? If you register, we will invite you to join us on our Slack network.

–Doug Ware

One thought on “IQParts Design – Isolating AngularJS and Bootstrap”

  1. Doug, I could kiss you. Thank you for sharing this awesome pattern for integrating Angular with SharePoint – you are doing all the things I’ve been wanting to do with our Angular practice, but haven’t had the time or the nouce: isolating from the SP page model, configuration forms for the web parts, etc.

    We’ve been working with factories to abstract the SharePoint REST and JSOM APIs for over a year now, but have been just using ng-includes in Script Editor WPs to bring them into the page, which has been giving us plenty of headaches when SharePoint doesn’t want to play ball. Thank you again for showing us a better way!

    Cheers,
    Bruce

Comments are closed.