SharePoint 2013 API OData For Lookup Fields

When using SharePoint data lists as the backend for an application, we can leverage the use of REST and OData to fetch the information from a data list. When the list contains lookup fields, a normal GET operation on the list only returns the id from the lookup field which may not be enough for some cases. 

In the case that more information is needed from the lookup or reference field, we can leverage the OData $expand parameter. This parameter is used to expand the related data so that in addition of the id other information also becomes available. As an example, we can look at a simple Project data list which has a lookup field named Client. This field uses the Client list as reference.

Project List Fields (internal names)	Client List Fields (internal names)
id	Id
Name	Name
Client  (lookup to Client)	CodeProject

How to fetch the data:

Note: my.sharepoint.com should be replaced with a specific domain name.

https://my.sharepoint.com/_api/web/lists/getbytitle('project')/items

In this URL string, we are using the getbytitle API which allows us to query a list by name. The items route suffix indicates to fetch all the items with no explicit filters (where clause) and all the available fields. The resulting data contains the fields Id, Name, ClientId (where is this coming from?) and other fields that are created by the SharePoint platform.  For our purposes, our focus is only on our custom fields (Name, ClientId)

We can notice that there is a ClientId field, but the field that we defined is named Client. SharePoint by default returns the lookup field id using this format: field name + id. In this case, the name is ClientId which as we can guess is the id of the client record.

What about also getting the client name?

In the case that more lookup data is required as in the case of client name, we must use a couple of OData parameters to expand on the selection of the look up fields: $select, $expand

Parameter	Description
$select	Use this parameter to control what fields should be selected.
$expand	Use this field to indicate what lookup field should be expanded to get additional information from that field. Field to expand must be in the $select parameter.

As an example, our request can be changed to this: (no domain name listed)

_api/web/lists/getbytitle('project')/items?$select=Client/Name,ClientId,Name,Id&$expand=Client

URL Segments:

URL Segment	Description
_api/web/lists/getbytitle('project')/items	This is the API and route to query a list by name and retrieve the items (records)
$select=Client/Name,ClientId,Name,Id	OData request parameter to select fields by name
$expand=Client	OData request parameter to indicate what look up field should be expanded to get additional information.

When using the $expand query parameter, the $select query parameter must also be used, and the field to be expanded must be explicitly declared as shown on our example above. The result of this request returns the project name and id as well as client name and client id.  We should note the format used to get the client name, Client/Name. This format is what indicates that we want the Name field from the Client list.

Sample Result:

A sample of the response is shown below. The results array contains each record, for which we can find the selected fields as well as the client property (object) with the name property (client name).

Expanded Results:

As shown above, the USE of OData request parameters are very important when there is a need to get related/lookup data with one request.


Originally Posted on ozkary.com

When using SharePoint data lists as the backend for an application, we can leverage the use of REST and OData to fetch the information fr...

Read Article →

SharePoint Choice Field Options with AngularJS $resource

A SharePoint data list can have a field of type = Choice which is used to provide the options for a dropdown control. When building SharePoint apps with AngularJS, we need to build the dropdown control with the options that are defined by the field’s metadata. Let’s see how we can go about to get this information.

In order to fetch the options from the Choice field from a given data list, we can use the REST APIs with OData operations. To show how this can be done using the AngularJS $resource service, we can take a look at an example in which we have a Task data list with a status field (type = Choice) with the following options:

Status (Choice) field options

Pending

In-Progress

Complete

We start by building an AngularJS service which uses the $resource service for our API calls. Note that we could also use the $http service as well.  Our service defines the $resource operation as follows: (note the relative path and the use of the getbytitle API route to get list information)

 var apiUrl = "../_api/web/lists/getbytitle('task')/:route";

       

        var api = $resource(apiUrl, { route: '@route' }, {

            //Other methods and routes

            status: { method: 'GET',params: {route:'fields'},isArray:false}        

        })

When making the call to get the data list status information, we need to send on the request an OData parameter to tell the API that we are interested in getting the information from a particular field. In our case, we need the metadata from the Status field which includes the choices that are available. Note that the Choice field does not provide a text/value pair. It only provides the text part of the options. This must be used for the value/text properties of the drop-down control. When updating the model and consequentially making a Create/Update API calls, we must persist the text value as this is the expected data (constraint) on the data list.

Our service and the Status method implementation to get the field's metadata looks like this:

