At SharePoint Conference, we announced a couple of experimental UI widgets to help you build apps for Office and SharePoint. The widgets included in this first release are the People Picker and the List View and in the rest of this post, we will explain what they are and how to use them, but first, an important caveat about the current state of the code.

The code is not complete and these widgets are “experimental”. In clearer terms, that means:

• The target audience for this release is developers and our primary goal is to collect feedback.
• The code is tested in Office 365. The People Picker works against SharePoint on-premises, but List View does not.
• The code has bugs and functionality limitations. Do not use this code for production scenarios.
• The developer interface will change—future versions may require you to change significant amounts of code.
• The license under which these controls are released grants you specific rights and has certain limitations. Read it carefully.
• We do plan to release these controls for production use soon. Your feedback is critical to identifying areas we should invest.

That said, technically, the controls are actually quite useful—and in the case of the People Picker—almost fully functional. By using them and providing feedback, you can help shape the direction and accelerate the delivery of these—and other widgets in the future.

A note about open source. We have not ruled out providing these controls as open source in the future, but now they still have a proprietary license. This release only includes the binaries. If you have feedback about open source-let us know!

Let’s dive into the widget details.

Widgets overview

First, a quick overview of the philosophy around widgets. The two core principles that we want to deliver on are:

• Bring Office to the Web and provide a delightful user experience. When possible, we want developers to be able to build the same experiences than those provided by our own products without having to spend excessive resources doing so.
• Provide a great developer experience. You should not have to reverse engineer our code to figure out how to use these widgets. The developer interface should be simple, familiar, and flexible to help you develop your scenarios.

Getting the code

The library code that you need for these widgets is part of a NuGet package. Install it and it will give you access to all the files you need to use the experimental widgets. If you have Visual Studio, it is as easy as choosing your project, choosing Manage NuGet Packages and searching for “Office Widgets”. Remember to sort by published date.

http://www.nuget.org/packages/Microsoft.Office.WebWidgets.Experimental/

Figure 1. Office Web Widgets - Experimental NuGet package in Visual Studio

People Picker

This is perhaps the most requested UI widget and hence it was an obvious choice for us to work on. We have seen several apps recreating this control on their own, several questions on our forums, and also requests on our UserVoice site to deliver a People Picker.

While there is already a Client People Picker that you can use in SharePoint hosted apps, you cannot use it in other hosting models. So, we created a pure HTML/JavaScript widget that you can use in apps for SharePoint in all hosting alternatives (SharePoint hosted, provider-hosted, or auto-hosted). The widget doesn’t have a dependency on where you host your pages, but it does require the use of the SharePoint cross-domain library and the SharePoint REST endpoint. It is specifically tailored to pick people from SharePoint.

You include the required files at the top of your HTML page, initialize the runtime, and instantiate the widget using a placeholder div with some special attributes. The following code shows the instantiation.

…  
    <script type="text/javascript">// Retrieve context tokens var hostWebUrl = "PUT HOSTWEB URL HERE"var appWebUrl = "PUT APPWEB URL HERE";// Initialize Controls RuntimeOffice.Controls.Runtime.initialize({
                sharePointHostUrl: hostWebUrl,
                appWebUrl: appWebUrl,
            });script>head><body style="height: 100%;" onload="Office.Controls.Runtime.renderAll();">Assigned to:<div id="PeoplePickerSimple" 
                     data-office-control="Office.Controls.PeoplePicker">
div>body>

…

Figure 2. People Picker widget

The widget supports various properties and events. For full sample code and documentation, see How to: Use the experimental People Picker widget in apps for SharePoint.

List View

The List View widget attempts to provide the same functionality that the List View on SharePoint pages provides. Be aware that the functionality of the experimental widget is limited. It displays tabular data with some basic sorting and relies on SharePoint pages to view and edit individual items. Instantiation of the widget is similar to the People Picker, you can do it declaratively or imperatively. Since the People Picker example used the declarative syntax, I’ll use the programmatic syntax to instantiate the List View and render a list that is deployed as part of the app.

…
<script type="text/javascript">
        function createListView() {// Retrieve context tokens var hostWebUrl = "PUT HOSTWEB URL HERE"var appWebUrl = "PUT APPWEB URL HERE";// Initialize Controls RuntimeOffice.Controls.Runtime.initialize({
                sharePointHostUrl: hostWebUrl,
                appWebUrl: appWebUrl,
            });var listUrlValue = appWebUrl + 
                             "/_api/web/lists/getbytitle('CustomersInApp')";
            theList= new Office.Controls.ListView(
            document.getElementById("listhere"), {
                listUrl: listUrlValue 
            }
          );

        }



    script>
…

Figure 3. List View widget

To see the full code sample and documentation for List View, see How to: Use the experimental Desktop List View widget in apps for SharePoint.

Runtime initialization and connectivity with SharePoint

Both widgets have a dependency on the SharePoint cross-domain library that in turn means that you must have an app web for things to work, even if you are not deploying any assets on SharePoint. To satisfy this requirement, use a dummy asset, for example, an empty web page hosted on SharePoint that is deployed as part of your SharePoint app package. To learn how the cross-domain library works, see How to: Access SharePoint 2013 data from apps using the cross-domain library.

To initialize the controls library as shown in the code sample, pass the app web and host web URLs to the runtime. If you get these parameters as part of your query string (for example, because you are passing them using context tokens), then you can initialize the runtime with an empty object and the code will attempt to get the parameters from the query string directly.

// Initialize with an empty object and the code 
// will attempt to get the tokens from the
// querystring directly.Office.Controls.Runtime.initialize({});

Using these widgets in apps for Office

In this first iteration, widgets are designed with apps for SharePoint in mind, but they can also be used in apps for Office if you are using SharePoint as a backend. This scenario requires you to have both, an app for SharePoint deployed and an app for Office that in turn connects to the app for SharePoint.

Feedback

Fantastic, you reached the most important part of this post—how you can give us feedback. We will be monitoring comments on this blog post, but you can also send us feedback on UserVoice using the Office Web Widgets category. Some key areas where we want your feedback:

• Interface and syntax
  • What do you think about the interface (for example, widget instantiation, manipulation)? Does it make sense? Is it easy? Is it difficult?
  • Do the properties and event names make sense? Are they too long? Are they too short? Are they clear or confusing?
  • Do you like the name “Office Web Widgets” or would you prefer something else?
• Functionality
  • Does it meet your app needs?
  • Are properties/events missing?
  • Did you find any critical bugs?
  • Do you consider any of the missing functionality an adoption blocker? What would be you would like us enable/fix before you could use the controls in your production apps?
• Form factors
  • What form factors and input methods do you see your customers using these widgets on the most? Currently, they are optimized for keyboard and mouse.
• Other frameworks
  • Would you like controls for a particular framework (for example, AngularJS)?
  • Do widgets conflict with your existing code or frameworks you already use?
• More controls
  • o What other widgets would you like to see?

We look forward to hearing from you: download the code, look at the docs and give us feedback.

Happy coding!