Category Archives: Widgets

Learn about the all new Office Web Widgets

Client controls, such as the Office Web Widgets – Experimental, can greatly reduce the amount of time required to build apps, and at the same time, increase the quality of the apps. For this to be true, we have to be sure the widgets meet certain criteria:         

               

  •              

    Widgets must be designed to be used in any webpage, even if the page is not hosted on SharePoint.

               

  •            

  •              

    Widgets work within the Office controls runtime. This lets us to provide a common set of requirements and a consistent syntax to use the widgets.

               

  •            

  •              

    Widgets that communicate back to SharePoint use the cross-domain library. The widgets don’t have a dependency on a particular server-side platform or technology. You can use the widgets regardless of your choice of server technology.

               

  •            

  •              

    Widgets must coexist with other elements in the page. The inclusion of the widget to a page should not modify other elements in it.

               

  •            

  •              

    Play nice with existing frameworks. We want to be sure you can still use the tools and technologies that you are used to.

               

  •          

         

Figure 1. An app using Office Web Widgets – Experimental

         
          Office Web Widgets - Experimental demo          

You can use the widgets by installing the Office Web Widgets – Experimental NuGet package from Visual Studio For more information, see Managing NuGet Packages Using the Dialog. You can also browse the NuGet gallery page.

         

Your feedback and comments helped us decide what widgets to provide. As you can see in Figure 1, the (1) People Picker and (2) Desktop List View widgets are ready for you to try and experiment. Please keep the feedback coming at the Office Developer Platform UserVoice site

         

You can also see the widgets in action in the Office Web Widgets – Experimental Demo code sample.

       

                                 

                   

           

                                              People Picker widget                            

                             

           

         

         

                                                 You can use the experimental People Picker widget in apps to help your users find and select people and groups in a tenant. Users can start typing in the text box and the widget retrieves the people whose name or e-mail matches the text.

           

Figure 2. People Picker widget solving a query

           
            People Picker experimental control on a page            

You can declare the widget in the HTML markup or programmatically using JavaScript. In either case, you use a div element as a placeholder for the widget. You can also set properties and event handlers for the People Picker widget. The following table shows the available properties and events in the People Picker widget.

           

                         

           

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                   

Property/Event

                 

                   

Type

                 

                   

Description

                 

                   

                      objectType                    

                 

                   

JSON Object (list of strings)

                 

                   

Type of items the widget will resolve. Options:

                   

                         

  •                        

    User

                         

  •                      

  •                        

    Group

                         

  •                    

                   

Default to user only.

                 

                   

                      allowMultipleSelections                    

                 

                   

Boolean

                 

                   

True/False. If False, the widget should allow selecting only one item at the time. Default=False.

                 

                   

                      rootGroupName                    

                 

                   

string

                 

                   

If provided, the widget will limit the selection to items in this group. If not provided, the widget will query objects from the whole tenancy.

                 

                   

                      selectedItems                    

                 

                   

JSON array

                 

                   

List of items selected. Each item will return an object representing a user or group.

                 

                   

                      onAdded                    

                 

                   

Function

                 

                   

Event that fires when a new object is added to the selection. The handler function received the object added.

                 

                   

                      onRemoved                    

                 

                   

Function

                 

                   

Event that fires when a new object is removed from the selection. The handler function received the object removed.

                 

                   

                      onChange                    

                 

                   

Function

                 

                   

Either adding or removing objects triggers this event. No parameters are passed to the handler function.

                 

                   

                      validationErrors                    

                 

                   

Array

                 

                   

Array of possible validation errors:

                   

                         

  •                        

    empty

                         

  •                      

  •                        

    unresolvedItem

                         

  •                      

  •                        

    tooManyItems

                         

  •                    

                 

                   

                      autoShowValidationMessage                    

                 

                   

Boolean

                 

                   

True=Show False=Don’t show

                 

                   

                      hasErrors                    

                 

                   

Boolean

                 

                   

True= There are 1 or more validation errors False=There are no validation errors

                 

                   

                      errors                    

                 

                   

Array

                 

                   

Array of possible validation errors:

                   

                         

  •                        

    empty

                         

  •                      

  •                        

    unresolvedItem

                         

  •                      

  •                        

    tooManyItems

                         

  •                    

                 

                   

                      displayErrors                    

                 

                   

Boolean

                 

                   

True=Display the errors False=Don’t display the errors

                 

           

           

The CSS classes for the People Picker widget are defined in the Office.Controls.css style sheet. You can override the classes and style the widget for your app.

           

For more information, see How to: Use the experimental People Picker widget in apps for SharePoint and Use the People Picker experimental widget in an app code sample.

                

                                 

         

           

                                              Desktop List View widget                            

                             

           

         

         

                                                 

Your users can benefit from the List View widget and display the data in a list just like the regular List View widget, but you can use it in your apps that are not necessarily hosted in SharePoint.

           

Figure 3. Desktop List View widget displaying the data in a list

           
            Desktop List View experimental control on a page            

You can specify an existing view on the list, the widget renders the fields in the order that they appear in the view.

           

                                                                                                                               

                    Note                     Note                  
                   

At this moment, the Desktop List View widget only displays the data. It doesn’t offer editing capabilities.

                 

           

           

You can provide a placeholder for the widget using a div element. You can programmatically or declaratively use the widget.

           

You also can set properties or event handlers for the Desktop List View widget. The following table shows the available properties and events in the Desktop List View widget.

           

                         

           

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                   

Property/Event

                 

                   

Type

                 

                   

Description

                 

                   

                      listUrl                    

                 

                   

URL

                 

                   

URL of the list view to draw items from. It can be a relative URL in which case it will be assumed to be located on the app web itself or an absolute URL.

                 

                   

                      viewName                    

                 

                   

string

                 

                   

Name of the view to show. This is the programmatic name of the view (not its display name).

                 

                   

                      onItemSelected                    

                 

                   

Function

                 

                   

Event that fires when an item is selected on the list.

                 

                   

                      onItemAdded                    

                 

                   

Function

                 

                   

Event that fires when a new item is added to the list.

                 

                   

                      onItemRemoved                    

                 

                   

Function

                 

                   

Event that fires when an item is removed from the list.

                 

                   

                      selectedItems                    

                 

                   

Array

                 

                   

List of Selected items in JSON format.

                 

           

           

The widget requires the SharePoint website style sheet. You can reference the SharePoint style sheet directly or use the chrome widget. For more information about the style sheet, see How to: Use a SharePoint website’s style sheet in apps for SharePoint and How to: Use the client chrome control in apps for SharePoint.

           

To see the List View widget in action, see the Use the Desktop List View experimental widget in an app code sample. Also see How to: Use the experimental Desktop List View widget in apps for .                    

Widgets can help to speed up the development process and reduce the cost and time-to-market of your apps. Office Web Widgets – Experimental provide widgets that you can use in your non-production apps. Your feedback and comments are welcome in the Office Developer Platform UserVoice site.

                        

                            
 
 

Advertisements