1. Microsoft Visual Studio For Mac
2. Sharepoint Client-side Web Part Visual Studio For Mac
3. Visual Studio For Mac Download

Getting started - creating a client web part “project” Seasoned SharePoint developers are used to opening Visual Studio and doing File > New > Project > and selecting one of the SharePoint templates, even if just an empty SharePoint project, or adding an item to an existing project using Add > New item > SharePoint > Empty element or similar. Creating SharePoint Application Pages with Visual Studio. SharePoint Application Pages provide truly flexible functionality across all the sites within a SharePoint front end. You can use Visual Studio to create those pages, with the added bonus of securing the content during development. And Web Part pages that contains Web Parts inside.

Client-side web parts are client-side components that run inside the context of a SharePoint page. Client-side web parts can be deployed to SharePoint Online, and you can also use modern JavaScript tools and libraries to build them.

Client-side web parts support:

• Building with HTML and JavaScript.
• Both SharePoint Online and on-premises environments.

[!NOTE]Before following the steps in this article, be sure to Set up your development environment.

You can also follow these steps by watching this video on the SharePoint PnP YouTube Channel:

[!Video https://www.youtube.com/embed/S3tG2DE8tR8]

The SharePoint Server 2013 Client Components SDK can be used to enable remote and local development with SharePoint Server 2013 Details Note: There are multiple files available for this download.

Create a new web part project

To create a new web part project

1. Create a new project directory in your favorite location.

2. Go to the project directory.

3. Create a new HelloWorld web part by running the Yeoman SharePoint Generator.

1. When prompted:

   • Accept the default helloworld-webpart as your solution name, and then select Enter.
   • Select SharePoint Online only (latest), and select Enter.
   • Select Use the current folder for where to place the files.
   • Select N to allow the solution to be deployed to all sites immediately.
   • Select N on the question if solution contains unique permissions.
   • Select WebPart as the client-side component type to be created.

2. The next set of prompts ask for specific information about your web part:

   • Accept the default HelloWorld as your web part name, and then select Enter.
   • Accept the default HelloWorld description as your web part description, and then select Enter.
   • Accept the default No javascript web framework as the framework you would like to use, and then select Enter.

At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the HelloWorld web part. This might take a few minutes.

When the scaffold is complete, you should see the following message indicating a successful scaffold.

For information about troubleshooting any errors, see Known issues.

Using your favorite Code Editor

Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your web part, such as:

SharePoint Framework documentation uses Visual Studio code in the steps and examples. Visual Studio Code is a lightweight but powerful source code editor from Microsoft that runs on your desktop and is available for Windows, Mac, and Linux. It comes with built-in support for JavaScript, TypeScript, and Node.js, and has a rich ecosystem of extensions for other languages (such as C++, C#, Python, PHP) and runtimes.

Preview the web part

To preview your web part, build and run it on a local web server. The client-side toolchain uses HTTPS endpoint by default. This setting can be configured in the serve.json file located in the config folder, but we do recommend using the default values.

Switch to your console, ensure that you are still in the helloworld-webpart directory, and then enter the following command:

[!NOTE]Developer certificate has to be installed ONLY once in your development environment, so you can skip this step, if you have already executed that in your environment.

Now that we have installed the developer certificate, enter the following command in the console to build and preview your web part:

This command executes a series of gulp tasks to create a local, node-based HTTPS server on localhost:4321 and localhost:5432. The workbench is then launched in your default browser to preview web parts from your local dev environment.

[!NOTE]If you are seeing issues with the certificate in browser, please see details on installing a developer certificate from the Set up your development environment article.If you are still seeing issues, please check nothing else is listening on the port numbers, by using resmon.exe, the network tab and looking at Listening Ports.

SharePoint client-side development tools use gulp as the task runner to handle build process tasks such as:

• Bundling and minifying JavaScript and CSS files.
• Running tools to call the bundling and minification tasks before each build.
• Compiling SASS files to CSS.
• Compiling TypeScript files to JavaScript.

Visual Studio Code provides built-in support for gulp and other task runners. Select Ctrl+Shift+B on Windows or Cmd+Shift+B on Mac to debug and preview your web part.

SharePoint Workbench is a developer design surface that enables you to quickly preview and test web parts without deploying them in SharePoint. SharePoint Workbench includes the client-side page and the client-side canvas in which you can add, delete, and test your web parts in development.

To use SharePoint Workbench to preview and test your web part

1. To add the HelloWorld web part, select the add icon (this icon appears when you mouse hovers over a section as shown in the previous image). This opens the toolbox where you can see a list of web parts available for you to add. The list includes the HelloWorld web part as well other web parts available locally in your development environment.

2. Select HelloWorld to add the web part to the page.

   Congratulations! You have just added your first client-side web part to a client-side page.

3. Select the pencil icon on the far left of the web part to reveal the web part property pane.

   The property pane is where you can define properties to customize your web part. The property pane is client-side driven and provides a consistent design across SharePoint.

4. Modify the text in the Description text box to Client-side web parts are awesome!

   Notice how the text in the web part also changes as you type.

One of the new capabilities available to the property pane is to configure its update behavior, which can be set to reactive or non-reactive. By default, the update behavior is reactive and enables you to see the changes as you edit the properties. The changes are saved instantly when the behavior is reactive.

Web part project structure

To use Visual Studio Code to explore the web part project structure

1. In the console, break the processing by selecting Ctrl+C.

2. Enter the following command to open the web part project in Visual Studio Code (or use your favorite editor):

If you get an error, you might need to install the code command in PATH.

TypeScript is the primary language for building SharePoint client-side web parts. TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. SharePoint client-side development tools are built using TypeScript classes, modules, and interfaces to help developers build robust client-side web parts.

The following are some key files in the project.

Web part class

HelloWorldWebPart.ts in the srcwebpartshelloworld folder defines the main entry point for the web part. The web part class HelloWorldWebPart extends the BaseClientSideWebPart. Any client-side web part should extend the BaseClientSideWebPart class to be defined as a valid web part.

BaseClientSideWebPart implements the minimal functionality that is required to build a web part. This class also provides many parameters to validate and access read-only properties such as displayMode, web part properties, web part context, web part instanceId, the web part domElement, and much more.

Notice that the web part class is defined to accept a property type IHelloWorldWebPartProps.

The property type is defined as an interface before the HelloWorldWebPart class in the HelloWorldWebPart.ts file.

This property definition is used to define custom property types for your web part, which is described in the property pane section later.

Web part render method

The DOM element where the web part should be rendered is available in the render method. This method is used to render the web part inside that DOM element. In the HelloWorld web part, the DOM element is set to a DIV. The method parameters include the display mode (either Read or Edit) and the configured web part properties if any:

This model is flexible enough so that web parts can be built in any JavaScript framework and loaded into the DOM element.

Configure the Web part property pane

The property pane is defined in the HelloWorldWebPart class. The getPropertyPaneConfiguration property is where you need to define the property pane.

When the properties are defined, you can access them in your web part by using this.properties.<property-value>, as shown in the render method:

Notice that we are performing an HTML escape on the property's value to ensure a valid string. To learn more about how to work with the property pane and property pane field types, see Make your SharePoint client-side web part configurable.

Let's now add a few more properties to the property pane: a check box, a drop-down list, and a toggle. We first start by importing the respective property pane fields from the framework.

1. Scroll to the top of the file and add the following to the import section from @microsoft/sp-property-pane:

   The complete import section looks like the following:

2. Update the web part properties to include the new properties. This maps the fields to typed objects.

3. Replace the IHelloWorldWebPartProps interface with the following code.

4. Save the file.

5. Replace the getPropertyPaneConfiguration method with the following code, which adds the new property pane fields and maps them to their respective typed objects.

6. After you add your properties to the web part properties, you can now access the properties in the same way you accessed the description property earlier:

   To set the default value for the properties, you need to update the web part manifest's properties property bag.

7. Open HelloWorldWebPart.manifest.json and modify the properties to:

The web part property pane now has these default values for those properties.

Web part manifest

The HelloWorldWebPart.manifest.json file defines the web part metadata such as version, id, display name, icon, and description. Every web part must contain this manifest.

Now that we have introduced new properties, ensure that you are again hosting the web part from the local development environment by executing the following command. This also ensures that the previous changes were correctly applied.

Preview the web part in SharePoint

SharePoint Workbench is also hosted in SharePoint to preview and test your local web parts in development. The key advantage is that now you are running in SharePoint context and you are able to interact with SharePoint data.

1. Go to the following URL: https://your-sharepoint-tenant.sharepoint.com/_layouts/workbench.aspx

   [!NOTE]If you do not have the SPFx developer certificate installed, Workbench notifies you that it is configured not to load scripts from localhost. Stop the currently running process in the console window, and execute the gulp trust-dev-cert command in your project directory console to install the developer certificate before running the gulp servecommand again. See details on installing a developer certificate from the Set up your development environment article.

2. Notice that the SharePoint Workbench now has the Office 365 Suite navigation bar.

3. Select the add icon in the canvas to reveal the toolbox. The toolbox now shows the web parts available on the site where the SharePoint Workbench is hosted along with your HelloWorldWebPart.

4. Add HelloWorld from the toolbox. Now you're running your web part in a page hosted in SharePoint!

[!NOTE]The color of the web part depends on the colors of the site. By default, web parts inherit the core colors from the site by dynamically referencing Office UI Fabric Core styles used in the site where the web part is hosted.

Because you are still developing and testing your web part, there is no need to package and deploy your web part to SharePoint.

Next steps

Congratulations on getting your first Hello World web part running!

Now that your web part is running, you can continue building out your Hello World web part in the next topic, Connect your web part to SharePoint. You will use the same Hello World web part project and add the ability to interact with SharePoint List REST APIs. Notice that the gulp serve command is still running in your console window (or in Visual Studio Code if you are using that as editor). You can continue to let it run while you go to the next article.

[!NOTE]If you find an issue in the documentation or in the SharePoint Framework, please report that to SharePoint engineering by using the issue list at the sp-dev-docs repository or by adding a comment to this article. Thanks for your input in advance.

In September 2017, Microsoft released Feature Pack 2 for SharePoint 2016. With this release came the long-awaited introduction of some SharePoint Framework capabilities on-premises, beginning with client-side web parts on classic pages (of course, there are no modern page experiences on-premises…yet).

So what do you need to do to start using client-side web parts on-premises? Follow the steps below!

Download and apply the September 2017 Public Update for SharePoint 2016

Of course it all starts with downloading and applying Feature Pack 2 (also known as the September 2017 Public Update for SharePoint 2016), which can be downloaded here. Once you’ve applied the Feature Pack, verify your configuration database version is 16.0.4588 in Central Administration:

Farm information shown on the Central Administration “Servers in Farm” screen.

Verify the farm configuration for apps/add-ins

If you are already using SharePoint add-ins and have completed the necessary steps to configure your on-premises environment for apps, you can skip this section. Otherwise, there is some infrastructure work that needs to be done before you can leverage the app/add-in model. Since SharePoint Framework packages must be uploaded to an app catalog, your on-premises farm must be configured for apps in order to use the SharePoint Framework. This is true even if you do not intend to leverage the add-in model (although you should definitely should consider it, as SharePoint Framework capabilities are complementary to–and not a wholesale replacement for–the add-in model).

At a high level, the steps you must perform include:

1. Creating the forward lookup zone and CNAME alias in DNS.
2. Configuring the Subscription Settings and App Management service applications.
3. Setting up app URLs in Central Administration.
4. Granting access to the app catalog to user(s) who may install your client-side web parts to a site (this is an important one and is definitely the first place to look if users trying to add them to a site don’t see them on the Add an app screen).

These steps are outlined in further detail here.

Update the Yeoman generator

Assuming you have already configured your SharePoint Framework development environment, ensure your Yeoman generator has been updated to version 1.3.0 or later. You can also develop client-side web parts for SharePoint 2016 on-premises using version 1.0.2 of the generator, but I would highly encourage you to update to the latest version of the generator using this command:

Beginning with v1.3.0 of the generator, you are given the option to choose whether your solution needs to support SharePoint 2016 on-premises and/or SharePoint Online:

Microsoft Visual Studio For Mac

Version 1.3.0 of the Yeoman generator now prompts you to choose between targeting SharePoint on-premises and/or SharePoint Online.

This is important because SharePoint Online will always have support for newer SharePoint Framework capabilities than what will be available on-premises and will therefore target different dependencies within its baseline packages.

Sharepoint Client-side Web Part Visual Studio For Mac

Build, package, and deploy the client-side web part

This process is largely the same as developing client-side web parts for SharePoint Online. There is even a live online workbench for local testing available within your on-premises sites at _layouts/15/workbench.aspx (in addition to the local workbench that is always available when you run gulp serve).

Before you build and package your solution, remember to update the cdnBasePath value in config/write-manifests.json to match the location where you intend to deploy your client-side web part’s assets. The files you will need to deploy are one .json and two .js files. NOTE: If you intend to deploy these assets to a SharePoint document library, you may need to remove .json files from the list of blocked file types. This may be done in Central Administration under Manage web applications by selecting Blocked File Types in the ribbon and removing json from the list:

Ensure that json does NOT appear in the list of blocked file type extensions if you intend to deploy your solution’s assets to SharePoint.

After you have deployed your solution’s assets, upload the .sppkg file from the sharepoint/solution directory to your app catalog. This will then make the solution available to install on sites where you wish to add the client-side web part.

Add the client-side web part to a site

From the Add an app screen, select your solution. You will then be able to add the web part to a page by selecting Web Partfrom the Insert tab of the ribbon on a wiki or web part page. By default, your client-side web part will appear in the Othercategory:

Visual Studio For Mac Download

SharePoint Framework client-side web parts can be added to the page just like any classic web part.

The web part will then appear on the page.

SharePoint Framework client-side web part added to a SharePoint 2016 on-premises wiki page.

Other notes

– Remember that you cannot add an app to a site when logged in as the System Account. Ensure you are signed in as a different user when adding the app to your site.
– The web part file’s properties, including its group, title, and description, can be changed by updating the [web part name].manifest.json file in the src/webparts/[web part name] directory.
– There will always be some capability gap between SharePoint Online and on-premises. The SharePoint team has committed to merging new SharePoint Framework capabilities into future on-premises releases, but don’t expect to see support for things like SharePoint Framework Extensions on-premises anytime soon.
– There is no on-premises support for tenant/farm-scoped deployment of client-side web parts. You must upload the .sppkg file to your on-premises app catalog(s) and manually add the app on each site where you need to leverage your client-side web part.
– If you have completed all of the appropriate farm configuration to support the add-in model but users don’t see your SharePoint Framework solutions from the Add an app screen, ensure you have explicitly granted those users access to your app catalog.

It is so exciting to have the first set of SharePoint Framework capabilities now available to on-premises users. Happy coding!

Reference:
Jessee, D. (2017). Running With Elevated Privileges. [online] Running With Elevated Privileges. Available at: http://dannyjessee.com/blog/ [Accessed 4 Jan. 2018].

Want to read more on the SharePoint Framework?

Download INTRODUCING SHAREPOINT ONLINE FOR DEVELOPERS the exclusive free chapter from the new book SharePoint Development with the SharePoint Framework byJussi Roine and Olli Jääskeläinen.