Using Kendo UI in SharePoint Online Pt. 2 - Development Options

Welcome to the second article in this series that explores how to use Kendo UI by Progress in SharePoint Online. Please review the previous article that serves as a guide to getting-ready to create SharePoint Solutions with Visual Studio.

Developers have several choices regarding how to build out and deploy their SharePoint customizations. We will look at Declarative Sandbox Solutions, SharePoint Add-Ins (Apps), and the newer SharePoint Framework. You will find the knowledge contained within Declarative Sandbox Solutions reused within the other article topics, so please be sure to give this article a thorough read regardless of which development option you ultimately select.

SharePoint Declarative Sandbox Solution

In this topic, we will create the baseline solution that we will build upon during successive articles and topics. The solution will begin by deploying what is necessary to run Kendo UI widgets in SharePoint Online.

The "classic" method used to build on-premise solutions for years has been the native SharePoint Solution packaging format of WSP. Visual Studio will build the deployment file which is a CAB file format with an extension of WSP. The solution contains Site Collection and Site (Web) level features that become activated and deploy "elements" (such as CSS/JavaScript/image files, schema, lists, branding, and much more).

The full trust version of a SharePoint solution deploys to an on-premise SharePoint farm. The sandbox version of a solution deploys to the solution gallery of a single site collection. If you exclude the "code" (the .NET Assembly / DLL), you are left with a "declarative sandbox" solution.

The declarative sandbox solution is still 100% valid in the current world of SharePoint Online, and it has served me extremely well in the past few years because the features you deploy can apply across the entire site collection. Further, you can deploy a modern front-end web application because "code" refers to a compiled .NET Assembly (DLL) and not to something like JavaScript code.

Create the Visual Studio Solution

In Visual Studio, create a new project. From the Office/SharePoint -> SharePoint Solutions section, choose the "SharePoint Empty Project". Name the Visual Studio Solution "KendoUI.SharePoint.Sandbox". After clicking OK, put in the URL of the SharePoint Team Site Collection you have created and be sure the "Deploy as a sandboxed solution" option is selected.

Important! Click on the Visual Studio Project in the Solution Explorer and ensure the "Include Assembly in Package" option is set to "False".

You may have heard that Microsoft will disable Sandbox Solutions in SharePoint Online. Well, that does not apply to "Declarative Only" Sandbox solutions. However, if this option is True, Visual Studio will include the DLL in the package anyways and you will not be able to activate this solution in SharePoint Online.

Add and Configure a Feature

To "extend" SharePoint with customizations, we add features. This is done in the same place as the site settings when you look at the OOTB Site Features and Site Collection Features that SharePoint provides.

Right click on the Features folder in the Visual Studio project and "Add Feature". It will add as "Feature1", but you can rename it. Double click on the feature in the Solution Explorer to bring up the Feature Designer in Visual Studio. Add one feature with the following details:

Name: KendoUI Title: _KendoUI.SharePoint.Sandbox Kendo UI Description: This feature deploys the Kendo UI assets to the Site Collection style library (in the root web). Scope: Site

Add a Module and Element

An element in a SharePoint project contains provisioning instructions in the Collaborative Application Markup Language (CAML). A "module" is a type of element that provisions files. Here we will provision the required Kendo UI files and references into our SharePoint Site Collection.

From the Visual Studio project menu, select "Add Item" and choose "Module" from the SharePoint section. Give it the name "KendoUIIcon".

You will see a "Sample.txt" file appear in the KendoUIIcon project folder, go ahead and delete that.

I have the following Kendo UI Icon file (kendoui_icon.ico):

I just dragged and dropped this into the KendoUIIcon folder of the Visual Studio Solution. Here's a peek at my Visual Studio solution so far showing the two features added as well as the "KendoUIIcon" folder:

Let's look at the Elements.xml when that Kendo UI Icon was dragged into the folder:

<?xmlversion="1.0"encoding="utf-8"?>
<Elementsxmlns="http://schemas.microsoft.com/sharepoint/">
  <ModuleName="KendoUiIcon">
    <FilePath="KendoUiIcon\kendoui\_icon.ico"
        Url="KendoUiIcon/kendoui\_icon.ico" />
  </Module>
</Elements>

"Module" implies we are provisioning a file into the SharePoint site. The File indicates the FROM Path, relative to the solution folder – which is KendoUIIcon, and so this is as it should be. The URL indicates where the file is to be copied TO in the SharePoint site. Visual Studio does not know where you actually want to put the files, so we provide the URL="Style Library" to indicate to put the files in the Style Library we pointed out in the first article.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="KendoUiIcon" Url="Style Library">
    <File Path="KendoUiIcon\kendoui_icon.ico"
        Url="KendoUiIcon/kendoui_icon.ico"
        Type="GhostableInLibrary" ReplaceContent="TRUE" />
  </Module>
