Installing Node.js

The following steps must be initiated if you wish to install Node.js on your Windows machine:

1. Browse to https://nodejs.org/en/download/ and download the distribution that is supported by your machine (.msi or .exe). I used the Windows 64-bit distribution for my Windows 10 machine.

2. Execute the download setup. On the main screen, click Next (Figure 8-3).

   

   Figure 8-3. Main Node.js installation screen

3. On the second screen, check the “I accept the terms in the License Agreement” and click Next (Figure 8-4).

   

   Figure 8-4. Node.js License Agreement

4. On the next screen, keep the default path and click Next (Figure 8-5).

   

   Figure 8-5. Node.js installation path

5. On the Custom Setup screen, keep all default options by default and click Next (Figure 8-6).

   

   Figure 8-6. Node.js Custom Setup screen

6. On the next screen, click the Install button and accept any confirmation from the User Account Control (UAC) (Figure 8-7).

   

   Figure 8-7. Node.js Initiate installation screen

7. Wait for the installation process to finish and click Finish (Figure 8-8).

   

   Figure 8-8. Node.js completed installation

8. To confirm the installation, launch a new command prompt window and type in the following command: node -help.

9. If the installation was successful, you should now see an exhaustive list of all available Node.js commands, as shown in Figure 8-9.

   

   Figure 8-9. Node.js help content

Installing Yeoman SharePoint Generator

As in the case for the Visual C++ Build Tools 2015 (see the preceding “Node Packet Manager” section), we will be using the NPM to acquire and install the Yeoman SharePoint generator on our machine. The following steps will guide you through the installation process :

1. Open a new command prompt as an administrator.

2. Execute the following commands:

   npm install -g yo
   npm install -g @microsoft/generator-sharepoint

   Executing the preceding command will automatically retrieve, download, and install the SharePoint Generator.

3. Upon completion of the installation, you should see displayed in the output window a list of the components that were just installed (see Figure 8-13 for an example).

   

   Figure 8-13. Completed installation of the Yeoman SharePoint generator

If you are like me and are always curious by nature, you may wonder what exactly has been downloaded to your machine by executing the preceding command. By default, the Node Package Manager keeps all its packages under the following path:

C:Users<user name>AppDataRoaming
pm
ode_modules

If you navigate to this location, you will find a folder named generator-sharepoint that contains all the files associated with our generator. While I will not be covering the creation of a Yeoman generator in this chapter, it may be useful for you to take a look at the index.js file located under the /app folder. It contains the execution flow for the Yeoman SharePoint generator.

Scaffolding a Project

Once the Yeoman SharePoint Generator has been properly installed on your machine, we can initiate the scaffolding process for a SharePoint Framework project. Before initiating a scaffolding operation, which will generate a good number of files, I recommend that you go ahead and create a new folder somewhere on your development machine. This will ensure that we keep everything isolated. In my case, I will be creating a new folder called SPFxDemo, which will be located directly at the root of my c: drive (Figure 8-14).

Figure 8-14. New empty folder at the root of my C: drive

Open a command line console and navigate to the newly created folder. To initiate the scaffolding operation, simply type in the following Yeoman command in your console:

yo @microsoft/sharepoint

Upon executing this line of code, Yeoman will prompt you to specify a name for the solution you are about to create. Pick a name and press Enter. In my case, the solution will be called SPFxDemo1. Upon entering a name for your solution, Yeoman will then proceed to ask you if you wish to reuse the current folder to create the solution in, or if you wish for it to create the folder structure for you. In our case, since we already created an isolated folder, we will simply choose the option to use the current folder. Yeoman is currently only allowing us to create client web part projects. It will, therefore, ask you to pick a name for that new web part you are about to create. For this example, we will be naming our web part “StockPrices.” Yes, you’ve guessed right, our example will be about creating a client web part that allows us to display the current stock price of a given registered company. Input the name for the web part and provide a description of what it will be doing, as shown in Figure 8-15.

Figure 8-15. Yeoman inputs for a new client web part

