Wednesday, August 26, 2015

Developing SharePoint 2013 Apps using Angular.js

Developing SharePoint 2013 Apps using Angular.js


Abstract: In this article, we will implement a SharePoint App using Angular.js. The Services and Controller features of Angular.js can be used to manage the SharePoint model declaration (controller scope objects) and external service calls (services) segregation will help to develop Apps for SharePoint effectively

The App Model introduced in SharePoint 2013 allows JavaScript Developers to develop Apps for SharePoint. In previous versions of SharePoint, running apps in full trusted mode would make the SharePoint server unstable which increased the maintenance costs. Although sandbox solutions existed, the restrictions applied were stringent which forced devs to run even untrusted custom code, in full-trust mode.

In SharePoint 2013, everything (which includes Lists, Libraries etc.) is an app. The JavaScript programming feature of App for SharePoint executes the custom code on a separate server e.g. Cloud, IIS, or even the client browser. This new model of SharePoint 2013 can allow access of Lists and Libraries in JavaScript using the JavaScript Object Model (JSOM). Before starting with a SharePoint App, we need to keep the following facts in mind.
  • SharePoint App can be developed only on the Developer site
  • The default SharePoint Administrator cannot create the SharePoint App
  • The App developer must be the member of the Administrator group of the developer site.
There are several JavaScript Libraries and Frameworks for DOM manipulations, and implementing MVVM and MVC programming on client-side. Some of them includes jQuery, Knockout, Angular.js etc. In the past, I have written about SharePoint 2013 Apps using JavaScript Object Model (JSOM) where I explained how to create a SharePoint app using JavaScript. In this article, we will implement a SharePoint App using Angular.js.
Editorial Note: If you are absolutely new to Angular.js, check this Angular article series by Praveen that brings you up to date with Angular.
In this article, we will be using SharePoint 2013 Online and the Developer site created on it. Alternatively this application can be used in an On-Premise SharePoint application also. The prerequisites for this article is to have a basic knowledge of SharePoint 2013, especially creating Lists.
Step 1: Open the SharePoint online portal using http://portal.microsoftonline.com. Login with your subscription. (Alternatively, on-premises SharePoint 201 installation can be used). Create a new developer site and a Custom List named CategoryList as shown in the following figure:

sharepoint-list
The list will have CategoryId and CategoryName columns. Note that the default Title Column is renamed to CategoryId. The programming always uses the Title as column name.
Step 2: Open Visual Studio 2013 and create a new App for SharePoint and name it SPNG as shown in the following figure.
apps-for-sharepoint
Set the SharePoint site for SharePoint hosted App as shown in the following figure:
sharepoint-site
Step 3: Once the app is created add the AngularJS Framework, jQuery and Bootstrap JavaScript libraries using Manage NuGet Package in the project.
Step 4: In the Scripts folder, add a new folder and name it MyScripts. In this folder, add the following JavaScript files:
Module.js
(function () {
    angular.module('spsmodule', []);
})();
The above code is for creating an Angular.js module. This is the entry point for our application.
Service.js
(function (app) {
app.service('spsservice', function ($q) {
 
 
    function manageQueryStringParameter(paramToRetrieve) {
        var params =
        document.URL.split("?")[1].split("&");
        var strParams = "";
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve) {
                return singleParam[1];
            }
        }
    }
 
    var hostWebUrl;
    var appWebUrl;
    //The SharePoint App where the App is actualy installed
    hostWebUrl = decodeURIComponent(manageQueryStringParameter('SPHostUrl'));
    //The App web where the component to be accessed by the app are deployed
    appWebUrl = decodeURIComponent(manageQueryStringParameter('SPAppWebUrl'));
 
 
    //Function to read all records
    this.get = function () {
 
        var deferred = $q.defer();
        //Get the SharePoint Context object based upon the URL
        var ctx = new SP.ClientContext(appWebUrl);
        var appCtxSite = new SP.AppContextSite(ctx, hostWebUrl);
 
        var web = appCtxSite.get_web(); //Get the Web
 
        var list = web.get_lists().getByTitle("CategoryList"); //Get the List
 
        var query = new SP.CamlQuery(); //The Query object. This is used to query for data in the List
 
        query.set_viewXml('<View><RowLimit></RowLimit>10</View>');
 
        var items = list.getItems(query);
 
        ctx.load(list); //Retrieves the properties of a client object from the server.
        ctx.load(items);
 
        
        //Execute the Query Asynchronously
        ctx.executeQueryAsync(
            Function.createDelegate(this, function () {
                var itemInfo = '';
                var enumerator = items.getEnumerator();
                var CategoryArray = [];
 
                while (enumerator.moveNext()) {
                    var currentListItem = enumerator.get_current();
                      
                    CategoryArray.push({
                        ID: currentListItem.get_item('ID'),
                        CategoryId: currentListItem.get_item('Title'),
                        CategoryName: currentListItem.get_item('CategoryName')
                    });
                }
                deferred.resolve(CategoryArray);
            }),
            Function.createDelegate(this, function (sender, args) {
                deferred.reject('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
            })
            );
        return deferred.promise;
    };
 
    //Function to Add the new record in the List
    this.add = function (Category) {
        
        var deferred = $q.defer();
       //debugger;
        var ctx = new SP.ClientContext(appWebUrl);//Get the SharePoint Context object based upon the URL
        var appCtxSite = new SP.AppContextSite(ctx, hostWebUrl);
 
        var web = appCtxSite.get_web(); //Get the Site
 
        var list = web.get_lists().getByTitle("CategoryList"); //Get the List based upon the Title
        var listCreationInformation = new SP.ListItemCreationInformation(); //Object for creating Item in the List
 
        ctx.load(list);
        var listItem = list.addItem(listCreationInformation);
 
        listItem.set_item("Title", Category.CategoryId);
        listItem.set_item("CategoryName", Category.CategoryName);
        listItem.update(); //Update the List Item
 
        ctx.load(listItem);
        //Execute the batch Asynchronously
        ctx.executeQueryAsync(
            Function.createDelegate(this, function () {
                var Categories = [];
                    var id = listItem.get_id();
                   Categories.push({
                        ID: listItem.get_item('ID'),
                        CategoryId: listItem.get_item('Title'),
                        CategoryName: listItem.get_item('CategoryName')
                   });
                   deferred.resolve(Categories);
                 }),
            Function.createDelegate(this, function () {
                deferred.reject('Request failed. ' + args.get_message() +
 
'\n' + args.get_stackTrace());
            })
           );
 
        return deferred.promise;
    }
 
    //Method to Update update the record
    this.update = function (Category) {
          
        var deferred = $q.defer();
        var ctx = new SP.ClientContext(appWebUrl);
        var appCtxSite = new SP.AppContextSite(ctx, hostWebUrl);
 
        var web = appCtxSite.get_web();
 
        var list = web.get_lists().getByTitle("CategoryList");
        ctx.load(list);
 
        listItemToUpdate = list.getItemById(Category.ID);
 
        ctx.load(listItemToUpdate);
 
        listItemToUpdate.set_item('CategoryName', Category.CategoryName);
        listItemToUpdate.update();
 
        ctx.executeQueryAsync(
            Function.createDelegate(this, function () {
               var Categories = [];
               var id = listItemToUpdate.get_id();
                    Categories.push({
                        ID: listItemToUpdate.get_item('ID'),
                        CategoryId: listItemToUpdate.get_item('Title'),
                        CategoryName: listItemToUpdate.get_item('CategoryName')
                    });
                    deferred.resolve(Categories);
            }),
            Function.createDelegate(this, function () {
                deferred.reject('Request failed. ' + args.get_message() +
 
'\n' + args.get_stackTrace());
            })
            );
        return deferred.promise;
    };
});
}(angular.module('spsmodule')));
The above code is very important, it has the following features:
  • This code has a dependency on $q. This service helps the functions to run asynchronously and use their return values when the processing is completed. In the above code, all functions uses the $q.defer() function. This is used to declare the deferred object, which helps us in building an asynchronous function. 
  • The code uses the hostWebUrl and appWebUrl which represents the URL for sharepoint app where the app will be installed, and the URL from where components required for the app can be accessed respectively.
  • The function get(), add() and update() is passed with $scope object which is used to update the $scope objects declared in the controller. These objects are further bound with the UI.
  • All functions in the above code get a reference of the SharePoint context object using SP.ClientContext ().
  • All functions in the above code perform execute operations using executeQueryAsync () method of the SharePoint context objects.
  • The get() function is used to read all data from the CategoryList and store data in the Categories array.
  • The add() is used to add a new record in the CategoryList. This uses the Category $scope object passed from the controller to the add () function.
  • The update() function is used to update the record from the CategoryList using the Category $scopeobject passed from the controller to the update () function.