</Elements>

Best Practice Tip: Notice I added the "Ghostable In Library" and "Replace Content" attributes to the File. The more important attribute to understand here is "Replace Content" – meaning that should you ever update the solution with a newer file, you are assured that the current version would be overwritten. This is certainly the behavior you want! You do not want to find out after deploying an update that, for instance, a JavaScript file is still the old version.

Add Module and Element for Kendo UI

The time was taken to explain the deployment of a simple Icon file, as the same technique applies to the files that are required by Kendo UI. We will be using the Kendo UI Grid, so the necessary JavaScript files we need to include are:

• /js/jquery.min.js
• /js/kendo.all.min.js

You may note that Kendo UI would also require the associated CSS files, but the next section will show a different technique for referencing the CSS files from the Content Delivery Network (CDN).

From the Visual Studio project menu, select "Add Item" and choose "Module" from the SharePoint section. Give it the name "KendoUI". Delete the "sample.txt" file. Create a "js" subfolder.

From your Kendo UI source files, drag the two referenced JavaScript files into the "js" subfolder of Kendo UI. Your Visual Studio project will now appear as follows:

Don't forget to add the Style Library URL to the Module and the "GhotableInLibrary" and "ReplaceContent" attributes to the Files. The Elements.xml file will look as follows:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="KendoUI" Url="Style Library">
    <File Path="KendoUI\js\jquery.min.js"
Url="KendoUI/js/jquery.min.js"
Type="GhostableInLibrary" ReplaceContent="TRUE" />
    <File Path="KendoUI\js\kendo.all.min.js"
Url="KendoUI/js/kendo.all.min.js"
Type="GhostableInLibrary" ReplaceContent="TRUE" />
  </Module>
</Elements>

Great! We will now have the files we need for Kendo UI deployed to the Style Library of our Site Collection. Next we will need to "inject" the required CSS and JavaScript references into the SharePoint MasterPage so we can start using Kendo UI in SharePoint Online.

Also if you are deploying any type of "asset" into SharePoint Online, it is a best practice to place those files in a folder of the Style Library, as these assets can now be referenced anywhere within the site collection. Assets include JavaScript, CSS and images.

SharePoint Hosted Add-In

Everything you have learned about creating declarative elements in a sandbox solution will apply 100% to creating a SharePoint-Hosted Add-in (previously known as a SharePoint app). There are a few nuances and considerations in choosing to use a SharePoint add-in versus a declarative sandbox solution.

We'll cover this topic in a future article where we'll rework this SharePoint example in an add-in style.

Remember that in the getting-started section, I referred to the " Get started creating SharePoint-hosted SharePoint Add-ins" article. You can finish this getting-started article by writing the sample Employee Orientation Add-In.

In the meantime, my colleague Rob Windsor had an excellent course on Pluralsight, if you want to know everything there is to know about developing SharePoint add-ins.

SharePoint Framework

A new model of SharePoint development is evolving to better support web front end technologies and frameworks – for example those who develop with Angular and React. This is the SharePoint Framework (SPFx).

It's still in an early stage, though! At the time of writing this article, it is still in preview. However, do not wait to explore this new SharePoint Framework. You can download SPFx on GitHub and create your first web part.

Progress recently published an excellent white paper that already has an example of using the SharePoint Framework, Kendo UI and Angular to build a web part. By all means, check it out.

I'll return to this in a future article to rework the SharePoint example presented above using the SharePoint Framework style.

Conclusion

In this article we learned there are two currently supported development models for SharePoint Online and a third in production:

• Declarative Sandbox Solutions
• SharePoint Add-In
• SharePoint Framework

Each development model is a valid choice for different reasons and will depend on your current expertise and specific needs.

What's Next

Next in our article series is "How To Reference Kendo UI in SharePoint Solutions". We'll look at how to reference the deployed JavaScript and CSS files so that we can start using Kendo UI components in SharePoint Online.

This is where it gets exciting! By the end of the next article, you will be able to create new OOTB SharePoint web pages and configure Kendo UI widgets using just the page editing tools. So do come back for more - next week.

Related resources:

• Other articles in this series:
  • Introduction to Using Kendo UI in SharePoint Online – A “How To” Series
  • Kendo UI in SharePoint Online Pt. 3 – Referencing Kendo UI
  • Kendo UI in SharePoint Online Pt. 4 – SharePoint Lists
• Introduction to Using Kendo UI in SharePoint Online – A “How To” Series (Pt. 1 in this series)
• Preparing Your Toolbox for the SharePoint Framework with Angular, Webpack and Kendo UI (Whitepaper)
• How to Prepare Your Toolbox for the SharePoint Framework (blog)
• Moving into the Modern Age of SharePoint Development (blog)
• Building SharePoint Add-ins with Kendo UI (tutorial)