The last prompt from Yeoman will ask you to pick what flavor of JavaScript you wish to use for your solution. Based on your choice, Yeoman will properly scaffold your solution to include any dependencies required by the library you chose. In either case, we want to keep things “low-level,” in order to properly demonstrate how everything works internally. We will, therefore, be choosing the option “No JavaScript web framework,” which will allow us to use pure JavaScript as our programming language. Upon choosing what flavor of JavaScript to use, Yeoman will go ahead and generate all the required files for us. If everything went as planned, you should see something similar to Figure 8-16 in your PowerShell session.

Figure 8-16. Results from a successful Yeoman scaffolding operation

Once the operation has completed, you can open Windows Explorer and take a look at the files that were automatically generated. If you were to look at the properties for your folder, you would see that there are more than 30,500 files that have been generated, together representing over 208MB of data (see Figure 8-17). Note that these numbers are subject to change as updates are made to the framework.

Figure 8-17. Files generated by Yeoman and their associated file size

Command Line Operation

While initiating the Scaffolding operation by simply calling the Yeoman generator is an effective way of getting started with the SharePoint Framework, you may be wondering if there is a more direct way to generate the files, or at least to automate this operation. Every Yeoman generator allows users to pass in the required parameters directly, so we are in luck. No need to manually answer each question every time Yeoman requires information (e.g., solution name, web part name, web part description, etc.). Instead, we can simply pass all these values at once, upon calling the Yeoman generator, and have the files generated with a simple line of code.

On top of accepting parameters directly, every Yeoman generator also defines a help switch that can be called with --help and provides additional information about the parameters that are accepted (see Figure 8-18). In the case of the SharePoint Yeoman generator, this help feature can be accessed by using the following command:

Figure 8-18. Help output for the SharePoint Yeoman generator

yo @microsoft/sharepoint --help

Based on Figure 8-18, we can see that the generator only requires values for four parameters: solutionName, componentType, componentName, and framework. Therefore, we are not required to pass the web part’s description as a parameter. If we want to initiate the scaffolding of a new SharePoint Framework client web part with a single line of code, we can do so by calling the following:

yo @microsoft/sharepoint:app --solutionName="SPFxDemo1" --componentType="webpart" --componentName="StockPrices" --framework="none" --component-description="Displays the Stock Price for a given Organization"

With Yeoman, arguments must be provided in the order they are defined. In our case, if we look at the result from the help operation (Figure 8-18), the first argument is solutionName, and the last one is to be framework. Options, on the other hand, are to be provided as a key/pair entry. If you pay closer attention to the preceding code example, you can see that the web part’s description is passed using the --component-description= clause. Calling the preceding command will automatically initiate the scaffolding of the SharePoint client web part project into a new folder called SPFxDemo1. Figure 8-19 shows the execution of this command to initiate the scaffolding operation.

Figure 8-19. Yeoman scaffolding of a SharePoint client web part by passing arguments

Overview of the Ecosystem with Yeoman

To recap what we have covered so far, the new Microsoft SharePoint Framework requires Node.js to render files to the user. It acts as a web server to render content. The files to be rendered by Node.js are generated by Yeoman, using the SharePoint generator that is provided by the SharePoint Product Group. Figure 8-20 shows the evolution of the SPFx ecosystem with the pieces we’ve covered thus far.

Figure 8-20. The SharePoint Framework ecosystem with Node.js and Yeoman

Installing Gulp

As in the case for Yeoman, we will be using NPM to install Gulp onto our development machine. To initiate the installation process, make sure you navigate to the folder where your files have been generated by Yeoman and simply execute the following command (Figure 8-21 shows the execution of the command):

Figure 8-21. Gulp installation using NPM

npm install gulp-cli -g
npm install gulp -D

Serving Pages with Gulp

Now that Gulp is properly installed on our development box, we can go ahead and have Gulp initiate a pipe to server our files and allow us to render the content of our solution. In order to initiate the Gulp process, you must execute the following command (make sure you navigate to the root of your solution folder first, e.g., C:SPFxDemoSPFxDemo1):

gulp serve

Because Gulp uses an SSL end point to serve the pages, it requires a developer to configure a default certificate, in order to render the pages through HTTPS. If you simply run the preceding command, you will receive the following warning in your console (Figure 8-22):

Figure 8-22. Certificate error running Gulp

Warning - [serve] When serving in HTTPS mode, a PFX cert path or a cert path and a key path must be provided, or a dev certificate must be generated and trusted. If a SSL certificate isn't provided, a default, self-signed certificate will be used. Expect browser security warnings.