function svcTask($q, $resource) {

        var apiUrl = "../_api/web/lists/getbytitle('task')/:route";

       

        var api = $resource(apiUrl, { route: '@route' }, {

            //Other methods and routes

            status: { method: 'GET', params: {route:'fields'}, isArray:false}        

        })

      

        var service = {

            /*

              name:status

              gets the options from a choice field type (sharepoint)

            */

            status: function () {

                var deferred = $q.defer();

 

 //gets the field by title

                var params = { '$filter': "Title eq 'Status'" };

               

api.status(params, function (data) {

                    statusOk(data);

                },

                    function (err) {

                        deferred.reject(err);

                    }

                );

                function statusOk(data) {

                    var result = data.value[0].Choices;

                    var list = [];

                    for (var idx = 0; idx < result.length; idx++) {

                        var item = { code: result[idx], name: result[idx] };

                        list.push(item);

                    }

                    service.statusList = list;

                    deferred.resolve(list);

                }

                return deferred.promise;

            }          

        }

        return service;

    }

A few notes about this code:

• The getbytitle API is used to query a list metadata as well as data.
• The Fields route segment is used to tell the API that we are interested in requesting field metadata information. This is where the options are defined.
• The $filter OData parameter is used to tell the API which field we need to query by filtering on the title property.
• The choices property is contained on the response Value property and has a results array.

The request is made by using the OData $filter request parameter. If the response is OK, the statusOk function is called. Otherwise an error is return by calling deferred.reject(err).

In the statusOk function, the code iterates thru the list and builds a JSON array that contains the value/text pairs. This is the model for our dropdown. Since there is a bit of data mapping/transformation that we need to do, and we want to encapsulate this away from the controller, the Status method returns a deferred promised. This allows us to handle the asynchronous request and perform the data mapping yet still keeping the asynchronous behavior. We then return the transformed data by calling deferred.resolve(list). 

The controller can now consume this service by calling the status method as shown below:

    function ctrlTask(svcTask) {

        var ctrl = this;

        ctrl.statusOptions = [];   //model for the status dropdown

        //load the status options waiting on a promise

        svcTask.status().then(function (data) {

            ctrl.statusOptions = data;

        },

            function (err) {

                $log.error(err);

            }

        );

    }

The ctrl.statusOptions is the model that holds the options for our dropdown on the view.

Finally, this is how the module is defined with both service and controller:

(function (angular) {

    'use strict';

    var appName = 'app';

    var app = angular.module(appName,['ngRoute', 'ngResource']);

    app.factory('svcTask', ['$q', '$resource', svcTask]);

    app.controller('ctrlTask', ['svcTask', ctrlTask]);

CodeProject

    function svcTask($q, $resource) {

        //...           

    }

    function ctrlTask(svcTask) {

        //...

    }

})(angular);

I hope this tip helps you build SharePoint Apps with AngularJS.

Origunally Posted on ozkary.com

A SharePoint data list can have a field of type = Choice which is used to provide the options for a dropdown control. When building SharePoi...

Read Article →

AngularJS HTML5 Date Range Controller

When dealing with date input fields, we often rely on the use of JavaScripts date pickers to control how the user can enter the data.  These date pickers in most cases take away from the native experience especially on mobile devices.  

With the support of HTML5 in modern devices, we could eliminate the use of JavaScript date pickers and instead make use of the native date type support (more information here).  As an example,  Let’s take a look at how we can build a date range simple app with AngularJS and HTML5. 

Widget:

In this implementation of a date range app, we bind our dateRange model properties (startDate, endDate) to two input fields (from,to). The idea is that based on the start date selection, we define the constraints for our end date. In this example, our constraints are set to a future date and no more than seven days.

To enable the native date picker control, we set both input fields to “type=date”. This enables the device to render a native control for the date selection as well as the limit on what can be typed in the control.

As we change the start date, the on-change event is raised.  In the handler for this event, we set the min and max HTML5 properties which help us on set the edge input constraints for the end date field. In our case, we set the min to one day more than the start date and max to seven days more.  This is done by binding the model properties (minDate,maxDate) to the input field properties (min,max) respectively. We should also note that we must use the ISO date format (yyyy-MM-dd) otherwise our constraints would not be enforced.

The result of settings these edge constraints are reflected on the date picker as only the dates with-in the constraints are enabled. All other dates are disabled (grayed-out) and can’t be selected.

