Welcome to the third article in this series that explores how to use Kendo UI by Progress in SharePoint Online. In the previous article, we created a Visual Studio solution that adds a new feature to our SharePoint site collection. The purpose of that feature was to deploy required Kendo UI files to the style library of the site collection. Now 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.
How to Reference Kendo UI in SharePoint Solutions
No matter what JavaScript framework you want to work with in SharePoint Online (e.g. Angular), you would need to inject any related JS and CSS references into SharePoint's OOTB ASP.NET Master page. Kendo UI is no different. The recommended method of doing so depends on the type of SharePoint solution that you are deploying.
For declarative sandbox solutions
To our declarative sandbox solution (WSP), add a feature named "Kendo UI References". This feature will use custom actions to inject the references into the ASP.NET master page. At this point, we will be able to use Kendo UI controls on any page within our site collection.
In the previous post, we already took care of including the following Kendo UI JS files that are required, and will be deployed into a Kendo UI sub-folder of the SharePoint site's style library:
- /js/jquery.min.js
- /js/kendo.all.min.js
Right click on the Features folder in the Visual Studio project and "Add Feature". It will add as "Feature1", but you can rename it. Add one feature with the following details:
Name: References
Title: _KendoUI.SharePoint.Sandbox Kendo UI References
Description: This features deploys the required Kendo UI CSS and JS files to the Style Library and then injects the necessary references into the Master Page.
Scope: Site
From the Visual Studio project menu, select "Add Item" and choose "Empty Element" from the SharePoint section. Give it the name "KendoUIReferences".
The Elements.xml file will open automatically in Visual Studio. Add the following custom actions. For the JS files:
<CustomAction
ScriptSrc="~SiteCollection/Style Library/KendoUI/js/jquery.min.js"
Location="ScriptLink"
Sequence="110" />
<CustomAction
ScriptSrc="~SiteCollection/Style Library/KendoUI/js/kendo.ui.min.js"
Location="ScriptLink"
Sequence="120" />
The following set of Kendo UI CSS files is required, as referenced from the Content Delivery Network (CDN):
- http://kendo.cdn.telerik.com/2016.1.412/styles/kendo.common-office365.min.css
- http://kendo.cdn.telerik.com/2016.1.412/styles/kendo.office365.min.css
- http://kendo.cdn.telerik.com/2016.1.412/styles/kendo.dataviz.min.css
- http://kendo.cdn.telerik.com/2016.1.412/styles/kendo.dataviz.office365.min.css
Here is a sample of one custom action to inject the CSS reference into the master page. Note that we cannot directly reference a CSS file the way we typically inject a JS file into the master page. We are using a "trick" here with the custom action where we are getting it to do a "document.write" to "inject" the CSS reference into the page:
<CustomAction Location="ScriptLink"
ScriptBlock="document.write('<link rel="stylesheet" type="text/css" href="http://kendo.cdn.telerik.com/2016.1.412/styles/kendo.common-office365.min.css"></' + 'link>');"
Sequence="100" />
Create three more custom actions for the other CSS files, with sequences of 101, 102 and 103 respectively.
Your Visual Studio project will now appear as follows:
Deploying the Declarative Sandbox Solution
We are now ready to package our SharePoint solution and deploy it to our SharePoint Online site, allowing us to use Kendo UI within our SharePoint web pages.
For a declarative sandbox solution, please double check that the "Include Assembly in Package" property of the Visual Studio Project is set to False.
Double-click on the Kendo UI feature and examine the feature designer, ensuring that the KendoUIIcon and the KendoUI Modules are in the "Items in the feature" section. Please add them if they are not.
While this feature designer is open, check the Properties window. There are some important best practices I would like you to employ:
- Set the "Always Force Install" to "True" to help ensure, for instance, that updated files get overwritten when the solution is updated.
- Fill in the image URL to be a reference to the icon we deployed with our solution. Specifically set this to "../../../Style Library/KendoUiIcon/kendoui_icon.ico". It is a very professional touch to add a Feature Icon – and you will see the result shortly. It has been stated that it is not possible to have a Feature Icon in a sandbox solution, but this technique shows that not to be true.
- Set the image alt text to "Kendo UI"
- Set the version to 1.0.0.0. There is a possibility that "Feature Upgrade" capabilities may come in handy, and it's best to have a version number populated you can baseline to.
The Feature properties should look as follows:
Double-click on the "References" feature and examine the feature designer, ensuring that the KendoUIReferences Element is in the "Items in the feature" section. Please add this if it is not.
Please also set the feature properties, as was done for the Kendo UI feature.
To build the SharePoint solution WSP and deploy it to the Solution Gallery of our site, right click your Visual Studio project and choose "Publish…". The following dialog will appear:
Choose the first option, fill in your site collection's URL (in my case http://telerik.kendoui.sharepoint/sites/sandbox/) and click the Publish button. We will now see the Solution Gallery of your site collection open up in the browser:
Select the KendoUI.SharePoint.Sandbox solution in the Solutions Gallery and then click on the Activate button in the ribbon. We will get a pop-up dialog, once again press the "Activate button in the ribbon.
A very important note: You may see a message about sandbox solutions having a quota, and if you go over it, your solution will be temporarily disabled. Be assured that a declarative sandbox solution consumes ZERO resources. Resources are only used by compiled C# code (DLLs). So, since we've not included the DLL in our sandbox solution, we correspondingly won't trigger resource consumption.
Let us check our feature activation by looking at Site Settings -> Site Collection Administration -> Site Collection Features. We should observe that our two solution features are present and are in status "Activated" as follows:
We can also verify from "View Source" in the web browser that the file references above have indeed been injected into the page.
Test Using Kendo UI Online Sample
To test if our Kendo UI references are working, let's refer to the Kendo UI basic grid sample. The steps required to get the sample working in our SharePoint Online Team Site:
-
From Site Settings, choose "Add a page", call it "Basic Grid Sample"
-
The page will appear in edit mode. Use the ribbon to "Edit Source" and place the following HTML snippet. Click OK.
-
Using the ribbon, choose to "Insert a Web Part". Choose the Script Editor Web Part from the "Media and Content" group and place it on the page.
-
Using the web part drop-down menu, choose to "Edit Web Part". Then choose the "Edit Snippet" link.
-
Paste in the following, which is an exact cut and paste from the Telerik web page:
<script>
$(document).ready(function () {
$("#grid").kendoGrid({
dataSource: {
type: "odata",
transport: {
read: "//demos.telerik.com/kendo-ui/service/Northwind.svc/Customers"
},
pageSize: 20
},
height: 550,
groupable: true,
sortable: true,
pageable: {
refresh: true,
pageSizes: true,
buttonCount: 5
},
columns: [{
template: "<div class='customer-photo'" +
"style='background-image: url(../content/web/Customers/#:data.CustomerID#.jpg);'></div>" +
"<div class='customer-name'>#: ContactName #</div>",
field: "ContactName",
title: "Contact Name",
width: 240
}, {
field: "ContactTitle",
title: "Contact Title"
}, {
field: "CompanyName",
title: "Company Name"
}, {
field: "Country",
width: 150
}]
});
});
</script>
- Close the editor, click OK in the web part edit pane and save the page.
Your page should now appear similar to the following:
KEY POINT! Because we have deployed the Kendo UI files and injected the references into the Master Page, any web page in the site collection is now capable of hosting ANY Kendo UI Control, using the same technique of source editing and the Script Editor web part!
Conclusion
In this article, we learned how to reference the deployed JavaScript and CSS files so that we can start using Kendo UI components in SharePoint Online.
We can now create new OOTB SharePoint web pages and configure Kendo UI widgets using just the page editing tools! We also learned how to package and deploy the customizations.
What's Next
Next in our article series is "How to Use a SharePoint List as a Data Source for Kendo UI". In almost all cases of wanting to use Kendo UI in SharePoint Online, certainly a SharePoint list will be required to store underlying data or documents.
You will learn not only the specifics of accessing a SharePoint list via the REST API, but also details of the underlying structure and schema, so that you will be able to provision your own custom SharePoint lists along with your solution.
Related resources: