From e4f121a59a67dcd7a9461b70b0e1a96cb952581d Mon Sep 17 00:00:00 2001 From: byron velasquez Date: Wed, 18 Oct 2017 08:02:28 -0400 Subject: [PATCH 01/26] Simple text correction on line 68 (#940) "SharePoint Serverthen does"... to "SharePoint Server then does" --- .../incoming-claims-signing-into-sharepoint.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general-development/incoming-claims-signing-into-sharepoint.md b/docs/general-development/incoming-claims-signing-into-sharepoint.md index f0d9a1eb5..ca2bbc391 100644 --- a/docs/general-development/incoming-claims-signing-into-sharepoint.md +++ b/docs/general-development/incoming-claims-signing-into-sharepoint.md @@ -65,7 +65,7 @@ In ASP.NET membership and role passive sign-in, the sign-in happens by redirecti -SharePoint Serverthen does claims augmentation. Win32 clients must support the forms-based authentication that is implemented in Office clients. +SharePoint Server then does claims augmentation. Win32 clients must support the forms-based authentication that is implemented in Office clients. From 25f596ac1084d81d51d46f0e2b48c3d30c523561 Mon Sep 17 00:00:00 2001 From: VesaJuvonen Date: Wed, 18 Oct 2017 15:03:01 +0300 Subject: [PATCH 02/26] Adding notes on the SPFx extension support --- docs/apis/communication-site-creation-rest.md | 3 --- docs/spfx/extensions/overview-extensions.md | 3 +++ 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/apis/communication-site-creation-rest.md b/docs/apis/communication-site-creation-rest.md index fd9314add..03540e24e 100644 --- a/docs/apis/communication-site-creation-rest.md +++ b/docs/apis/communication-site-creation-rest.md @@ -2,9 +2,6 @@ Learn how to create and get the status of a new modern SharePoint Communication site with the REST interface. -> [!NOTE] -> There is a known bug with this API which is blocking completely this behavior. Fix will be rolling gradually to SharePoint Online by end of October 2017. - ## Prerequisites This topic assumes that you are already familiar with the topics Get to know the SharePoint REST service and Complete basic operations using SharePoint REST endpoints. It does not provide code snippets. diff --git a/docs/spfx/extensions/overview-extensions.md b/docs/spfx/extensions/overview-extensions.md index 17029a489..8b7990714 100644 --- a/docs/spfx/extensions/overview-extensions.md +++ b/docs/spfx/extensions/overview-extensions.md @@ -12,6 +12,9 @@ SharePoint Framework Extensions enable you to extend the SharePoint user experie You can build extensions alongside common scripting frameworks, such as AngularJS and React, in addition to plain JavaScript projects. For example, you can use React along with components from Office UI Fabric React to create experiences based on the same components used in Office 365. +> [!NOTE] +> There is a known bug with list and library extension support in the classic experiences. These only work currently in context of modern team sites aka. group associated team sites. Work is being done to address this issue. + ## Get started If you haven't installed the SharePoint Framework, follow the steps to [Set up your development environment](../set-up-your-development-environment.md). From 932de7312033d50e879990ae30614301de065118 Mon Sep 17 00:00:00 2001 From: Phil Date: Wed, 18 Oct 2017 08:11:44 -0400 Subject: [PATCH 03/26] making examples consistent in search rest api overview (#942) --- .../sharepoint-search-rest-api-overview.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/general-development/sharepoint-search-rest-api-overview.md b/docs/general-development/sharepoint-search-rest-api-overview.md index bd4977b09..bfe10cf7d 100644 --- a/docs/general-development/sharepoint-search-rest-api-overview.md +++ b/docs/general-development/sharepoint-search-rest-api-overview.md @@ -533,7 +533,7 @@ http:// _server_/_api/search/query?querytext='sharepoint'&hiddenconstraints= { '__metadata':{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext':'sharepoint', -'HiddenConstraints'='developer' +'HiddenConstraints':'developer' } ``` @@ -649,7 +649,7 @@ http:// _server_/_api/search/query?querytext='sharepoint'&trimduplicates=fal { '__metadata':{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext':'sharepoint', -'TrimDuplicates'='False' +'TrimDuplicates':'False' } ``` @@ -681,7 +681,7 @@ http:// _server_/_api/search/query?querytext='sharepoint'&timeout=60000 { '__metadata':{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext':'sharepoint', -'Timeout'='60000' +'Timeout':'60000' } ``` @@ -717,7 +717,7 @@ http:// _server_/_api/search/query?querytext='sharepoint'&enablenicknames=tr { '__metadata':{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext':'sharepoint', -'EnableNicknames'='True' +'EnableNicknames':'True' } ``` @@ -753,7 +753,7 @@ http:// _server_/_api/search/query?querytext='sharepoint'&enablephonetic=tru { '__metadata':{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'}, 'Querytext':'sharepoint', -'EnablePhonetic'='True' +'EnablePhonetic':'True' } ``` From 88d80b41bfa016fb11bc9b811413cdd293bb4ff9 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Wed, 18 Oct 2017 05:12:36 -0700 Subject: [PATCH 04/26] Edit complete (#947) * Edit complete * Minor updates --- .../serving-your-extension-from-sharepoint.md | 118 +++++++++--------- 1 file changed, 62 insertions(+), 56 deletions(-) diff --git a/docs/spfx/extensions/get-started/serving-your-extension-from-sharepoint.md b/docs/spfx/extensions/get-started/serving-your-extension-from-sharepoint.md index 39721e89e..2092f0789 100644 --- a/docs/spfx/extensions/get-started/serving-your-extension-from-sharepoint.md +++ b/docs/spfx/extensions/get-started/serving-your-extension-from-sharepoint.md @@ -1,12 +1,12 @@ -# Deploy your extension to SharePoint (Hello world part 3) +# Deploy your extension to SharePoint (Hello World part 3) -In this article, you will learn how to deploy your SharePoint Framework Application Customizer to SharePoint and see it working on modern SharePoint pages. This article continues with the hello world extension built in the previous article [Using page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md). +This article describes how to deploy your SharePoint Framework Application Customizer to SharePoint and see it working on modern SharePoint pages. This article continues with the Hello World extension built in the previous article [Use page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md). Be sure you have completed the procedures in the following articles before you begin: * [Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md) -* [Using page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md) +* [Use page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md) You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=P_yWI0WVQIg&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV). @@ -14,44 +14,46 @@ You can also follow these steps by watching the video on the [SharePoint PnP You Screenshot of the YouTube video player for this tutorial -## Package the helloWorld Application Customizer -In the console window, go to the extension project directory created in [Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md) +## Package the Hello World Application Customizer +In the console window, go to the extension project directory created in [Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md). ``` cd app-extension ``` -If gulp serve is still running, stop it from running by pressing `Ctrl+C`. +If gulp serve is still running, stop it from running by selecting Ctrl+C. -Unlike in **Debug** mode, in order to use an extension on modern SharePoint server-side pages, you need to deploy and register the extension with SharePoint in either `Site collection`, `Site`, or `List` scope. The scope defines where and how the Application Customizer will be active. In this particular scenario, we'll register the Application Customizer using the `Site Collection` scope. +Unlike in **Debug** mode, to use an extension on modern SharePoint server-side pages, you need to deploy and register the extension with SharePoint in `Site collection`, `Site`, or `List` scope. The scope defines where and how the Application Customizer will be active. In this particular scenario, we'll register the Application Customizer by using the `Site collection` scope. -Before we package our solution, we want to include the code needed to automate the extension activation within the site, whenever the solution is installed on the site. In this case, we'll use feature framework elements to perform these actions directly in the solution package, but you could also associate the application customizer to a SharePoint site using REST or CSOM as part of the site provisioning, for example. +Before we package our solution, we want to include the code needed to automate the extension activation within the site whenever the solution is installed on the site. In this case, we'll use feature framework elements to perform these actions directly in the solution package, but you could also associate the application customizer to a SharePoint site by using REST or CSOM as part of the site provisioning, for example. -1. Install the solution package to the site where it should be installed, so that extension manifest is being white listed for execution -2. Associate the Application Customizer to the planned scope. This can be performed programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the `UserCustomAction` object at the site collection, site or list level. - * **ClientSideComponentId:** This is the identifier (GUID) of the Field Customizer, which has been installed in the app catalog. - * **ClientSideComponentProperties:** This is an optional parameter, which can be used to provide properties for the Field Customizer instance - -> Notice, you can control the requirement to add a solution containing your extension to the site by using `skipFeatureDeployment` setting in **package-solution.json**. Event though you would not require solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible. +1. Install the solution package to the site where it should be installed so that the extension manifest is being white listed for execution. -In the following steps, we'll review `CustomAction` definition, which was automatically created for the solution as part of the scaffolding for enabling solution in a site when it's being installed. +2. Associate the Application Customizer to the planned scope. This can be performed programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the `UserCustomAction` object at the site collection, site, or list level. + * **ClientSideComponentId:** This is the identifier (GUID) of the Field Customizer, which has been installed in the app catalog. + * **ClientSideComponentProperties:** This is an optional parameter, which can be used to provide properties for the Field Customizer instance. + + Note that you can control the requirement to add a solution containing your extension to the site by using the `skipFeatureDeployment` setting in **package-solution.json**. Even though you would not require the solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible. + +In the following steps, we'll review the `CustomAction` definition, which was automatically created for the solution as part of the scaffolding for enabling the solution on a site when it's being installed. + +1. Return to your solution package in Visual Studio Code (or to your preferred editor). -Return to your solution package in Visual Studio Code (or to your preferred editor). +2. Extend the **sharepoint** folder and **assets** subfolder in the root of the solution to see the existing **elements.xml** file. -Extend **sharepoint** folder and **assets** sub folder in the root of the solution to see existing **elements.xml** file. + ![assets folder in solution structure](../../../images/ext-app-assets-folder.png) -![assets folder in solution structure](../../../images/ext-app-assets-folder.png) +
-### Review existing elements.xml file for SharePoint definitions +### Review the existing elements.xml file for SharePoint definitions -Review the existing xml structure in the **elements.xml** file. Notice that the **ClientSideComponentId** property has been automatically updated based on the unique Id of your Application Customizer available in the **HelloWorldApplicationCustomizer.manifest.json** file in the **src\extensions\helloWorld** folder. +Review the existing xml structure in the **elements.xml** file. Note that the **ClientSideComponentId** property has been automatically updated based on the unique ID of your Application Customizer available in the **HelloWorldApplicationCustomizer.manifest.json** file in the **src\extensions\helloWorld** folder. -**ClientSideComponentProperties** has been also automatically set with default structure and pass JSON properties for this extension instance. Notice how the JSON is escaped so that we can set it properly within an XML attribute. +**ClientSideComponentProperties** has also been automatically set with the default structure and JSON properties for this extension instance. Note how the JSON is escaped so that we can set it properly within an XML attribute. -Notice that configuration uses the specific location of `ClientSideExtension.ApplicationCustomizer` to define that this is an Application Customizer. Since by default this **elements.xml** will be associated to a *Web* scoped feature, this `CustomAction` will be automatically added to the `Web.UserCustomAction` collection in the site where the solution is being installed. +The configuration uses the specific location of `ClientSideExtension.ApplicationCustomizer` to define that this is an Application Customizer. Because this **elements.xml** is associated to a *Web* scoped feature by default, this `CustomAction` is automatically added to the `Web.UserCustomAction` collection in the site where the solution is being installed. -To ensure that the configuration matches updates performed in the Application Customizer, update the **ClientSideComponentProperties** as in the below xml structure. +To ensure that the configuration matches updates performed in the Application Customizer, update the **ClientSideComponentProperties** as in the following xml structure. Note that you should not copy the whole structure because it would cause a mismatch with your **ClientSideComponentId**. -> Notice that you should not copy the whole structure, since it would cause a mismatch with your **ClientSideComponentId**. ```xml @@ -68,6 +70,8 @@ To ensure that the configuration matches updates performed in the Application Cu ``` +
+ ### Ensure that definitions are taken into account within the build pipeline Open **package-solution.json** from the **config** folder. The **package-solution.json** file defines the package metadata as shown in the following code: @@ -102,55 +106,57 @@ Open **package-solution.json** from the **config** folder. The **package-solutio ``` -To ensure that **element.xml** file is taken into account while the solution is being packaged, default scaffolding has added needed configuration to define a Feature Framework feature definition for the solution package. +
-## Deploy the extension to SharePoint Online and host JavaScript from local host - -Now you are ready to deploy the solution to a SharePoint site and to have the `CustomAction` automatically associated on the site level. +To ensure that the **element.xml** file is taken into account while the solution is being packaged, default scaffolding adds needed configuration to define a feature framework feature definition for the solution package. -In the console window, enter the following command to package your client-side solution that contains the extension, so that we get the basic structure ready for packaging: - -``` -gulp bundle -``` +## Deploy the extension to SharePoint Online and host JavaScript from local host -Next, execute the following command so that the solution package is created: +Now you are ready to deploy the solution to a SharePoint site and have the `CustomAction` automatically associated on the site level. -``` -gulp package-solution -``` +1. In the console window, enter the following command to package your client-side solution that contains the extension so that we get the basic structure ready for packaging: -The command will create the package in the **sharepoint/solution** folder: + ``` + gulp bundle + ``` -``` -app-extension.sppkg -``` +2. Execute the following command so that the solution package is created: -Next you need to deploy the package that was generated to the App Catalog. + ``` + gulp package-solution + ``` -Go to your tenant's **App Catalog** and open the **Apps for SharePoint** library. + The command will create the package in the **sharepoint/solution** folder: -Upload or drag and drop the `app-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint will display a dialog and ask you to trust the client-side solution. + ``` + app-extension.sppkg + ``` -Notice that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to `https://localhost:4321`. Click the **Deploy** button. +3. You now need to deploy the package that was generated to the App Catalog. To do this, go to your tenant's **App Catalog** and open the **Apps for SharePoint** library. -![Trust operation in app catalog upload](../../../images/ext-app-sppkg-deploy-trust.png) +4. Upload or drag and drop the `app-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint displays a dialog and asks you to trust the client-side solution. -Move back to your console and ensure that the solution is running. If it's not running, execute the following command in the solution folder: + Note that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to `https://localhost:4321`. + +5. Select the **Deploy** button. -``` -gulp serve --nobrowser -``` + ![Trust operation in app catalog upload](../../../images/ext-app-sppkg-deploy-trust.png) -Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package. +6. Move back to your console and ensure that the solution is running. If it's not running, execute the following command in the solution folder: + + ``` + gulp serve --nobrowser + ``` + +7. Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package. -Choose the gear icon on the top navigation bar on the right and choose **Add an app** to go to your Apps page. +8. Select the gear icon on the top navigation bar on the right, and then select **Add an app** to go to your Apps page. -In the **Search** box, enter '**app**' and press *Enter* to filter your apps. +9. In the **Search** box, enter **app**, and then select Enter to filter your apps. -![installing field customizer to site](../../../images/ext-app-install-solution-to-site.png) + ![installing field customizer to site](../../../images/ext-app-install-solution-to-site.png) -Choose the **app-extension-client-side-solution** app to install the solution on the site. When the installation is completed, refresh the page by pressing **F5**. +10. Select the **app-extension-client-side-solution** app to install the solution on the site. When the installation is completed, refresh the page by selecting **F5**. When the application has been successfully installed, you can see the header and footer being rendered just like with the debug query parameters. @@ -158,4 +164,4 @@ When the application has been successfully installed, you can see the header and ## Next steps -Congratulations, you have deployed an extension to a modern SharePoint page from the app catalog! You can continue building out your Hello World extension in the next topic, [Hosting extension from Office 365 CDN (Hello world part 4)](./hosting-extension-from-office365-cdn.md), where you will learn how to deploy and load the extension assets from a CDN instead of localhost. +Congratulations, you have deployed an extension to a modern SharePoint page from the app catalog! You can continue building out your Hello World extension in the next topic, [Host extension from Office 365 CDN (Hello World part 4)](./hosting-extension-from-office365-cdn.md), where you will learn how to deploy and load the extension assets from a CDN instead of from localhost. From 90620b4df41a7e61fed1297b7e4000149974a7fb Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Wed, 18 Oct 2017 05:14:04 -0700 Subject: [PATCH 05/26] Edit complete. (#948) --- .../hosting-extension-from-office365-cdn.md | 161 +++++++++--------- 1 file changed, 82 insertions(+), 79 deletions(-) diff --git a/docs/spfx/extensions/get-started/hosting-extension-from-office365-cdn.md b/docs/spfx/extensions/get-started/hosting-extension-from-office365-cdn.md index 85cad4a13..0a80a3cac 100644 --- a/docs/spfx/extensions/get-started/hosting-extension-from-office365-cdn.md +++ b/docs/spfx/extensions/get-started/hosting-extension-from-office365-cdn.md @@ -1,12 +1,12 @@ -# Hosting extension from Office 365 CDN (Hello world part 4) +# Host extension from Office 365 CDN (Hello World part 4) -In this article, you will learn how to deploy your SharePoint Framework Application Customizer to be hosted from an Office 365 CDN and how to deploy that to SharePoint for the end users. This article continues with the hello world extension built in the previous article [# Deploy your extension to SharePoint (Hello world part 3)](./using-page-placeholder-with-extensions.md) where we were still hosting the customizer from localhost. +This article describes how to deploy your SharePoint Framework Application Customizer to be hosted from an Office 365 CDN and how to deploy that to SharePoint for end users. This article continues with the Hello World extension built in the previous article [Deploy your extension to SharePoint (Hello World part 3)](./serving-your-extension-from-sharepoint.md), where we were still hosting the customizer from localhost. -Be sure you have completed the procedures in the following articles before you start: +Be sure you have completed the procedures in the following articles before you begin: -* [Build your first SharePoint Framework Extension (Hello world part 1)](./build-a-hello-world-extension.md) -* [Connect your client-side web part to SharePoint (Hello world part 2)](./using-page-placeholder-with-extensions.md) -* [Deploy your extension to SharePoint (Hello world part 3)](./serving-your-extension-from-sharepoint.md) +* [Build your first SharePoint Framework Extension (Hello World part 1)](./build-a-hello-world-extension.md) +* [Use page placeholders from Application Customizer (Hello World part 2)](./using-page-placeholder-with-extensions.md) +* [Deploy your extension to SharePoint (Hello World part 3)](./serving-your-extension-from-sharepoint.md) You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=oOIHWamPr34&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV). @@ -14,92 +14,95 @@ You can also follow these steps by watching the video on the [SharePoint PnP You Screenshot of the YouTube video player for this tutorial -## Using the CDN in your Office 365 tenant +## Enable the CDN in your Office 365 tenant Office 365 CDN is the easiest way to host SharePoint Framework solutions directly from your tenant while still taking advantage of the Content Delivery Network (CDN) service for faster load times of your assets. -## Enabling the CDN in your Office 365 tenant -Ensure that you have latest version of the SharePoint Online Management Shell by downloading it from the [Microsoft Download site](https://www.microsoft.com/en-us/download/details.aspx?id=35588). - -Connect to your SharePoint Online tenant through PowerShell: -``` -Connect-SPOService -Url https://contoso-admin.sharepoint.com -``` - -Get the current status of public CDN settings from the tenant level by executing the following commands one-by-one. -``` -Get-SPOTenantCdnEnabled -CdnType Public -Get-SPOTenantCdnOrigins -CdnType Public -Get-SPOTenantCdnPolicies -CdnType Public -``` -Enable public CDN in the tenant -``` -Set-SPOTenantCdnEnabled -CdnType Publicget -``` -Now public CDN has been enabled in the tenant using the default file type configuration allowed. This means that the following file type extensions are supported: "CSS,EOT,GIF,ICO,JPEG,JPG,JS,MAP,PNG,SVG,TTF,WOFF". - -Open up a browser and move to a site collection where you'd like to host your CDN library. This could be any site collection in your tenant. In this tutorial, we will create a specific library to act as your CDN library, but you can also use a specific folder in any existing document library as the CDN endpoint. - -Create a new document library on your site collection called **CDN** and add a folder named **helloworld** to it. - -![helloworld-extension folder in CDN library](../../../images/ext-app-cdn-folder-created.png) - -Move back to the PowerShell console and add a new CDN origin. In this case, we are setting the origin as `*/cdn`, which means that any relative folder with the name of **cdn** will act as a CDN origin. -``` -Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */cdn -``` -Execute the following command to get the list of CDN origins from your tenant -``` -Get-SPOTenantCdnOrigins -CdnType Public -``` -Notice that your newly added origin is listed as a valid CDN origin. Final configuration of the origin will take a while (approximately 15 minutes), so we can continue creating your test extension, which will be hosted from the origin once deployment is completed. +1. Download the [SharePoint Online Management Shell](https://www.microsoft.com/en-us/download/details.aspx?id=35588) to ensure that you have the latest version. + +2. Connect to your SharePoint Online tenant by using PowerShell: + + ``` + Connect-SPOService -Url https://contoso-admin.sharepoint.com + ``` + +3. Get the current status of public CDN settings from the tenant level by executing the following commands one-by-one: + + ``` + Get-SPOTenantCdnEnabled -CdnType Public + Get-SPOTenantCdnOrigins -CdnType Public + Get-SPOTenantCdnPolicies -CdnType Public + ``` + +4. Enable public CDN in the tenant: + + ``` + Set-SPOTenantCdnEnabled -CdnType Publicget + ``` + + Public CDN has now been enabled in the tenant by using the default file type configuration allowed. This means that the following file type extensions are supported: CSS, EOT, GIF, ICO, JPEG, JPG, JS, MAP, PNG, SVG, TTF, and WOFF. + +5. Open up a browser and move to a site collection where you'd like to host your CDN library. This could be any site collection in your tenant. In this tutorial, we will create a specific library to act as your CDN library, but you can also use a specific folder in any existing document library as the CDN endpoint. + +6. Create a new document library on your site collection called **CDN** and add a folder named **helloworld** to it. + + ![helloworld-extension folder in CDN library](../../../images/ext-app-cdn-folder-created.png) + +
+ +7. In the PowerShell console, add a new CDN origin. In this case, we are setting the origin as `*/cdn`, which means that any relative folder with the name of **cdn** acts as a CDN origin. + + ``` + Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */cdn + ``` + +8. Execute the following command to get the list of CDN origins from your tenant: + + ``` + Get-SPOTenantCdnOrigins -CdnType Public + ``` + +Note that your newly added origin is listed as a valid CDN origin. Final configuration of the origin takes approximately 15 minutes, so we can continue creating your test extension, which will be hosted from the origin after deployment is completed. ![List of public origins in tenant](../../../images/ext-app-cdn-origins-pending.png) -> When origin is listed without the *(configuration pending)* text, it is ready to be used in your tenant. This is the indication of an on-going configuration between SharePoint Online and the CDN system. +When the origin is listed without the `(configuration pending)` text, it is ready to be used in your tenant. This indicates an on-going configuration between SharePoint Online and the CDN system. -## Updating your solution project for the CDN URLs -Return to the previously created solution to perform the needed URL updates. -``` -code . -``` +## Update your solution project for the CDN URLs -Update the *write-manifests.json* file (under the *config* folder) as follows to point to your CDN endpoint. +1. Return to the previously created solution to perform the needed URL updates. + +2. Update the **write-manifests.json** file (under the **config** folder) as follows to point to your CDN endpoint. Use `publiccdn.sharepointonline.com` as the prefix, and then extend the URL with the actual path of your tenant. The format of the CDN URL is as follows: + + ``` + https://publiccdn.sharepointonline.com//sites/site/library/folder + ``` + + ![Updated write manifest content with path to CDN endpoint](../../../images/ext-app-cdn-write-manifest.png) -* You will need to use the publiccdn.sharepointonline.com as the prefix and then extend the URL with the actual path of your tenant -* Format of the CDN URL is as follows +3. Save your changes. -``` -https://publiccdn.sharepointonline.com//sites/site/library/folder -``` +4. Execute the following tasks to bundle your solution. This executes a release build of your project using the CDN URL specified in the **write-manifests.json** file. The output of this command is located in the **./temp/deploy** folder. These are the files that you need to upload to the SharePoint folder acting as your CDN endpoint. + + ``` + gulp bundle --ship + ``` + +5. Execute the following task to package your solution. This command creates an **app-extension.sppkg** package in the **sharepoint/solution** folder and also prepares the assets in the **temp/deploy** folder to be deployed to the CDN. + + ``` + gulp package-solution --ship + ``` + +6. Upload or drag-and-drop the newly created client-side solution package to the app catalog in your tenant, and then select the **Deploy** button. -![Updated write manifest content with path to CDN endpoint](../../../images/ext-app-cdn-write-manifest.png) + ![App Catalog Trust Dialog with path to CDN endpoint](../../../images/ext-app-approve-cdn-address.png) -Save your changes. +7. Upload or drag-and-drop the files in the **temp/deploy** folder to the **CDN/helloworld** folder created earlier. -Execute the following tasks to bundle your solution +8. Install the new version of the solution to your site and ensure that it's working properly without your *locahost* hosting the JavaScript file. -* This will execute a release build of your project using the CDN URL specified in the **write-manifests.json** file. The output of this command will be located in the **./temp/deploy** folder. These are the files which you will need to upload to the SharePoint folder acting as your CDN endpoint. + ![Custom header and footer elements rendered in the page](../../../images/ext-app-header-footer-visible.png) -``` -gulp bundle --ship -``` - -Execute the following task to package your solution - -``` -gulp package-solution --ship -``` - -This command will create an **app-extension.sppkg** package in the **sharepoint/solution** folder and also prepare the assets in the **temp/deploy** folder to be deployed to the CDN. - -Upload or drag & drop the newly created client-side solution package to the app catalog in your tenant. Click the **Deploy** button. - -![App Catalog Trust Dialog with path to CDN endpoint](../../../images/ext-app-approve-cdn-address.png) - -Upload or drag & drop the files in the **temp/deploy** folder to the **CDN/helloworld** folder created earlier. - -Install the new version of the solution to your site and ensure that it's working properly without your *locahost* hosting the JavaScript file. - -![Custom header and footer elements rendered in the page](../../../images/ext-app-header-footer-visible.png) +
Congratulations, you have enabled a public CDN in your Office 365 tenant and taken advantage of it from your solution! From cf3822ec4d887dfb9ccb8bdaf97c712516e0ad95 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Wed, 18 Oct 2017 05:14:49 -0700 Subject: [PATCH 06/26] Edit complete (#949) * Edit complete * Update building-simple-field-customizer.md * Minor updates --- .../building-simple-field-customizer.md | 415 +++++++++--------- 1 file changed, 211 insertions(+), 204 deletions(-) diff --git a/docs/spfx/extensions/get-started/building-simple-field-customizer.md b/docs/spfx/extensions/get-started/building-simple-field-customizer.md index 64cb341f7..cdc36f0b4 100644 --- a/docs/spfx/extensions/get-started/building-simple-field-customizer.md +++ b/docs/spfx/extensions/get-started/building-simple-field-customizer.md @@ -1,79 +1,81 @@ -# Build your first Field Customizer extension +# Build your first Field Customizer Extension -Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online and you can use modern JavaScript tools and libraries to build them. +Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online, and you can use modern JavaScript tools and libraries to build them. -You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=fijOzUmlXrY&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV). +This article describes how to create your first Field Customizer Extension. You can follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=fijOzUmlXrY&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV). Screenshot of the YouTube video player for this tutorial ## Create an extension project -Create a new project directory in your favorite location. -``` -md field-extension -``` - -Go to the project directory. - -``` -cd field-extension -``` - -Create a new HelloWorld extension by running the Yeoman SharePoint Generator. - -``` -yo @microsoft/sharepoint -``` - -When prompted: - -* Accept the default value of **field-extension** as your solution name and press **Enter**. -* Choose **SharePoint Online only (latest)**, and press **Enter**. -* Choose **Use the current folder** and press **Enter**. -* Choose **N** to require extension to be installed on each site explicitly when it's being used. -* Choose **Extension** as the client-side component type to be created. -* Choose **Field Customizer** as the extension type to be created. - -The next set of prompts will ask for specific information about your extension: - -* Accept the default value of **HelloWorld** as your extension name and press **Enter**. -* Accept the default value of **HelloWorld description** as your extension description and press **Enter**. -* Accept the default **No JavaScript Framework** as the framework selection and press **Enter** - -![Yeoman SharePoint generator prompts to create an extension solution](../../../images/ext-field-yeoman-prompts.png) - -At this point, Yeoman will install the required dependencies and scaffold the solution files along with the **HelloWorld** extension. This might take a few minutes. - -When the scaffold is complete, you should see the following message indicating a successful scaffold: - -![SharePoint client-side solution scaffolded successfully](../../../images/ext-field-yeoman-complete.png) +1. Create a new project directory in your favorite location. + + ``` + md field-extension + ``` + +2. Go to the project directory. + + ``` + cd field-extension + ``` + +3. Create a new HelloWorld extension by running the Yeoman SharePoint Generator. + + ``` + yo @microsoft/sharepoint + ``` + +4. When prompted: + + * Accept the default value of **field-extension** as your solution name, and then select Enter. + * Select **SharePoint Online only (latest)**, and select Enter. + * Select **Use the current folder**, and select Enter. + * Select **N** to require the extension to be installed on each site explicitly when it's being used. + * Select **Extension** as the client-side component type to be created. + * Select **Field Customizer** as the extension type to be created. + +5. The next set of prompts ask for specific information about your extension: + + * Accept the default value of **HelloWorld** as your extension name, and then select Enter. + * Accept the default value of **HelloWorld description** as your extension description, and select Enter. + * Accept the default value of **No JavaScript Framework** as the framework selection, and select Enter. + + ![Yeoman SharePoint generator prompts to create an extension solution](../../../images/ext-field-yeoman-prompts.png) + + At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the **HelloWorld** extension. This might take a few minutes. + + When the scaffold is complete, you should see the following message indicating a successful scaffold: + + ![SharePoint client-side solution scaffolded successfully](../../../images/ext-field-yeoman-complete.png) + + For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). + +6. When the solution scaffolding is complete, type the following into the console to start Visual Studio Code. + + ``` + code . + ``` + + **Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. + + Note how the default solution structure looks like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types. + + ![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-field-vscode-solution-structure.png) + +7. Open **HelloWorldFieldCustomizer.manifest.json** in the **src\extensions\helloWorld** folder. + + This file defines your extension type and a unique identifier `id` for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint. + + ![Application customizer manifest json content](../../../images/ext-field-vscode-manifest.png) + +## Code your Field Customizer -For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). - -Once the solution scaffolding is completed, type the following into the console to start Visual Studio Code. - -``` -code . -``` - -> Notice that because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. - -Notice how the default solution structure is like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure with similar configuration options across all solution types. - -![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-field-vscode-solution-structure.png) - -Open **HelloWorldFieldCustomizer.manifest.json** at the **src\extensions\helloWorld** folder. - -This file defines your extension type and a unique identifier **“id”** for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint. - -![Application customizer manifest json content](../../../images/ext-field-vscode-manifest.png) - -## Coding your Field Customizer Open the **HelloWorldFieldCustomizer.ts** file in the **src\extensions\helloWorld** folder. -Notice that the base class for the Field Customizer is imported from the **sp-application-base** package, which contains SharePoint framework code required by the Field Customizer. +Notice that the base class for the Field Customizer is imported from the **sp-application-base** package, which contains SharePoint Framework code required by the Field Customizer. ```ts import { Log } from '@microsoft/sp-core-library'; @@ -86,11 +88,11 @@ import { The logic for your Field Customizer is contained in the **OnInit()**, **onRenderCell()**, and **onDisposeCell()** methods. -* **onInit():** this is where you should perform any setup needed for your extension. This event occurs after `this.context` and `this.properties` are assigned, but before the page DOM is ready. As with web parts, `onInit()` returns a promise that you can use to perform asynchronous operations; `onRenderCell()` will not be called until your promise has resolved. If you don’t need that, simply return `Promise.resolve();`. -* **onRenderCell():** This event occurs when each cell is rendered. It provides an `event.domElement` HTML element where your code can write its content. -* **onDisposeCell():** This event occurs immediately before the `event.cellDiv` is deleted. It can be used to free any resources that were allocated during field rendering. For example, if `onRenderCell()` mounted a React element, `onDisposeCell()` must be used to free it, otherwise a resource leak would occur.  +* **onInit()** is where you should perform any setup needed for your extension. This event occurs after `this.context` and `this.properties` are assigned, but before the page DOM is ready. As with web parts, `onInit()` returns a promise that you can use to perform asynchronous operations; `onRenderCell()` will not be called until your promise has resolved. If you don’t need that, simply return `Promise.resolve();`. +* **onRenderCell()** occurs when each cell is rendered. It provides an `event.domElement` HTML element where your code can write its content. +* **onDisposeCell()** occurs immediately before the `event.cellDiv` is deleted. It can be used to free any resources that were allocated during field rendering. For example, if `onRenderCell()` mounted a React element, `onDisposeCell()` must be used to free it; otherwise, a resource leak would occur.  -Below are the contents of **onRenderCell()** and **onDisposeCell()** in the default solution: +The following are the contents of **onRenderCell()** and **onDisposeCell()** in the default solution: ```ts @override @@ -112,145 +114,150 @@ Below are the contents of **onRenderCell()** and **onDisposeCell()** in the defa } ``` -## Debugging your Field Customizer using gulp serve and query string parameters -SharePoint Framework extensions cannot currently be tested using the local workbench, so you'll need to test and develop them directly against a live SharePoint Online site. You do not however need to deploy your customization to the app catalog to do this, which keeps the debugging experience simple and efficient. - -First, compile your code and host the compiled files from the local machine by running this command: -``` -gulp serve --nobrowser -``` - -Notice that we used the `--nobrowser` option, since there's no value in launching the local workbench since you currently cannot debug extensions locally. - -Once it compiles the code without errors, it will serve the resulting manifest from https://localhost:4321. - -![gulp serve](../../../images/ext-field-gulp-serve.png) - -To test your extension, navigate to a site in your SharePoint Online tenant. +## Debug your Field Customizer using gulp serve and query string parameters +You cannot currently use the local workbench to test SharePoint Framework Extensions. You'll need to test and develop them directly against a live SharePoint Online site. You don't have to deploy your customization to the App Catalog to do this, which makes the debugging experience simple and efficient. -Move to the **Site Contents** page. +1. Compile your code and host the compiled files from the local machine by running this command: + + ``` + gulp serve --nobrowser + ``` + + You use the `--nobrowser` option because you don't need to launch the local workbench, since you can't debug extensions locally. -Click **New** from the toolbar and choose **List**: + When the code compiles without errors, it will serve the resulting manifest from https://localhost:4321. -![Creating a new list](../../../images/ext-field-create-new-list.png) + ![gulp serve](../../../images/ext-field-gulp-serve.png) -Create a new list named *Orders* and click **Create**: +2. To test your extension, go to a site in your SharePoint Online tenant. -![Creating a new list with name of Orders](../../../images/ext-field-create-new-list-order.png) +3. Move to the **Site Contents** page. -Click the **plus** sign and choose **Number** to create a new Number field for the list: +4. On the toolbar, select **New**, and then select **List**. + + ![Creating a new list](../../../images/ext-field-create-new-list.png) + +5. Create a new list named **Orders** and then select **Create**. + + ![Creating a new list with name of Orders](../../../images/ext-field-create-new-list-order.png) + +6. Select the **plus** sign, and then select **Number** to create a new Number field for the list. + + ![Creating a new Number field](../../../images/ext-field-new-number-field.png) + +7. Set the name of the field to **Percent**, and then select **Save**. + + ![Creating a new field called Percent](../../../images/ext-field-new-number-field-percent.png) + +8. Add a few items with different numbers in the percent field. We'll modify the rendering later in this tutorial, so the different numbers will be presented differently based on your custom implementation. -![Creating a new Number field](../../../images/ext-field-new-number-field.png) + ![Creating items in the newly created list with different values in the Percent field](../../../images/ext-field-create-items-to-list.png) -Set name of the field to **Percent** and click **Save**: + Because our Field Customizer is still hosted in localhost and is running, we can use specific debug query parameters to execute the code in the newly created list. -![Creating a new field called Percent](../../../images/ext-field-new-number-field-percent.png) +9. Append the following query string parameters to the URL. Notice that you will need to update the ID to match your own extension identifier available from the **HelloWorldFieldCustomizer.manifest.json** file. -Add a few items with different numbers in the percent field. We'll modify the rendering later in this tutorial, so the different numbers will be presented differently based on your custom implementation. + ``` + ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}} + ``` -![Creating items in the newly created list with different values in the Percent field](../../../images/ext-field-create-items-to-list.png) - -Since our Field Customizer is still hosted in localhost and is running, we can use specific debug query parameters to execute the code in the newly created list. - -Append the following query string parameters to the URL. Notice that you will need to update the id to match your own extension identifier available from the **HelloWorldFieldCustomizer.manifest.json** file: - -``` -?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}} -``` More detail about the URL query parameters: -* **loadSPFX=true:** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Since no components are registered yet, we must explicitly load the framework. -* **debugManifestsFile:** specifies that we want to load SPFx components that are being locally served. Normally the loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). -* **fieldCustomizers**: Indicates which fields in your list should have their rendering controlled by the Field Customizer. The ID parameter specifies the GUID of the extension that should be used to control the rendering of the field. The properties parameter is an optional text string containing a JSON object that will be deserialized into `this.properties` for your extension. - * **Key:** use the internal name of the field as the key - * **Id:** the guid of the field customizer extension associated with this field - * **Properties:** property values defined in the extension. In this example, *‘sampleText’* is a property defined by the extension +- **loadSPFX=true** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Because no components are registered yet, we must explicitly load the framework. +- **debugManifestsFile** specifies that you want to load SPFx components that are locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). +- **fieldCustomizers** indicates which fields in your list should have their rendering controlled by the Field Customizer. The ID parameter specifies the GUID of the extension that should be used to control the rendering of the field. The properties parameter is an optional text string containing a JSON object that will be deserialized into `this.properties` for your extension. + - **Key**: Use the internal name of the field as the key. + - **Id**: The GUID of the Field Customizer extension associated with this field. + - **Properties**: The property values defined in the extension. In this example, `sampleText` is a property defined by the extension. The full URL should look similar to the following, depending on your tenant URL and the location of the newly created list: - + ``` contoso.sharepoint.com/Lists/Orders/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}} ``` - -Accept the loading of Debug Manifests, by clicking **Load debug scripts** when prompted: + +Accept the loading of Debug Manifests by selecting **Load debug scripts** when prompted. ![Accept loading debug scripts](../../../images/ext-field-accept-debug-scripts.png) -Notice how the Percent values are now presented with additional prefix string as 'Hello!: ', which is provided as a property for the field customizer: +Notice how the Percent values are now presented with an additional prefix string as 'Hello!: ', which is provided as a property for the Field Customizer. ![List view with field customizer rendered for percent field](../../../images/ext-field-default-customizer-output.png) -## Enhancing the Field Customizer rendering -Now that we have successfully tested the out of the box starting point of the Field Customizer, let's modify the logic slightly to have a more polished rendering of the field value. - -Open the **HelloWorld.module.scss** file in the **src\extensions\helloWorld** folder and update the styling definition as follows. - -``` -.HelloWorld { - .cell { - display: 'inline-block'; - } - .full { - background-color: '#e5e5e5'; - width: '100px'; - } -} +## Enhance the Field Customizer rendering +Now that we have successfully tested the out-of-the-box starting point of the Field Customizer, let's modify the logic slightly to have a more polished rendering of the field value. -``` -Open the **HelloWorldFieldCustomizer.ts** file in the **src\extensions\helloWorld** folder and update the **onRednerCell** method as follows. - -```ts - @override - public onRenderCell(event: IFieldCustomizerCellEventParameters): void { +1. Open the **HelloWorld.module.scss** file in the **src\extensions\helloWorld** folder, and update the styling definition as follows. - event.domElement.classList.add(styles.cell); - event.domElement.innerHTML = ` -
-
-   ${event.fieldValue} -
-
`; - } -``` + ``` + .HelloWorld { + .cell { + display: 'inline-block'; + } + .full { + background-color: '#e5e5e5'; + width: '100px'; + } + } + + ``` + +2. Open the **HelloWorldFieldCustomizer.ts** file in the **src\extensions\helloWorld** folder, and update the **onRednerCell** method as follows. + + ```ts + @override + public onRenderCell(event: IFieldCustomizerCellEventParameters): void { + + event.domElement.classList.add(styles.cell); + event.domElement.innerHTML = ` +
+
+   ${event.fieldValue} +
+
`; + } + ``` -Switch back to your console window and ensure that you do not have any exceptions. If you do not have the solution running in *localhost*, execute the following command: +3. In your console window, ensure that you do not have any exceptions. If you do not have the solution running in *localhost*, execute the following command: -``` -gulp serve --nobrowser -``` + ``` + gulp serve --nobrowser + ``` -Move back to your previously created list and use the same query parameter as used previously with the Field being 'Percent' and the Id being updated to your extension identifier available from the **HelloWorldFieldCustomizer.manifest.json** file. +4. In your previously created list, use the same query parameter as used previously, with the field being `Percent` and the `ID` being updated to your extension identifier available from the **HelloWorldFieldCustomizer.manifest.json** file. -Accept the loading of Debug Manifests, by clicking **Load debug scripts** when prompted. +5. Accept the loading of debug manifests by selecting **Load debug scripts** when prompted. -![Accept loading debug scripts](../../../images/ext-field-accept-debug-scripts.png) + ![Accept loading debug scripts](../../../images/ext-field-accept-debug-scripts.png) -Notice how we have changed the field rendering style completely. The field value is indicated using a graphical representation of the value. + Note how we changed the field rendering style completely. The field value is indicated by using a graphical representation of the value. -![Graphical Representation of Percent](../../../images/ext-field-percent-field-graphic.png) + ![Graphical Representation of Percent](../../../images/ext-field-percent-field-graphic.png) ## Add the field definition to the solution package for deployment -Now that we have tested our solution properly in debug mode, we can package this to be deployed automatically as part of the solution package deployed to the sites. There are few things to take care of here. +Now that we have tested our solution properly in debug mode, we can package this to be deployed automatically as part of the solution package deployed to the sites. -1. Install the solution package to the site where it should be installed, so that the extension manifest is being white listed for execution -2. Associate the Field Customizer to an existing field in the site. This can be performed programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the *SPField* object at the site or list level. - * **ClientSiteComponentId:** This is the identifier (GUID) of the Field Customizer, which has been installed in the app catalog. - * **ClientSideComponentProperties:** This is an optional parameter, which can be used to provide properties for the Field Customizer instance. +1. Install the solution package to the site where it should be installed, so that the extension manifest is white listed for execution. -> Notice, you can control the requirement to add a solution containing your extension to the site by using `skipFeatureDeployment` setting in **package-solution.json**. Event though you would not require solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible. +2. Associate the Field Customizer to an existing field in the site. You can do this programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the `SPField` object at the site or list level. + - **ClientSiteComponentId** is the identifier (GUID) of the Field Customizer, which has been installed in the App Catalog. + - **ClientSideComponentProperties** is an optional parameter, which can be used to provide properties for the Field Customizer instance. -In the following steps, we'll review default field definition, which was automatically created and will then be used to automatically deploy needed needed configurations when the solution package is installed on a site. + Note that you can control the requirement to add a solution containing your extension to the site by using the `skipFeatureDeployment` setting in **package-solution.json**. Even though you would not require the solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible. -Return to your solution in Visual Studio Code (or to your preferred editor). + In the following steps, we'll review the default field definition, which was automatically created and will then be used to automatically deploy needed configurations when the solution package is installed on a site. -Extend **sharepoint** folder and **assets** sub folder in the root of the solution to see existing **elements.xml** file. +3. Return to your solution in Visual Studio Code (or to your preferred editor). -![assets folder in solution structure](../../../images/ext-field-assets-folder.png) +4. Extend the **sharepoint** folder and **assets** subfolder in the root of the solution to see the existing **elements.xml** file. + + ![assets folder in solution structure](../../../images/ext-field-assets-folder.png) + +### Review the elements.xml file -### Review elements.xml file -Open **elements.xml** file inside the **sharepoint\assets** folder. +Open the **elements.xml** file inside the **sharepoint\assets** folder. -Notice the following xml structure into **elements.xml**. **ClientSideComponentId** property has been automatically updated to the unique Id of your Field Customizer available in the **HelloWorldFieldCustomizer.manifest.json** file in the **src\extensions\helloWorld** folder. +Note the following XML structure in **elements.xml**. The **ClientSideComponentId** property has been automatically updated to the unique ID of your Field Customizer available in the **HelloWorldFieldCustomizer.manifest.json** file in the **src\extensions\helloWorld** folder. ```xml @@ -299,79 +306,79 @@ Open **package-solution.json** from the **config** folder. The **package-solutio ``` -To ensure that **element.xml** file is taken into account while the solution is being packaged, default scaffolding has added needed configuration to define a Feature Framework feature definition for the solution package. +To ensure that the **element.xml** file is taken into account while the solution is being packaged, default scaffolding added needed configuration to define a feature framework feature definition for the solution package. ## Deploy the field to SharePoint Online and host JavaScript from local host -Now you are ready to deploy the solution to a SharePoint site and to get the field association automatically included in a field. -In the console window, enter the following command to package your client-side solution that contains the extension, so that we get the basic structure ready for packaging: +Now you are ready to deploy the solution to a SharePoint site and get the field association automatically included in a field. -``` -gulp bundle -``` +1. In the console window, enter the following command to package your client-side solution that contains the extension so that we get the basic structure ready for packaging: -Next, execute the following command so that the solution package is created: + ``` + gulp bundle + ``` -``` -gulp package-solution -``` +2. Execute the following command so that the solution package is created: -The command will create the package in the **sharepoint/solution** folder: + ``` + gulp package-solution + ``` -``` -field-extension.sppkg -``` + The command creates the package in the **sharepoint/solution** folder: -Next you need to deploy the package that was generated to the App Catalog. + ``` + field-extension.sppkg + ``` -Go to your tenant's **App Catalog** and open the **Apps for SharePoint** library. +3. You now need to deploy the package that was generated to the App Catalog. To do this, go to your tenant's **App Catalog** and open the **Apps for SharePoint** library. -Upload or drag and drop the `field-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint will display a dialog and ask you to trust the client-side solution. +4. Upload or drag-and-drop the `field-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint displays a dialog and asks you to trust the client-side solution. -Notice that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to https://localhost:4321. Click the **Deploy** button. + Note that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to https://localhost:4321. + +5. Select the **Deploy** button. -![Deploy Dialog](../../../images/ext-field-sppkg-deploy-trust.png) + ![Deploy Dialog](../../../images/ext-field-sppkg-deploy-trust.png) -Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package. +6. Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package. -Choose the gears icon on the top navigation bar on the right and choose **Add an app** to go to your Apps page. +7. Select the gears icon on the top navigation bar on the right, and then select **Add an app** to go to your Apps page. -In the **Search** box, enter '**field**' and press *Enter* to filter your apps. +8. In the **Search** box, enter **field**, and then select Enter to filter your apps. -![installing field customizer to site](../../../images/ext-field-install-solution-to-site.png) + ![installing field customizer to site](../../../images/ext-field-install-solution-to-site.png) -Choose the **field-extension-client-side-solution** app to install the solution on the site. Once the installation is completed, refresh the page by pressing **F5**. +9. Select the **field-extension-client-side-solution** app to install the solution on the site. After the installation is complete, refresh the page by selecting **F5**. -When the solution has been installed, Click **New** from the toolbar in **Site Contents** page and choose **List**: +10. When the solution has been installed, select **New** from the toolbar on the **Site Contents** page, and then select **List**. -![Creating a new list](../../../images/ext-field-create-new-list.png) + ![Creating a new list](../../../images/ext-field-create-new-list.png) -Create a list named **Invoices**: +11. Create a list named **Invoices**. -When the new list has been created, move back to the **Site Contents** page and choose **Settings** from the context menu of the just created list: +12. When the new list is created, on the **Site Contents** page, select **Settings** from the menu of the newly created list. -![List settings for the new list](../../../images/ext-field-list-settings.png) + ![List settings for the new list](../../../images/ext-field-list-settings.png) -Choose **Add from existing site columns** under the **Columns** section: +13. Under **Columns**, select **Add from existing site columns**. -Choose the **Percentage** field which was provisioned from the solution package, under the **SPFx Columns** group: +14. Under the **SPFx Columns** group, select the **Percentage** field that was provisioned from the solution package, and then select **OK**. -![Adding Percentage field to list](../../../images/ext-field-add-field-to-list.png) + ![Adding Percentage field to list](../../../images/ext-field-add-field-to-list.png) -Click **OK**. +15. On your console, ensure that the solution is running. If it's not running, execute the following command in the solution folder: -Move back to your console and ensure that the solution is running. If it's not running, execute the following command in the solution folder: + ``` + gulp serve --nobrowser + ``` -``` -gulp serve --nobrowser -``` -Navigate to the newly created **Invoices** list and add a few new items to the list with different values in the Percentage column to see how the field is being rendered without the Debug query parameters. +16. Go to the newly created **Invoices** list. Add a few items to the list with different values in the Percentage column to determine how the field is rendering without the debug query parameters. ![Field Rendering without Debug Query Parameters](../../../images/ext-field-render-field-without-debug.png) In this case, we continued to host the JavaScript from the localhost, but you could just as well relocate the assets to any CDN and update the URL to enable the loading of the JavaScript assets outside of the localhost as well. -The process for publishing your app is identical among the different extension types. You can follow the following publishing steps to update the assets to be hosted from a CDN. +The process for publishing your app is identical among the different extension types. You can use the following publishing steps to update the assets to be hosted from a CDN. -* [Deploy extension to Office 365 CDN](./hosting-extension-from-office365-cdn.md). +* [Host extension from Office 365 CDN](./hosting-extension-from-office365-cdn.md). From e97f4c09fee07f2a77b511b732d2e4d8cbff48f2 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Wed, 18 Oct 2017 05:15:18 -0700 Subject: [PATCH 07/26] Edit complete (#952) --- .../building-simple-cmdset-with-dialog-api.md | 344 +++++++++--------- 1 file changed, 177 insertions(+), 167 deletions(-) diff --git a/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md b/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md index 7eb9229a5..559188470 100644 --- a/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md +++ b/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md @@ -1,82 +1,84 @@ -# Build your first ListView Command Set extension +# Build your first ListView Command Set Extension -Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online and you can use modern JavaScript tools and libraries to build them. +Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online, and you can use modern JavaScript tools and libraries to build them. -You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=iW0LQQqAY0Y&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV). +This article describes how to create your first ListView Command Set Extension. You can follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=iW0LQQqAY0Y&list=PLR9nK3mnD-OXtWO5AIIr7nCR3sWutACpV). Screenshot of the YouTube video player for this tutorial ## Create an extension project -Create a new project directory in your favorite location. -``` -md command-extension -``` +1. Create a new project directory in your favorite location. + + ``` + md command-extension + ``` + +2. Go to the project directory. + + ``` + cd command-extension + ``` + +3. Create a new HelloWorld extension by running the Yeoman SharePoint Generator. + + ``` + yo @microsoft/sharepoint + ``` + +4. When prompted: -Go to the project directory. + * Accept the default value of **command-extension** as your solution name, and then select Enter. + * Select **SharePoint Online only (latest)**, and select Enter. + * Select **Use the current folder**, and select Enter. + * Select **N** to require the extension to be installed on each site explicitly when it's being used. + * Select **Extension** as the client-side component type to be created. + * Select **ListView Command Set** as the extension type to be created. -``` -cd command-extension -``` +5. The next set of prompts ask for specific information about your extension: -Create a new HelloWorld extension by running the Yeoman SharePoint Generator. + * Accept the default value of **HelloWorld** as your extension name, and then select Enter. + * Accept the default value of **HelloWorld description** as your extension description, and select Enter. -``` -yo @microsoft/sharepoint -``` + ![Yeoman SharePoint generator prompts to create an extension solution](../../../images/ext-com-yeoman-prompts.png) -When prompted: + At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the **HelloWorld** extension. This might take a few minutes. -* Accept the default value of **command-extension** as your solution name and press **Enter**. -* Choose **SharePoint Online only (latest)**, and press **Enter**. -* Choose **Use the current folder** and press **Enter**. -* Choose **N** to require extension to be installed on each site explicitly when it's being used. -* Choose **Extension** as the client-side component type to be created. -* Choose **ListView Command Set** as the extension type to be created. + When the scaffold is complete, you should see the following message indicating a successful scaffold: -The next set of prompts will ask for specific information about your extension: + ![SharePoint client-side solution scaffolded successfully](../../../images/ext-com-yeoman-complete.png) -* Accept the default value of **HelloWorld** as your extension name and press **Enter**. -* Accept the default value of **HelloWorld description** as your extension description and press **Enter**. + For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). -![Yeoman SharePoint generator prompts to create an extension solution](../../../images/ext-com-yeoman-prompts.png) +6. When the solution scaffolding is complete, type the following into the console to start Visual Studio Code. -At this point, Yeoman will install the required dependencies and scaffold the solution files along with the **HelloWorld** extension. This might take a few minutes. + ``` + code . + ``` -When the scaffold is complete, you should see the following message indicating a successful scaffold: + **Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. -![SharePoint client-side solution scaffolded successfully](../../../images/ext-com-yeoman-complete.png) + Note how the default solution structure looks like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types. -For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). + ![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-com-vscode-solution-structure.png) -Once the solution scaffolding is completed, type the following into the console to start Visual Studio Code. +7. Open **HelloWorldCommandSet.manifest.json** in the **src\extensions\helloWorld** folder. -``` -code . -``` - -> Notice that because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. - -Notice how the default solution structure is like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types. + This file defines your extension type and a unique identifier `id` for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint. -![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-com-vscode-solution-structure.png) + Note the actual command definitions in the manifest file. These are the actual buttons that are exposed based on the registration target. In the default template, you'll find two different buttons: **Command One** and **Command Two**. -Open **HelloWorldCommandSet.manifest.json** in the **src\extensions\helloWorld** folder. + ![ListView Command Set manifest json content](../../../images/ext-com-vscode-manifest.png) -This file defines your extension type and a unique identifier **“id”** for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint. + Currently, images are not properly referenced unless you are referring to them from absolute locations in a CDN within your manifest. This will be improved in future releases. -Notice also the actual command definitions in the manifest file. These are the actual buttons which will be exposed based on the registration target. In the default template, you'll find two different buttons: *"Command One"* and *"Command Two"* +## Code your ListView Command Set -![ListView Command Set manifest json content](../../../images/ext-com-vscode-manifest.png) - -> Currently, images are not properly referenced unless you are referring to them from absolute locations in a CDN within your manifest. This will be improved in future releases. - -## Coding your ListView Command Set Open the **HelloWorldCommandSet.ts** file in the **src\extensions\helloWorld** folder. -Notice that the base class for the ListView Command Set is imported from the **sp-listview-extensibility** package, which contains SharePoint framework code required by the ListView Command Set. +Notice that the base class for the ListView Command Set is imported from the **sp-listview-extensibility** package, which contains SharePoint Framework code required by the ListView Command Set. ```ts import { override } from '@microsoft/decorators'; @@ -92,9 +94,9 @@ import { Dialog } from '@microsoft/sp-dialog'; The behavior for your custom buttons is contained in the **onListViewUpdated()** and **OnExecute()** methods. -The **onListViewUpdated()** event occurs separately for each command (e.g. menu item), whenever a change happens in the ListView and the UI needs to be re-rendered. The `“event”` function parameter represents information about the command being rendered. The handler can use this information to customize the title or adjust the visibility. For example, if a command should only be shown when a certain number of items are selected in the list view. Here's the default implementation: +The **onListViewUpdated()** event occurs separately for each command (for example, a menu item) whenever a change happens in the ListView, and the UI needs to be re-rendered. The `event` function parameter represents information about the command being rendered. The handler can use this information to customize the title or adjust the visibility, for example, if a command should only be shown when a certain number of items are selected in the list view. This is the default implementation. -When using the method `“tryGetCommand”` you’ll get a Command object, which is a representation of the command that shows in the UI. You can modify its values, like `“title”`, or `“visible”` in order to modify the UI element. SPFx will use this information when re-rendering the commands. These objects keep the state from the last render, so if a command is set to `“visible = false”` it will remain invisible until is set back to `“visible = true”`. +When using the method `tryGetCommand`, you’ll get a Command object, which is a representation of the command that shows in the UI. You can modify its values, such as `title`, or `visible`, to modify the UI element. SPFx uses this information when re-rendering the commands. These objects keep the state from the last render, so if a command is set to `visible = false`, it will remain invisible until it is set back to `visible = true`. ```ts @override @@ -106,7 +108,9 @@ When using the method `“tryGetCommand”` you’ll get a Command object, which } } ``` -The **OnExecute()** method defines what happens when a command is executed (e.g. the menu item is clicked). In the default implementation, different messages are shown based on which button was clicked: + +The **OnExecute()** method defines what happens when a command is executed (for example, the menu item is selected). In the default implementation, different messages are shown based on which button was selected. + ```ts @override @@ -125,37 +129,41 @@ The **OnExecute()** method defines what happens when a command is executed (e.g. ``` -## Debugging your ListView Command Set using gulp serve and query string parameters -SharePoint Framework extensions cannot be currently tested using the local workbench, so you'll need to test and develop them directly against a live SharePoint Online site. You do not, however, need to deploy your customization to the app catalog to do this, which keeps the debugging experience simple and efficient. +## Debug your ListView Command Set using gulp serve and query string parameters -First, compile your code and host the compiled files from the local machine by running this command: -``` -gulp serve --nobrowser -``` +You cannot currently use the local workbench to test SharePoint Framework Extensions. You'll need to test and develop them directly against a live SharePoint Online site. You don't have to deploy your customization to the App Catalog to do this, which makes the debugging experience simple and efficient. -Notice that we used the `--nobrowser` option, since there's no value in launching the local workbench since you currently cannot debug extensions locally. +1. Compile your code and host the compiled files from the local machine by running this command: -Once it compiles the code without errors, it will serve the resulting manifest from *http://localhost:4321*. + ``` + gulp serve --nobrowser + ``` -Navigate to any SharePoint list in your SharePoint Online site using the modern experience. + You use the `--nobrowser` option because you don't need to launch the local workbench, since you can't debug extensions locally. -Since our ListView Command Set is hosted from localhost and is running, we can use specific debug query parameters to execute the code in the list view. + When the code compiles without errors, it will serve the resulting manifest from https://localhost:4321. -Append the following query string parameters to the URL. Notice that you will need to update the GUID to match the ID of your list view command set extension available in the **HelloWorldCommandSet.manifest.json** file: +2. Go to any SharePoint list in your SharePoint Online site by using the modern experience. + + Because our ListView Command Set is hosted from localhost and is running, we can use specific debug query parameters to execute the code in the list view. + +3. Append the following query string parameters to the URL. Notice that you will need to update the GUID to match the ID of your ListView Command Set Extension available in the **HelloWorldCommandSet.manifest.json** file: + + ``` + ?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}} + ``` -``` -?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}} -``` +More detail about the URL query parameters: -* **loadSPFX=true:** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Since no components are registered yet, we must explicitly load the framework. -* **debugManifestsFile:** specifies that we want to load SPFx components that are being locally served. Normally the loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). -* **customActions:** this URL query parameter simulates a custom action. There are many properties you can set on this *CustomAction* object that affect the look, feel, and location of your button; we’ll cover them all later. - * **Key:** guid of the extension - * **Location:** where the commands are displayed. The possible values are: - * **ClientSideExtension.ListViewCommandSet.ContextMenu:** The context menu of the item(s) - * **ClientSideExtension.ListViewCommandSet.CommandBar:** The top command set menu in a list or library - * **ClientSideExtension.ListViewCommandSet:** Both the context menu and the command bar (Corresponds to SPUserCustomAction.Location="CommandUI.Ribbon") -* **Properties:** an optional JSON object containing properties that will be available via the `this.properties` member. +- **loadSPFX=true** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Because no components are registered yet, we must explicitly load the framework. +- **debugManifestsFile** specifies that we want to load SPFx components that are being locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). +- **customActions** simulates a custom action. You can set many properties on this `CustomAction` object that affect the look, feel, and location of your button; we’ll cover them all later. + - **Key**: GUID of the extension. + - **Location**: Where the commands are displayed. The possible values are: + - **ClientSideExtension.ListViewCommandSet.ContextMenu:** The context menu of the item(s) + - **ClientSideExtension.ListViewCommandSet.CommandBar:** The top command set menu in a list or library + - **ClientSideExtension.ListViewCommandSet:** Both the context menu and the command bar (Corresponds to SPUserCustomAction.Location="CommandUI.Ribbon") + - **Properties**: An optional JSON object containing properties that are available via the `this.properties` member. The full URL should look similar to the following, depending on your tenant URL and the location of the list. @@ -163,83 +171,85 @@ The full URL should look similar to the following, depending on your tenant URL contoso.sharepoint.com/Lists/Orders/AllItems.aspx?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}} ``` -Accept the loading of Debug Manifests, by clicking **Load debug scripts** when prompted. - -![Accept loading debugripts](../../../images/ext-com-accept-debug-scripts.png) - -Notice new button available in the toolbar with title of *Command Two*. If you click that button, you'll see the text provided as property for the *sampleTextTwo* property. +4. Accept the loading of debug manifests by selecting **Load debug scripts** when prompted. + + ![Accept loading debugripts](../../../images/ext-com-accept-debug-scripts.png) + + Notice the new **Command Two** button available in the toolbar. If you select that button, you'll see the text provided as property for the `sampleTextTwo` property. -![Command Two button visible in the document library toolbar](../../../images/ext-com-default-customizer-output.png) + ![Command Two button visible in the document library toolbar](../../../images/ext-com-default-customizer-output.png) -*Command One* is not visible based on the code, until one row is selected in the document library. Upload or create a document to the library and confirm that the second button will be visible. + The **Command One** button is not visible based on the code, until one row is selected in the document library. Upload or create a document to the library and confirm that the second button is visible. -![Selecting one document to get Command One button visible](../../../images/ext-com-default-customizer-doc-select.png) + ![Selecting one document to get Command One button visible](../../../images/ext-com-default-customizer-doc-select.png) -Click *Command Two* button to also see how the dialog control works, which is used in the default output from solution scaffolding when ListView Command Set is selected as the extension type. +5. Select **Command Two** to see how the dialog control works, which is used in the default output from the solution scaffolding when the ListView Command Set is selected as the extension type. -![Selecting one document to get Command One button visible](../../../images/ext-com-default-customizer-btn-click.png) + ![Selecting one document to get Command One button visible](../../../images/ext-com-default-customizer-btn-click.png) -## Enhancing the ListView Command Set rendering -Default solution takes advantage of a new Dialog API, which can be used to show modal dialogs easily from your code. In following steps, we'll slightly modify the default experience to demonstrate Dialog API use cases. +## Enhance the ListView Command Set rendering -Return to the console and execute the following command to include the dialog API in our solution. +The default solution takes advantage of a new Dialog API, which can be used to show modal dialogs easily from your code. In the following steps, we'll slightly modify the default experience to demonstrate Dialog API use cases. -Return to Visual Studio Code (or your preferred editor). +1. Return to the console and execute the following command to include the Dialog API in our solution. -Open **HelloWorldCommandSet.ts** from the **src\extensions\helloWorld** folder. +2. Return to Visual Studio Code (or your preferred editor). -Add the following import statement for the `Dialog` class from `@microsoft/sp-dialog` after the existing import statements. - -Update the **onExecute** method as follows - -```ts - @override - public onExecute(event: IListViewCommandSetExecuteEventParameters): void { - switch (event.commandId) { - case 'COMMAND_1': - Dialog.alert(`Clicked ${strings.Command1}`); - break; - case 'COMMAND_2': - Dialog.prompt(`Clicked ${strings.Command2}. Enter something to alert:`).then((value: string) => { - Dialog.alert(value); - }); - break; - default: - throw new Error('Unknown command'); - } - } -``` -Switch back to your console window and ensure that you do not have any exceptions. If you do not already have the solution running in localhost, execute the following command: +3. Open **HelloWorldCommandSet.ts** from the **src\extensions\helloWorld** folder. -``` -gulp serve --nobrowser -``` +4. Add the following import statement for the `Dialog` class from `@microsoft/sp-dialog` after the existing import statements. -Return to the list view and use the same query parameters used previously with the Id matching your extension identifier available in the **HelloWorldCommandSet.manifest.json** file. +5. Update the **onExecute** method as follows: + + ```ts + @override + public onExecute(event: IListViewCommandSetExecuteEventParameters): void { + switch (event.commandId) { + case 'COMMAND_1': + Dialog.alert(`Clicked ${strings.Command1}`); + break; + case 'COMMAND_2': + Dialog.prompt(`Clicked ${strings.Command2}. Enter something to alert:`).then((value: string) => { + Dialog.alert(value); + }); + break; + default: + throw new Error('Unknown command'); + } + } + ``` + +6. In your console window, ensure that you do not have any exceptions. If you do not already have the solution running in localhost, execute the following command: -Accept the loading of Debug Manifests, by clicking **Load debug scripts** when prompted. + ``` + gulp serve --nobrowser + ``` -![Accept loading debugripts](../../../images/ext-com-accept-debug-scripts.png) +7. In the list view, use the same query parameters used previously with the ID matching your extension identifier available in the **HelloWorldCommandSet.manifest.json** file. -We still have the same buttons in the toolbar, but you'll notice they behave differently if you click them one-by-one. Now we are using the new dialog API, which can be easily used with your solutions even for complex scenarios. +8. Accept the loading of debug manifests by selecting **Load debug scripts** when prompted. -![Accept loading debugripts](../../../images/ext-com-show-adv-dialog-input.png) + ![Accept loading debugripts](../../../images/ext-com-accept-debug-scripts.png) + We still have the same buttons in the toolbar, but you'll notice they behave differently if you select them one-by-one. Now we are using the new Dialog API, which can be easily used with your solutions, even for complex scenarios. -## Adding a ListView Command Set to a solution package for deployment + ![Accept loading debugripts](../../../images/ext-com-show-adv-dialog-input.png) -Return to your solution in Visual Studio Code (or to your preferred editor). -Extend **sharepoint** folder and **assets** sub folder in the root of the solution to see existing **elements.xml** file. +## Add a ListView Command Set to a solution package for deployment -![assets folder in solution structure](../../../images/ext-com-assets-folder.png) +1. Return to your solution in Visual Studio Code (or to your preferred editor). -### Review elements.xml file +2. Extend the **sharepoint** folder and **assets** subfolder in the root of the solution to see the existing **elements.xml** file. + + ![assets folder in solution structure](../../../images/ext-com-assets-folder.png) + +### Review the elements.xml file -Open **elements.xml** file inside the **sharepoint\assets** folder. +Open the **elements.xml** file inside the **sharepoint\assets** folder. -Notice the following xml structure into **elements.xml**. **ClientSideComponentId** property has been automatically updated to the unique Id of your ListView Command Set available in the **HelloWorldCommandSet.manifest.json** file in the **src\extensions\helloWorld** folder. +Note the following XML structure in **elements.xml**. The **ClientSideComponentId** property has been automatically updated to the unique ID of your ListView Command Set available in the **HelloWorldCommandSet.manifest.json** file in the **src\extensions\helloWorld** folder. Notice that we use a specific location value of `ClientSideExtension.ListViewCommandSet.CommandBar` to define that this is a ListView Command Set and it should be displayed in the command bar. We also define the `RegistrationId` as **100** and the `RegistrationType` as **List** to associate this custom action automatically with generic lists. `ClientSideComponentProperties` can be used to provide instance specific configurations. In this case we are using default properties called *sampleTextOne* and *sampleTextTwo*. @@ -260,7 +270,7 @@ Notice that we use a specific location value of `ClientSideExtension.ListViewCom ``` -Possible location values which can be used with a ListView Command Set: +Possible location values that can be used with a ListView Command Set: * `ClientSideExtension.ListViewCommandSet.CommandBar` - Toolbar of the list or library * `ClientSideExtension.ListViewCommandSet.ContextMenu` - Context menu for list or library items @@ -297,62 +307,62 @@ Open **package-solution.json** from the **config** folder. The **package-solutio } ``` -To ensure that **element.xml** file is taken into account while the solution is being packaged, default scaffolding has added needed configuration to define a Feature Framework feature definition for the solution package. +To ensure that the **element.xml** file is taken into account while the solution is being packaged, default scaffolding added needed configuration to define a feature framework feature definition for the solution package. ## Deploy the Extension to SharePoint Online and host JavaScript from local host -Now you are ready to deploy the solution to a SharePoint site and to have the *CustomAction* automatically associated on the site level. - -In the console window, enter the following command to package your client-side solution that contains the extension, so that we get the basic structure ready for packaging: - -``` -gulp bundle -``` +Now you are ready to deploy the solution to a SharePoint site and to have the `CustomAction` automatically associated on the site level. -Next, execute the following command so that the solution package is created: +1. In the console window, enter the following command to package your client-side solution that contains the extension so that we get the basic structure ready for packaging: + + ``` + gulp bundle + ``` + +2. Execute the following command so that the solution package is created: + + ``` + gulp package-solution + ``` + + The command creates the package in the **sharepoint/solution** folder: + + ``` + command-extension.sppkg + ``` + +3. You now need to deploy the package that was generated to the App Catalog. To do this, go to your tenant's **App Catalog** and open the **Apps for SharePoint** library. -``` -gulp package-solution -``` +4. Upload or drag-and-drop the `command-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint displays a dialog and asks you to trust the client-side solution. -The command will create the package in the **sharepoint/solution** folder: - -``` -command-extension.sppkg -``` + Note that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to https://localhost:4321. + +5. Select the **Deploy** button. -Next you need to deploy the package that was generated to the App Catalog. + ![Trust operation in app catalog upload](./../../../images/ext-com-sppkg-deploy-trust.png) -Go to your tenant's **App Catalog** and open the **Apps for SharePoint** library. +6. In your console, ensure that the solution is running. If it's not running, execute the following command in the solution folder: -Upload or drag and drop the `command-extension.sppkg` located in the **sharepoint/solution** folder to the App Catalog. SharePoint will display a dialog and ask you to trust the client-side solution. - -Notice that we did not update the URLs for hosting the solution for this deployment, so the URL is still pointing to `https://localhost:4321`. Click the **Deploy** button. - -![Trust operation in app catalog upload./../../../images/ext-com-sppkg-deploy-trust.png) - -Move back to your console and ensure that the solution is running. If it's not running, execute the following command in the solution folder: - -``` -gulp serve --nobrowser -``` + ``` + gulp serve --nobrowser + ``` -Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package. +7. Go to the site where you want to test SharePoint asset provisioning. This could be any site collection in the tenant where you deployed this solution package. -Chose the gear icon on the top navigation bar on the right and choose **Add an app** to go to your Apps page. +8. Select the gears icon on the top navigation bar on the right, and then select **Add an app** to go to your Apps page. -In the **Search** box, enter '**extension**' and press *Enter* to filter your apps. +9. In the **Search** box, enter **extension**, and then select Enter to filter your apps. -![installing the listview command set to a site](../../../images/ext-com-install-solution-to-site.png) + ![installing the listview command set to a site](../../../images/ext-com-install-solution-to-site.png) -Choose the **command-extension-client-side-solution** app to install the solution on the site. When the installation is completed, refresh the page by pressing **F5**. +10. Select the **command-extension-client-side-solution** app to install the solution on the site. When the installation is complete, refresh the page by selecting **F5**. -When the application has been successfully installed, Click **New** from the toolbar on the **Site Contents** page and choose **List** +11. When the application has been successfully installed, select **New** from the toolbar on the **Site Contents** page, and then select **List**. -![Cring a new list](../../../images/ext-com-create-new-list.png) + ![Creating a new list](../../../images/ext-com-create-new-list.png) -Provide the name as **Sample** and click **Create**. +12. Provide the name as **Sample**, and then select **Create**. -Notice how **Command One** and **Command Two** are being rendered in the toolbar based on your ListView Command Set customizations. + Notice how **Command One** and **Command Two** are rendering in the toolbar based on your ListView Command Set customizations. -![Addional buttons visible in the toolbar](../../../images/ext-com-dialog-visible-deployment.png) + ![Additional buttons visible on the toolbar](../../../images/ext-com-dialog-visible-deployment.png) From 7e519cd2d7d2fc8959fbdcd715b6c257e1b7d1bf Mon Sep 17 00:00:00 2001 From: Yannick Plenevaux Date: Wed, 18 Oct 2017 14:16:23 +0200 Subject: [PATCH 08/26] Update tenant-properties.md (#950) Fixes a small typo in Set-SPOStorageEntity example --- docs/spfx/tenant-properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spfx/tenant-properties.md b/docs/spfx/tenant-properties.md index d7339fc9a..3502af5d1 100644 --- a/docs/spfx/tenant-properties.md +++ b/docs/spfx/tenant-properties.md @@ -22,7 +22,7 @@ Get-SPOStorageEntity [-Site] [-Key] Applies to: Office 365, SharePoint Online Syntax -Get-SPOStorageEntity [-Site] [-Key] [-Value] [-Description] [-Comments] +Set-SPOStorageEntity [-Site] [-Key] [-Value] [-Description] [-Comments] ## Reading tenant properties From 1a90930ad390d41f29069a1a2e6f7a2ff3b5e6f8 Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Wed, 18 Oct 2017 14:17:10 +0200 Subject: [PATCH 09/26] Updated team-based development guidance (#954) --- ...sed-development-on-sharepoint-framework.md | 32 +++++++++++-------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/spfx/team-based-development-on-sharepoint-framework.md b/docs/spfx/team-based-development-on-sharepoint-framework.md index 883ef33ff..68744ebef 100644 --- a/docs/spfx/team-based-development-on-sharepoint-framework.md +++ b/docs/spfx/team-based-development-on-sharepoint-framework.md @@ -36,7 +36,7 @@ Building SharePoint Framework solutions requires developers to use a certain set SharePoint Framework requires Node.js to be installed on the developer machine. Node.js is used as the runtime for design-time tools used to build and package the project. Node.js is installed globally on the developer machine and there are solutions available to support running multiple versions of Node.js side-by-side if necessary. -> More information about installing Node.js and the supported versions is available at [https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment). +> See more information about [installing Node.js and the supported versions](./set-up-your-development-environment.md). #### Npm @@ -74,7 +74,7 @@ In the past it was challenging for many organizations to justify providing Share Probably the easiest option to setup a development environment for SharePoint Framework projects is to install all the tools directly on the host machine. If your team is working only on SharePoint Framework projects, then they can install Node.js on their machines. If they work on other Node.js projects as well then they could use third party solutions such as [nvm](https://github.com/creationix/nvm) to run multiple versions of Node.js side-by-side. -Following the tools required by the SharePoint Framework toolchain, developers would install Yeoman and the SharePoint Framework Yeoman generator. Typically both these tools are installed globally. Given however, that the SharePoint Framework Yeoman generator is tied to a specific version of the SharePoint Framework and developers might need to work with projects created using a different version, they would have to uninstall and install the version of the generator specific for the particular project they are working on at the moment. A more viable approach would be to install both Yeoman and the SharePoint Framework Yeoman generator locally in the given project. While it introduces some overhead it helps developers ensure that should they need to add new elements to the project in the future they would be compatible with the rest of the project. +Following the tools required by the SharePoint Framework toolchain, developers would install Yeoman and the SharePoint Framework Yeoman generator. Typically both these tools are installed globally. Given however, that the SharePoint Framework Yeoman generator is tied to a specific version of the SharePoint Framework and developers might need to work with projects created using a different version, they would have to uninstall and install the version of the generator specific for the particular project they are working on at the moment. A more viable approach would be to install Yeoman globally but the SharePoint Framework Yeoman generator locally in the given project. While it introduces some overhead, it helps developers ensure that should they need to add new elements to the project in the future they would be compatible with the rest of the project. Big benefit of developing on the host is that developers can configure their machine to their preferences once and use it across all projects. Also, as the software executes on the host, it has direct access to the CPU, memory and disk I/O without a virtualization layer in between which leads to a better performance than when running the same software virtualized. @@ -100,7 +100,7 @@ SharePoint Framework is based on open source toolchain and follows the general d ### Create new SharePoint Framework project -When building SharePoint customizations using the SharePoint Framework the first step is to scaffold new SharePoint Framework project. This is done using the SharePoint Framework Yeoman generator. The generator will prompt you to answer a few questions regarding the name of the project or its location. It will also allow you to create the first web part. The important thing to remember is, that the framework you choose to build the first web part with, will be automatically used for all other web parts you will add to the project later on. While you are free to manually change the framework yourself, the general recommendation is to use a single framework per SharePoint Framework project. +When building SharePoint customizations using the SharePoint Framework the first step is to scaffold new SharePoint Framework project. This is done using the SharePoint Framework Yeoman generator. The generator will prompt you to answer a few questions regarding the name of the project or its location. It will also allow you to create the first web part or extension. Although you are free to choose a different JavaScript framework for each of your components, the general recommendation is to use a single framework per SharePoint Framework project. ### Lock dependencies version @@ -132,7 +132,7 @@ As your team develops the solution, new or updated dependencies might be added t Using existing packages to accomplish specific tasks allows you to be more productive. npmjs.com is a public registry of packages that you can use in your project. -> Note: Since there is no formal verification process before a package is published to npmjs.com, you should carefully examine if you can use the particular package both from the contents and license point of view. +> **Important:** Since there is no formal verification process before a package is published to npmjs.com, you should carefully examine if you can use the particular package both from the contents and license point of view. To add a package to your SharePoint Framework project execute the `npm install --save` or `npm install --save-dev` command in the command line, eg. `npm install angular --save`. Using the `--save` or `--save-dev` argument ensures that the package is added to the **package.json** file and other developers on your team will get it as well when restoring dependencies. Without it building the project on a machine other than your own will fail. When adding packages that are required by your solution on runtime, such as Angular or jQuery, you should use the `--save` argument. Packages that are required in the build process, such as additional gulp tasks, should be installed with the `--save-dev` argument. @@ -150,7 +150,7 @@ When using private package registries organizations can choose between different Using a private package registry allows organizations to centrally manage common code used across the different projects. By defining a separate governance plan around contributing changes to the shared code base, organizations can ensure that the code library is of high quality and that it offers all developers benefits as intended rather than being a burden slowing projects down. -A popular private registry hosted in the cloud is [npm Enterprise](https://www.npmjs.com/enterprise). Organizations that are interested in hosting their registry themselves can choose from a number of open source implementations such as [Sinopia](https://github.com/rlidwka/sinopia) or its fork [Verdaccio](https://github.com/verdaccio/verdaccio) or [Nexus](https://www.sonatype.com/nexus-repository-oss). +Organizations using Visual Studio Team Services or the Team Foundation Server, can conveniently [create a private npm registry directly in VSTS/TFS](https://docs.microsoft.com/en-us/vsts/package/overview). Organizations using other source control systems, can use other solutions for hosting their packages. A popular private registry hosted in the cloud is [npm Enterprise](https://www.npmjs.com/enterprise). Organizations that are interested in hosting their registry themselves can choose from a number of open source implementations such as [Sinopia](https://github.com/rlidwka/sinopia) or its fork [Verdaccio](https://github.com/verdaccio/verdaccio) or [Nexus](https://www.sonatype.com/nexus-repository-oss). > Note: Different engines for hosting private package registries are in different development stages and you should carefully evaluate that the particular engine meets your requirements, both from the functionality, license and support point of view. @@ -211,7 +211,7 @@ SharePoint Framework offers standard support for the [Karma](http://karma-runner Where linting is helpful to validate the syntax of the particular file, often developers need more support in order to verify that the project as a whole meets the guidelines. Generally linters focus on the code itself but miss the context of what the particular code file represents. In SharePoint Framework solutions artifacts have specific requirements, for example a web part should have a unique ID in the project. Also organizations might have other requirements such as not referencing scripts from CDN or only using a specific version of a particular library. This is where linters generally fall short and developers need other tools. -[SharePoint Code Analysis Framework](http://rencore.com/spcaf) (SPCAF) is a third part solution frequently used by SharePoint developers, administrators and employees in quality assurance and security roles to verify that SharePoint customizations meet organizational quality guidelines. SPCAF integrates with the whole application lifecycle process helping organizations lower the total cost of ownership of SharePoint customizations. SPCAF offers a set of rules that specifically target SharePoint Framework solutions. +[SharePoint Code Analysis Framework](http://rencore.com/spcaf) (SPCAF) is a third party solution frequently used by SharePoint developers, administrators and employees in quality assurance and security roles to verify that SharePoint customizations meet organizational quality guidelines. SPCAF integrates with the whole application lifecycle process helping organizations lower the total cost of ownership of SharePoint customizations. SPCAF offers a set of rules that specifically target SharePoint Framework solutions. ## Upgrading SharePoint Framework projects @@ -239,23 +239,29 @@ When updating a part of a SharePoint Framework solution, developers should incre #### Increase package version in package.json -SharePoint Framework package is structured like a Node.js package. Its dependencies and metadata are stored in the **package.json** file in the project folder. One of the properties in the **package.json** file is the version property that denotes the version of the whole project. Although it's purely informational and it's not used by any of the deployed artifacts, developers should increase the version number in the **package.json** every time a new release of the project is planned following the SemVer convention. +SharePoint Framework package is structured like a Node.js package. Its dependencies and metadata are stored in the **package.json** file in the project folder. One of the properties in the **package.json** file is the version property that denotes the version of the whole project. By default, all components in the current solution inherit this version number as their version. Developers should increase the version number in the **package.json** file every time a new release of the project is planned following the SemVer convention. #### Increase solution package version in package-solution.json -SharePoint Framework solutions are deployed using an **.spapp** file installed in the App Catalog on a SharePoint tenant. An **.spapp** file is similar to a SharePoint add-in package and follows the same versioning conventions. The current version of the **.spapp** package is defined using a four-part (MAJOR.MINOR.REVISION.BUILD) number stored in the **config/package-solution.json** file. For clarity, developers should keep this number in sync with the version number in the **package.json** file as both number refer to the version of the project as a whole. +SharePoint Framework solutions are deployed using an **.sppkg** file installed in the App Catalog on a SharePoint tenant. An **.sppkg** file is similar to a SharePoint add-in package and follows the same versioning conventions. The current version of the **.sppkg** package is defined using a four-part (MAJOR.MINOR.REVISION.BUILD) number stored in the **config/package-solution.json** file. For clarity, developers should keep this number in sync with the version number in the **package.json** file as both number refer to the version of the project as a whole. > Note: Increasing the version number in the package-solution.json file between releases is required in order for the new version of the package to be correctly deployed in SharePoint. -#### Increase web part version in the web part manifest +### Update dependencies -Each client-side web part built on the SharePoint Framework contains a manifest that provides the SharePoint Framework with information about that web part such as its title, icon, properties and where the code bundle is located. Each web part also has its own version number stored in the manifest of each web part in the **version** property. The **version** property follows the SemVer schema with three numbers without a label. Web part manifest is included in the **.spapp** package which is deployed to SharePoint. +One of the reasons for an update of a SharePoint Framework project might be a change to one of the underlying dependencies, for example a new release of Angular with bug fixes and performance improvements. If your team follows the recommended approach of using npm shrinkwrap for locking dependencies' versions then you would use the `npm install @ --save` command to update your dependency to the specific version and test your project to verify that it works as expected with the latest updates. Depending on how the changes to the underlying dependencies impact the project, the overall project update might vary from a patch to a full major release. -When updating a web part, developers should change its version number in a way that corresponds to the scope of applied changes. If the project contains multiple web parts and the particular web part hasn't been changed between releases then the version number of that web part shouldn't be changed. +> **Important:** don't modify the version numbers of dependencies in the **package.json** file manually. If you're using a lock file such as npm shrinkwrap, your manual changes to the package.json file will be ignored and the version numbers recorded in the lock files will be used instead which will lead to hard to track errors in your project. -### Update dependencies +#### Mind project structure changes -One of the reasons for an update of a SharePoint Framework project might be a change to one of the underlying dependencies, for example a new release of Angular with bug fixes and performance improvements. If your team follows the recommended approach of using npm shrinkwrap for locking dependencies' versions then you would use the `npm install @ --save` command to update your dependency to the specific version and test your project to verify that it works as expected with the latest updates. Depending on how the changes to the underlying dependencies impact the project, the overall project update might vary from a patch to a full major release. +Updating your project to a newer version of the SharePoint Framework, might require changes to your project structure and project configuration files. Before updating the versions of the SharePoint Framework in your project dependencies, you should always create a new project using the version of the SharePoint Framework to which you want to upgrade and carefully compare its structure and contents with your existing project. This will allow you to determine the impact of the upgrade on your project and help you avoid applying breaking changes to your project. + +#### Beware of using npm outdated + +One of the ways to find out which dependencies in your project need updating, is to run the **npm outdated** command. This command will scan your dependency tree and will show you which packages could be updated. While using this command is convenient, it has to be done with caution. + +Starting from version 1.3, the SharePoint Framework Yeoman generator allows you to choose whether you want to scaffold a project that should work only in SharePoint Online or in both SharePoint 2016 Feature Pack 2 and up and SharePoint Online. SharePoint hosted on-premises uses an older version of the SharePoint Framework than the latest version available in SharePoint Online. If you would run the **npm outdated** command on a project compatible with SharePoint on-premises, it would suggest updating all core SharePoint Framework packages to the latest versions published to Npm. Unfortunately, by updating these packages to their latest versions, your project wouldn't work with SharePoint on-premises anymore. Before updating the versions of the SharePoint Framework packages, you should always verify if your project is meant to work with SharePoint hosted on-premises and if so, what version of the SharePoint Framework you have to support. ### Build and package project in release mode From e18cc5197d2be36a70bd80f52e8b368f596d11e8 Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Wed, 18 Oct 2017 14:18:03 +0200 Subject: [PATCH 10/26] Updated guidance on SPFx development for SP2016 FP2 (#955) --- docs/spfx/sharepoint-2016-support.md | 36 +++++++--------------------- 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/docs/spfx/sharepoint-2016-support.md b/docs/spfx/sharepoint-2016-support.md index 15aa5efb1..fc135451c 100644 --- a/docs/spfx/sharepoint-2016-support.md +++ b/docs/spfx/sharepoint-2016-support.md @@ -5,39 +5,21 @@ ms.date: 09/25/2017 # SharePoint Framework development with SharePoint 2016 Feature Pack 2 -SharePoint 2016 Feature Pack 2 supports SharePoint Framework client-side web parts hosted in classic SharePoint pages. +SharePoint 2016 Feature Pack 2 supports SharePoint Framework client-side web parts hosted in classic SharePoint pages. -An introduction to SharePoint Framework development in SharePoint 2016 using Feature Pack 2 is also covered in the following video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=LGLMxnmHk6U&list=PLR9nK3mnD-OXZbEvTEPxzIOMGXj_aZKJG). +An introduction to SharePoint Framework development in SharePoint 2016 using Feature Pack 2 is also covered in the following video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=LGLMxnmHk6U&list=PLR9nK3mnD-OXZbEvTEPxzIOMGXj_aZKJG). > [!VIDEO https://www.youtube.com/embed/LGLMxnmHk6U?list=PLR9nK3mnD-OXZbEvTEPxzIOMGXj_aZKJG] ## Which version of the SharePoint Framework to use -Since SharePoint Online and SharePoint 2016 have different release cycles for new capabilities, they also have different capabilities when it comes to the SharePoint Framework. SharePoint Online always uses the latest version of the SharePoint Framework, but SharePoint 2016 only supports the version which matches the server-side dependencies of the deployed packages. +Since SharePoint Online and SharePoint 2016 have different release cycles for new capabilities, they also have different capabilities when it comes to the SharePoint Framework. SharePoint Online always uses the latest version of the SharePoint Framework, but SharePoint 2016 only supports the version which matches the server-side dependencies of the deployed packages. -SharePoint 2016 Feature Pack 2 supports SharePoint Framework client-side web parts hosted in classic SharePoint pages built using the SharePoint Framework v1.0. This means that when you are targeting the SharePoint 2016 platform, you'll need to use the SharePoint Framework v1.0.2 due to the server-side version dependencies. +SharePoint 2016 Feature Pack 2 supports SharePoint Framework client-side web parts hosted in classic SharePoint pages built using the SharePoint Framework v1.1.0. This means that when you are targeting the SharePoint 2016 platform, you'll need to use the SharePoint Framework v1.1.0 due to the server-side version dependencies. -If you are planning to use the same client-side web parts in both SharePoint 2016 and in SharePoint Online, you will need to use the SharePoint Framework v1.0.2 as your baseline version to ensure that the web part works in both environments. +If you are planning to use the same client-side web parts in both SharePoint 2016 and in SharePoint Online, you will need to use the SharePoint Framework v1.1.0 as your baseline version to ensure that the web part works in both environments. -## Installing the SharePoint Framework version needed for SP2016 development - -You should ensure that you are using the right version of the SharePoint Framework on your development machine. You can check the currently globally installed SharePoint Framework Yeoman template package version using the following command: - -``` -npm list -g --depth 0 -``` - -This will list the globally installed packages, including their versions. If the `@microsoft/generator-sharepoint` package version is incorrect, you can uninstall the generator by using the following command: - -``` -npm uninstall -g @microsoft/generator-sharepoint -``` - -To install v1.0.2 of the SharePoint Framework Yeoman templates, you can use the following command: - -``` -npm install -g @microsoft/generator-sharepoint@1.0.2 -``` +Starting from version 1.3, the SharePoint Framework Yeoman generator supports scaffolding solutions both that use the latest version of the SharePoint Framework meant for use with SharePoint Online, and solutions that can be used also with SharePoint on-premises based on the v1.1.0 of the SharePoint Framework. You don't need to install a separate version of the SharePoint Framework Yeoman generator to scaffold solutions meant for use with SharePoint on-premises. ## Hosting your SharePoint Framework solution for on-premises deployment @@ -54,13 +36,13 @@ You can host the JavaScript files in the location that best fits your environmen > You can find more details on blocked file types in SharePoint 2016 from the following support article: [Types of files that cannot be added to a list or library](https://support.office.com/en-us/article/Types-of-files-that-cannot-be-added-to-a-list-or-library-30be234d-e551-4c2a-8de8-f8546ffbf5b3#ID0EAADAAA=2016) -## Development environment considerations +## Development environment considerations When you are developing SharePoint Framework client-side web parts you need Internet connectivity to access npm packages. This is required when solutions are being scaffolded using the SharePoint Framework Yeoman templates. If Internet access is not available for the development machines, you can setup a local on-premises registry for the required npm packages. However, this requires additional software and a significant amount of work to setup and maintain local package versions with packages in the actual npm gallery. -> The [Team-based development on the SharePoint Framework](team-based-development-on-sharepoint-framework.md) guidance document includes different options for development environment setup including when you might need to support multiple SharePoint Framework versions. +> The [Team-based development on the SharePoint Framework](team-based-development-on-sharepoint-framework.md) guidance document includes different options for development environment setup including when you might need to support multiple SharePoint Framework versions. ## How to determine which SharePoint Framework version was used for a solution @@ -69,4 +51,4 @@ If you have existing SharePoint Framework solutions and you'd like to confirm wh - **.yo-rc.json** - file in the solution's root folder that stores the SharePoint Framework Yeoman template version used when the solution was created. - **package.json** - file in the solution's root folder that contains references to package versions used in the solution. - **npm-shrinkwrap.json** - file in the solution's root folder that contains information about the exact versions used (if you used the `npm shrinkwrap` command to lock-down the exact versions of the solution). --- **package.json** - file in the *node_modules/@microsoft/sp-webpart-base* folder that contains a *version* attribute matching the used SharePoint Framework version, if you have installed packages to your solution. +- **package.json** - file in the *node_modules/@microsoft/sp-webpart-base* folder that contains a *version* attribute matching the used SharePoint Framework version, if you have installed packages to your solution. From d68d6cf927d69696a3561f7d8ffe9a3ed9dbd03c Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Wed, 18 Oct 2017 14:18:55 +0200 Subject: [PATCH 11/26] Updated the GraphHttpClient guidance (#956) --- docs/spfx/overview-graphhttpclient.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/spfx/overview-graphhttpclient.md b/docs/spfx/overview-graphhttpclient.md index 12d739c3f..78f5a3555 100644 --- a/docs/spfx/overview-graphhttpclient.md +++ b/docs/spfx/overview-graphhttpclient.md @@ -1,7 +1,7 @@ # Overview of the GraphHttpClient class (preview) > [!IMPORTANT] ->The **GraphHttpClient** is currently in preview and is subject to change. It is not currently supported for use in production environments. +> The **GraphHttpClient** is currently in preview and is subject to change. It is not currently supported for use in production environments. You can use Microsoft Graph to build powerful solutions that access data from Office 365 and other Microsoft services. To connect SharePoint Framework (SPFx) solutions to Microsoft Graph, you have to register an Azure Active Directory (Azure AD) application and complete the authorization flow. To make this easier, you can use the SPFx **GraphHttpClient** class to call Microsoft Graph directly, without any additional setup. @@ -13,7 +13,7 @@ The following example shows a request to Microsoft Graph that uses the **GraphHt ```ts // ... -import { GraphHttpClient, GraphClientResponse } from '@microsoft/sp-http'; +import { GraphHttpClient, GraphHttpClientResponse } from '@microsoft/sp-http'; export default class MyApplicationCustomizer extends BaseApplicationCustomizer { @@ -23,7 +23,7 @@ export default class MyApplicationCustomizer @override public onRender(): void { this.context.graphHttpClient.get("v1.0/groups?$select=displayName", GraphHttpClient.configurations.v1) - .then((response: GraphClientResponse): Promise => { + .then((response: GraphHttpClientResponse): Promise => { return response.json(); }) .then((data: any): void => { @@ -32,16 +32,17 @@ export default class MyApplicationCustomizer } } ``` + To make a request to Microsoft Graph: -- Import the **GraphHttpClient** and **GraphClientResponse** modules from the **@microsoft/sp-http** package. -- Use the instance of **GraphHttpClient** that's available on the `this.context.graphHttpClient` property to issue a GET or POST request to Microsoft Graph. -- As parameters, specify the Microsoft Graph API that you want to call (start with the API version without a leading `/` - slash), followed by the **GraphHttpClient** configuration. +- Import the **GraphHttpClient** and **GraphHttpClientResponse** modules from the **@microsoft/sp-http** package. +- Use the instance of **GraphHttpClient** that's available on the `this.context.graphHttpClient` property to issue a GET or POST request to Microsoft Graph. +- As parameters, specify the Microsoft Graph API that you want to call (start with the API version without a leading `/` - slash), followed by the **GraphHttpClient** configuration. - Optionally, you can specify additional request headers that will be merged with the default headers set by **GraphHttpClient** (`'Accept': 'application/json'`, `'Authorization': 'Bearer [token]'` and `'Content-Type': 'application/json; charset=utf-8'`). ## Considerations for using the **GraphHttpClient** class -The **GraphHttpClient** class provides a convenient way to communicate with Microsoft Graph because it abstracts the authorization flow and management of access tokens. Because **GraphHttpClient** is currently in developer preview, there are some considerations that you should take into account before using it. +The **GraphHttpClient** class provides a convenient way to communicate with Microsoft Graph because it abstracts the authorization flow and management of access tokens. Because **GraphHttpClient** is currently in developer preview, there are some considerations that you should take into account before using it. ### Use for Microsoft Graph access only @@ -49,10 +50,10 @@ Use the **GraphHttpClient** class only to access Microsoft Graph. The URL specif ### Permissions -The GraphHttpClient uses the Office 365 SharePoint Online Azure AD application to retrieve a valid access token to Microsoft Graph on behalf of the current user. The retrieved access token contains two permissions: +The GraphHttpClient uses the Office 365 SharePoint Online Azure AD application to retrieve a valid access token to Microsoft Graph on behalf of the current user. The retrieved access token contains two permissions: -* Read and write all groups (preview) (`Group.ReadWrite.All`) -* Read all usage reports (`Reports.Read.All`) +- Read and write all groups (preview) (`Group.ReadWrite.All`) +- Read all usage reports (`Reports.Read.All`) These are the only permissions that are available when you use **GraphHttpClient**. If you need other permissions for your solution, you can use [ADAL JS with implicit OAuth flow](web-parts/guidance/call-microsoft-graph-from-your-web-part.md) instead. From 21af9583061f178ed0078d53b27cac392780a2ba Mon Sep 17 00:00:00 2001 From: jmaznerMSFT <31773691+jmaznerMSFT@users.noreply.github.com> Date: Wed, 18 Oct 2017 09:23:22 -0700 Subject: [PATCH 12/26] Update column-formatting.md updated first conditional example so that JSON matches image, and updated conditional operator definition --- docs/declarative-customization/column-formatting.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/declarative-customization/column-formatting.md b/docs/declarative-customization/column-formatting.md index 4f3f89be1..fe24f0503 100644 --- a/docs/declarative-customization/column-formatting.md +++ b/docs/declarative-customization/column-formatting.md @@ -74,8 +74,8 @@ The following image shows an example of conditional formatting applied to a numb ![Severity warning of 70 with orange background](../images/sp-columnformatting-conditionalbasic.png) -This example customizes a number field to color that field red when its value less than 70. This example adds a style attribute to the parent `
` element, specifies a CSS class (`sp-field-severity--warning`) to apply to that item if the value inside the field is less than 70, and specifies no color if the value is outside that range (in which case it will use the default color for values in that list view). -Note: this example uses a binary operation with the less than operator, "<", nested inside the conditional operation indicated by the operator, "?". Another description of the section in the following example is: If @currentField < 70 Then class = sp-field-severity--warning. +This example customizes a number field to color that field yellow when its value is 70 or less. This example adds a style attribute to the parent `
` element, specifies a CSS class (`sp-field-severity--warning`) to apply to that item if the value inside the field is less than or equal to 70, and specifies no color if the value is outside that range (in which case it will use the default color for values in that list view). +Note: this example uses a binary operation with the less than operator, "<", nested inside the conditional operation indicated by the operator, "?". Another description of the section in the following example is: If @currentField <= 70 Then class = sp-field-severity--warning. ```JSON { @@ -86,7 +86,7 @@ Note: this example uses a binary operation with the less than operator, "<", nes "operator": "?", "operands": [ { - "operator": "<", + "operator": "<=", "operands": [ "@currentField", 70 @@ -901,7 +901,7 @@ Operators specify the type of operation to perform. The following operators are - Date() - cos - sin -- : +- ? **Binary operators** - The following are the standard arithmetic binary operators that expect two operands: @@ -924,7 +924,7 @@ Operators specify the type of operation to perform. The following operators are **Conditional operator** - The conditional operator is: -- : +- ? This is to achieve an expression equivalent to a ? b : c, where if the expression a evaluates to true, then the result is b, else the result is c. From f851bab35e8b9861ae60b95111d31f3953ea7fb9 Mon Sep 17 00:00:00 2001 From: "Chakkaradeep (Chaks) CC" Date: Thu, 19 Oct 2017 16:40:11 -0700 Subject: [PATCH 13/26] Doc updates for tenant properties Fixed few things and added a missing cmdlet - Remove-SPOStorageEntity. --- docs/spfx/tenant-properties.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/spfx/tenant-properties.md b/docs/spfx/tenant-properties.md index 3502af5d1..587d0bfea 100644 --- a/docs/spfx/tenant-properties.md +++ b/docs/spfx/tenant-properties.md @@ -1,16 +1,18 @@ # SharePoint Framework Tenant Properties ->**Note:** Tenant Propeties is currently in preview in First Release and is subject to change. They are not currently supported for use in production environments. +>**Note:** Tenant Propeties is currently in preview in First Release and is subject to change. They are currently not supported for use in production environments. Tenant properties allows tenant administrators to add properties in the app catalog that can be read by various SharePoint Framework components. The tenant properties are managed by tenant administrators using the [Microsoft SharePoint Online Management Shell](https://technet.microsoft.com/en-us/library/fp161372.aspx) which is a PowerShell module to manage your SharePoint Online subscription in the Office 365. ## Manage tenant properties -Using the Microsoft SharePoint Online Management Shell, tenant administrators can add and remove tenant properties in PowerShell. +Using the Microsoft SharePoint Online Management Shell, tenant administrators can add and remove tenant properties using PowerShell. > Download the Microsoft SharePoint Online Management Shell [here](https://www.microsoft.com/en-us/download/details.aspx?id=35588) -The following PowerShell commands are available to manage the tenant properties: +The following PowerShell cmdlets are available to manage the tenant properties: + +Since tenant properties are stored in the tenant app catalog, you will need to provide the tenant app catalog site collection URL in the cmdlets below. ### Get-SPOStorageEntity Applies to: Office 365, SharePoint Online @@ -24,6 +26,12 @@ Applies to: Office 365, SharePoint Online Syntax Set-SPOStorageEntity [-Site] [-Key] [-Value] [-Description] [-Comments] +### Remove-SPOStorageEntity +Applies to: Office 365, SharePoint Online + +Syntax +Remove-SPOStorageEntity [-Site] [-Key] + ## Reading tenant properties Developers can read tenant properties using the SharePoint REST APIs and use them in SharePoint Framework components such as web parts and extensions. From ee45f8c7d6edf7cb4235c489dcfd02eeac6e6a3e Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Fri, 20 Oct 2017 13:46:48 +0200 Subject: [PATCH 14/26] Updated enterprise guidance (#957) --- docs/spfx/enterprise-guidance.md | 38 ++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/spfx/enterprise-guidance.md b/docs/spfx/enterprise-guidance.md index 8bec7e8fa..7b76189df 100644 --- a/docs/spfx/enterprise-guidance.md +++ b/docs/spfx/enterprise-guidance.md @@ -46,7 +46,7 @@ The SharePoint Framework solutions does not, at the time of writing, have a stor ### JavaScript embeddings -One of the more popular approaches used by developers has been to use a method called JavaScript embeddings (also known as JavaScript injections). That means that arbitrary JavaScript has been inserted to the sites and pages using for instance Custom Actions, master pages or page layouts and even Script Editor Web Parts. This method has proven more simple than creating SharePoint hosted add-ins and also allows the script code to run in the full context of the users and therefore gained a lot of popularity. The downside with this approach is that many of these embeddings relied on DOM manipulation and that it required developers skills to do and maintain. And due to the evergreen nature of SharePoint Online these solutions built using JavaScript embeddings could potentially break whenever SharePoint Online was updated, since the developers might have taken dependencies (even accidentally) on how the SharePoint pages is structured or styled. When updates are done in SharePoint, even minor and subtle, it can have huge impacts on these solutions and cause the embedded JavaScript to break completley. +One of the more popular approaches used by developers has been to use a method called JavaScript embeddings (also known as JavaScript injections). That means that arbitrary JavaScript has been inserted to the sites and pages using for instance Custom Actions, master pages or page layouts and even Script Editor Web Parts. This method has proven more simple than creating SharePoint hosted add-ins and also allows the script code to run in the full context of the users and therefore gained a lot of popularity. The downside with this approach is that many of these embeddings relied on DOM manipulation and that it required developers skills to do and maintain. And due to the evergreen nature of SharePoint Online these solutions built using JavaScript embeddings could potentially break whenever SharePoint Online was updated, since the developers might have taken dependencies (even accidentally) on how the SharePoint pages is structured or styled. When updates are done in SharePoint, even minor and subtle, it can have huge impacts on these solutions and cause the embedded JavaScript to break completely. Now with the SharePoint Framework there is, a by Microsoft standardized and supported, way to achieve many of these solutions previously built using JavaScript embeddings. ### Script Editor Web Parts @@ -82,53 +82,53 @@ Developers of the SharePoint Framework solution can choose to use any CDN servic By default, there is a built-in task in the build tools to deploy the packaged solution to an Azure Blob storage. This is something that is typically extended, by SI's or ISV's, to support custom CDN locations or configurations. -Once the SharePoint Framework solution is deployed to a CDN, there is no requirement to re-deploy the package in the App Catalog or update any of the SharePoint Framework artifacts, such as client-side web parts, when updates are done to the solution resources, such as scripts and assets. There is only need to redeploy the solution in the App Catalog, whenever there are package scoped property changes such as addition of new client-side web parts, references to third party libraries or change of the CDN location. +After changing the code and building the solution, the SharePoint Framework toolchain produces a new solution package (.sppkg) and a set of script files. These script files include a unique hash in their filename, which indicates that the contents of these files differ from their previously deployed versions. To use a new version of the solution, you have to deploy the new set of scripts to your CDN and update the solution package in the App Catalog. While theoretically, you could replace the contents of the existing script files and avoid upgrading the solution package, it's unreliable and not recommended. Depending on the configuration of your CDN, it could be that the previously downloaded script files are cached for a long time on the client computers, complicating the rollout of the solution to end-users. The location of the CDN is of importance. The location where the SharePoint Framework assets are hosted must have high availability, so trusted CDN providers such as Azure, Akamai or similar, and SharePoint itself, are recommended. From a security standpoint it is important to know what CDN's are in use by the SharePoint framework solutions deployed. A broken CDN can also break the SharePoint Framework solutions, and in worst case a compromised CDN might lead to that the data in the SharePoint (Online) tenant also being compromised. -When approving third party SharePoint Framework solutions, a typical checklist item is to check the authority and trust of the CDN location and any third parties that might host them. This is because once the applications is installed and used within SharePoint Site collections, these site collections will have a dependency on the CDN location. As of this writing, there is no easy way to to control that end-point. The third party provider of the CDN can update with both wanted and unwanted changes without the users knowledge opening up an attack surface, given that the SharePoint Framework is running under the users context and can do whatever the user are allowed to do. +When approving third party SharePoint Framework solutions, a typical checklist item is to check the authority and trust of the CDN location and any third parties that might host them. This is because once the application is installed and used within SharePoint Site collections, these site collections will have a dependency on the CDN location. As of this writing, there is no easy way to to control that end-point. The third party provider of the CDN can update with both wanted and unwanted changes without the users knowledge opening up an attack surface, given that the SharePoint Framework is running under the users context and can do whatever the user are allowed to do. A recommendation is for IT administrators to keep track of what CDN's are used, and what CDN's are approved by the organization - which should also be communicated to the enterprise developers. ### Office 365 Public CDN -The [Office 365 Public CDN](https://dev.office.com/blogs/general-availability-of-office-365-cdn) is a new capbility in Office 365 and SharePoint Online that allows administrators to automatically host static assets such as JavaScript files, images and CSS styles in a CDN for providing better performance. The Office 365 Public CDN is a geo-distributed caching feature, that keeps static assets as close to the end-users browsers requesting them. +The [Office 365 Public CDN](https://dev.office.com/blogs/general-availability-of-office-365-cdn) is a new capability in Office 365 and SharePoint Online that allows administrators to automatically host static assets such as JavaScript files, images and CSS styles in a CDN for providing better performance. The Office 365 Public CDN is a geo-distributed caching feature, that keeps static assets as close to the end-users browsers requesting them. Administrators can enable the Office 365 Public CDN capability on one or more designated document libraries, which will serve as the origin for the static assets. Administration of the libraries and the CDN are done using the SharePoint Online PowerShell cmdlets. The assets, in the document library, will be replicated to the Office 365 CDN and be accessible through the Office 365 Public CDN URLs generated and associated with the document library. Any updates to the assets will be reflected on the CDN end-points within 15 minutes. Note that any assets within the document libraries will be available for anonymous users, through the CDN end-point. ## SharePoint Framework in the enterprise -SharePoint is and have been one of the most successfull enterprise collaboration platforms and one of the reasons to its success has been the possibility to extend SharePoint and consider it as a platform for applications and integrations. The SharePoint Framework will further expand this success by making SharePoint a more modern platform to build client side customizations on top of in a supported and standardized way. +SharePoint is and have been one of the most successful enterprise collaboration platforms and one of the reasons to its success has been the possibility to extend SharePoint and consider it as a platform for applications and integrations. The SharePoint Framework will further expand this success by making SharePoint a more modern platform to build client side customizations on top of in a supported and standardized way. ### Enterprise developers -The SharePoint Framework allows **Enterprise developers**, typically a developer that creates application for use within an organization, to extend SharePoint (Online) with new functionality in a structured and supported way. The SharePoint Framework offers everything from the development framework, build pipeline, to the actual deployment and allows the developers in a short time reach out to all Site Collections with new solutions and features, all controlled by the App Catalog. In an enterprise scenarion you also have full control of the CDN locations; external or internal in SharePoint and you can very easy deploy fixes and updates to your whole organization. +The SharePoint Framework allows **Enterprise developers**, typically a developer that creates application for use within an organization, to extend SharePoint (Online) with new functionality in a structured and supported way. The SharePoint Framework offers everything from the development framework, build pipeline, to the actual deployment and allows the developers in a short time reach out to all Site Collections with new solutions and features, all controlled by the App Catalog. In an enterprise scenario you also have full control of the CDN locations; external or internal in SharePoint and you can very easy deploy fixes and updates to your whole organization. Within your enterprise administrators and developers jointly should create a *blue print* for how SharePoint Frameworks solutions should be deployed. The blue print should contain details on preferred client side frameworks, CDN locations etc. For more details, see the section below on *Building a plan around SharePoint Framework customizations*. ### Citizen developers Citizen developers have for a long time used SharePoint to build business applications using a lot of different methods and techniques. -SharePoint Framework will for certain scenarios, specifically JavaScript embeddings and Script Editor Web Parts solutions be one good way forward. This to make these solutions more standardized and maintainable over time. For citizen developers there might be a little bit of learning curve to adjust to this new structured way of building solutions, but will in the long run proove to be more stable, secure and maintainable. +SharePoint Framework will for certain scenarios, specifically JavaScript embeddings and Script Editor Web Parts solutions be one good way forward. This to make these solutions more standardized and maintainable over time. For citizen developers there might be a little bit of learning curve to adjust to this new structured way of building solutions, but will in the long run prove to be more stable, secure and maintainable. -Given that the, above mentioned, *Custom Script* control methods are in place, the citizen developers will not be allowed to add arbitrary JavaScript code or Script Editor Web Parts. This can potentially make your SharePoint environment more stable and maintainable, but at the same time you might prohibt some *innovation* in your company, and should make sure that your citizen developers aligns with your enterprise developers on using SharePoint Framework going forward. +Given that the, above mentioned, *Custom Script* control methods are in place, the citizen developers will not be allowed to add arbitrary JavaScript code or Script Editor Web Parts. This can potentially make your SharePoint environment more stable and maintainable, but at the same time you might prohibit some *innovation* in your company, and should make sure that your citizen developers aligns with your enterprise developers on using SharePoint Framework going forward. ### User experience designers and front-end developers -For web developers or user experience/interface designers the SharePoint Framework will be very valuable. The Workbench allows front-end developers to work with a SharePoint Framework solution on any operating system and using their prefferred editing tools without SharePoint, given that they use mock data, and focus on the user experience. The SharePoint Framework is released in parallel with [Office UI Fabric](https://dev.office.com/fabric), which is the official front-end development framework for Office and Office 365, and allows the user experience designers to create a seamless experience across Office, Office 365 and the custom built solutions. +For web developers or user experience/interface designers the SharePoint Framework will be very valuable. The Workbench allows front-end developers to work with a SharePoint Framework solution on any operating system and using their preferred editing tools without SharePoint, given that they use mock data, and focus on the user experience. The SharePoint Framework is released in parallel with [Office UI Fabric](https://dev.office.com/fabric), which is the official front-end development framework for Office and Office 365, and allows the user experience designers to create a seamless experience across Office, Office 365 and the custom built solutions. ### System Integrators (SI) -If you leverage System Integrators (SI) or consultancies to build your SharePoint and Office 365 solutions you should place recommendations, or even requirements, on how they should build SharePoint Framework solutions so that it is aligned with your enterprise plan for the SharePoint Framework. Typically System Integratos have a preferred way of building their solutions, which might not always be aligned with your governance, so this discussion with the System Integrators is important and will in the end make it easier for all parties. -A typical scenario with System Integratos is that they build the solution for your company and after the project is complete it is up to you to maintain, upgrade and update the solution, which only emphasises that you need to align with the SI on how the SharePoint Framework solutions are built and hosted. +If you leverage System Integrators (SI) or consultancies to build your SharePoint and Office 365 solutions you should place recommendations, or even requirements, on how they should build SharePoint Framework solutions so that it is aligned with your enterprise plan for the SharePoint Framework. Typically System Integrators have a preferred way of building their solutions, which might not always be aligned with your governance, so this discussion with the System Integrators is important and will in the end make it easier for all parties. +A typical scenario with System Integrators is that they build the solution for your company and after the project is complete it is up to you to maintain, upgrade and update the solution, which only emphasizes that you need to align with the SI on how the SharePoint Framework solutions are built and hosted. ### Independent Software Vendors (ISV) -Independent Software Vendors (ISV) are organizations building third party solutions for the mass market and they might not always fulfill your plan on SharePoint Framework solutions. Also ISV's typically own their own code and intellectual property which makes it very hard for you to change the way they implement and host their solutions. In the case of using SharePoint Framework solutions from third party providers you need to specifcally look into how they manage updates and how their solutions are hosted. For instance; Do you allow the solution to be updated without your knowledge? Do you allow the static assets to be hosted on the ISV's CDN without your control? What is your trust relationship with this ISV? Remember that any client side code in SharePoint Framework executes under the current users context and there is no possibility for you to put constraints on that, which you can do with SharePoint Add-ins. +Independent Software Vendors (ISV) are organizations building third party solutions for the mass market and they might not always fulfill your plan on SharePoint Framework solutions. Also ISV's typically own their own code and intellectual property which makes it very hard for you to change the way they implement and host their solutions. In the case of using SharePoint Framework solutions from third party providers you need to specifically look into how they manage updates and how their solutions are hosted. For instance; Do you allow the solution to be updated without your knowledge? Do you allow the static assets to be hosted on the ISV's CDN without your control? What is your trust relationship with this ISV? Remember that any client side code in SharePoint Framework executes under the current users context and there is no possibility for you to put constraints on that, which you can do with SharePoint Add-ins. ## Building a plan around SharePoint Framework customizations -When introducing SharePoint Framework as one of the tools to extend your SharePoint (Online) instances, you need to plan for it. The plan should start with introducing the new technology stack used when building SharePoint Framework solutions. Developers may need training on using TypeScript as the primary language for writing the SharePoint Framework code and depending on where your developers are coming from; for instance the client-side world with JavaScript or a server oriented programming style using C#/.NET, PHP and others. Another facet of the SharePoint Framework developers may need to learn is the actual tool chain for SharePoint Framework, including node.js, npm and Gulp, and how you use the different Gulp tasks to build, package and deploy solutions. A very good starting resource for this is the [official SharePoint Framework documentation](https://dev.office.com/sharepoint/docs/spfx/sharepoint-framework-overview) or the [SharePoint Github repositories](https://github.com/SharePoint/). +When introducing SharePoint Framework as one of the tools to extend your SharePoint (Online) instances, you need to plan for it. The plan should start with introducing the new technology stack used when building SharePoint Framework solutions. Developers may need training on using TypeScript as the primary language for writing the SharePoint Framework code and depending on where your developers are coming from; for instance the client-side world with JavaScript or a server oriented programming style using C#/.NET, PHP and others. Another facet of the SharePoint Framework developers may need to learn is the actual tool chain for SharePoint Framework, including node.js, npm and Gulp, and how you use the different Gulp tasks to build, package and deploy solutions. A very good starting resource for this is the [official SharePoint Framework documentation](./sharepoint-framework-overview.md) or the [SharePoint Github repositories](https://github.com/SharePoint/). Developers might want to standardize on one specific client-side framework for the organization or if even standardize on different frameworks. Client-side frameworks include, but are not limited to, React, Knockout, Angular, Handlebars, jQuery etc. There are advantages on standardizing on one framework, since that enables developers to build more reusable code and have better consistency in how they build and maintain their solutions. On the other hand, there are advantages of allowing more than one framework since each client-side framework has its pros and cons and use cases. But, allowing any client-side framework may cause fragmentation in your enterprise solutions, not to mention having multiple different frameworks might add to the page load time, since many frameworks requires loading of more external libraries. @@ -144,7 +144,7 @@ All SharePoint Framework solutions deployed into a tenant must be approved by a ![SharePoint Framework app catalog trust dialog](../images/enterprise-guidance-trust-spfx-dialog.png) -An administrator of the App Catalog can at any time remove the package from the App Catalog by removing the solution package from the *Apps for SharePoint* library. This will prohibit the solution to be used in all Site Collections. The solution can also be disabled by modifying the *Enabled* property of the uploaded package. This will immediatley disable the solution in all Site Collections; existing pages using client side web parts will not render the web part and the app will not be available on the Site Collections or available to add on existing Site Collections. When removing a SharePoint Framework solution it will not remove any data or information created by the actual client side solution either in SharePoint or in any external data source used by the solution. +An administrator of the App Catalog can at any time remove the package from the App Catalog by removing the solution package from the *Apps for SharePoint* library. This will prohibit the solution to be used in all Site Collections. The solution can also be disabled by modifying the *Enabled* property of the uploaded package. This will immediately disable the solution in all Site Collections; existing pages using client side web parts will not render the web part and the app will not be available on the Site Collections or available to add on existing Site Collections. When removing a SharePoint Framework solution it will not remove any data or information created by the actual client side solution either in SharePoint or in any external data source used by the solution. The administrator can also modify other properties on the package in the App Catalog in order to enhance the *visibility* of the solution in the Site Collections; for instance, the icon, category, description and the featured status can be changed. @@ -156,7 +156,11 @@ To enable a SharePoint Framework solution on a Site Collection, the Site Collect ### SharePoint Framework Deployment Scopes -For SharePoint Framework solutions, there is only one deployment scope: tenant wide. Once added, and enabled, in the App Catalog, the SharePoint Framework solution will be available to all Site Collections. +When building SharePoint Framework solutions, developers can choose whether their solution supports tenant-wide deployment or if it has to be deployed on each site separately. The latter is required, when the solution needs to provision additional resources, such as lists, after being deployed to a site. + +While the developers building the solution decide if the solution supports tenant-wide deployment or not, it's the administrators who make the final decision how the solution is deployed. Even if a solution could be deployed to all sites in the tenant, administrators can choose to deploy it only to the specific sites. If the solution doesn't support tenant-wide deployment, then administrators can deploy it only to specific sites. + +> **Important:** tenant-wide deployment is available only in SharePoint Online. In SharePoint hosted on-premises, SharePoint Framework solutions can de deployed only to specific sites. The SharePoint Framework does not have a store, which SharePoint Add-ins have. For this reason, any deployments always must be initiated by the tenant admin by adding and approving a solution package to the App Catalog. @@ -168,12 +172,12 @@ What you cannot backup is the actual solution artifacts such as script bundles a ## SharePoint Framework Roadmap -The SharePoint Framework reached General Availability (GA) in February 2017. General Availability means that IT and developers can supportably use SharePoint Framework in production. Beyond General Availability, we would expect that the set of scenarios where we would see SharePoint Framework-based components are built and used will expand beyond web parts scenarios, and into areas like list and site customizations. For more information about the SharePoint Framework see the dedicated [SharePoint Framework Roadmap article](https://dev.office.com/sharepoint/docs/spfx/roadmap). Also, the SharePoint team is looking to bring the SharePoint Framework to SharePoint 2016 on-premises during 2017, as part of a future Feature Pack. +The SharePoint Framework reached General Availability (GA) in February 2017. General Availability means that IT and developers can use SharePoint Framework in production in a supported manner. Beyond General Availability, we would expect that the set of scenarios where we would see SharePoint Framework-based components are built and used will expand beyond web parts scenarios, and into areas like list and site customizations. For more information about the SharePoint Framework see the dedicated [SharePoint Framework Roadmap article](./roadmap.md). Major changes or introduction of new major features will be announced through the Office 365 Message Center, found in your tenant admin - something that an Office 365 administrator already should have on their daily routine to check. Another important resource is the [Office Developer blog](http://dev.office.com/blogs) where you will find even more details and updates. ## Summary -The SharePoint Framework is a great new addition to and evolution of the SharePoint customization toolbox that allows developerto in a supported and controllable way extend SharePoint (Online). SharePoint Framework, based on open source and modern technologies, lets developers extend your SharePoint enterprise development story to not only the SharePoint team, but can include a more diverse set of developers. As an administrator, providing proper governance and support for SharePoint Framework within your tenancy can empower your developers to build more engaging solutions more quickly, resulting in better efficiency all around. +The SharePoint Framework is a great new addition to and evolution of the SharePoint customization toolbox that allows developers to extend SharePoint in a supported and controllable way. SharePoint Framework, based on open source and modern technologies, lets developers extend your SharePoint enterprise development story to not only the SharePoint team, but can include a more diverse set of developers. As an administrator, providing proper governance and support for SharePoint Framework within your tenancy can empower your developers to build more engaging solutions more quickly, resulting in better efficiency all around. Since the SharePoint Framework is created for first and third party developers, and in growing use by Microsoft for future feature enhancements of SharePoint, it is also a safe bet for your organization. We can expect to see incremental updates and additions to the SharePoint Framework over time to close the feature gap between the classic SharePoint and the modern SharePoint experience. From caa35d71260e91b1ba2d85955fb6f89233677a26 Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Fri, 20 Oct 2017 15:37:05 +0200 Subject: [PATCH 15/26] Updated the development environment setup guide (#958) --- .../set-up-your-development-environment.md | 35 +++++++++++-------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/spfx/set-up-your-development-environment.md b/docs/spfx/set-up-your-development-environment.md index bd866ef84..249ff5cd0 100644 --- a/docs/spfx/set-up-your-development-environment.md +++ b/docs/spfx/set-up-your-development-environment.md @@ -11,16 +11,16 @@ You can use Visual Studio, or your own custom development environment to build S >**Note:** Before following the steps in this article, be sure to [Set up your Office 365 Tenant](./set-up-your-developer-tenant.md). -You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=_fxYexlUhe0&t=5s&list=PLR9nK3mnD-OXvSWvS2zglCzz4iplhVrKq&index=1). +You can also follow these steps by watching the video on the [SharePoint PnP YouTube Channel](https://www.youtube.com/watch?v=_fxYexlUhe0&t=5s&list=PLR9nK3mnD-OXvSWvS2zglCzz4iplhVrKq&index=1). Screenshot of the YouTube video player for this tutorial - ## Install developer tools ### NodeJS + Install [NodeJS](https://nodejs.org/en/) Long Term Support (LTS) version. * If you have NodeJS already installed please check you have the latest version using `node -v`. It should return the current [LTS version](https://nodejs.org/en/download/). @@ -29,27 +29,28 @@ Install [NodeJS](https://nodejs.org/en/) Long Term Support (LTS) version. > Notice that SPFx build pipeline does **NOT** currently support npm v5.x, so you'll need to use either v3 or v4. At the time of the writing, NodeJS LTS version (v6.11.0) installs npm v3.10.10. We'll update this section when there are changes in the supportability statement. You can downgrade to older npm version with following command `npm install -g npm@3`. ### Code Editors + Install a code editor. You can use any code editor or IDE that supports client-side development to build your web part, such as: * [Visual Studio Code](https://code.visualstudio.com/) * [Atom](https://atom.io) -* [Webstorm](https://www.jetbrains.com/webstorm) +* [Webstorm](https://www.jetbrains.com/webstorm) -The steps and examples in this documentation use [Visual Studio Code](https://code.visualstudio.com/), but you can use any editor of your choice. +The steps and examples in this documentation use [Visual Studio Code](https://code.visualstudio.com/), but you can use any editor of your choice. ### If you are using Ubuntu You need to install compiler tools using the following command: - -``` + +```sh sudo apt-get install build-essential ``` ### If you are using fedora You need to install compiler tools using the following command: - -``` + +```sh sudo yum install make automake gcc gcc-c++ kernel-devel ``` @@ -58,8 +59,8 @@ sudo yum install make automake gcc gcc-c++ kernel-devel [Yeoman](http://yeoman.io/) helps you kick-start new projects, and prescribes best practices and tools to help you stay productive. SharePoint client-side development tools include a Yeoman generator for creating new web parts. The generator provides common build tools, common boilerplate code, and a common playground web site to host web parts for testing. Enter the following command to install Yeoman and gulp: - -``` + +```sh npm install -g yo gulp ``` @@ -67,13 +68,17 @@ npm install -g yo gulp The Yeoman SharePoint web part generator helps you quickly create a SharePoint client-side solution project with the right toolchain and project structure. -Enter the following command to install the Yeoman SharePoint generator: - -``` -npm install -g @microsoft/generator-sharepoint +To install the SharePoint Framework Yeoman generator globally, enter the following command: + +```sh +npm install -g @microsoft/generator-sharepoint ``` ->**Note:** Yeoman generator for SharePoint is targeted to get deployed globally with the initial General Availability (GA) version. There are some known issues if it's installed locally to the project, which are planned to be addressed post GA. +If you need to switch between the different projects created using different versions of the SharePoint Framework Yeoman generator, you can install the generator locally as a development dependency in the project folder by executing the following command: + +```sh +npm install @microsoft/generator-sharepoint --save-dev +``` ## Optional tools From 0a39da6014cadbf791c7879b4e612fb819849d73 Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Fri, 20 Oct 2017 15:37:40 +0200 Subject: [PATCH 16/26] Added npm shrinkwrap to all tutorials (#960) --- .../get-started/build-a-hello-world-extension.md | 10 ++++++++-- .../building-simple-cmdset-with-dialog-api.md | 10 ++++++++-- .../get-started/building-simple-field-customizer.md | 10 ++++++++-- .../guidance/using-custom-dialogs-with-spfx.md | 10 ++++++++-- .../get-started/add-jqueryui-accordion-to-web-part.md | 8 +++++++- .../get-started/build-a-hello-world-web-part.md | 4 ++-- .../get-started/hosting-webpart-from-office-365-cdn.md | 10 ++++++++-- .../get-started/provision-sp-assets-from-package.md | 8 +++++++- .../get-started/use-fabric-react-components.md | 10 ++++++++-- .../build-client-side-web-parts-with-angular-1-x.md | 8 +++++++- .../guidance/build-custom-property-pane-controls.md | 8 +++++++- .../guidance/connect-to-sharepoint-using-jsom.md | 8 +++++++- docs/spfx/web-parts/guidance/localize-web-parts.md | 8 +++++++- ...angular-1-x-applications-to-sharepoint-framework.md | 8 +++++++- .../migrate-jquery-datatables-script-to-spfx.md | 8 +++++++- .../migrate-jquery-fullcalendar-script-to-spfx.md | 8 +++++++- .../guidance/reference-third-party-css-styles.md | 8 +++++++- ...lify-adding-web-parts-with-preconfigured-entries.md | 8 +++++++- ...ial-share-data-between-web-parts-global-variable.md | 8 +++++++- .../use-cascading-dropdowns-in-web-part-properties.md | 8 +++++++- .../guidance/use-sp-pnp-js-with-spfx-web-parts.md | 8 +++++++- .../guidance/validate-web-part-property-values.md | 8 +++++++- 22 files changed, 155 insertions(+), 29 deletions(-) diff --git a/docs/spfx/extensions/get-started/build-a-hello-world-extension.md b/docs/spfx/extensions/get-started/build-a-hello-world-extension.md index e25228237..62f933401 100644 --- a/docs/spfx/extensions/get-started/build-a-hello-world-extension.md +++ b/docs/spfx/extensions/get-started/build-a-hello-world-extension.md @@ -54,7 +54,13 @@ This article describes how to create your first Hello World SharePoint Framework For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). -6. When the solution scaffolding is complete, type the following into the console to start Visual Studio Code. +6. Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + + ```sh + npm shrinkwrap + ``` + +7. Next, type the following into the console to start Visual Studio Code. ``` code . @@ -66,7 +72,7 @@ This article describes how to create your first Hello World SharePoint Framework ![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-app-vscode-solution-structure.png) -7. Open **HelloWorldApplicationCustomizer.manifest.json** in the src\extensions\helloWorld folder. +8. Open **HelloWorldApplicationCustomizer.manifest.json** in the src\extensions\helloWorld folder. This file defines your extension type and a unique identifier for your extension. You’ll need this ID later when you debug and deploy your extension to SharePoint. diff --git a/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md b/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md index 559188470..b06c92721 100644 --- a/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md +++ b/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md @@ -52,7 +52,13 @@ This article describes how to create your first ListView Command Set Extension. For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). -6. When the solution scaffolding is complete, type the following into the console to start Visual Studio Code. +6. Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + + ```sh + npm shrinkwrap + ``` + +7. Next, type the following into the console to start Visual Studio Code. ``` code . @@ -64,7 +70,7 @@ This article describes how to create your first ListView Command Set Extension. ![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-com-vscode-solution-structure.png) -7. Open **HelloWorldCommandSet.manifest.json** in the **src\extensions\helloWorld** folder. +8. Open **HelloWorldCommandSet.manifest.json** in the **src\extensions\helloWorld** folder. This file defines your extension type and a unique identifier `id` for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint. diff --git a/docs/spfx/extensions/get-started/building-simple-field-customizer.md b/docs/spfx/extensions/get-started/building-simple-field-customizer.md index cdc36f0b4..f74a903c7 100644 --- a/docs/spfx/extensions/get-started/building-simple-field-customizer.md +++ b/docs/spfx/extensions/get-started/building-simple-field-customizer.md @@ -52,8 +52,14 @@ This article describes how to create your first Field Customizer Extension. You ![SharePoint client-side solution scaffolded successfully](../../../images/ext-field-yeoman-complete.png) For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). + +6. Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + + ```sh + npm shrinkwrap + ``` -6. When the solution scaffolding is complete, type the following into the console to start Visual Studio Code. +7. Next, type the following into the console to start Visual Studio Code. ``` code . @@ -65,7 +71,7 @@ This article describes how to create your first Field Customizer Extension. You ![SharePoint Framework solution opened after initial scaffolding](../../../images/ext-field-vscode-solution-structure.png) -7. Open **HelloWorldFieldCustomizer.manifest.json** in the **src\extensions\helloWorld** folder. +8. Open **HelloWorldFieldCustomizer.manifest.json** in the **src\extensions\helloWorld** folder. This file defines your extension type and a unique identifier `id` for your extension. You’ll need this unique identifier later when debugging and deploying your extension to SharePoint. diff --git a/docs/spfx/extensions/guidance/using-custom-dialogs-with-spfx.md b/docs/spfx/extensions/guidance/using-custom-dialogs-with-spfx.md index 443c7effc..c48e051a9 100644 --- a/docs/spfx/extensions/guidance/using-custom-dialogs-with-spfx.md +++ b/docs/spfx/extensions/guidance/using-custom-dialogs-with-spfx.md @@ -52,7 +52,7 @@ The next set of prompts will ask for specific information about your extension: ![Yeoman SharePoint generator prompts to create an extension solution](../../../images/ext-com-dialog-yeoman-prompts.png) -At this point, Yeoman will install the required dependencies and scaffold the solution files along with the *DialogDemo* extension. This might take a few minutes. +At this point, Yeoman will install the required dependencies and scaffold the solution files along with the *DialogDemo* extension. This might take a few minutes. When the scaffold is complete, you should see the following message indicating a successful scaffold: @@ -60,7 +60,13 @@ When the scaffold is complete, you should see the following message indicating a >**Note:** For information about troubleshooting any errors, see [Known issues](../../known-issues-and-common-questions.md). -When the scaffolding is complete, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots, but you can use any editor you prefer. To open the folder in Visual Studio Code, use the following command in the console: +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots, but you can use any editor you prefer. To open the folder in Visual Studio Code, use the following command in the console: ```sh code . diff --git a/docs/spfx/web-parts/get-started/add-jqueryui-accordion-to-web-part.md b/docs/spfx/web-parts/get-started/add-jqueryui-accordion-to-web-part.md index 0b80523ef..2a01563fa 100644 --- a/docs/spfx/web-parts/get-started/add-jqueryui-accordion-to-web-part.md +++ b/docs/spfx/web-parts/get-started/add-jqueryui-accordion-to-web-part.md @@ -67,7 +67,13 @@ The next set of prompts will ask for specific information about your web part: At this point, Yeoman will install the required dependencies and scaffold the solution files. This might take a few minutes. Yeoman will scaffold the project to include your **jQueryWebPart** web part as well. -In the console, type the following to open the web part project in Visual Studio Code: +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, type the following to open the web part project in Visual Studio Code: ``` code . diff --git a/docs/spfx/web-parts/get-started/build-a-hello-world-web-part.md b/docs/spfx/web-parts/get-started/build-a-hello-world-web-part.md index f949269ba..48e81b4c7 100644 --- a/docs/spfx/web-parts/get-started/build-a-hello-world-web-part.md +++ b/docs/spfx/web-parts/get-started/build-a-hello-world-web-part.md @@ -58,7 +58,7 @@ The next set of prompts will ask for specific information about your web part: ![Yeoman SharePoint generator prompts to create a web part client-side solution](../../../images/yeoman-sp-prompts.png) -At this point, Yeoman will install the required dependencies and scaffold the solution files along with the **HelloWorld** web part. This might take a few minutes. +At this point, Yeoman will install the required dependencies and scaffold 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: @@ -73,7 +73,7 @@ Because the SharePoint client-side solution is HTML/TypeScript based, you can us * [Atom](https://atom.io) * [Webstorm](https://www.jetbrains.com/webstorm) -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 which 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.. +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 which 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. However, since a default certificate is not configured for the local dev environment, your browser will report a certificate error. The SPFx toolchain comes with a developer certificate that you can install for building web parts. diff --git a/docs/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn.md b/docs/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn.md index dbf9729d2..af99d526a 100644 --- a/docs/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn.md +++ b/docs/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn.md @@ -82,8 +82,14 @@ When prompted: ![Yeoman generator questions around the newly created web part](../../../images/cdn-create-webpart-yo.png) At this point, Yeoman will scaffold the solution files and install the required dependencies. This might take a few minutes. Yeoman will scaffold the project to include your custom web part as well. - -When the scaffold is complete, in the console, type the following to open the web part project in Visual Studio Code: + +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, type the following to open the web part project in Visual Studio Code: ``` code . diff --git a/docs/spfx/web-parts/get-started/provision-sp-assets-from-package.md b/docs/spfx/web-parts/get-started/provision-sp-assets-from-package.md index e4c782763..184182326 100644 --- a/docs/spfx/web-parts/get-started/provision-sp-assets-from-package.md +++ b/docs/spfx/web-parts/get-started/provision-sp-assets-from-package.md @@ -54,7 +54,13 @@ The next set of prompts will ask for specific information about your web part: At this point, Yeoman will install the required dependencies and scaffold the solution files. This might take a few minutes. Yeoman will scaffold the project to include your **AssetDeployment** web part as well. -In the console, type the following to open the web part project in Visual Studio Code: +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, type the following to open the web part project in Visual Studio Code: ``` code . diff --git a/docs/spfx/web-parts/get-started/use-fabric-react-components.md b/docs/spfx/web-parts/get-started/use-fabric-react-components.md index 649fc0b1e..f4f7563a5 100644 --- a/docs/spfx/web-parts/get-started/use-fabric-react-components.md +++ b/docs/spfx/web-parts/get-started/use-fabric-react-components.md @@ -59,8 +59,14 @@ The next set of prompts will ask for specific information about your web part: * Select **React** as the framework and choose **Enter**. At this point, Yeoman will install the required dependencies and scaffold the solution files. This might take a few minutes. Yeoman will scaffold the project to include your DocumentCardExample web part as well. - -When the scaffold is complete, in the console, type the following to open the web part project in Visual Studio Code: + +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, type the following to open the web part project in Visual Studio Code: ``` code . diff --git a/docs/spfx/web-parts/guidance/build-client-side-web-parts-with-angular-1-x.md b/docs/spfx/web-parts/guidance/build-client-side-web-parts-with-angular-1-x.md index 395a7786b..5e919dc46 100644 --- a/docs/spfx/web-parts/guidance/build-client-side-web-parts-with-angular-1-x.md +++ b/docs/spfx/web-parts/guidance/build-client-side-web-parts-with-angular-1-x.md @@ -44,7 +44,13 @@ When prompted, define values as follows: ![SharePoint Framework Yeoman generator with the default choices](../../../images/ng-intro-yeoman-generator.png) -Once the scaffolding completes, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. ![SharePoint Framework project open in Visual Studio Code](../../../images/ng-intro-project-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md index 3b8852bea..57ca6f142 100644 --- a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md +++ b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md @@ -47,7 +47,13 @@ When prompted, enter the following values: ![SharePoint Framework Yeoman generator with the default choices](../../../images/custom-property-pane-control-yeoman.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![SharePoint Framework project open in Visual Studio Code](../../../images/custom-property-pane-control-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/connect-to-sharepoint-using-jsom.md b/docs/spfx/web-parts/guidance/connect-to-sharepoint-using-jsom.md index a0a97ea31..51f4ee4d6 100644 --- a/docs/spfx/web-parts/guidance/connect-to-sharepoint-using-jsom.md +++ b/docs/spfx/web-parts/guidance/connect-to-sharepoint-using-jsom.md @@ -42,7 +42,13 @@ When prompted, enter the following values: ![The SharePoint Framework Yeoman generator with the default choices](../../../images/tutorial-spjsom-yo-sharepoint.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![The SharePoint Framework project open in Visual Studio Code](../../../images/tutorial-spjsom-vscode.png) diff --git a/docs/spfx/web-parts/guidance/localize-web-parts.md b/docs/spfx/web-parts/guidance/localize-web-parts.md index d00bdfbf1..0a757a4a0 100644 --- a/docs/spfx/web-parts/guidance/localize-web-parts.md +++ b/docs/spfx/web-parts/guidance/localize-web-parts.md @@ -46,7 +46,13 @@ When prompted, enter the following values: ![The SharePoint Framework Yeoman generator with the default choices](../../../images/localization-yo-sharepoint.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![The SharePoint Framework project open in Visual Studio Code](../../../images/localization-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/migrate-angular-1-x-applications-to-sharepoint-framework.md b/docs/spfx/web-parts/guidance/migrate-angular-1-x-applications-to-sharepoint-framework.md index 787d06c91..df68e1f50 100644 --- a/docs/spfx/web-parts/guidance/migrate-angular-1-x-applications-to-sharepoint-framework.md +++ b/docs/spfx/web-parts/guidance/migrate-angular-1-x-applications-to-sharepoint-framework.md @@ -51,7 +51,13 @@ When prompted, define values as follows: ![SharePoint Framework Yeoman generator with the default choices](../../../images/ng-migration-yeoman-generator.png) -Once the scaffolding completes, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. ![SharePoint Framework project open in Visual Studio Code](../../../images/ng-migration-project-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/migrate-jquery-datatables-script-to-spfx.md b/docs/spfx/web-parts/guidance/migrate-jquery-datatables-script-to-spfx.md index 46c296178..a368c6d2f 100644 --- a/docs/spfx/web-parts/guidance/migrate-jquery-datatables-script-to-spfx.md +++ b/docs/spfx/web-parts/guidance/migrate-jquery-datatables-script-to-spfx.md @@ -159,7 +159,13 @@ When prompted, define values as follows: ![SharePoint Framework Yeoman generator with the default choices](../../../images/datatables-yeoman.png) -Once the scaffolding completes, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. ![SharePoint Framework project open in Visual Studio Code](../../../images/datatables-vscode.png) diff --git a/docs/spfx/web-parts/guidance/migrate-jquery-fullcalendar-script-to-spfx.md b/docs/spfx/web-parts/guidance/migrate-jquery-fullcalendar-script-to-spfx.md index 8412a103c..9c437cc8d 100644 --- a/docs/spfx/web-parts/guidance/migrate-jquery-fullcalendar-script-to-spfx.md +++ b/docs/spfx/web-parts/guidance/migrate-jquery-fullcalendar-script-to-spfx.md @@ -196,7 +196,13 @@ When prompted, define values as follows: ![SharePoint Framework Yeoman generator with the default choices](../../../images/fullcalendar-yeoman.png) -Once the scaffolding completes, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. In this tutorial, you will use Visual Studio Code. ![SharePoint Framework project open in Visual Studio Code](../../../images/fullcalendar-vscode.png) diff --git a/docs/spfx/web-parts/guidance/reference-third-party-css-styles.md b/docs/spfx/web-parts/guidance/reference-third-party-css-styles.md index ea09a4230..582de9592 100644 --- a/docs/spfx/web-parts/guidance/reference-third-party-css-styles.md +++ b/docs/spfx/web-parts/guidance/reference-third-party-css-styles.md @@ -45,7 +45,13 @@ When prompted, enter the following values: ![The SharePoint Framework Yeoman generator with the default choices](../../../images/thirdpartycss-yeoman.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![The SharePoint Framework project open in Visual Studio Code](../../../images/thirdpartycss-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/simplify-adding-web-parts-with-preconfigured-entries.md b/docs/spfx/web-parts/guidance/simplify-adding-web-parts-with-preconfigured-entries.md index 8eebc99ce..cab83ba52 100644 --- a/docs/spfx/web-parts/guidance/simplify-adding-web-parts-with-preconfigured-entries.md +++ b/docs/spfx/web-parts/guidance/simplify-adding-web-parts-with-preconfigured-entries.md @@ -132,7 +132,13 @@ When prompted, enter the following values: ![SharePoint Framework Yeoman generator with the default choices](../../../images/preconfiguredentries-yeoman.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![SharePoint Framework project open in Visual Studio Code](../../../images/preconfiguredentries-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/tutorial-share-data-between-web-parts-global-variable.md b/docs/spfx/web-parts/guidance/tutorial-share-data-between-web-parts-global-variable.md index 50bf41929..07e133a94 100644 --- a/docs/spfx/web-parts/guidance/tutorial-share-data-between-web-parts-global-variable.md +++ b/docs/spfx/web-parts/guidance/tutorial-share-data-between-web-parts-global-variable.md @@ -46,7 +46,13 @@ When prompted, use the following values: ![The SharePoint Framework Yeoman generator with the default choices](../../../images/tutorial-sharingdata-yo-sharepoint-recent-documents.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots, but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots, but you can use any editor you prefer. ![The SharePoint Framework project open in Visual Studio Code](../../../images/tutorial-sharingdata-vscode.png) diff --git a/docs/spfx/web-parts/guidance/use-cascading-dropdowns-in-web-part-properties.md b/docs/spfx/web-parts/guidance/use-cascading-dropdowns-in-web-part-properties.md index 983f9a810..73c73498a 100644 --- a/docs/spfx/web-parts/guidance/use-cascading-dropdowns-in-web-part-properties.md +++ b/docs/spfx/web-parts/guidance/use-cascading-dropdowns-in-web-part-properties.md @@ -45,7 +45,13 @@ When prompted, enter the following values: ![SharePoint Framework Yeoman generator with the default choices](../../../images/react-cascading-dropdowns-yo-sharepoint.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![SharePoint Framework project open in Visual Studio Code](../../../images/react-cascading-dropdowns-visual-studio-code.png) diff --git a/docs/spfx/web-parts/guidance/use-sp-pnp-js-with-spfx-web-parts.md b/docs/spfx/web-parts/guidance/use-sp-pnp-js-with-spfx-web-parts.md index 24261fb94..bb0dad382 100644 --- a/docs/spfx/web-parts/guidance/use-sp-pnp-js-with-spfx-web-parts.md +++ b/docs/spfx/web-parts/guidance/use-sp-pnp-js-with-spfx-web-parts.md @@ -48,7 +48,13 @@ Enter the following values when prompted during the setup of the new project: ![Completed Project Scaffolding](../../../images/sp-pnp-js-guide-completed-setup.png) -Once the scaffolding completes, open the project in the code editor of your choosing. The screenshots shown here demonstrate [Visual Studio Code](https://code.visualstudio.com/). To open the directory within Visual Studio Code, enter the following in the console: +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open the project in the code editor of your choosing. The screenshots shown here demonstrate [Visual Studio Code](https://code.visualstudio.com/). To open the directory within Visual Studio Code, enter the following in the console: ```sh code . diff --git a/docs/spfx/web-parts/guidance/validate-web-part-property-values.md b/docs/spfx/web-parts/guidance/validate-web-part-property-values.md index 3857c41cd..c4f8d35d0 100644 --- a/docs/spfx/web-parts/guidance/validate-web-part-property-values.md +++ b/docs/spfx/web-parts/guidance/validate-web-part-property-values.md @@ -41,7 +41,13 @@ When prompted, enter the following values: ![SharePoint Framework Yeoman generator with the default choices](../../../images/property-validation-yeoman-generator.png) -Once the scaffolding completes, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. +Once the scaffolding completes, lock down the version of the project dependencies by running the following command: + +```sh +npm shrinkwrap +``` + +Next, open your project folder in your code editor. This article uses Visual Studio Code in the steps and screenshots but you can use any editor you prefer. ![SharePoint Framework project open in Visual Studio Code](../../../images/property-validation-visual-studio-code.png) From c2c712ff856febce7cf84bd9de4ed43b76599e4c Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 06:39:35 -0700 Subject: [PATCH 17/26] moved Query Para details to its own section (#966) --- .../building-simple-field-customizer.md | 54 ++++++++++--------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/spfx/extensions/get-started/building-simple-field-customizer.md b/docs/spfx/extensions/get-started/building-simple-field-customizer.md index f74a903c7..712b23458 100644 --- a/docs/spfx/extensions/get-started/building-simple-field-customizer.md +++ b/docs/spfx/extensions/get-started/building-simple-field-customizer.md @@ -65,7 +65,7 @@ This article describes how to create your first Field Customizer Extension. You code . ``` - **Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. + > **Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. Note how the default solution structure looks like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types. @@ -143,7 +143,7 @@ You cannot currently use the local workbench to test SharePoint Framework Extens ![Creating a new list](../../../images/ext-field-create-new-list.png) -5. Create a new list named **Orders** and then select **Create**. +5. Create a new list named **Orders**, and then select **Create**. ![Creating a new list with name of Orders](../../../images/ext-field-create-new-list-order.png) @@ -161,34 +161,38 @@ You cannot currently use the local workbench to test SharePoint Framework Extens Because our Field Customizer is still hosted in localhost and is running, we can use specific debug query parameters to execute the code in the newly created list. -9. Append the following query string parameters to the URL. Notice that you will need to update the ID to match your own extension identifier available from the **HelloWorldFieldCustomizer.manifest.json** file. +9. Append the following query string parameters to the URL. Notice that you will need to update the ID to match your own extension identifier available from the **HelloWorldFieldCustomizer.manifest.json** file. For more information, see [More details about the URL query parameters](#more-details-about-the-url-query-parameters). ``` ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}} ``` -More detail about the URL query parameters: -- **loadSPFX=true** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Because no components are registered yet, we must explicitly load the framework. -- **debugManifestsFile** specifies that you want to load SPFx components that are locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). -- **fieldCustomizers** indicates which fields in your list should have their rendering controlled by the Field Customizer. The ID parameter specifies the GUID of the extension that should be used to control the rendering of the field. The properties parameter is an optional text string containing a JSON object that will be deserialized into `this.properties` for your extension. - - **Key**: Use the internal name of the field as the key. - - **Id**: The GUID of the Field Customizer extension associated with this field. - - **Properties**: The property values defined in the extension. In this example, `sampleText` is a property defined by the extension. - -The full URL should look similar to the following, depending on your tenant URL and the location of the newly created list: + The full URL should look similar to the following, depending on your tenant URL and the location of the newly created list: -``` -contoso.sharepoint.com/Lists/Orders/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}} -``` + ``` + contoso.sharepoint.com/Lists/Orders/AllItems.aspx?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Percent":{"id":"45a1d299-990d-4917-ba62-7cb67158be16","properties":{"sampleText":"Hello!"}}} + ``` -Accept the loading of Debug Manifests by selecting **Load debug scripts** when prompted. +10. Accept the loading of debug manifests by selecting **Load debug scripts** when prompted. + + ![Accept loading debug scripts](../../../images/ext-field-accept-debug-scripts.png) + + Notice how the Percent values are now presented with an additional prefix string as `Hello!: `, which is provided as a property for the Field Customizer. -![Accept loading debug scripts](../../../images/ext-field-accept-debug-scripts.png) + ![List view with field customizer rendered for percent field](../../../images/ext-field-default-customizer-output.png) -Notice how the Percent values are now presented with an additional prefix string as 'Hello!: ', which is provided as a property for the Field Customizer. -![List view with field customizer rendered for percent field](../../../images/ext-field-default-customizer-output.png) +### More details about the URL query parameters + +- **loadSPFX=true** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Because no components are registered yet, we must explicitly load the framework. +- **debugManifestsFile** specifies that you want to load SPFx components that are locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). +- **fieldCustomizers** indicates which fields in your list should have their rendering controlled by the Field Customizer. The ID parameter specifies the GUID of the extension that should be used to control the rendering of the field. The properties parameter is an optional text string containing a JSON object that will be deserialized into `this.properties` for your extension. + - **Key**: Use the internal name of the field as the key. + - **Id**: The GUID of the Field Customizer extension associated with this field. + - **Properties**: The property values defined in the extension. In this example, `sampleText` is a property defined by the extension. + +
## Enhance the Field Customizer rendering Now that we have successfully tested the out-of-the-box starting point of the Field Customizer, let's modify the logic slightly to have a more polished rendering of the field value. @@ -246,7 +250,7 @@ Now that we have tested our solution properly in debug mode, we can package this 1. Install the solution package to the site where it should be installed, so that the extension manifest is white listed for execution. 2. Associate the Field Customizer to an existing field in the site. You can do this programmatically (CSOM/REST) or by using the feature framework inside of the SharePoint Framework solution package. You'll need to associate the following properties in the `SPField` object at the site or list level. - - **ClientSiteComponentId** is the identifier (GUID) of the Field Customizer, which has been installed in the App Catalog. + - **ClientSiteComponentId** is the identifier (GUID) of the Field Customizer, which has been installed in the App Catalog. - **ClientSideComponentProperties** is an optional parameter, which can be used to provide properties for the Field Customizer instance. Note that you can control the requirement to add a solution containing your extension to the site by using the `skipFeatureDeployment` setting in **package-solution.json**. Even though you would not require the solution to be installed on the site, you'd need to associate **ClientSideComponentId** to specific objects for the extension to be visible. @@ -258,7 +262,9 @@ Now that we have tested our solution properly in debug mode, we can package this 4. Extend the **sharepoint** folder and **assets** subfolder in the root of the solution to see the existing **elements.xml** file. ![assets folder in solution structure](../../../images/ext-field-assets-folder.png) - + +
+ ### Review the elements.xml file Open the **elements.xml** file inside the **sharepoint\assets** folder. @@ -282,6 +288,8 @@ Note the following XML structure in **elements.xml**. The **ClientSideComponent ``` +
+ ### Ensure that definitions are taken into account within the build pipeline Open **package-solution.json** from the **config** folder. The **package-solution.json** file defines the package metadata as shown in the following code: @@ -385,6 +393,4 @@ Now you are ready to deploy the solution to a SharePoint site and get the field In this case, we continued to host the JavaScript from the localhost, but you could just as well relocate the assets to any CDN and update the URL to enable the loading of the JavaScript assets outside of the localhost as well. -The process for publishing your app is identical among the different extension types. You can use the following publishing steps to update the assets to be hosted from a CDN. - -* [Host extension from Office 365 CDN](./hosting-extension-from-office365-cdn.md). +The process for publishing your app is identical among the different extension types. You can use the following publishing steps to update the assets to be hosted from a CDN: [Host extension from Office 365 CDN](./hosting-extension-from-office365-cdn.md). From 6f845788a2f6ac76f43aa398f698ad1f8e15b106 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 06:40:00 -0700 Subject: [PATCH 18/26] Moved Query Para details to own section (#967) --- .../building-simple-cmdset-with-dialog-api.md | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md b/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md index b06c92721..ae8598efd 100644 --- a/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md +++ b/docs/spfx/extensions/get-started/building-simple-cmdset-with-dialog-api.md @@ -64,7 +64,7 @@ This article describes how to create your first ListView Command Set Extension. code . ``` - **Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. + > **Note:** Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension. Note how the default solution structure looks like the solution structure of client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types. @@ -153,47 +153,49 @@ You cannot currently use the local workbench to test SharePoint Framework Extens Because our ListView Command Set is hosted from localhost and is running, we can use specific debug query parameters to execute the code in the list view. -3. Append the following query string parameters to the URL. Notice that you will need to update the GUID to match the ID of your ListView Command Set Extension available in the **HelloWorldCommandSet.manifest.json** file: +3. Append the following query string parameters to the URL. Notice that you will need to update the GUID to match the ID of your ListView Command Set Extension available in the **HelloWorldCommandSet.manifest.json** file. For more information, see [More details about the URL query parameters](#more-details-about-the-url-query-parameters). ``` ?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}} ``` -More detail about the URL query parameters: + The full URL should look similar to the following, depending on your tenant URL and the location of the list. -- **loadSPFX=true** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Because no components are registered yet, we must explicitly load the framework. -- **debugManifestsFile** specifies that we want to load SPFx components that are being locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). -- **customActions** simulates a custom action. You can set many properties on this `CustomAction` object that affect the look, feel, and location of your button; we’ll cover them all later. - - **Key**: GUID of the extension. - - **Location**: Where the commands are displayed. The possible values are: - - **ClientSideExtension.ListViewCommandSet.ContextMenu:** The context menu of the item(s) - - **ClientSideExtension.ListViewCommandSet.CommandBar:** The top command set menu in a list or library - - **ClientSideExtension.ListViewCommandSet:** Both the context menu and the command bar (Corresponds to SPUserCustomAction.Location="CommandUI.Ribbon") - - **Properties**: An optional JSON object containing properties that are available via the `this.properties` member. - -The full URL should look similar to the following, depending on your tenant URL and the location of the list. - -``` -contoso.sharepoint.com/Lists/Orders/AllItems.aspx?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}} -``` + ``` + contoso.sharepoint.com/Lists/Orders/AllItems.aspx?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{"location":"ClientSideExtension.ListViewCommandSet.CommandBar","properties":{"sampleTextOne":"One item is selected in the list.","sampleTextTwo":"This command is always visible."}}} + ``` 4. Accept the loading of debug manifests by selecting **Load debug scripts** when prompted. ![Accept loading debugripts](../../../images/ext-com-accept-debug-scripts.png) - Notice the new **Command Two** button available in the toolbar. If you select that button, you'll see the text provided as property for the `sampleTextTwo` property. +5. Notice the new **Command Two** button available in the toolbar. Select that button to see the text provided as property for the `sampleTextTwo` property. ![Command Two button visible in the document library toolbar](../../../images/ext-com-default-customizer-output.png) - The **Command One** button is not visible based on the code, until one row is selected in the document library. Upload or create a document to the library and confirm that the second button is visible. +6. The **Command One** button is not visible based on the code, until one row is selected in the document library. Upload or create a document to the library and confirm that the second button is visible. ![Selecting one document to get Command One button visible](../../../images/ext-com-default-customizer-doc-select.png) -5. Select **Command Two** to see how the dialog control works, which is used in the default output from the solution scaffolding when the ListView Command Set is selected as the extension type. +7. Select **Command Two** to see how the dialog control works, which is used in the default output from the solution scaffolding when the ListView Command Set is selected as the extension type. ![Selecting one document to get Command One button visible](../../../images/ext-com-default-customizer-btn-click.png) +### More details about the URL query parameters + +- **loadSPFX=true** ensures that the SharePoint Framework is loaded on the page. For performance reasons, the framework is not normally loaded unless at least one extension is registered. Because no components are registered yet, we must explicitly load the framework. +- **debugManifestsFile** specifies that we want to load SPFx components that are being locally served. The loader only looks for components in the App Catalog (for your deployed solution) and the SharePoint manifest server (for the system libraries). +- **customActions** simulates a custom action. You can set many properties on this `CustomAction` object that affect the look, feel, and location of your button; we’ll cover them all later. + - **Key**: GUID of the extension. + - **Location**: Where the commands are displayed. The possible values are: + - **ClientSideExtension.ListViewCommandSet.ContextMenu:** The context menu of the item(s) + - **ClientSideExtension.ListViewCommandSet.CommandBar:** The top command set menu in a list or library + - **ClientSideExtension.ListViewCommandSet:** Both the context menu and the command bar (Corresponds to SPUserCustomAction.Location="CommandUI.Ribbon") + - **Properties**: An optional JSON object containing properties that are available via the `this.properties` member. + +
+ ## Enhance the ListView Command Set rendering The default solution takes advantage of a new Dialog API, which can be used to show modal dialogs easily from your code. In the following steps, we'll slightly modify the default experience to demonstrate Dialog API use cases. From b78c5c3f70c8d5b12bdd77d0c426decdc5ca2609 Mon Sep 17 00:00:00 2001 From: Lincoln DeMaris Date: Fri, 20 Oct 2017 06:40:24 -0700 Subject: [PATCH 19/26] Update column-formatting.md (#973) --- docs/declarative-customization/column-formatting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/declarative-customization/column-formatting.md b/docs/declarative-customization/column-formatting.md index fe24f0503..c8f3a6672 100644 --- a/docs/declarative-customization/column-formatting.md +++ b/docs/declarative-customization/column-formatting.md @@ -74,8 +74,7 @@ The following image shows an example of conditional formatting applied to a numb ![Severity warning of 70 with orange background](../images/sp-columnformatting-conditionalbasic.png) -This example customizes a number field to color that field yellow when its value is 70 or less. This example adds a style attribute to the parent `
` element, specifies a CSS class (`sp-field-severity--warning`) to apply to that item if the value inside the field is less than or equal to 70, and specifies no color if the value is outside that range (in which case it will use the default color for values in that list view). -Note: this example uses a binary operation with the less than operator, "<", nested inside the conditional operation indicated by the operator, "?". Another description of the section in the following example is: If @currentField <= 70 Then class = sp-field-severity--warning. +This example uses the conditional operator `?` to apply a class (`sp-field-severity--warning`) to the parent `
` element when the value in the current field is less than or equal to 70. This causes the field to be highlighted when the value is less than or equal to 70, and appear normally if it's greater than 70. ```JSON { @@ -433,7 +432,7 @@ You can use column formatting to render quick action links next to fields. The f "@currentField.email", "?subject=Task status&body=Hey, how is your task coming along?.\r\n---\r\n", "@currentField.title", - "\r\nClick this link for more info. https://msft.spoppe.com/sites/LincolnsFunHouse2/Lists/Conference%20Prep/DispForm.aspx?ID=", + "\r\nClick this link for more info. http://contoso.sharepoint.com/sites/ConferencePrep/Tasks/Prep/DispForm.aspx?ID=", "[$ID]" ] } From bae0710cd9f5b40f87b4b801a1c54174f2b52fb8 Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Fri, 20 Oct 2017 15:40:59 +0200 Subject: [PATCH 20/26] Updated the guidance on updating SharePoint Framework packages (#970) --- docs/spfx/update-latest-packages.md | 77 ++++++++++++----------------- 1 file changed, 32 insertions(+), 45 deletions(-) diff --git a/docs/spfx/update-latest-packages.md b/docs/spfx/update-latest-packages.md index 308439f57..76fe25688 100644 --- a/docs/spfx/update-latest-packages.md +++ b/docs/spfx/update-latest-packages.md @@ -5,18 +5,19 @@ ms.prod: sharepoint --- -# Update SharePoint Framework packages +# Update SharePoint Framework packages SharePoint client-side development tools use the [npm](https://www.npmjs.com/) package manager to manage dependencies and other required JavaScript helpers. npm is typically included as part of Node.js setup. -When you create a new client-side solution, the yeoman generator for SharePoint fetches the latest SharePoint Framework packages required for your client-side project. As you build your project, your existing packages could be outdated as there could be new versions of one or more packages available. Based on the [release notes](https://aka.ms/spfx-release-notes) for a particular release or the latest package, you may decide to update your SharePoint Framework packages used in your project. SharePoint Framework packages include both the npm packages you have installed in your project, for example: [@microsoft/sp-core-library](https://www.npmjs.com/package/@microsoft/sp-core-library), and npm packages installed globally, for example: [@microsoft/generator-sharepoint](https://www.npmjs.com/package/@microsoft/generator-sharepoint). +When you create a new client-side solution, the yeoman generator for SharePoint fetches the latest SharePoint Framework packages required for your client-side project. As you build your project, your existing packages could be outdated as there could be new versions of one or more packages available. Based on the [release notes](https://aka.ms/spfx-release-notes) for a particular release or the latest package, you may decide to update your SharePoint Framework packages used in your project. SharePoint Framework packages include both the npm packages you have installed in your project, for example: [@microsoft/sp-core-library](https://www.npmjs.com/package/@microsoft/sp-core-library), and npm packages installed globally, for example: [@microsoft/generator-sharepoint](https://www.npmjs.com/package/@microsoft/generator-sharepoint). -While it may not be required, it is recommended you update the SharePoint Framework packages every so often so that you can get the latest changes and fixes that have been released. +While it may not be required, it is recommended you update the SharePoint Framework packages every so often so that you can get the latest changes and fixes that have been released. ## Find outdated packages in your project -To find the outdated packages in your client-side project, including SharePoint Framework and other packages your project depends on, run the following command in a console in the same directory as your project. -``` +To find the outdated packages in your client-side project, including SharePoint Framework and other packages your project depends on, run the following command in a console in the same directory as your project. + +```sh npm outdated ``` @@ -30,69 +31,61 @@ The command will list the following information about the packages your project To identify the SharePoint Framework packages, look for the package names that start with the following npm scope and prefix: -``` +```sh @microsoft/sp- ``` -Along with the framework packages, you may also need to update `react` and `office-ui-fabric-react` packages. Make sure you read the [release notes](https://aka.ms/spfx-release-notes) for that specific release to infer which packages require updates and plan accordingly. -### Update packages -To update one or more packages to the latest version, you will need to edit the package(s) information in the `package.json` file and then fetch the latest packages. - -#### Update package versions -Open your project in your favorite code editor and locate the `package.json` file in the root of your project directory. +Along with the framework packages, you may also need to update `react` and `office-ui-fabric-react` packages. Make sure you read the [release notes](https://aka.ms/spfx-release-notes) for that specific release to infer which packages require updates and plan accordingly. -In the `package.json` file, locate the package(s) under the `dependencies` and `devDependencies` section and update the version to the latest version available that was listed in the `npm outdated` command. For example, the image below highlights the version updates to SharePoint Framework packages, the left section referring to the old and the right section referring to the latest package versions. +### Using npm outdated with project targeting SharePoint 2016 -![Edit package versions in package.json file](../images/npm-update-packagejson-versions.png) +Starting from Feature Pack 2, SharePoint 2016 supports SharePoint Framework solutions. SharePoint 2016 uses an older version of the SharePoint Framework, than the version available in SharePoint Online. When scaffolding new projects, the SharePoint Framework Yeoman generator prompts you to choose if your solution should be using the latest version of the SharePoint Framework and be working only with SharePoint Online or if it should use an older version of the SharePoint Framework and work with both SharePoint 2016 and SharePoint Online. -Once you have updated the package versions, Save the `package.json` file. +When you run the `npm outdated` command in a project targeting both SharePoint Online and SharePoint 2016, it will show you the latest versions of the SharePoint Framework packages. These versions however work only with SharePoint Online. If you would update your solution to use these latest packages, it would not work with SharePoint 2016 anymore. -#### Update packages -Open your favorite console and navigate to the root of your project directory. Follow the instructions below to successfully update the packages to its latest version. +When working with SharePoint Framework solutions compatible with SharePoint hosted on-premises, you should always verify which patch level the target SharePoint farm has and which version of the SharePoint Framework it supports. -Delete the `node_modules` folder. This is the folder where npm installs the packages locally for your project. Deleting this folder forces npm to fetch the latest and not duplicate existing packages. +### Update packages -If you are using a Mac or a Linux environment, then run the following command: +When updating packages to newer versions, you should always use your package manager (npm or Yarn). You should not edit the `package.json` file manually. If you follow the recommended practice of using a lock file, your changes to the `package.json` file would be ignored. -``` -rm -rf node_modules/ -``` +Start with identifying which packages need updating and which newer version you want to use. Please note, that it might not always be possible for you to use the latest version of the given package as it might be incompatible with other SharePoint Framework dependencies, such as TypeScript. -If you are using a Windows environment, then run the following command: +For each package that you want to update, run the following command: -``` - rd /s /q node_modules/ +```sh +npm install mypackage@newversion --save ``` -Now, execute the following command to fetch the latest packages from the npm registry: +For example, if you were using AngularJS version v1.5.9 and wanted to update to version 1.6.5, you would run: -``` -npm install +```sh +npm install angular@1.6.5 --save ``` -This command will create the `node_modules` folder and install all the packages your project depends on and its dependencies based on the information available in the `package.json` file. As we updated the file with the latest versions, npm will now have the latest packages and their dependencies installed. +Updating the package using npm will install the specified version of the package in your project, update the version number in the package.json file dependencies and the lock file used in your project. Once the packages are installed, execute the following command to clean up any old build artifacts: -``` +```sh gulp clean ``` ### Update your code + Depending on breaking API changes, you may have to update your existing project code and config files. For each release, the [release notes](https://aka.ms/spfx-release-notes) will highlight any such breaking changes and the modifications required to your existing code. You will need to make sure you update your code with those fixes. You can always build the project to see if you have any errors and warnings by running the command in a console in your project directory: -``` +```sh gulp build ``` ## Update yeoman generator for SharePoint -Unlike the npm packages that are installed to a specific client-side project, the yeoman generator for SharePoint is installed globally in your machine. -To find if the yeoman generator for SharePoint is out of date, run the following command in a console window. +If you have installed the SharePoint Framework Yeoman generator globally, you can find out if it requires updating by running the following command: -``` +```sh npm outdated -g ``` @@ -106,26 +99,20 @@ The command will list the following information about the packages installed glo To identify the generator package, look for the following package name: -``` +```sh @microsoft/generator-sharepoint ``` ### Update generator package + Open your favorite console and execute the following command to update the generator to its latest published version: -``` +```sh npm install @microsoft/generator-sharepoint@latest -g ``` -The command will update the yeoman generator for SharePoint to the latest published version along with its depedencies. You can validate this by executing the following command in the console: +The command will update the yeoman generator for SharePoint to the latest published version along with its dependencies. You can validate this by executing the following command in the console: -``` +```sh npm ls @microsoft/generator-sharepoint -g --depth=0 ``` - - - - - - - From 9c458121628425716442abddbc97a1f61f18a74c Mon Sep 17 00:00:00 2001 From: aaronmi Date: Fri, 20 Oct 2017 06:44:49 -0700 Subject: [PATCH 21/26] Update building-simple-field-customizer.md (#971) Changed onRenderCell() to avoid folder item being rendered as "width: px" which displays full width of the column. --- .../get-started/building-simple-field-customizer.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/spfx/extensions/get-started/building-simple-field-customizer.md b/docs/spfx/extensions/get-started/building-simple-field-customizer.md index 712b23458..a752d1a8c 100644 --- a/docs/spfx/extensions/get-started/building-simple-field-customizer.md +++ b/docs/spfx/extensions/get-started/building-simple-field-customizer.md @@ -219,12 +219,14 @@ Now that we have successfully tested the out-of-the-box starting point of the Fi public onRenderCell(event: IFieldCustomizerCellEventParameters): void { event.domElement.classList.add(styles.cell); - event.domElement.innerHTML = ` + if (typeof event.fieldValue != 'undefined' && event.fieldValue) { // for folder fieldValue is "". + event.domElement.innerHTML = `
  ${event.fieldValue}
`; + } } ``` From 76e3fc8fc63c5a4edf9927f4d0f4e1440c13a2e0 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 14:09:08 -0700 Subject: [PATCH 22/26] Fixed red table? --- docs/design/themes-colors.md | 49 +++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/docs/design/themes-colors.md b/docs/design/themes-colors.md index e4ab604fb..b5e45b115 100644 --- a/docs/design/themes-colors.md +++ b/docs/design/themes-colors.md @@ -5,9 +5,9 @@ ms.date: 09/25/2017 # SharePoint themes and colors -Like the Microsoft brand palette, the SharePoint themes are designed to build on the Microsoft brand, while at the same time allow for flexibility to enliven our partnerships without dominating them. They reveal our shared goals and personality, and reflect our diversity and ability to optimize the SharePoint experience. - +Like the Microsoft brand palette, the SharePoint themes are designed to build on the Microsoft brand, while at the same time allow for flexibility to enliven our partnerships without dominating them. They reveal our shared goals and personality and reflect our diversity and ability to optimize the SharePoint experience. +
![SharePoint color palette, Red D13438, Orange CA5010, Green 10893E, Blue 0078D7, Purple 6B69D6, Gray 5D5A5B ](../images/design-theme-colors.png) @@ -17,7 +17,7 @@ The following design principles helped form the current SharePoint themes and co **Guided** -Our theming system works at a global level so updates can be made consistently across each site, allowing users to optimize their websites effortlessly. +Our theming system works at a global level so that updates can be made consistently across each site, allowing users to optimize their websites effortlessly. Our theming system operates in a controlled environment so that successful outcomes can be optimized quickly. @@ -40,7 +40,48 @@ The SharePoint color palette has been optimized for screens and devices, and to ### Red -
themeDarker: #751b1eblack: #000000
themeDark: #952226neutralDark: #212121
themeDarkAlt: #c02b30neutralPrimary: #333
themePrimary: #d13438neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666
neutralTertiary: #a6a6a6
themeSecondary: #d6494dneutralTertiaryAlt: #c8c8c8
themeTertiary: #ecaaacneutralLight: #eaeaea
themeLight: #f6d6d8neutralLighter: #f4f4f4
themeLighter: #faebebneutralLighterAlt: #f8f8f8
themeLighterAlt: #fdf5f5white: #fff
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
themeDarker: #751b1eblack: #000000
themeDark: #952226neutralDark: #212121
themeDarkAlt: #c02b30neutralPrimary: #333
themePrimary: #d13438neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666neutralTertiary: #a6a6a6
themeSecondary: #d6494dneutralTertiaryAlt: #c8c8c8
themeTertiary: #ecaaacneutralLight: #eaeaea
themeLight: #f6d6d8neutralLighter: #f4f4f4
themeLighter: #faebebneutralLighterAlt: #f8f8f8
themeLighterAlt: #fdf5f5white: #fff
### Orange From 2cf55805434c935bb35443ca8a8ea7c9bc3eb8a1 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 14:22:59 -0700 Subject: [PATCH 23/26] Orange and green --- docs/design/themes-colors.md | 88 ++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 3 deletions(-) diff --git a/docs/design/themes-colors.md b/docs/design/themes-colors.md index b5e45b115..9e6bcebee 100644 --- a/docs/design/themes-colors.md +++ b/docs/design/themes-colors.md @@ -31,7 +31,7 @@ Our themes embody a professional look and feel that ensures coherency and convey **Accessible** -Our built-in accessibility checker ensures universal design at all levels of default themes. For users who decide to customize, we provide helpful guidelines to design for accessibility. +Our built-in accessibility checker ensures universal design at all levels of default themes. For users who decide to customize, we provide helpful guidelines to design for accessibility. ## Colors @@ -85,11 +85,93 @@ The SharePoint color palette has been optimized for screens and devices, and to ### Orange -
themeDarker: #6f2d09black: #000000
themeDark: #8d390bneutralDark: #212121
themeDarkAlt: #b5490fneutralPrimary: #333
themePrimary: #ca5010neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666
neutralTertiary: #a6a6a6
themeSecondary: #e55c12neutralTertiaryAlt: #c8c8c8
themeTertiary: #f6b28dneutralLight: #eaeaea
themeLight: #fbdac9neutralLighter: #f4f4f4
themeLighter: #fdede4neutralLighterAlt: #f8f8f8
themeLighterAlt: #fef6f1white: #fff
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
themeDarker: #6f2d09black: #000000
themeDark: #8d390bneutralDark: #212121
themeDarkAlt: #b5490fneutralPrimary: #333
themePrimary: #ca5010neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666neutralTertiary: #a6a6a6
themeSecondary: #e55c12neutralTertiaryAlt: #c8c8c8
themeTertiary: #f6b28dneutralLight: #eaeaea
themeLight: #fbdac9neutralLighter: #f4f4f4
themeLighter: #fdede4neutralLighterAlt: #f8f8f8
themeLighterAlt: #fef6f1white: #fff
### Green -
themeDarker: #094c23black: #000000
themeDark: #0c602cneutralDark: #212121
themeDarkAlt: #0f7c39neutralPrimary: #333
themePrimary: #10893eneutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666
neutralTertiary: #a6a6a6
themeSecondary: #14a94eneutralTertiaryAlt: #c8c8c8
themeTertiary: #7aefa7neutralLight: #eaeaea
themeLight: #bff7d5neutralLighter: #f4f4f4
themeLighter: #dffbeaneutralLighterAlt: #f8f8f8
themeLighterAlt: #effdf4white: #fff
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
themeDarker: #094c23black: #000000
themeDark: #0c602cneutralDark: #212121
themeDarkAlt: #0f7c39neutralPrimary: #333
themePrimary: #10893eneutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666neutralTertiary: #a6a6a6
themeSecondary: #14a94eneutralTertiaryAlt: #c8c8c8
themeTertiary: #7aefa7neutralLight: #eaeaea
themeLight: #bff7d5neutralLighter: #f4f4f4
themeLighter: #dffbeaneutralLighterAlt: #f8f8f8
themeLighterAlt: #effdf4white: #fff
### Blue From d7396b98cab27bdc83a2a7c121eab6e288b8db73 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 14:39:56 -0700 Subject: [PATCH 24/26] Attempt to fix tables I removed "rowspan=3" which was showing up outside the boxes on the live site, and made a few other changes, so let's hope this does the trick... --- docs/design/themes-colors.md | 129 ++++++++++++++++++++++++++++++++++- 1 file changed, 126 insertions(+), 3 deletions(-) diff --git a/docs/design/themes-colors.md b/docs/design/themes-colors.md index 9e6bcebee..4d7048711 100644 --- a/docs/design/themes-colors.md +++ b/docs/design/themes-colors.md @@ -175,12 +175,135 @@ The SharePoint color palette has been optimized for screens and devices, and to ### Blue -
themeDarker: #004578black: #000000
themeDark: #005a9eneutralDark: #212121
themeDarkAlt: #106ebeneutralPrimary: #333
themePrimary: #0078d7neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666
neutralTertiary: #a6a6a6
themeSecondary: #2b88d8neutralTertiaryAlt: #c8c8c8
themeTertiary: #71afe5neutralLight: #eaeaea
themeLight: #c7e0f4neutralLighter: #f4f4f4
themeLighter: #deecf9neutralLighterAlt: #f8f8f8
themeLighterAlt: #eff6fcwhite: #fff
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
themeDarker: #004578black: #000000
themeDark: #005a9eneutralDark: #212121
themeDarkAlt: #106ebeneutralPrimary: #333
themePrimary: #0078d7neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666neutralTertiary: #a6a6a6
themeSecondary: #2b88d8neutralTertiaryAlt: #c8c8c8
themeTertiary: #71afe5neutralLight: #eaeaea
themeLight: #c7e0f4neutralLighter: #f4f4f4
themeLighter: #deecf9neutralLighterAlt: #f8f8f8
themeLighterAlt: #eff6fcwhite: #fff
### Purple -
themeDarker: #27268ablack: #000000
themeDark: #3230b0neutralDark: #212121
themeDarkAlt: #5250cfneutralPrimary: #333
themePrimary: #6b69d6neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666
neutralTertiary: #a6a6a6
themeSecondary: #7a78daneutralTertiaryAlt: #c8c8c8
themeTertiary: #c1c0eeneutralLight: #eaeaea
themeLight: #e1e1f7neutralLighter: #f4f4f4
themeLighter: #f0f0fbneutralLighterAlt: #f8f8f8
themeLighterAlt: #f8f7fdwhite: #fff
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
themeDarker: #27268ablack: #000000
themeDark: #3230b0neutralDark: #212121
themeDarkAlt: #5250cfneutralPrimary: #333
themePrimary: #6b69d6neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666neutralTertiary: #a6a6a6
themeSecondary: #7a78daneutralTertiaryAlt: #c8c8c8
themeTertiary: #c1c0eeneutralLight: #eaeaea
themeLight: #e1e1f7neutralLighter: #f4f4f4
themeLighter: #f0f0fbneutralLighterAlt: #f8f8f8
themeLighterAlt: #f8f7fdwhite: #fff
### Gray -
themeDarker: #323130black: #000000
themeDark: #403e3dneutralDark: #212121
themeDarkAlt: #53504eneutralPrimary: #333
themePrimary: #5d5a58neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666
neutralTertiary: #a6a6a6
themeSecondary: #6d6a67neutralTertiaryAlt: #c8c8c8
themeTertiary: #bbb9b8neutralLight: #eaeaea
themeLight: #dfdeddneutralLighter: #f4f4f4
themeLighter: #efeeeeneutralLighterAlt: #f8f8f8
themeLighterAlt: #f7f7f7white: #fff
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
themeDarker: #323130black: #000000
themeDark: #403e3dneutralDark: #212121
themeDarkAlt: #53504eneutralPrimary: #333
themePrimary: #5d5a58neutralPrimaryAlt: #3c3c3c
neutralSecondary: #666666neutralTertiary: #a6a6a6
themeSecondary: #6d6a67neutralTertiaryAlt: #c8c8c8
themeTertiary: #bbb9b8neutralLight: #eaeaea
themeLight: #dfdeddneutralLighter: #f4f4f4
themeLighter: #efeeeeneutralLighterAlt: #f8f8f8
themeLighterAlt: #f7f7f7white: #fff
From 279acb3e2887ff651f803d5931719b358a890d39 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 14:42:08 -0700 Subject: [PATCH 25/26] Tweaked spacing --- docs/design/themes-colors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/themes-colors.md b/docs/design/themes-colors.md index 4d7048711..2982762d2 100644 --- a/docs/design/themes-colors.md +++ b/docs/design/themes-colors.md @@ -31,7 +31,7 @@ Our themes embody a professional look and feel that ensures coherency and convey **Accessible** -Our built-in accessibility checker ensures universal design at all levels of default themes. For users who decide to customize, we provide helpful guidelines to design for accessibility. +Our built-in accessibility checker ensures universal design at all levels of default themes. For users who decide to customize, we provide helpful guidelines to design for accessibility. ## Colors From 43f6288225e82b563ae83084b788c9046c8e3832 Mon Sep 17 00:00:00 2001 From: Linda Caputo Date: Fri, 20 Oct 2017 14:49:13 -0700 Subject: [PATCH 26/26] Updating to create pull request --- docs/design/themes-colors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/themes-colors.md b/docs/design/themes-colors.md index 2982762d2..183eebeed 100644 --- a/docs/design/themes-colors.md +++ b/docs/design/themes-colors.md @@ -31,7 +31,7 @@ Our themes embody a professional look and feel that ensures coherency and convey **Accessible** -Our built-in accessibility checker ensures universal design at all levels of default themes. For users who decide to customize, we provide helpful guidelines to design for accessibility. +Our built-in accessibility checker ensures universal design at all levels of default themes. For users who decide to customize, we provide helpful guidelines to design for accessibility. ## Colors