Chapter 4
Developing Custom Web Parts
We will now shift and look at a very code-centric piece of SharePoint. There are several things that can be coded on the backend, the most common of which is the custom web part. A web part is code that works behind the scenes and presents a viewable interface to users after it has been placed somewhere on the SharePoint site’s layout. Web parts are written in .NET and are compiled in Visual Studio. The compiled code is then deployed to SharePoint and can be added to the site. In this chapter, we will go through the steps required to build and deploy a web part.
A Few Thoughts on Level of Effort
Before we look at the specifics of development, let’s first discuss how best to scope the level of effort in building these components. All of us have been asked for estimates to build out components for platforms that we may not be completely familiar with. “How many hours will it take you to build out X and present it in Y?” In this case, there is an easy way to estimate a web part (assuming you are already a .NET developer). The following items will guide you to your estimate:
–If this is your first web part, give yourself about four to eight hours to prepare. This includes getting Visual Studio up-to-date so you can build, figure out how to deploy, and write simple code base (like that shown in this exercise).
–There are client-side web parts, which can be coded that consist of HTML and JavaScript. If you are going to build these, you can use a new command line-based tool called the SharePoint Client-side Solution Generator. While this tool is a poor development alternative to Visual Studio, it does give you options to test and view your web part without having to deploy it to Share-Point first (as opposed to Visual Studio, which requires that you deploy first in order to test). The bane of web part developers in older versions of Share-Point is the fact that testing took a lot of extra steps (due to having to deploy first). Realizing that the solution to this is the SharePoint Client-side Solution Generator can be disappointing, but it is an option. Give yourself about four to eight hours to ramp up on this tool and then make the decision to skip it and build web parts the old-fashioned way—in Visual Studio!
–For the meat of the standard web part—the portion of the code that does work—determine how long it would take you to code it in a .NET windows application. For example, in this chapter we look at calling a web API that returns stock information. It might take an hour or two for you to work through this, test it, and ensure your code is ready to go. In cases where you have complex functionality in your web part, and you are interacting with SharePoint components and building out complex visuals, give yourself substantially more time to test and debug than you usually would. If you think it would take you two hours to code, give yourself four to six hours.
–Deploying your web part and configuring your site to display it only takes a few minutes, so you might want to estimate and hour or so for deployment activities. Chances are good that you will have to deploy multiple times as you test it, recode, and redeploy it.
–You will spend a lot of your time testing your web part. Using the Visual Studio approach to developing (as opposed to the Client-side Solution Generator), you really can’t test your web part unless you put your code in a test app. In many cases, you can develop your web part code in a simple Visual Studio Windows application, test it, and then simply move that tested code into the web part framework and deploy it. But, if your web part is heavy on visual functionality, you’ll have to deploy it to SharePoint before you can test it.
–A good rule of thumb for web part development would be as follows (you can use these guidelines if you are being asked to estimate on the fly, especially in an Agile project environment).
○For a simple web part, give yourself four to eight hours.
○For a web part of medium complexity, give yourself twelve to twenty-four hours.
○For a complex web part, give yourself forty or more hours.
Developing a Web Part
Let’s get into the details of development. In the example that we’ll work through, we are going to create a simple stock ticker. We want a user to be able to type in a stock symbol and get the current value of that stock in return. With this, you’ll be able to see all the steps required to create, deploy, and run a fully functional web part.
We’ll start by getting Visual Studio ready to go. You should use the latest version of Visual Studio for your work. Begin by creating a new project of type SharePoint Add-in, as shown in Figure 4.1. For this example, we’ll name it the “StockSymbolApp,” so enter this in the Name field.
Next, you’ll need to specify the targeted SharePoint site that you’ll want to deploy your solution to. There are two options to choose from:
- Provider-hosted—this is a solution that is hosted outside of SharePoint. For example, it could be on your own web server, within an Azure instance, or anywhere else. For complex functionality, including data that integrates with external systems from SharePoint, you may decide to host your code elsewhere.
- SharePoint-hosted—this is by far the most common and follows the classic path of web parts that were available in previous editions. With this option, your code is deployed to and resides within SharePoint itself.
In the case of this example, we will keep things simple and let SharePoint do the work (this is most likely what you will use as well), so select the SharePoint-hosted option (see Figure 4.2).
After clicking Next, you will get to determine which version of SharePoint you want to deploy to. Of course, and as you can see in Figure 4.3, for this exercise, select SharePoint Online. Once you select this option, click the Finish tab to complete this Add-In wizard process.
When the wizard completes, your solution will automatically be created for you in Visual Studio. Right click Pages in the StockSymbolApp solution and select Add and then New Item (refer to Figure 4.4). You will be creating a client web part page where you can build out your code that will display within the final web part.
In the window that opens, select the Office/SharePoint option on the left and then select the Client Web Part (Host Web) option from the right (see Figure 4.5).
Immediately after selecting Client Web Part (Host Web), the Create Client Web Part window shown in Figure 4.6 opens. Next, name the page that will be created. We’ll keep the StockSymbolApp name and then click the Finish button.
With that, you have created your containing page where code can be written (we will refer to this as Page.aspx). Next, you’ll need to include the correct references in your solution. This can be done by right clicking your project in Visual Studio and selecting the Manage NuGet Packages option. You’re going to add in the jQuery package that is shown in Figure 4.7.
When you have successfully referenced the jQuery package in NuGet, you’ll see the scripts added to your solution. As Figure 4.8 shows, there are several jQuery scripts that will be added.
Web Part Code
You can now begin coding your page! You’ll take the following steps, which you can do in whatever order you would like:
- Create a javascript file to store your custom jQuery code. For this example, we’ll call it “App.js.”
- Add a reference to the App.js file and jQuery file to your page.
- Add the visual content of your web part to the page ASPX file.
Listing 4.1 below shows the code for the App.js file that you need to add. For this example,
Listing 4.1: The App.js code for the example web part
This javascript code simply calls an existing REST service, publicly available online, and parses the JSON that is returned. Listing 4.2 below shows an example of the JSON that is returned by this. You can call the service from a browser to see your own results by using the following URL. Just replace the “MSFT” with whatever stock code you would like.
https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol-=MSFT&apikey=OW7YYNETTUQNT9N1
Listing 4.2: JSON returned by API call
When the App.js file has been completed, you can then add it to the script section of your Page.aspx file. You also need to remove the default script references and add a reference to one of the jQuery files that were added when you referenced the NuGet package. The script section of your file should look like that shown in Figure 4.9.
The next step is to add the custom code to the body of the page. This code represents the visual aspect of the web part and is what will display once the web part is added to a site within SharePoint. Listing 4.3 shows the code in the Page. aspx file with the revised script content and custom code within the <body> tag. The key pieces of functionality added to this web part are:
- The text box called “tickerSymbol,” where the user can type in the stock symbol they want to get results for. This tickerSymbol value is pulled into the URL in the JavaScript to make it dynamic.
- The “getQuote” button is clicked to initiate the call to the JavaScript in the App.js file. The getQuote onclick event is triggered when this button is clicked. Javascript will print out the HTML that converts the JSON returned by the service call.
Listing 4.3: The default Page.aspx code with the revised script references
With the coding complete, you can now deploy the project to SharePoint for testing. Right-click the project name and select Deploy (see Figure 4.10). This will deploy to the URL that you entered during the Add-in setup earlier in the chapter. If you want to change the URL, just open the properties on the project.
The build process takes places during the deployment, and the status of the build and deploy will display in your build output. A successful build will look like that shown in Figure 4.11.
The deployment having succeeded, you can now go into SharePoint and use the web part. You can add the web part to any existing page by editing the page and clicking the “+” icon or by adding it in from the toolbar. As you can see in Figure 4.12, your web part will display in the list of available items to add to your page. If your Visual Studio deployment was successful, the web part will automatically show in this list.
After selecting the web part, it will be added to the page. The example code that we built out in this chapter is shown in Figure 4.13. The web part is still in design mode—it must first be published before it will appear on the site for other users. But, you can test it while it’sin design. This is your opportunity to test and debug your code. Keep deploying and testing until you have it working the way you want, then click the Publish tab to share it directly on your site.
Summary
Focusing on building out a custom web part allows you to see the steps required to deploy .NET developed SharePoint components to your Online environment. There are several other types of customizable objects, but all of them follow a similar pattern. When determining the level of effort and scope of work, focus on the business requirement of the web part itself (what must it do functionally and what would that require to code in any .NET environment) and give yourself plenty of extra time for testing and debugging.