Luckily for us, the framework comes with a developer certificate that we can use to get around this error. This development certificate can be easily configured by simply executing the following Gulp command:

gulp trust-dev-cert

Upon executing this command, you will be prompted to install the certificate, as seen in Figure 8-23. Simply click Yes to have the certificate installed and configured.

Figure 8-23. Installation prompt for the SharePoint Framework developer’s certificate

With the certificate configured, you can now initiate a new Gulp process, by running Gulp Serve, and this time, you shouldn’t receive any certificate errors and be able to view the SharePoint Framework workbench, as shown in Figure 8-24. What you are seeing here is what we refer to as the SharePoint Framework workbench. It is the component that allows you to locally test your solution without having to deploy it to Office 365.

Figure 8-24. SharePoint Framework workbench

Overview of the Ecosystem with Gulp

We have now completed the tour of our SharePoint Framework tool chain that is used to serve our solutions locally. Figure 8-25 gives a complete picture of what the three main pillars of the SharePoint Framework are and how they each fit within the bigger picture.

Figure 8-25. Complete SharePoint Framework ecosystem with Gulp

Creating Your First Client-Side Web Part

Let us now look at how we can get started and create our very first Client-Side Web Part. By default, the Microsoft Yeoman generator automatically generates all the required files for our web part. If you remember correctly from the previous examples, we have already created our Client-Side Web Part called StockPrices . In fact, if you just attempt to run gulp serve on the project folder created earlier, you will see that the workbench already allows you to add that web part to your page (see Figure 8-27).

Figure 8-27. New Client-Side Web Part showing on the workbench

If we were to add this web part to the workbench as it stands, it would simply generate generic HTML to indicate that no logic or content has been included with that web part (see Figure 8-28).

Figure 8-28. Adding a newly created Client-Side Web Part to the local workbench

If you take a closer look at the set of files that were automatically generated by the Microsoft Yeoman generator, you can see that under the src folder, we have a folder named webparts, which contains a subfolder having the name we gave to our solution (see Figure 8-29).

Figure 8-29. Generated content for our Client-Side Web Part

To modify the code of our web part, I will be using Visual Studio 2017; however, feel free to use whatever your favorite editor software happens to be, because remember that in the end, all we will be editing is HTML and JavaScript. Inside of Visual Studio, I will simply choose the option to open a folder and will browse to the C:SPFxDemoSPFxDemo1 folder I created earlier (see Figures 8-30 and 8-31).

Figure 8-30. Opening a folder in Visual Studio 2017

Figure 8-31. Viewing our Client-Side Web Part folder with Visual Studio Solution Explorer

The file we are interested in modifying first is named StockPricesWebPart.ts and is located directly under our stockPrices folder. This is a TypeScript file, and it contains the core logic for our Client-Side Web Part. If you take a closer look at the render() method in there, you will see that it is where the HTML printed out by default when we add our web part to the workbench is declared. For the purpose of our example, our web part will accept the name of an organization as part of its properties and will randomly display a fictive stock quote for that given organization. To achieve this, we will start by modifying the render() method , by replacing its entire content with the following:

public render(): void
{
    this.domElement.innerHTML = `<div id="StockPricePanel">
      <p>The stock price for ${escape(this.properties.Organization)} is ` +
      Math.round((Math.random()) * 100).toString()+ `$</p>
    </div>`;
}

This tells the web part that upon rendering its output back to the client, it has to display a sentence that will use the provided organization name in the properties panel, along with a random number between 0 and 100. This may not be the most exciting web part ever created, but the important thing here is to ensure that you have an overview of the various pieces involved in creating a new Client-Side Web Part.

Simply trying to run a Gulp process with this code in place will generate errors, because TypeScript doesn’t know anything about that Organization property we just specified. For us to make TypeScript aware of the fact that this property exists, we have to define it in our web part’s interface, which is named IStockPricesWebPartProps.ts. Replace the entire file’s content with the following:

export interface IStockPricesWebPartProps
{
    Organization: string;
}