As devices adapt the HTML5 standards, our apps can leverage their native support which enables our apps with a much better user experience.

Thanks for reading.

When dealing with date input fields, we often rely on the use of JavaScripts date pickers to control how the user can enter the data.  The...

Read Article →

AngularJS Autocomplete Directive with Label and Value Model Properties

With AngularJS, we can use the JQuery UI Autocomplete widget (details here) to convert any text box to an autocomplete control which can either call a web service or use an object array as data source.  The limitation with this widget is that it only knows of the one control associated to the directive which means that we can only set either the label or value.

To illustrate this limitation, let’s look at a simple customer search with autocomplete implementation in which we just type names starting with the letter O.

Problem Description:

As we type the client information, we can see that the widget automatically shows a list of names matching what has been entered. When a name is selected from the list, it is assigned to the autocomplete text box which is bound to a model property (client.name), but for more practical purposes, we would also like to get the id.  We can also note the header label only shows the information that was typed, but not the selected name. There is also a problem with updating the view.

Solution:

Since for most common cases we need the behavior to be similar to a Select control which has both a Label and Option value properties, we need to add a hidden input field and set the ng-model attribute to the model property, client.id. We are now set to capture the client name and id in two different fields. The problem still remains that we need to extend the autocomplete functionality, so that we are able to set the client.id property on the form.

To address this challenge in a simple approach, we can add a callback on the controller scope which can be used by the directive to callback and set any additional properties.  Let’s take a look at a simple implementation of this approach:

The controller has a new scope function (setCliendData) which is available to the directive via the injected scope variable.  This function just sets the controller model with the selected option. The change on the directive is to implement the select event handler which is raised after every selection from the list. We should note that we need to call the controller function using scope.$apply to force a digest cycle which updates the view with the new model value.  If this is not done, the view would not get updated, and our header would not display the client id and name properly.

What to Note:

The autocomplete widget by default uses the properties value or label to build the list. If those properties are not found, a list with empty names is displayed. To address this, on the directive autocomplete source handler, we map the name property to the value (or label) property that is expected by the autocomplete widget.

We should note that this approach works by sharing the controller scope with the directive. When using isolated scope on the directive, the calls to the dataSource and setCliendData would not be available on the directive, and this would need to be implemented differently.  

I hope this provides some help on how to address some of the limitations when building autocomplete functionality on your apps.

With AngularJS, we can use the JQuery UI Autocomplete widget ( details here ) to convert any text box to an autocomplete control which can ...

Read Article →

AngularJS Sharing Data Across Controllers with a Service

An AngularJS controller manages the data that is used with its associated HTML views. In some cases, there is a need for several controllers to share some common data. The common data can be user, security or settings that are needed to enable some access or configuration to elements on the view. For other cases, we may need to share data in different controllers to complete a process.

To see this in action, we can create a simple order system which works like a wizard and collects customer and food information. Each view on this demo is managed by a different controller.

Code:

Controllers are stateless and the data that is used by the controller is initialized every time it is loaded. To address this, we need a service that can be injected into the different controllers and can maintain the information. In AngularJS, a service is a singleton which only gets instantiated one time during the life cycle of the module. This allows us to maintain and share information across the initialization of different controllers.

In our demo, the svcAppData services persists the data that is captured from the user in each view.

Service Model:

this.detail = { name: '', dish: '', drink: '' };

Each controller accesses this information via the service detail model. This is done by the following statement:

ctrl.order = svcAppData.detail;

The views bind to the information by using the ng-model directive as shown below:

<input class="form-control" ng-model="ctrl.order.name" placeholder="enter name" type="text">

As the user enters the information, the data field in the model (detail) gets updated with the new information.

I hope this article is able to provide some clarity on how to use services and share data across controllers.

An AngularJS controller manages the data that is used with its associated HTML views. In some cases, there is a need for several controller...

Read Article →

AngularJS ngOption Directive Simplified

With AngularJS, we can use the ngOption directive to dynamically create the options that are available from the select input field. There are a few ways to use this directive and depending on the application requirements, we may choose one from another. Let’s try to simplify its usage by using some practical examples:

Demo Preview:  (see working demo below)

Bind to a String Array:

We can use this approach to bind a list of strings as options. Both the input value and text take on the array value. When an option is selected, the Value is set to the model defined by the ngModel Directive. When we look at the result from Selected Option 1 (see demo below), we can see how the selected option text is also the selected option value.

