This article was updated on April 26th to reflect the comments by Rafael and Ravi. Thanks to Ravi Kiran for technically reviewing this article. Thanks Rafael for pointing out the error and Mahesh for fixing it.
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:
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.
Set the SharePoint site for SharePoint hosted App as shown in the following figure:
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 $scope object 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 the IsUpdate 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:
Here we need to set permissions on the Web Sire and the List, so that we can perform Read/Write operations.
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:
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:
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.
Download the entire source code of this article (Github)
This article has been editorially reviewed by Suprotim Agarwal.
C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.
We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).
Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.
Click here to Explore the Table of Contents or Download Sample Chapters!
Was this article worth reading? Share it with fellow developers too. Thanks!
Mahesh Sabnis is a DotNetCurry author and a Microsoft MVP having over two decades of experience in IT education and development. He is a Microsoft Certified Trainer (MCT) since 2005 and has conducted various Corporate Training programs for .NET Technologies (all versions), and Front-end technologies like Angular and React. Follow him on twitter @
maheshdotnet or connect with him on
LinkedIn