Category Archives: IQApp Central

IQApp Central is a powerful set of tools for building cloud compatible SharePoint Add-ins. If you aren’t using it you are working too hard!

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

IQParts – Cloud App Compatible Web Parts using AngularJS and Bootstrap

We are in the process of releasing three free SharePoint Add-ins from IQApp Central: Absence and Vacation Request Management Site, Board of Directors Site, and AngularJS 1.4 and Bootstrap 3.3 Web Parts. We’ll release all three as side-loaded apps over the next couple weeks for host webs and the first two as SharePoint hosted apps will be available via the Office store. Until then, you can get all three using Free SharePoint Add-Ins page in IQApp Central.

Today I am pleased to introduce AngularJS 1.4 and Bootstrap 3.3 Web Parts. This is a sample created using IQApp Central​. It is a framework that allows for user configurable Web Parts built using SharePopint, AngularJS 1.4 and Bootstrap 3​. ​This sample contains two Web Parts, six sample apps, an extensible configuration system, a template to help you get started with your own apps, and some handy functions to make integrating with SharePoint pages and services easy.

This sample started as an exercise to attempt an ideal design based on the 8 Characteristics of an Ideal SharePoint Customization. Integrating AngularJS and Bootstrap with SharePoint while trying to maximize the 8 ideals is a great challenge because SharePoint and AngularJS are both very assertive, demanding frameworks that want total control over a page and Bootstrap wants to completely own the base styles.

For example, here is a SharePoint page.

And here is the same page with Bootstrap 3’s CSS loaded.

Most projects that use Bootstrap start with a custom master page and end with a complete theme. Naturally this is not an option when you are creating components that, like Web Parts, are expected to work on any site.

Here is one of the sample pages included in AngularJS 1.4 and Bootstrap 3.3 Web Parts. It contains three of the sample apps and has a theme applied. Note how the parts do not break the containing page or the site’s style.

Configurability

There are a few projects out there that have tackled the configurable Web Part problem including this very good one by Rachid Bouzalmat. This approach works, but it is less than ideal on a couple of counts (based on the 8 Characteristics of an Ideal SharePoint Customization). Specifically it uses jQuery to target particular elements in a SharePoint page. It also depends on the ability to hijack SharePoint’s JavaScript. In the interest of full disclosure, we have code that does both of those things for different reasons. I am just as guilty, just not in the case of this sample!

I will write more about how we implemented our Web Part containers and the configuration system in a future post. In the meantime you can see for yourself how it works by installing the sample. Until then here is a shot of the sample page in design mode.

–Doug Ware