This tells our web part that we must expose a custom property named Organization and let the users be able to modify its value. Now, if you go back to our main web part file (StockPricesWebPart.ts), we will modify the property panel to reflect the new Organization property we wish to capture. At the bottom of the file, there is a method defined, which is called getPropertyPaneConfiguration(). This method is expected to return a structured set of properties and values that will contain information about how our web part’s property panel will be displayed to the user. We are particularly interested in changing the labels that will be displayed, to show messages that are specific to the Organization property we are trying to capture. If you pay close attention to the structure returned by this method, you’ll see a section named groupFields. This is the section we wish to modify, to affect the rendering of the property panel. Replace the entire content of the groupFields section by the following lines of code:

groupFields: [
    PropertyPaneTextField('Organization', {
        label: strings.OrganizationLabel
    })
]

We are almost there. We now have only to make two more minor modifications for our web part to be functional again. As part of the groupFields property that we just modified, we are now specifying that the property we will be capturing is a property named Organization, and that the field that is exposed in the web part property panel allowing the user to enter a value should have a label defined in a localized string variable named OrganizationLabel. This localized string must be defined in a TypeScript definition file named mystrings.d.ts, which is located under the /src/webparts/<project name>/loc folder. Open the file and replace the content of the IStockPriceStrings interface with the following lines of code:

declare interface IStockPricesStrings {
    PropertyPaneDescription: string;
    BasicGroupName: string;
    OrganizationLabel: string;
}

We have now defined that our property panel will expose a localized label named Organization, but we have not specified what the value for that label should be. By default, our web part is localized for English US and, therefore, under the loc folder, you will find a JavaScript file named en-us.js that will contain the localized values for our labels. Open that file, replace the default labels, and add our new one, by replacing the entire content with the following lines of code:

define([], function() {
  return {
    "PropertyPaneDescription": "Stock Price Properties",
    "BasicGroupName": "Settings",
    "OrganizationLabel":"Patate"
  }
});

Our web part is now fully functional. As mentioned previously, the purpose of this example is not to build a real-life web part that you can use immediately in your production environment. It is, rather, to give you all the information and tools you need to get started on your own projects.

Packaging Your Client-Side Web Part

Once you are done making the changes to your web part, you are ready to bundle it into a .sppkg package. We will need to use Gulp to achieve this. In a new console, browse to your project’s folder and type in the following line of command:

gulp package-solution --ship

This will automatically generate your .sppkg package, under the folder <project path>/SharePoint/solution/ (see Figure 8-33).

Figure 8-33. SharePoint Client-Side Web Part Package generation

Deploying Your Client-Side Web Part

The question you are probably asking yourself now is how to actually deploy this Client-Side Web Part onto your Office 365 tenant. This is actually done the same way you would deploy a SharePoint Add-in: via the Add-in Catalog. To deploy your web part to the rest of your organization, simply navigate to your Office 365 tenant’s Add-in Catalog and browse to the Apps for SharePoint library (see Figure 8-34).

Figure 8-34. Apps for SharePoint in a SharePoint Online Add-in Catalog site

Once you are in the library, simply click the Upload button to open the browse dialog that will allow you to select our web part file. Browse to the .sppkg package created in the previous section and upload it into the library. Upon completion of the upload process, SharePoint will automatically prompt you to trust your new web part (see Figure 8-35). Simply click Deploy, to have that new Client-Side Web Part available to the rest of your organization.

Figure 8-35. Deploying a Client-Side Web Part via the Add-in Catalog

Reuse Your Client Side Web Part

Now that your web part has been properly deployed in the Add-in Catalog, you can go and install it onto any SharePoint site within your organization. Because it has been deployed through the catalog, in order to use it within a site, you must proceed the same way you would if it were a SharePoint Add-in: you need to install it at the web level. The first thing you have to do is navigate to the site in which you wish to use your newly created Client-Side Web Part. Once you are there, click the Site Action icon at the top right (cog icon), then select Add and App. In the left navigation, select From your Organization. This will automatically filter the list of available add-ins and display our newly uploaded solution (see Figure 8-36).

Figure 8-36. Adding our custom Client-Side Web Part solution to a SharePoint site

From there, simply click your solution’s icon, to install it onto your SharePoint site. Once the installation completes, you will be able to access your web part, by editing a page on your site (see Figure 8-37).

Figure 8-37. Adding a custom Client-Side Web Part to a page