Controller.js
(function (app) {
app.controller('spscontroller', function ($scope,spsservice) {
 
    load();
     
     $scope.Categories = [];
     $scope.Category = {
         ID:0,
         CategoryId: "",
         CategoryName:""
     };
    var IsUpdate = false;
    //Function to load all categories
    function load() {
        var promiseGet = spsservice.get();
        promiseGet.then(function (resp) {
            $scope.Categories = resp;
        }, function (err) {
            $scope.Message = "Error " + err.status;
        });
    }
 
    //Function to load the selected record
    $scope.loadRecord = function (cat,$event) {
        $event.preventDefault();
        $scope.Category.ID = cat.ID;
        $scope.Category.CategoryId = cat.CategoryId;
        $scope.Category.CategoryName = cat.CategoryName;
        IsUpdate = true;
    }
 
    //Function to Create a new category or update existing base on the
    //IdUpdate boolean
    $scope.save = function ($event) {
        $event.preventDefault();
        if (!IsUpdate) {
            var promiseSave = spsservice.add($scope.Category);
            promiseSave.then(function (resp) {
                alert("Saved");
            }, function (err) {
                $scope.Message = "Error " + err.status;
            });
        } else {
            var promiseUpdate = spsservice.update($scope.Category);
            promiseUpdate.then(function (resp) {
                alert("Saved");
            }, function (err) {
                $scope.Message = "Error " + err.status;
            });
            IsUpdate = false;
        }
    }
});
}(angular.module('spsmodule')));
The above controller code has the following features
  • This controller class uses the $scope object and the spsservice Angular service.
  • Declares Categories array and Category object. These will be used for DataBinding on UI.
  • The load() function calls the get () function of the service. This receives the promise object which represents the result when the asynchronous call is completed from the service.
  • loadRecord() is used to display the selected category from the table on the UI.
  • The save() function is used to either create a new record in the list or update the existing one based on theIsUpdate Boolean object.

Step 5: Open Default.aspx and add the following script references:
<script src="../Scripts/jquery-2.1.3.min.js"></script>
<script src="../Scripts/bootstrap.min.js"></script>
<script src="../Scripts/angular.min.js"></script>
<script src="../Scripts/angular-ui/ui-bootstrap-tpls.min.js"></script>
 
<script src="../Scripts/MyScripts/module.js"></script>
<script src="../Scripts/MyScripts/service.js" ></script>
<script src="../Scripts/MyScripts/controller.js" ></script>
 
<link href="../Content/bootstrap-theme.min.css" rel="stylesheet" />
<link href="../Content/bootstrap.min.css" rel="stylesheet" />
The above references are used to load Angular Framework and the bootstrap library for the RICH UI.
Step 6: Add the following markup in the PlaceHolderMain of Default.aspx
<div ng-app="spsmodule">
    <div ng-controller="spscontroller">
        <hr />
        <br />
 
    <div id="dvdml">
        <table class="table table-condensed table-striped table-bordered">
            <tr>
                <td>Category Id:</td>
                <td>
                    <input type="text" class="form-control"
                           ng-model="Category.CategoryId" />
                </td>
            </tr>
            <tr>
                <td>Category Name:</td>
                <td>
                    <input type="text" class="form-control"
                           ng-model="Category.CategoryName">
                </td>
            </tr>
        </table>
 
</div>
 
<input type="button" id="btnaddcategory"
   class="btn btn-small btn-primary"
    value="Save" ng-click="save($event)"/>       
<br />
  <table class="table table-bordered table-striped">
    <thead>
        <tr>
            <th class="c1">RecordId</th>
             <th class="c1">CategoryId</th>
             <th class="c1">CategoryName</th>
            <th class="c1"></th>
            <th class="c1"></th>
        </tr>
    </thead>
    <tbody>
        <tr ng-repeat="Cat in Categories|orderBy:'CategoryId'">
            <td>{{Cat.ID}}</td>
            <td>{{Cat.CategoryId}}</td>
            <td>{{Cat.CategoryName}}</td>
             <td>
                <button class="btn glyphicon glyphicon-pencil"
                     ng-click="loadRecord(Cat,$event)"/>
            </td>
             
        </tr>
    </tbody>
</table>
    </div>
</div>
In the above markup, the <div> tag is bound with the spsmodule and spscontroller. In the markup the <input> elements are bound with the Category properties using ng-model and the <input> button is ng-click bound with the functions defined in the controller. All the ng-click function bindings are passed with the $event parameter. This object contains information about the event and  is used to prevent the page from post-back. The markup contains a table which is ng-repeat bound with the Categories array declared in the controller. This is used to generate the table rows based on the data in the object CategoryList List.
Step 7: Since we need to perform a Read/Write operations on the List using App, we need to apply access rights. In the project we have an AppManifest.xml. This is used to set the App permissions. Double-Click on this file and set the permissions as shown in the following figure:
manifest-permissions
Here we need to set permissions on the Web Sire and the List, so that we can perform Read/Write operations.
sharepoint-app-trust
Run the application, after deployment we can set the trust for the app as shown here:
Click on Trust It and the following result will be displayed:

angular-sharepoint
Enter Category Details in the textboxes and click on the Save button, the new category record added in the table will be displayed as shown in the following figure:

enter-category
table-crud
Conclusion: The SharePoint App Model can be developed effectively using a client-side library like Angular.js. The abstractions provided by Angular fit very well into the SharePoint ecosystem and hence we can develop rich interfaces using this combination. The abstractions also help us in keeping the code base pretty clean.
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)