Expression	ng-options="option for option in ctrl.makes"
Description	Use the string as both value and text.

Bind to Collection of Objects:

This approach provides more flexibility since it allows us to bind to more than just a Value/Text reference. We can use an object as an option, and when the option is selected, this object is assigned to the model defined by the ngModel Directive. This means that in addition to the value, we have access to all other properties of this object. Let’s look at Seleted Option 2 (demo). As we select a value from the select control, we can see the output display the JSON contained by the object.

Expression	ng-options="car as car.model for car in ctrl.cars"
Description	Use a car object as value, use the model attribute as text.

Bind to Collection of Objects with Explicit Attributes as Key/Value Pairs:

This approach allows us to use a collection with key/value nodes. This provides the flexibility to explicitly indicate what attributes from the object should be the text and value. It also uses simple data types for the binding, so only the attributes used in the ngOption directive are assigned. If we look at Selected Option 3, we can see that the value contained in the id property is displayed.

Expression	ng-options="car.id  as car.model for car in ctrl.cars"
Description	Use attribute id as value and model as text.

Bind to Collection of Objects with Explicit JSON:

This approach is similar to the previous one, but it allows us to indicate that we may just want to use some attributes in a JSON structure from the object and only assigned those to the model. In Selected Option 4, we can see how we are only using a couple of attributes from the object and creating a JSON to map them. This is then assigned as an object to the model.

Expression	ng-options="{model:car.model,id: car.id } as car.model for car in ctrl.cars track by car.id"
Description	Use JSON declaration and assigned only the attributes id and model. Use model as text. The selected value is determined by card.id

Track Selected Object:

One important item to note when using the ngOption directive with complex types is that we need to explicitly indicate what attribute should be used to track the selected option. This is done with the expression “track by”.  If this is not properly assigned, the selected text does is not displayed even though an object assignment is actually made. See Selected Option 5.

CodeProject

Expression	ng-options="{model:car.model,id: car.id } as car.model for car in ctrl.cars"
Description	Use JSON declaration and assigned only the attributes id and model. Use model as text. There is no tracking of the value, so no text is displayed.

Demo:

Well I hope this provides some clarifications on how to use the ngOption directive.

Originally posted by ozkary.com

With AngularJS, we can use the ngOption directive to dynamically create the options that are available from the select input field. There a...

Read Article →

AngularJS Data Grid with Paging

With AngularJS, we can easily display a data grid with some data by just binding a JSON model to a view. In cases where the data is somewhat large, we would like to provide users with a much better experience by adding paging to the grid.  We should note that the purpose of this article is to show a technique for client side paging. For much larger data sets, this approach may not be recommended.

With AngularJS, paging can be done with the use of a custom filter and service. The filter enable us to control the data (subset) that should be displayed on each page. The service is used by the controller to manage the paging commands like previous, next and to update the model that is used by the filter to know when to show a corresponding set of data based on the current page selection. We should take a look at the following code snippet and result to see how things work, and we can then cover the details of the implementation.

As we can see in the result tab, as we press the paging buttons the grid displays only the records for the selected page (shown on the footer).  We can also change the default page size from the select box and either select 5 or 10.  Let’s cover the implementation in more detail.

Filter:

The filter basically just slices the array to return a subset of data for the selected page. The filter is placed on the ng-repeat mark-up and takes three parameters (items : data, page: current page, onPage: page size).

Service:

The service provides the model and actions that are used by the user interface elements. It is injected into the controller (app.grid) to make it available to the mark-up. This is what allows the user to page through the data and reset the page size setting. It also provides pager status like current page, number of pages and total number of records. On the controller, we set a reference of the service (ctrl.pager).

The View:

On the view, we access the paging service using the ctrl.pager property of the controller. This exposes the properties and methods of the paging service. Review the HTML tab and take a look at the HTML mark-up to see how this is done.

How this works:

As the user interacts with the paging elements (page size, previous and next buttons), the properties of the service are updated. This causes the filter (ng-repeat directive) to update again with the new paging values which can be a page changed or page size changed.

I hope this is able to show how simple paging can be implemented as a reusable service that can be injected into controllers.

With AngularJS, we can easily display a data grid with some data by just binding a JSON model to a view. In cases where the data is somewhat...

Read Article →