- Taxonomy
- Social
- ProjectServer
- Search
- BcsConnection
- Content
+## Migration steps overview -The required permissions are as follows in the Azure Storage API: +Start a migration job with three steps. Check the guidance in each of the steps in this section. -```csharp -(SharedAccessBlobPermissions.Read | SharedAccessBlobPermissions.List) -``` +### Provision the destination containers and the queue -**Note:** The change to enforce Read and List permissions on the SAS token is coming in a future build. Until then it will not be enforced. However, it is a best practice to use these values. +> [!IMPORTANT] +> Use [GetMigrationJobProgress API](migration-job-progress-api-reference.md) to retrieve migration job status. +> +> Provisioning Azure Queues for migration job status tracking is no longer required. Deprecation is planned for the second half of 2026. Until then, Azure Queues will remain available for status retrieval. -All files in the container must have at least a single snapshot applied to them to ensure that no file modification is made by the customer during the import. Any file that does not have a snapshot will be skipped during import and have an error thrown, although the job will attempt to continue the import. The import pipeline will use the latest snapshot of the file available at the time of import. The following is an example of the code that might be used to create a snapshot on a file after it is uploaded to Azure Blob Storage: +Use the `ProvisionMigrationContainers` method to provision the containers. Check [Use Azure Blob Storage Containers and Azure Queues with Migration API](migration-azure.md) for details. You can also use your own containers and queues if needed. -```csharp -CloudBlockBlob blob = blobContainerObj.GetBlockBlobReference(file); -blob.UploadFromStream(stm); -blob.CreateSnapshot(); -``` +### Prepare the content -> [!NOTE] -> The change to require and use the latest SnapShots on all files is coming in a future build, and until then will be ignored. +Package the contents in the defined format and upload them to Azure Blob Storage Containers as the content package. -##### azureContainerManifestUri +Check [Content package](migration-content-package.md) to see the detailed requirements. -The valid URL including SAS token for accessing the Azure Blob Storage Container which contains the block blobs for the manifest and other package describing XML files. This location will also be used for the log output. This container cannot be the same as the one used for the azureContainerSourceUri. The SAS token must have been created with only Read, List and Write permissions or the migration job will fail. The SAS token should at least have a lifetime that starts no later than when the job was submitted, until a reasonable time for successful import to have concluded. +### Create the manifest files -> [!NOTE] -> The change to enforce Read, List and Write permissions on the SAS token is coming in a future build, and until then will be not be enforced, however it is best practice to use these values. If an issue arises using a current build, try removing the List permission as a temporary workaround, noting that it will become required soon. +Based on the contents, create manifest files in XML format, and upload them to Azure Blob Storage Containers as the manifest package. -All files in the container must have at least a single snapshot applied to them to ensure that no file modification is made by the customer during the import. Any file that does not have a snapshot will cause failures during the import and have errors thrown, potentially failing the entire migration job. +Check [Manifest files](migration-manifest.md) to see the detailed requirements. -> [!NOTE] -> The change to require and use the latest SnapShots on all files is coming in a future build. Until then they will be ignored. +### Use Migration API to start the migration and get status -##### azureQueueReportUri +The `CreateMigrationJob` method creates a migration job, which is queued up for processing. Migration API manages the queue and returns status and logs. Use the `CreateMigrationEncrypted` method to migrate encrypted contents. Check [SharePoint Migration API Reference](migration-api-reference.md) for details. -The valid URL including SAS token for accessing the user provided Azure Queue used for returning notifications of migration job progress. This value can be null if no notification queue will be used during the import. If this value is not null and proper access is granted in the SAS token in this URI, it will be used for real time status update. The SAS token must have been created with only Add, Read and Update permissions or the migration job will be unable to add events to the queue. The required permissions are as follows in the Azure Storage API: +> [!IMPORTANT] +> Use GetMigrationJobProgress API to track migration job status. -``` -(SharedAccessQueuePermissions.Add | SharedAccessQueuePermissions.Read | SharedAccessQueuePermissions.Update) -``` -Once accepted, the job ID will be written to the notification queue if it was provided and access is valid. The notification queue can be used for multiple migration jobs at the same time, as each job will identify itself in values sent back to the notification queue. +Upon creation of a new migration job, Migration API returns the Job ID. Track the status of the import with [GetMigrationJobProgress API](migration-job-progress-api-reference.md). -#### Return values +Migration API generates logs in the manifest container. Check the log entries for migration results. -The unique identifier for the migration job is returned if the job is successfully queued, or if unsuccessful, a null value will be returned. The migration job unique identifier can be used to query the migration job status while it is in the queue or being processed by using the GetMigrationJobStatus method. +Migration API also generates logs of file-level activities performed by migration. The supported file-level activities include FileUploaded, FileDeleted, FileRenamed, FileMoved. Check M365 Admin Center for activity details when needed. -**Example:** +## Best Practice -```csharp -Guid MigrationJobId = TargetSite.CreateMigrationJob( - TargetWebId, - azureContainerSourceUri, - azureContainerManifestUri, - azureQueueReportUri); -``` +### Use app-based authentication -### GetMigrationJobStatus +Migration generates workload to the SharePoint backend differently from end user-generated traffic. To properly allocate resources with our elastic capability, only use app-based authentication in your migration solution. -This method queries the queue status for the specified migration job. It is an optional check after calling the CreateMigrationJob method. Once the migration job has completed, it will no longer show up in the queue and the notification queue and/or log output should be checked for detailed status. +Don't use user mode in your migration solution. Running migration in user mode triggers increased throttling, resulting in poor performance. -#### Syntax +To learn more about how to register an app ID and how to implement app-based authentication, check [How to register an app ID](/azure/active-directory/develop/active-directory-v2-registration-portal) and [Microsoft Graph Auth guidance](/graph/auth). -```xml -[ClientNS.ClientCallableMethod] -public SPMigrationJobState GetMigrationJobStatus(Guid MigrationJobId) -``` +### Microsoft Entra ID Permissions -#### Parameters +Microsoft Entra ID provides two types of permission: Delegated Permission and Application Permissions. Check[ +Permissions and consent in the Azure Active Directory v1.0 endpoint](/azure/active-directory/develop/v1-permissions-and-consent) for details. -##### Id +For SharePoint and OneDrive migration scenarios, follow the Microsoft Entra ID permission specification. -The unique identifier of the migration job returned from CreateMigrationJob method. +For migration tools that rely on end-user sign-in and presence, use Delegated permission. -#### Return values +For service-based migration tools that run without a signed-in user present, such as applications that run as background services, use Application permission. -The migration job status is returned using a SPMigrationJobState object if the job is found in the queue, or if unsuccessful, a value of none (0) will be returned. +### App IDs -**Example** +You can choose to share a single App ID to cover multiple migration solutions created or create an individual App ID for each of the products. Make sure to register App IDs. Sharing App IDs doesn't affect performance or throttling. -```csharp -SPMigrationJobState CurrentJobState = TargetSite.GetMigrationJobStatus(MigrationJobId); -``` +### Keep destination SharePoint Site unactivated -## Enumerations +To avoid migration issues, deactivate the target site for users until migration completion. The source could remain active, allowing read and write access to keep productivity. Switch users to the new SharePoint destination sites after migration completion. -### SPMigrationJobState +## Performance -SPMigrationJobState is an enumeration that tracks possible major states in the import queue. +Migration API processes jobs through a queue mechanism with preconfigured workload management settings. Migration API processes the jobs on a best-effort basis, without Service Level Agreement (SLA) or guaranteed performance. -#### Members +### Optimize migration performance -| Member name | Description | -| ----------- | --------------------------------------------------------------------------------------------------------------------------- | -| None | Migration job is currently unknown to the queue, either through completion and removal, or invalid job identifier. Value=0. | -| Queued | Migration job is currently known by the queue and not being processed. Value=2. | -| Processing | Migration job is currently known by the queue and is being actively processed. Value=4. | +In order to ensure optimal performance for your migration projects, it's important to plan carefully, especially when dealing with large-scale migrations. For more information on how to estimate timespans and optimize performance, see our [performance guide](/sharepointmigration/sharepoint-online-and-onedrive-migration-speed). -## Import Package Structure +### I'm seeing throttling messages -Package structure is based on a constrained version of the Content Deployment package schema. Documentation for the original full schema can be found at [docs.microsoft.com](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). Until published on docs.microsoft.com, the constrained structure can be found in this document in the appendix. +To ensure good user experiences for all Microsoft 365 customers, SharePoint uses throttling to protect the SharePoint infrastructure. Avoid getting throttled by following [throttling guidance](https://aka.ms/spo429). -| XML file | Schema File | Description | -| ------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| ExportSettings.xml | DeploymentExportSettings Schema | Provides validation for the ExportSettings.XML file exported into the content migration package. ExportSettings.XML does the following:
- Contains the export settings specified by using the SPExportSettings class and other classes that are part of the content migration object model.
- Ensures that the subsequent import process (at the migration target site) enforces the directives specified in the export settings.
- Maintains a catalog of all objects exported to the migration package. | -| LookupListMap.xml | DeploymentLookupListMap Schema | Provides validation for the LookupListMap.XML file exported into the content migration package. LookupListMap.XML maintains a simple lookup list that records SharePoint list item (list item to list item) references. | -| Manifest.xml | DeploymentManifest Schema | Provides validation for the Manifest.xml file that is exported into the content migration package. Provides a comprehensive manifest containing listings of both the contents and the structure of the source site. The migration operation uses the manifest file to reconstitute the source site and its components when it is imported to the destination site. | -| Requirements.xml | DeploymentRequirements Schema | Provides validation for the Requirements.xml file exported into the content migration package. Requirements.xml maintains list of deployment requirements in the form of installation requirements on the migration target, such as feature definitions, template versions, Web Part assemblies, language packs, and so forth. | -| RootObjectMap.xml | DeploymentRootObjectMap Schema | Provides validation for the RootObjectMap.xml file exported into the content migration package.RootObjectMap.xml maintains a list of mappings of secondary (dependent) objects, which allows the import phase of the migration operation to correctly place the dependent objects relative to the locations of the root object mappings. | -| SystemData.xml | DeploymentSystemData Schema | Provides validation for the SystemData.xml file exported into the content migration package.SystemData.xml does the following: Collects a variety of low-level system data. Records the number and names of Manifest.xml files (in cases where the migration uses multiple manifests). | -| UserGroupMap.xml | DeploymentUserGroupMap Schema | Provides validation for the UserGroup.xml file exported into the content migration package. UserGroup.xml maintains a list of users and user security groups with respect to access security and permissions. | -| ViewFormsList.xml | DeploymentViewFormsList Schema | Provides validation for the ViewFormsList.xml file exported into the content migration package.ViewFormsList.xml maintains a list of Web Parts and tracks whether each is a view or form. | +## Special articles -### Content structure +### Migrating sharing events of files and folders -File content that is referenced within the manifest of the package structure must be stored in either a flat or hierarchical structure within the Azure Blob Store Container defined by the CreateMigrationJob’s `azureContainerSourceUri` parameter. For example, import packages generated form a legacy version export will not be hierarchical, and will instead have all files stored at the root level with a pattern like ########.dat where the # symbols are hexadecimal characters starting at 0 and no file names are repeated within a package. Alternately, a package generated from a file share can have the source folder hierarchy and file names preserved in the same hierarchy. +Check [Sharing events](/sharepoint/dev/apis/migration-api-shared) article for instructions when migrating shared events metadata with files and folders. -The main requirement for the structure is that the FileValue references in the **Manifest.XML** file must refer to the exact name and physical hierarchy that the content is stored in within the Azure Blob Store location for import. The destination file names and folder hierarchy from the import operation are not directly related to the physical naming and hierarchy and are instead defined through the **Manifest.XML** file. +### Web Parts -### ExportSettings.XML - -The **ExportSettings.XML** file is expected to be at the root of the Azure Blob Store Container defined by the CreateMigrationJob’s `azureContainerManifestUri` parameter. This required file is validated using the constrained DeploymentExportSettings.XSD, which has some limited changes from current published [full 2013 package schema](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). - -The main requirement is that the ExportSettings `SiteUrl` value must be populated with a URL consistent with the source URL used for the rest of the import package. In the case of file shares as a source, the URL would be pre-specified to be the source URL in the rest of the package, whereas a package generated through an export operation at a source site would be its original source site collection URL. - -### LookupListMap.XML - -The **LookupListMap.XML** file, if included, is expected to be at the root of the Azure Blob Store Container defined by the CreateMigrationJob’s azureContainerManifestUri parameter. This optional file is validated using the constrained **DeploymentLookupListMap.XSD**, which has no change from current published [full 2013 package schema](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). - -Since an import package for the pipeline does not include defining fields or views on a list or document library, the **LookupListMap.XML** file will normally include no child nodes under the root and as such can also be excluded from the package if not required, although a warning may be logged in this case. - -### Manifest.XML - -All instances of the **Manifest.XML** file for a package are expected to be at the root of the Azure Blob Store Container defined by the CreateMigrationJob’s `azureContainerManifestUri` parameter. This required file is validated using the constrained **DeploymentManifest.XSD**, which has multiple major changes and significant reduction in types from current published [full 2013 package schema](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). - -The **Manifest.XML** is the primary descriptor for metadata within the package, and provides the list/folder/item hierarchy, along with metadata for the items including references back to users and groups defined in the **UserGroupMap.XML** file. There may be more than one **Manifest.XML** file (which can be identified using different file names to uniquely identify them), and all are found by the import pipeline through references within the **SystemData.XML** file’s ManifestFile entries. - -The main requirements for **Manifest.XML** to be able to successfully import through the pipeline is that the Web Id and Document Library ID/List ID be consistent with the target location. If a Web ID is used which doesn’t match the target location, errors will occur because the parent web for the import operation cannot be found. - -Likewise, an incorrect Document Library ID/List ID will prevent the importation into the target Document Library or List. IDs should never be reused within the same site collection, so same packages should not be imported to the same target site collection regardless of the destination web. - -For individual files and folders within the document library or list, their identifiers should be consistent between import events to the same location. Specifically, performing an import of a package generated from a file share would initially require generating new GUIDs for each file and folder, along with matching GUIDs for the list items that represent them. Therefore, performing a second import against the same target using the same package would keep the same IDs, but performing a second import against the same target using a new package for the same content would result in ID conflicts and import errors for all items in conflict. - -The package generated initially from a file share is effectively a form of record for the original generated IDs and can potentially be used as a reference for follow up package generation to prevent ID collisions when unintended, and to allow like IDs to ensure correct overwrite, deletion or move activities. - -### Requirements.XML - -The **Requirements.XML** file is expected to be at the root of the Azure Blob Store Container defined by the CreateMigrationJob’s azureContainerManifestUri parameter. This optional file is validated using the constrained DeploymentRequirements.XSD, which has no change from current published [full 2013 package schema](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). - -For file shares this is expected to normally include no child nodes under the root and as such can also be excluded from the package if not required, although a warning will be logged in this case. - -### RootObjectMap.XML - -The **RootObjectMap.XML** file is expected to be at the root of the Azure Blob Store Container defined by the CreateMigrationJob’s `azureContainerManifestUri` parameter. This required file is validated using the constrained **DeploymentRootObjectMap.XSD**, which has some limited changes from current published [full 2013 package schema](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). The most common `RootObject` that will be included will be a single object of type List. The Id for this item should be the List Id for the target list, and the `ParentWebID` should match the Id of the parent target web containing this list in order for migration to be successful. The Id, WebUrl and Url values of this object must also match the related structure laid out in the **Manifest.XML** file. - -### SystemData.XML - -The **SystemData.XML** file is expected to be at the root of the Azure Blob Store Container defined by the CreateMigrationJob’s `azureContainerManifestUri` parameter. This required file is validated using the constrained **DeploymentSystemData.XSD**, which has no change from current published [full 2013 package schema](https://docs.microsoft.com/sharepoint/dev/schema/content-migration-schemas). - -The `SchemaVersion` information is expected to reference the current Build and DatabaseVersion of the target farm, a Version of “15.0.0.0”, and the `SiteVersion` value is expected to always match the target site collection `UIVersion` (i.e. most commonly this will be “15”). Each **Manifest.XML** file for the package is expected to be listed in this file within the `ManifestFile` entries. - -The SystemObjects that define dependent objects that should remain immutable by the migration code should also be listed here to ensure correct behavior of the import operation. The following is an example of the common objects in the **SystemObjects.XML** file from a file share based import, noting that the IDs are expected to be different for each package, and the URLs may be different. - -#### Table 1: Example SystemData.XML file - -```xml - -
- -| Content | Manifest | -| ----------------- | --------- | -| Files and folders | XML files | - -There are two new optional parameters in manifest.xml: - -- MD5Hash -- InitializationVector - -#### Preparing the package -The method for calling the migration job doesn’t change; only the package generation needs to be changed. - -In the Manifest container one file is named Manifest.xml. There are 2 optional attributes added to the file node: *MD5Hash* and *InitializationVector*.
- -Example: - -```xml -
- -  - -9. Make sure the **expirationDateTime** is at most 6 months from today. - -10. Make sure you are debugging the webhook receiver as in Step 4. - -11. Select **Send** to execute the request. - - If the request is successful, you should see the response from SharePoint that provides the subscription details. The following example shows a response for a newly created subscription: - - ```json - { - "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449", - "expirationDateTime": "2016-10-27T16:17:57Z", - "id": "32b95d9-4d20-4a17-bfa3-2957cb38ead8", - "notificationUrl": "https://85557d4b.ngrok.io/api/spwebhook/handlerequest", - "resource": "c34420f9-2ad7-4e54-94c9-b67798d2299b" - } - ``` - -12. Copy the subscription **id**. You will need it for the next set of requests. - -13. Go to the webhook receiver project in Visual Studio and examine the **Output** window. You should see the trace logs that look similar to the following trace, along with other messages: - - ``` - iisexpress.exe Information: 0 : Message='Received client state: A0A354EC-97D4-4D83-9DDB-144077ADB449' - iisexpress.exe Information: 0 : Message='Received validation token: daf2803c-43cf-44c7-8dff-7066eaa40f13' - ``` - - The trace indicates that the webhook received initially received a validation request. If you look at the code, you'll see that it returns the validation token immediately so that SharePoint can validate the request: - - ```cs - if (queryStringParams.AllKeys.Contains("validationtoken")) - { - httpResponse = new HttpResponseMessage(HttpStatusCode.OK); - validationToken = queryStringParams.GetValues("validationtoken")[0].ToString(); - httpResponse.Content = new StringContent(validationToken); - - traceWriter.Trace(Request, "SPWebhooks", - TraceLevel.Info, - string.Format("Received validation token: {0}", validationToken)); - return httpResponse; - } - ``` +1. Enter the following as the request URL: + + ```http + https://site-collection/_api/web/lists('list-id')/subscriptions + ``` + +1. Replace _site-collection_ with your site collection. +1. Go to the **Headers** tab. +1. Make sure you still have the **Authorization** header. If not, you need to request a new access token. +1. Add the following header **key** > **value** pairs: + + * **Accept**: `application/json;odata=nometadata` + * **Content-Type**: `application/json` + +1. Go to the **Body** tab and select **raw** format. +1. Paste the following JSON as the body: + + ```json + { + "resource": "https://site-collection/_api/web/lists('list-id')", + "notificationUrl": "https://ngrok-forwarding-address/api/spwebhook/handlerequest", + "expirationDateTime": "2016-10-27T16:17:57+00:00", + "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449" + } + ``` + +  + +1. Make sure the **expirationDateTime** is at most 6 months from today. +1. Make sure you are debugging the webhook receiver as in Step 4. +1. Select **Send** to execute the request. + + If the request is successful, you should see the response from SharePoint that provides the subscription details. The following example shows a response for a newly created subscription: + + ```json + { + "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449", + "expirationDateTime": "2016-10-27T16:17:57Z", + "id": "32b95d9-4d20-4a17-bfa3-2957cb38ead8", + "notificationUrl": "https://85557d4b.ngrok.io/api/spwebhook/handlerequest", + "resource": "c34420f9-2ad7-4e54-94c9-b67798d2299b" + } + ``` + +1. Copy the subscription **id**. You will need it for the next set of requests. +1. Go to the webhook receiver project in Visual Studio and examine the **Output** window. You should see the trace logs that look similar to the following trace, along with other messages: + + ```console + iisexpress.exe Information: 0 : Message='Received client state: A0A354EC-97D4-4D83-9DDB-144077ADB449' + iisexpress.exe Information: 0 : Message='Received validation token: daf2803c-43cf-44c7-8dff-7066eaa40f13' + ``` + + The trace indicates that the webhook received initially received a validation request. If you look at the code, you'll see that it returns the validation token immediately so that SharePoint can validate the request: + + ```csharp + if (queryStringParams.AllKeys.Contains("validationtoken")) + { + httpResponse = new HttpResponseMessage(HttpStatusCode.OK); + validationToken = queryStringParams.GetValues("validationtoken")[0].ToString(); + httpResponse.Content = new StringContent(validationToken); + + traceWriter.Trace(Request, "SPWebhooks", + TraceLevel.Info, + string.Format("Received validation token: {0}", validationToken)); + return httpResponse; + } + ``` ## Step 6: Get subscription details Now you'll run queries in Postman to get the subscription details. 1. Open the Postman client. +1. Change the request to **GET** from **POST**. +1. Enter the following as the request: -2. Change the request to **GET** from **POST**. - -3. Enter the following as the request: - - ``` - https://site-collection/_api/web/lists('list-id')/subscriptions - ``` - -4. Replace _site-collection_ with your site collection. + ```http + https://site-collection/_api/web/lists('list-id')/subscriptions + ``` -5. Select **Send** to execute the request. +1. Replace _site-collection_ with your site collection. +1. Select **Send** to execute the request. - If successful, you should see SharePoint return the subscriptions for this list resource. Because we just added one, you should at least see one subscription returned. The following example shows a response with one subscription: + If successful, you should see SharePoint return the subscriptions for this list resource. Because we just added one, you should at least see one subscription returned. The following example shows a response with one subscription: - ```json - { - "value": [ - { - "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449", - "expirationDateTime": "2016-10-27T16:17:57Z", - "id": "32b95add-4d20-4a17-bfa3-2957cb38ead8", - "notificationUrl": "https://85557d4b.ngrok.io/api/spwebhook/handlerequest", - "resource": "c34420f9-2a67-4e54-94c9-b67798229f9b" - } - ] - } - ``` + ```json + { + "value": [ + { + "clientState": "A0A354EC-97D4-4D83-9DDB-144077ADB449", + "expirationDateTime": "2016-10-27T16:17:57Z", + "id": "32b95add-4d20-4a17-bfa3-2957cb38ead8", + "notificationUrl": "https://85557d4b.ngrok.io/api/spwebhook/handlerequest", + "resource": "c34420f9-2a67-4e54-94c9-b67798229f9b" + } + ] + } + ``` -6. Run the following query to get details of the specific subscription: +1. Run the following query to get details of the specific subscription: - ``` - https://site-collection/_api/web/lists('list-id')/subscriptions('subscription-id') - ``` + ```http + https://site-collection/_api/web/lists('list-id')/subscriptions('subscription-id') + ``` -7. Replace `subscription-id` with your subscription id. +1. Replace `subscription-id` with your subscription id. ## Step 7: Test webhook notification Now add a file to the Documents library and test if you get a notification from SharePoint in the webhook receiver. 1. Go to Visual Studio. +1. In the **SPWebhookController**, place a breakpoint on the following line of code: -2. In the **SPWebhookController**, place a breakpoint on the following line of code: - - ```cs - var requestContent = Request.Content.ReadAsStringAsync().Result; - ``` - -3. Go to the **Documents** library. It is named **Shared Documents** library in your default site collection. - -4. Add a new file. - -5. Go to Visual Studio and wait for the breakpoint to be hit. + ```csharp + var requestContent = Request.Content.ReadAsStringAsync().Result; + ``` - The wait time may vary from a few seconds to up to five minutes. When the breakpoint is hit, the webhook receiver has just received a notification from SharePoint. +1. Go to the **Documents** library. It is named **Shared Documents** library in your default site collection. +1. Add a new file. +1. Go to Visual Studio and wait for the breakpoint to be hit. -6. Select **F5** to continue. + The wait time may vary from a few seconds to up to five minutes. When the breakpoint is hit, the webhook receiver has just received a notification from SharePoint. -7. To see the notification data, look in the **Output** window for the following entries, since you added the notification data into the trace log: +1. Select **F5** to continue. +1. To see the notification data, look in the **Output** window for the following entries, since you added the notification data into the trace log: - ``` - iisexpress.exe Information: 0 : Message='Resource: c34420f9-2a67-4e54-94c9-b6770892299b' - iisexpress.exe Information: 0 : Message='SubscriptionId: 32b95ad9-4d20-4a17-bfa3-2957cb38ead8' - iisexpress.exe Information: 0 : Message='TenantId: 7a17cb7d-6898-423f-8839-45f363076f06' - iisexpress.exe Information: 0 : Message='SiteUrl: /' - iisexpress.exe Information: 0 : Message='WebId: 62b80e0b-f889-4974-a519-cc138413be40' - iisexpress.exe Information: 0 : Message='ExpirationDateTime: 2016-10-27T16:17:57.0000000Z' - ``` + ```console + iisexpress.exe Information: 0 : Message='Resource: c34420f9-2a67-4e54-94c9-b6770892299b' + iisexpress.exe Information: 0 : Message='SubscriptionId: 32b95ad9-4d20-4a17-bfa3-2957cb38ead8' + iisexpress.exe Information: 0 : Message='TenantId: 7a17cb7d-6898-423f-8839-45f363076f06' + iisexpress.exe Information: 0 : Message='SiteUrl: /' + iisexpress.exe Information: 0 : Message='WebId: 62b80e0b-f889-4974-a519-cc138413be40' + iisexpress.exe Information: 0 : Message='ExpirationDateTime: 2016-10-27T16:17:57.0000000Z' + ``` -This project only writes the information to the trace log. However, in your receiver, you send this information into a table or a queue that can process the received data to get information from SharePoint. +This project only writes the information to the trace log. However, in your receiver, you send this information into a table or a queue that can process the received data to get information from SharePoint. With this data, you can construct the URL and use the [GetChanges](https://msdn.microsoft.com/library/office/dn531433.aspx#bk_ListGetChanges) API to get the latest changes. diff --git a/docs/apis/webhooks/lists/create-subscription.md b/docs/apis/webhooks/lists/create-subscription.md index 065537129..bab6f9320 100644 --- a/docs/apis/webhooks/lists/create-subscription.md +++ b/docs/apis/webhooks/lists/create-subscription.md @@ -1,15 +1,12 @@ --- title: Create a new subscription description: Creates a new webhook subscription on a SharePoint list. -ms.date: 02/08/2018 -ms.prod: sharepoint -localization_priority: Priority +ms.date: 10/20/2020 +ms.localizationpriority: high --- +# Create a new subscription - -# Create a new subscription - -Creates a new webhook subscription on a SharePoint list. +Creates a new webhook subscription on a SharePoint list. ## Permissions @@ -19,7 +16,7 @@ The application must have at least edit permissions to the SharePoint list where You must grant the Azure AD app the permissions specified in the following table: -Application | Permission +Application | Permission ------------|------------ Office 365 SharePoint Online|Read and write items and lists in all site collections. @@ -27,13 +24,13 @@ Office 365 SharePoint Online|Read and write items and lists in all site collecti You must grant the SharePoint Add-in the following permission(s) or higher: -Scope | Permission rights +Scope | Permission rights ------|------------ List|Manage ## HTTP request -``` +```http POST /_api/web/lists('list-id')/subscriptions ``` @@ -41,7 +38,7 @@ POST /_api/web/lists('list-id')/subscriptions Include the following properties in the request body. -Name | Type | Description +Name | Type | Description -----|------|------------ resource|string|The URL of the list to receive notifications from. notificationUrl|string|The service URL to send notifications to. @@ -75,7 +72,7 @@ Content-Type: application/json { "id": "a8e6d5e6-9f7f-497a-b97f-8ffe8f559dc7", - "expirationDateTime": "2016-04-27T16:17:57Z", + "expirationDateTime": "2016-04-27T16:17:57Z", "notificationUrl": "https://91e383a5.ngrok.io/api/webhook/handlerequest", "resource": "5c77031a-9621-4dfc-bb5d-57803a94e91d" } @@ -83,9 +80,16 @@ Content-Type: application/json ## URL validation -Before a new subscription is created, SharePoint sends a request with a validation token in the body of the request to the service URL provided. Your service must respond to this request by returning the validation token. +> [!IMPORTANT] +> Before a new subscription is created, SharePoint sends a request with a validation token in the querystring of the request to the notification URL provided. Your service must respond to this request by returning the validation token. If your service fails to validate the request in this way, the subscription is not created.** -If your service fails to validate the request in this way, the subscription is not created. +### Example + +```csharp +{ + return new OkObjectResult(req.Query["validationtoken"].ToString()); +} +``` ## See also diff --git a/docs/apis/webhooks/lists/delete-subscription.md b/docs/apis/webhooks/lists/delete-subscription.md index 5d60d8a5b..397d90237 100644 --- a/docs/apis/webhooks/lists/delete-subscription.md +++ b/docs/apis/webhooks/lists/delete-subscription.md @@ -1,12 +1,9 @@ --- title: Delete a subscription description: Deletes a webhook subscription from a SharePoint list. After deleting the subscription, notifications are no longer delivered. -ms.date: 02/08/2018 -ms.prod: sharepoint -localization_priority: Normal +ms.date: 09/23/2022 +ms.localizationpriority: medium --- - - # Delete a subscription Deletes a webhook subscription from a SharePoint list. After deleting the subscription, notifications are no longer delivered. @@ -19,7 +16,7 @@ The application must have at least edit permissions to the SharePoint list where You must grant the Azure AD app the permissions specified in the following table. A subscription can only be deleted by the Azure AD application that created it. -Application | Permission +Application | Permission ------------|------------ Office 365 SharePoint Online|Read and write items and lists in all site collections. @@ -27,7 +24,7 @@ Office 365 SharePoint Online|Read and write items and lists in all site collecti You must grant the SharePoint Add-in the following permission(s) or higher. A subscription can only be deleted by the SharePoint Add-in that created it. -Scope | Permission rights +Scope | Permission rights ------|------------ List|Manage diff --git a/docs/apis/webhooks/lists/get-subscription.md b/docs/apis/webhooks/lists/get-subscription.md index bb0f36b52..661e9076e 100644 --- a/docs/apis/webhooks/lists/get-subscription.md +++ b/docs/apis/webhooks/lists/get-subscription.md @@ -1,12 +1,9 @@ --- title: Get subscriptions description: Gets one or more webhook subscriptions on a SharePoint list. -ms.date: 02/08/2018 -ms.prod: sharepoint -localization_priority: Normal +ms.date: 09/23/2022 +ms.localizationpriority: medium --- - - # Get subscriptions Gets one or more webhook subscriptions on a SharePoint list. @@ -19,17 +16,17 @@ The application must have at least edit permissions to the SharePoint list where #### If your application is a Microsoft Azure Active Directory (Azure AD) application -You must grant the Azure AD application the permissions specified in the following table. A subscription can only be retrieved by the Azure AD application that created it. +You must grant the Azure AD application the permissions specified in the following table. A subscription can only be retrieved by the Azure AD application that created it. -Application | Permission +Application | Permission ------------|------------ Office 365 SharePoint Online|Read and write items and lists in all site collections. #### If your application is a SharePoint Add-in -You must grant the SharePoint Add-in the following permission(s) or higher. A subscription can only be retrieved by the SharePoint Add-in that created it. +You must grant the SharePoint Add-in the following permission(s) or higher. A subscription can only be retrieved by the SharePoint Add-in that created it. -Scope | Permission rights +Scope | Permission rights ------|------------ List|Manage @@ -39,17 +36,17 @@ The application must have manage list permissions to the SharePoint list where t #### If your application is an Azure AD application -You must grant the Azure AD app the permissions specified in the following table. +You must grant the Azure AD app the permissions specified in the following table. -Application | Permission +Application | Permission ------------|------------ Office 365 SharePoint Online|Have full control of all site collections. #### If your application is a SharePoint Add-in -You must grant the SharePoint Add-in the following permission(s) or higher. +You must grant the SharePoint Add-in the following permission(s) or higher. -Scope | Permission rights +Scope | Permission rights ------|------------ List|Full control @@ -111,7 +108,7 @@ Do not supply a request body for this method. #### Response -This returns a collection of all subscriptions on a SharePoint resource. +This returns a collection of all subscriptions on a SharePoint resource. ```http HTTP/1.1 200 OK diff --git a/docs/apis/webhooks/lists/overview-sharepoint-list-webhooks.md b/docs/apis/webhooks/lists/overview-sharepoint-list-webhooks.md index 0aeab4115..f8d775112 100644 --- a/docs/apis/webhooks/lists/overview-sharepoint-list-webhooks.md +++ b/docs/apis/webhooks/lists/overview-sharepoint-list-webhooks.md @@ -1,19 +1,16 @@ --- title: SharePoint list webhooks description: List webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. -ms.date: 02/08/2018 -ms.prod: sharepoint -localization_priority: Priority +ms.date: 09/23/2022 +ms.localizationpriority: high --- - - # SharePoint list webhooks The SharePoint list webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhooks provide a simple notification pipeline so your application can be aware of changes to a SharePoint list without polling the service. ## Tasks -| Task | HTTP method | +| Task | HTTP method | |-----------------------------------------------------|--------------------------------------------------------| | [Create a new subscription](./create-subscription.md) | `POST /_api/web/lists('list-guid')/subscriptions` | | [Get subscriptions](./get-subscription.md) | `GET /_api/web/lists('list-guid')/subscriptions` | diff --git a/docs/apis/webhooks/lists/update-subscription.md b/docs/apis/webhooks/lists/update-subscription.md index 2b1673568..6ba4aa7a7 100644 --- a/docs/apis/webhooks/lists/update-subscription.md +++ b/docs/apis/webhooks/lists/update-subscription.md @@ -1,33 +1,30 @@ --- title: Update a subscription description: Updates a webhook subscription on a SharePoint list. -ms.date: 02/08/2018 -ms.prod: sharepoint -localization_priority: Normal +ms.date: 09/23/2022 +ms.localizationpriority: medium --- - - # Update a subscription Updates a webhook subscription on a SharePoint list. ## Permissions -The application must have at least edit permissions to the SharePoint list where the subscription will be updated. +The application must have at least edit permissions to the SharePoint list where the subscription will be updated. ### If your application is a Microsoft Azure Active Directory (Azure AD) application You must grant the Azure AD application the permissions specified in the following table. A subscription can only be updated by the Azure AD application that created it. -Application | Permission +Application | Permission ------------|------------ -Office 365 SharePoint Online|Read and write items and lists in all site collections. +Office 365 SharePoint Online|Read and write items and lists in all site collections. ### If your application is a SharePoint Add-in You must grant the SharePoint Add-in the following permission(s) or higher. A subscription can only be updated by the SharePoint Add-in that created it. -Scope | Permission rights +Scope | Permission rights ------|------------ List|Manage @@ -53,11 +50,11 @@ Content-Type: application/json Include the following properties in the request body. -Name | Type | Description +Name | Type | Description -----|------|------------ notificationUrl|string|The service URL to send notifications to. expirationDateTime|date|The date the notification will expire and be deleted. -client-clientState|string|Optional. Opaque string passed back to the client on all notifications.
You can use this for validating notifications or tagging different subscriptions. +clientState|string|Optional. Opaque string passed back to the client on all notifications.
You can use this for validating notifications or tagging different subscriptions. ## Response diff --git a/docs/apis/webhooks/overview-sharepoint-webhooks.md b/docs/apis/webhooks/overview-sharepoint-webhooks.md index ef2ba04a2..190a3a4ea 100644 --- a/docs/apis/webhooks/overview-sharepoint-webhooks.md +++ b/docs/apis/webhooks/overview-sharepoint-webhooks.md @@ -1,27 +1,24 @@ --- title: Overview of SharePoint webhooks description: Build applications that subscribe to receive notifications on specific events that occur in SharePoint. -ms.date: 02/08/2018 -ms.prod: sharepoint -localization_priority: Priority +ms.date: 09/23/2022 +ms.localizationpriority: high --- - - # Overview of SharePoint webhooks SharePoint webhooks enable developers to build applications that subscribe to receive notifications on specific events that occur in SharePoint. When an event is triggered, SharePoint sends an HTTP POST payload to the subscriber. Webhooks are easier to develop and consume than Windows Communication Foundation (WCF) services used by SharePoint Add-in remote event receivers because webhooks are regular HTTP services (web API). -Currently webhooks are only enabled for SharePoint list items. SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. For more information, see [SharePoint list webhooks](./lists/overview-sharepoint-list-webhooks.md). +Currently webhooks are only enabled for SharePoint list items. SharePoint list item webhooks cover the events corresponding to list item changes for a given SharePoint list or a document library. SharePoint webhooks provide a simple notification pipeline so that your application can be aware of changes to a SharePoint list without polling the service. For more information, see [SharePoint list webhooks](./lists/overview-sharepoint-list-webhooks.md). ## Creating webhooks -To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list. +To create a new SharePoint webhook, you add a new subscription to the specific SharePoint resource, such as a SharePoint list. The following information is required for creating a new subscription: - **Resource**. The resource endpoint URL you are creating the subscription for. For example, a SharePoint List API URL. - **Server notification URL**. Your service endpoint URL. SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource. -- **Expiration date**. The expiration date for your subscription. The expiration date should not be more than 180 days. By default, subscriptions are set to expire 180 days from when they are created. +- **Expiration date**. The expiration date for your subscription. The expiration date should not be more than 180 days. By default, subscriptions are set to expire 180 days from when they are created. You can also include the following information if needed: @@ -145,9 +142,9 @@ If an error occurs while sending the notification to your application, SharePoin ## Expiration -Webhook subscriptions are set to expire after 180 days by default if an **expirationDateTime** value is not specified. +Webhook subscriptions are set to expire after 180 days by default if an **expirationDateTime** value is not specified. -You need to set an expiration date when creating the subscription. The expiration date should be less than 180 days. Your application is expected to handle the expiration date according to your application's needs by updating the subscription periodically. +You need to set an expiration date when creating the subscription. The expiration date should be less than 180 days. Your application is expected to handle the expiration date according to your application's needs by updating the subscription periodically. ## Retry mechanism diff --git a/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md b/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md new file mode 100644 index 000000000..1de5d665e --- /dev/null +++ b/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md @@ -0,0 +1,178 @@ +--- +title: Create Azure Functions for SharePoint webhooks using an azd template +description: Use Azure Developer cli (azd) to deploy an Azure function app that connects to your SharePoint Online + tenant, to register and manage webhooks, and process the notifications from SharePoint. +ms.date: 07/07/2025 +ms.localizationpriority: low +--- +# Azure Functions for SharePoint webhooks using azd + +[Azure Developer CLI (azd)](https://aka.ms/azd) is an open-source tool that accelerates provisioning and deploying app resources in Azure. + +This article uses the [Azure function app for SharePoint webhooks public template](https://github.com/Azure-Samples/azd-functions-sharepoint-webhooks) to deploy an Azure function app that connects to your SharePoint Online tenant, to register and manage [webhooks](overview-sharepoint-webhooks.md), and process the notifications from SharePoint. + +## Prerequisites + +- [Node.js 22](https://www.nodejs.org/) +- [Azure Functions Core Tools](/azure/azure-functions/functions-run-local) +- [Azure Developer CLI (azd)](/azure/developer/azure-developer-cli/install-azd) +- An Azure subscription that trusts the same Microsoft Entra ID directory as the SharePoint tenant + +## Permissions required to provision the resources in Azure + +The account running **azd** must have at least the following roles to successfully provision the resources: + +- Azure role **[Contributor](/azure/role-based-access-control/built-in-roles/privileged#contributor)**: To create all the resources needed +- Azure role **[Role Based Access Control Administrator](/azure/role-based-access-control/built-in-roles/privileged#role-based-access-control-administrator)**: To assign roles (to access the storage account and Application Insights) to the managed identity of the function app + +## Deploy the function app in Azure + +1. Run **azd init** from an empty local (root) folder: + + ```console + azd init --template azd-functions-sharepoint-webhooks + ``` + + Enter an environment name, such as **spofuncs-quickstart** when prompted. In **azd**, the environment is used to maintain a unique deployment context for your app. + +1. Open the file **infra/main.parameters.json**, and set the variables `TenantPrefix` and `siteRelativePath` to match your SharePoint tenant. + + Review the article on [Manage environment variables](/azure/developer/azure-developer-cli/manage-environment-variables) to manage the azd's environment variables. + +1. Finally, run the command **azd up** to build the app, provision the resources in Azure and deploy the app package. + +## Grant the function app access to SharePoint Online + +The authentication to SharePoint is done using `DefaultAzureCredential`, so the credential used depends on whether the function app runs locally, or in Azure. + +If you never heard about `DefaultAzureCredential`, you should familiarize yourself with its concept by referring to the section **Use DefaultAzureCredential for flexibility** in [Credential chains in the Azure Identity client library for JavaScript](/azure/developer/javascript/sdk/authentication/credential-chains). + +### Using its managed identity + +`DefaultAzureCredential` will use a managed identity to authenticate to SharePoint. This may be the existing, system-assigned managed identity of the function app service or a user-assigned managed identity. + +This tutorial assumes the system-assigned managed identity is used. + +#### Grant the SharePoint API permission Sites.Selected to the managed identity + +Navigate to your function app in the [Azure portal](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Web%2Fsites/kind/functionapp) > select **Identity** and note the **Object (principal) ID** of the system-assigned managed identity. + +> [!NOTE] +> In this tutorial, it is **d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8**. + +Then, use one of the scripts below to grant this identity the app-only permission **Sites.Selected** on the SharePoint API: + +> [!IMPORTANT] +> The scripts below require at least the delegated permission [`AppRoleAssignment.ReadWrite.All`](/graph/permissions-reference#approleassignmentreadwriteall) (requires admin consent) + +
+
+
+Using the Microsoft Graph PowerShell SDK
+ +```powershell +# This script requires the modules Microsoft.Graph.Authentication, Microsoft.Graph.Applications, Microsoft.Graph.Identity.SignIns, which can be installed with the cmdlet Install-Module below: +# Install-Module Microsoft.Graph.Authentication, Microsoft.Graph.Applications, Microsoft.Graph.Identity.SignIns -Scope CurrentUser -Repository PSGallery -Force +Connect-MgGraph -Scope "Application.Read.All", "AppRoleAssignment.ReadWrite.All" +$managedIdentityObjectId = "d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8" # 'Object (principal) ID' of the managed identity +$scopeName = "Sites.Selected" +$resourceAppPrincipalObj = Get-MgServicePrincipal -Filter "displayName eq 'Office 365 SharePoint Online'" # SPO +$targetAppPrincipalAppRole = $resourceAppPrincipalObj.AppRoles | ? Value -eq $scopeName + +$appRoleAssignment = @{ + "principalId" = $managedIdentityObjectId + "resourceId" = $resourceAppPrincipalObj.Id + "appRoleId" = $targetAppPrincipalAppRole.Id +} +New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $managedIdentityObjectId -BodyParameter $appRoleAssignment | Format-List +``` +
+
+
+#### Grant the managed identity effective access to a SharePoint site
+
+Navigate to the [Enterprise applications](https://entra.microsoft.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/) > Set the **Application type** filter to **Managed Identities** > select your managed identity and note its **Application ID**.
+
+> [!NOTE]
+> In this tutorial, it is **3150363e-afbe-421f-9785-9d5404c5ae34**.
+
+Then, use one of the scripts below to grant it the app-only permission **manage** (minimum required to register a webhook) on a specific SharePoint site:
+
+> [!IMPORTANT]
+> The app registration used to run those scripts must have at least the following permissions:
+>
+> - Delegated permission **Application.ReadWrite.All** in the Graph API (requires admin consent)
+> - Delegated permission **AllSites.FullControl** in the SharePoint API (requires admin consent)
+
+Using az cli in Bash
+ +```bash +managedIdentityObjectId="d3e8dc41-94f2-4b0f-82ff-ed03c363f0f8" # 'Object (principal) ID' of the managed identity +resourceServicePrincipalId=$(az ad sp list --query '[].[id]' --filter "displayName eq 'Office 365 SharePoint Online'" -o tsv) +resourceServicePrincipalAppRoleId="$(az ad sp show --id $resourceServicePrincipalId --query "appRoles[?starts_with(value, 'Sites.Selected')].[id]" -o tsv)" + +az rest --method POST --uri "https://graph.microsoft.com/v1.0/servicePrincipals/${managedIdentityObjectId}/appRoleAssignments" --headers 'Content-Type=application/json' --body "{ 'principalId': '${managedIdentityObjectId}', 'resourceId': '${resourceServicePrincipalId}', 'appRoleId': '${resourceServicePrincipalAppRoleId}' }" +``` +
+
+
+Using PnP PowerShell
+ +[PnP PowerShell](https://pnp.github.io/powershell/cmdlets/Grant-PnPAzureADAppSitePermission.html) + +```powershell +Connect-PnPOnline -Url "https://YOUR_SHAREPOINT_TENANT_PREFIX.sharepoint.com/sites/YOUR_SHAREPOINT_SITE_NAME" -Interactive -ClientId "YOUR_PNP_APP_CLIENT_ID" +Grant-PnPAzureADAppSitePermission -AppId "3150363e-afbe-421f-9785-9d5404c5ae34" -DisplayName "YOUR_FUNC_APP_NAME" -Permissions Manage +``` +
+
+
+## Call the function app
+
+For security reasons, when running in Azure, the function app requires an app key to pass in the query string parameter **code**. The app keys are found in the function app service's **App Keys** keys page.
+
+Most HTTP functions take optional parameters `TenantPrefix` and `siteRelativePath`. If they are not specified, the values in the app's environment variables are used.
+
+Below is a sample script in PowerShell to call the function app:
+
+```powershell
+# Edit those variables to match your environment
+$funchost = "YOUR_FUNC_APP_NAME"
+$code = "YOUR_HOST_KEY"
+$listTitle = "YOUR_SHAREPOINT_LIST"
+$notificationUrl = "https://${funchost}.azurewebsites.net/api/webhooks/service?code=${code}"
+
+# List all the webhooks registered on a list
+Invoke-RestMethod -Method GET -Uri "https://${funchost}.azurewebsites.net/api/webhooks/list?code=${code}&listTitle=${listTitle}"
+
+# Register a webhook in a list
+Invoke-RestMethod -Method POST -Uri "https://${funchost}.azurewebsites.net/api/webhooks/register?code=${code}&listTitle=${listTitle}¬ificationUrl=${notificationUrl}"
+
+# Show this webhook registered on a list
+Invoke-RestMethod -Method GET -Uri "https://${funchost}.azurewebsites.net/api/webhooks/show?code=${code}&listTitle=${listTitle}¬ificationUrl=${notificationUrl}"
+
+# Remove the webhook from a list
+# Step 1: Call the function /webhooks/show to get the webhook id
+$webhookId = $(Invoke-RestMethod -Method GET -Uri "https://${funchost}.azurewebsites.net/api/webhooks/show?code=${code}&listTitle=${listTitle}¬ificationUrl=${notificationUrl}").Id
+# Step 2: Call the function /webhooks/remove and pass the webhook id
+Invoke-RestMethod -Method POST -Uri "https://${funchost}.azurewebsites.net/api/webhooks/remove?code=${code}&listTitle=${listTitle}&webhookId=${webhookId}"
+```
+
+## Cleanup the resources in Azure
+
+You can delete all the resources this project created in Azure, by running the command **azd down**.
+
+Alternatively, you can delete the resource group, that has the azd environment's name by default.
+
+## See also
+
+- [Overview of SharePoint webhooks](overview-sharepoint-webhooks.md)
diff --git a/docs/apis/webhooks/sharepoint-webhooks-using-azure-functions.md b/docs/apis/webhooks/sharepoint-webhooks-using-azure-functions.md
index 7ea7c77c0..967d0e43d 100644
--- a/docs/apis/webhooks/sharepoint-webhooks-using-azure-functions.md
+++ b/docs/apis/webhooks/sharepoint-webhooks-using-azure-functions.md
@@ -1,19 +1,18 @@
---
title: Using Azure Functions with SharePoint webhooks
description: Set up and use Azure Functions for your webhooks to take care of the hosting and scaling of your function.
-ms.date: 05/09/2020
-ms.prod: sharepoint
-localization_priority: Priority
+ms.date: 09/23/2022
+ms.localizationpriority: high
---
-
-
# Using Azure Functions with SharePoint webhooks
-[Azure Functions](https://docs.microsoft.com/azure/azure-functions/functions-overview) offers an easy way to host your SharePoint webhooks: you can add your webhook C# or JavaScript code via the browser, and Azure takes care of the hosting and scaling of your function. This guide shows how to set up and use Azure Functions for your webhooks.
+[Azure Functions](/azure/azure-functions/functions-overview) offers an easy way to host your SharePoint webhooks: you can add your webhook C# or JavaScript code via the browser, and Azure takes care of the hosting and scaling of your function.
+
+This guide shows how to set up and use Azure Functions for your webhooks using the Azure portal. Alternatively, you can refer to article [Create Azure Functions for SharePoint webhooks using an azd template](sharepoint-webhooks-using-azd-template.md), to automate the whole process using an **azd** template.
## Create an Azure Function App
-The first step you need to do is create an Azure Function App, which is a special Azure Web App focused on hosting Azure Functions.
+The first step you need to do is to create an Azure Function App, which is a special Azure Web App focused on hosting Azure Functions.
1. Navigate to [https://portal.azure.com](https://portal.azure.com), search for **function app**. Select **Function App** from the search results.
@@ -63,7 +62,7 @@ In our case, we want this Azure Function to behave as a SharePoint webhook servi
You can achieve this by replacing the default code with the following code:
-```cs
+```csharp
#r "Newtonsoft.Json"
using System.Net;
@@ -226,7 +225,7 @@ We'll need to let SharePoint know what webhook URL we're using. To do so, let's
1. Click **Get function URL**.
- 
+ 
1. Click **Copy** to copy the Azure Function App URL to your clipboard.
diff --git a/docs/apis/webhooks/webhooks-reference-implementation.md b/docs/apis/webhooks/webhooks-reference-implementation.md
index c69946a02..f6285aaf7 100644
--- a/docs/apis/webhooks/webhooks-reference-implementation.md
+++ b/docs/apis/webhooks/webhooks-reference-implementation.md
@@ -1,46 +1,38 @@
---
title: SharePoint webhooks sample reference implementation
-description: This SharePoint Patterns and Practices (PnP) reference implementation shows how you can use SharePoint webhooks in your application.
-ms.date: 02/08/2018
-ms.prod: sharepoint
-localization_priority: Priority
+description: This SharePoint Patterns and Practices (PnP) reference implementation shows how you can use SharePoint webhooks in your application.
+ms.date: 06/05/2024
+ms.localizationpriority: high
---
-
-
# SharePoint webhooks sample reference implementation
The SharePoint Patterns and Practices (PnP) reference implementation shows how you can use SharePoint webhooks in your application. The webhooks are implemented in an enterprise ready manner using various Microsoft Azure components such as Azure Web Jobs, Azure SQL Server, and Azure Storage Queues for asynchronous web job notification handling.
-The reference implementation only works with [SharePoint list webhooks](./lists/overview-sharepoint-list-webhooks.md).
+The reference implementation only works with [SharePoint list webhooks](./lists/overview-sharepoint-list-webhooks.md).
-You can also follow these steps by watching the video on the SharePoint PnP YouTube Channel:
-
-Using m365 cli in Bash
+ +[m365 cli](https://pnp.github.io/cli-microsoft365/cmd/spo/site/site-apppermission-add/) + +```bash +targetapp="3150363e-afbe-421f-9785-9d5404c5ae34" +siteUrl="https://YOUR_SHAREPOINT_TENANT_PREFIX.sharepoint.com/sites/YOUR_SHAREPOINT_SITE_NAME" +m365 spo site apppermission add --appId $targetapp --permission manage --siteUrl $siteUrl +``` ++You can also follow these steps by watching the video on the Microsoft 365 Platform Community (PnP) YouTube Channel: > [!Video https://www.youtube.com/embed/P4a1_EWokwM] -
- **Applies to** Office 365 Multi Tenant (MT). -Microsoft Azure is used to host the various components needed to implement Azure webhooks. +Microsoft Azure is used to host the various components needed to implement SharePoint webhooks. + +Source code and other materials for the reference implementation are available in two flavors: -Source code and other materials for the reference implementation are available in two flavors: - A SharePoint provider-hosted application version -- An Office 365 Azure AD application, which can be found in the [SharePoint developer samples GitHub repository](https://aka.ms/sp-webhooks-sample-reference). +- An Office 365 Azure AD application, which can be found in the [SharePoint developer samples GitHub repository](https://aka.ms/sp-webhooks-sample-reference). ## Deploy the reference implementation -The application shows you how to manage webhooks, specifically for a SharePoint list. It also contains a reference implementation of a webhook service endpoint that you can reuse in your webhook projects. +The application shows you how to manage webhooks, specifically for a SharePoint list. It also contains a reference implementation of a webhook service endpoint that you can reuse in your webhook projects.  ### Deployment guides -- The [SharePoint web hooks reference implementation deployment guide](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/Deployment%20guide.md) lists the deployment steps used to deploy the SharePoint provider-hosted reference implementation. - -- To deploy the Office 365 Azure AD application, use the steps described at [SharePoint web hooks Azure AD reference implementation deployment guide](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List.AzureAD/Deployment%20guide.md), which shows you how to use a Web API function as webhook service. - +- The [SharePoint webhooks reference implementation deployment guide](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/Deployment%20guide.md) lists the deployment steps used to deploy the SharePoint provider-hosted reference implementation. +- To deploy the Office 365 Azure AD application, use the steps described at [SharePoint webhooks Azure AD reference implementation deployment guide](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List.AzureAD/Deployment%20guide.md), which shows you how to use a Web API function as webhook service. - If you're more interested in using Azure Functions, see the [Azure Functions guide](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List.AzureAD/azure%20functions%20guide.md) for more details on how to use Azure Functions in this reference implementation. ### Introduction to webhooks @@ -51,9 +43,9 @@ Webhooks notify your application about changes in SharePoint that the applicatio The reference implementation works with a SharePoint list. To add a webhook to a SharePoint list, your application first creates a webhook subscription by sending a [`POST /_api/web/lists('list-id')/subscriptions`](./lists/create-subscription.md) request. The request includes the following items: -* A payload that identifies the list that you're adding the webhook for. -* The location of your webhook service URL to send the notifications. -* The expiration date of the webhook. +- A payload that identifies the list that you're adding the webhook for. +- The location of your webhook service URL to send the notifications. +- The expiration date of the webhook. After you've requested SharePoint to add your webhook, SharePoint validates that your webhook service endpoint exists. It sends a validation string to your service endpoint. SharePoint expects that your service endpoint returns the validation string within 5 seconds. If this process fails, the webhook creation is canceled. If you've deployed your service, this works and SharePoint returns an HTTP 201 message on the POST request that the application initially sent. The payload in the response contains the ID of the new webhook subscription. @@ -61,7 +53,7 @@ After you've requested SharePoint to add your webhook, SharePoint validates that Take a look at the reference implementation, and you'll see that all webhook CRUD operations are consolidated in the [WebHookManager](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/SharePoint.WebHooks.Common/WebHookManager.cs) class of the **SharePoint.WebHooks.Common** project. Adding a webhook is done by using the **AddListWebHookAsync** method: -```cs +```csharp ///
- When making a call to SharePoint, you need to provide authentication information, and in this case you're using a **Bearer** authentication header with an **access token**. To obtain the access token, intercept the token via an **ExecutingWebRequest** event handler: -```cs +```csharp ClientContext cc = null; // Create SharePoint ClientContext object... @@ -92,7 +82,7 @@ cc.ExecutingWebRequest += Cc_ExecutingWebRequest; // Capture the OAuth access token since we want to reuse that one in our REST requests private void Cc_ExecutingWebRequest(object sender, WebRequestEventArgs e) { - this.accessToken = e.WebRequestExecutor.RequestHeaders.Get("Authorization").Replace("Bearer ", ""); + this.accessToken = e.WebRequestExecutor.RequestHeaders.Get("Authorization").Replace("Bearer ", ""); } ``` @@ -119,14 +109,13 @@ In the previous step, your service endpoint was called, but SharePoint only prov  -You can learn more about the `GetChanges()` implementation in the **ProcessNotification** method in the [ChangeManager](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/SharePoint.WebHooks.Common/ChangeManager.cs) class of the **SharePoint.WebHooks.Common** project. +You can learn more about the `GetChanges()` implementation in the **ProcessNotification** method in the [ChangeManager](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/SharePoint.WebHooks.Common/ChangeManager.cs) class of the **SharePoint.WebHooks.Common** project. To avoid getting the same change repeatedly, it's important that you inform SharePoint from which point you want the changes. This is done by passing a **changeToken**, which also implies that your service endpoint needs to persist the last used **changeToken** so that it can be used the next time the service endpoint is called. The following are some key things to note about changes: - SharePoint does not call your service in real-time: when a change happens on a list that has a webhook, SharePoint queues a webhook callout. Once each minute, this queue is read and the appropriate service endpoints are called. This batching of requests is important. For example, if a bulk upload of 1000 records occurred at once, batching prevents SharePoint from calling your endpoint 1000 times. So your endpoint is only called once, but when you call the `GetChanges()` method, you get 1000 change events that you need to process. - - To guarantee an immediate response, regardless of the number of changes there, it's important that the workload of your service endpoint runs asynchronously. In the reference implementation, we leveraged the power of Azure: the service serializes the incoming payload and stores it in an Azure Storage queue while there's an Azure web job that runs continuously and checks for messages in the queue. When there are messages in the queue, the web job processes them and also executes your logic asynchronously. ## Complete end-to-end flow @@ -136,14 +125,14 @@ The following diagram describes the complete end-to-end webhook flow.  1. Your application creates a webhook subscription. When it does, it gets the current **changeToken** from the list it created the webhook for. -2. Your application persists the **changeToken** in a persistent storage, such as SQL Azure in this case. -3. A change in SharePoint occurs, and SharePoint calls your service endpoint. -4. Your service endpoint serializes the notification request and stores it in a storage queue. -5. Your web job sees the message in the queue and starts your message processing logic. -6. Your message processing logic retrieves the last used change token from the persistent storage. -7. Your message processing logic uses the `GetChanges()`API to determine what changed. -8. The returned changes are processed and now your application performs what it needs to do based on the changes. -9. Finally, the application persists the last retrieved **changeToken** so that next time it does not receive changes that were already processed. +1. Your application persists the **changeToken** in a persistent storage, such as SQL Azure in this case. +1. A change in SharePoint occurs, and SharePoint calls your service endpoint. +1. Your service endpoint serializes the notification request and stores it in a storage queue. +1. Your web job sees the message in the queue and starts your message processing logic. +1. Your message processing logic retrieves the last used change token from the persistent storage. +1. Your message processing logic uses the `GetChanges()`API to determine what changed. +1. The returned changes are processed and now your application performs what it needs to do based on the changes. +1. Finally, the application persists the last retrieved **changeToken** so that next time it does not receive changes that were already processed. ## Work with webhook renewal @@ -155,14 +144,14 @@ When your service receives a notification, it also gets information about the su ### Reliable but more complex model -Create a web job that on a weekly basis reads all the subscription IDs from the persistent storage. One-by-one extend the found subscriptions each time. +Create a web job that on a weekly basis reads all the subscription IDs from the persistent storage. One-by-one extend the found subscriptions each time. > [!NOTE] > This web job is not part of this reference implementation. -The actual renewal of a SharePoint list webhook can be done by using a [`PATCH /_api/web/lists('list-id')/subscriptions(‘subscriptionID’)`](./lists/update-subscription.md) REST call. +The actual renewal of a SharePoint list webhook can be done by using a [`PATCH /_api/web/lists('list-id')/subscriptions(‘subscriptionID’)`](./lists/update-subscription.md) REST call. -In the reference implementation, updating of webhooks is implemented in the [WebHookManager](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/SharePoint.WebHooks.Common/WebHookManager.cs) class of the **SharePoint.WebHooks.Common** project. +In the reference implementation, updating of webhooks is implemented in the [WebHookManager](https://github.com/SharePoint/sp-dev-samples/blob/master/Samples/WebHooks.List/SharePoint.WebHooks.Common/WebHookManager.cs) class of the **SharePoint.WebHooks.Common** project. Updating a webhook is done by using the **UpdateListWebHookAsync** method: @@ -179,7 +168,7 @@ Updating a webhook is done by using the **UpdateListWebHookAsync** method: ///
- -The following example shows how a location field might be used on a current field. - -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/column-formatting.schema.json", - "elmType": "div", - "style": { - "display": "block" - }, - "children": [ - { - "elmType": "a", - "txtContent": "@currentField.DisplayName", - "attributes": { - "href": "='https://www.bing.com/maps?cp=' + @currentField.Coordinates.Latitude + '~' + @currentField.Coordinates.Longitude + '&lvl=17&sV=2'", - "target": "_blank", - "title": "=@currentField.Coordinates.Latitude + ', ' + @currentField.Coordinates.Longitude" - }, - "style": { - "display": "block" - } - }, - { - "elmType": "div", - "txtContent": "@currentField.Address.Street" - }, - { - "elmType": "div", - "txtContent": "=@currentField.Address.City + ', ' + @currentField.Address.State" - }, - { - "elmType": "div", - "txtContent": "@currentField.Address.CountryOrRegion" - } - ] -} -``` - - -**Lookup fields** - -The lookup field object has the following properties (with example values): - -```JSON -{ - "lookupId": "100", - "lookupValue": "North America", -} -``` - -
- -The following example shows how a lookup field might be used on a current field. - -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", - "elmType": "a", - "txtContent": "@currentField.lookupValue", - "attributes": { - "href": { - "operator": "+", - "operands": [ - "https://contoso.sharepoint.com/teams/Discovery/Lists/Regions/DispForm.aspx?ID=", - "@currentField.lookupId" - ] - }, - "target": "_blank" - } -} -``` - -**Hyperlink fields** - -The hyperlink field object has the following property (with example value): - -```JSON -{ - "desc": "SharePoint Patterns and Practices", -} -``` - -
- -To reference the URL value, use `@currentField`. - -The following example shows how a hyperlink field might be used on a current field. - -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", - "elmType": "a", - "txtContent": "@currentField.desc", - "attributes": { - "href": "@currentField", - "target": "_blank" - } -} -``` - -#### "[$FieldName]" - -The column is formatted within the context of the entire row. You can use this context to reference the values of other fields within the same row by specifying the **internal name** of the field surrounded by square brackets and preceded by a dollar sign: `[$InternalName]`. For example, to get the value of a field with an internal name of "MarchSales", use `[$MarchSales]`. - -If the value of a field is an object, the object's properties can be accessed. For example, to access the "Title" property of a person field named "SalesLead", use "[$SalesLead.title]". - -#### "@currentWeb" - -This will evaluate to the absolute URL for the site. This is equivalent to the `webAbsoluteUrl` value within the page context. This value is only available in SharePoint Online. - -#### "@me" - -This will evaluate to the email address of the current logged in user. - -This field can be used to display the current user's email address, but more likely it will be used within conditions. The following is an example of setting the color for a person field to red when it is equal to the current logged in user and blue otherwise: - -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", - "elmType": "div", - "txtContent": "@currentField.title", - "style": { - "color": { - "operator": "?", - "operands": [ - { - "operator": "==", - "operands": [ - "@me", - "@currentField.email" - ] - }, - "red", - "blue" - ] - } - } -} -``` - -Here's the same sample from above, using the Excel-style expression syntax: - -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", - "elmType": "div", - "txtContent": "@currentField.title", - "style": { - "color": "=if(@me == @currentField.email, 'red', 'blue')" - } -} -``` - -#### "@now" - -This will evaluate to the current date and time. - -#### "@rowIndex" - -This will evaluate to the rendered index of a row within a view. This value is based on render position and will remain consistent based on position even as views are sorted and filtered. Indexes start at 0. This value is only available in SharePoint Online. - -Here's an example of using the value within a view format to apply alternating styles to rows: - -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json", - "additionalRowClass": "=if(@rowIndex % 2 == 0,'ms-bgColor-themeLighter ms-bgColor-themeLight--hover','')" -} -``` - -#### "@window.innerHeight" - -This will evaluate to a number equal to the height of the browser window (in pixels) when the list was rendered. - -#### "@window.innerWidth" - -This will evaluate to a number equal to the width of the browser window (in pixels) when the list was rendered. - -#### Thumbnails - -In a document library, there is a series of tokens that can be used to retrieve the URL to the thumbnail of a file, including: - -- `@thumbnail.small`, `@thumbnail.medium`, and `@thumbnail.large` evaluate to the thumbnail URL in 3 different predefined sizes. -- `@thumbnail.
- -```javascript -RestRequest("/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteDesign", {info:{Title:"Contoso company theme", Description:"Applies standard company theme to site", SiteScriptIds:["89516c6d-9f4d-4a57-ae79-36b0c95a817b"], WebTemplate:"68", IsDefault: true}}); -``` - -### Which default site designs are updated? - -In the previous example, the **WebTemplate** value of `"68"` refers to the SharePoint Online Communication site template. That template contains the following default site designs: - -- Topic -- Showcase -- Blank - -When you apply a new site design, it updates all three default site designs at the same time. - -The SharePoint Online Team site template contains only one default site design named **Team**. In this case, when you apply a default site design, only the **Team** site design is updated. - -## Restore the default site designs - -To restore a site design to the defaults, remove the site design that you applied. In the previous example, if the site design created had the ID `db752673-18fd-44db-865a-aa3e0b28698e`, you would remove it as shown in the following example. - -```powershell -C:\> Remove-SPOSiteDesign db752673-18fd-44db-865a-aa3e0b28698e -``` - -
- -```javascript -RestRequest("/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.DeleteSiteDesign", {id:"db752673-18fd-44db-865a-aa3e0b28698e"}); -``` - -> [!NOTE] -> If you're not sure which site design is the default, run the **Get-SPOSiteDesign** cmdlet. It will list all site designs, and indicates which ones are defaults. - -## See also - -- [SharePoint site design and site script overview](site-design-overview.md) +--- +title: Customize default site templates in SharePoint +description: Customize the default site templates for the SharePoint Team site or Communication site template. +ms.date: 06/28/2022 +ms.localizationpriority: high +--- + +# Customize a default site template + +SharePoint offers several [site templates that are already available](https://support.microsoft.com/office/apply-and-customize-sharepoint-site-templates-39382463-0e45-4d1b-be27-0e96aeec8398). These are the default site templates and they can be modified by using PowerShell or the REST APIs to control the entire site provisioning experience. For example, you can ensure that your company theme is applied to every site that gets created, or you can make sure a logging mechanism always runs regardless of which site template is chosen. + +## Apply a site script to a default site template + +To customize a default site template, apply a new template script using PowerShell **Add-SPOSiteDesign** cmdlet or the **CreateSiteDesign** REST API. Specify the **IsDefault** switch to apply the site template as the default template. + +| Parameter | Value | Site template type | +| :------------------- | :------------------- |:----------------| +| WebTemplate | 64 | Team site template | +| WebTemplate | 1 | Team site (with group creation disabled) | +| WebTemplate | 68 | Communication site template | +| WebTemplate | 69 | Channel site template | + +The following example shows how to use the **IsDefault** switch to apply the Contoso company theme to the default site templates. The site script referenced by ID contains the JSON script to apply the correct theme. + +```powershell +C:\> Add-SPOSiteDesign ` + -Title "Contoso company theme" ` + -WebTemplate "68" ` + -SiteScripts "89516c6d-9f4d-4a57-ae79-36b0c95a817b" ` + -Description "Applies standard company theme to site" ` + -IsDefault +``` + +```javascript +RestRequest("/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteDesign", {info:{Title:"Contoso company theme", Description:"Applies standard company theme to site", SiteScriptIds:["89516c6d-9f4d-4a57-ae79-36b0c95a817b"], WebTemplate:"68", IsDefault: true}}); +``` + +### Which default site templates are updated? + +The default site template for a communication site is the **Topic** template. The default for a team site is the **Team collaboration** template. When you apply a new default site template, it updates the Microsoft-provided default templates. + +## Restore the default site templates + +To restore a site template to the defaults, remove the site template script that you applied. In the previous example, if the site template created had the ID `db752673-18fd-44db-865a-aa3e0b28698e`, you would remove it as shown in the following example. + +```powershell +C:\> Remove-SPOSiteDesign db752673-18fd-44db-865a-aa3e0b28698e +``` + +```javascript +RestRequest("/_api/Microsoft.SharePoint.Utilities.WebTemplateExtensions.SiteScriptUtility.DeleteSiteDesign", {id:"db752673-18fd-44db-865a-aa3e0b28698e"}); +``` + +> [!NOTE] +> If you're not sure which site template is the default, run the **Get-SPOSiteDesign** cmdlet. It will list all site templates, and indicates which ones are defaults. + +## See also + +- [SharePoint site template and site script overview](site-design-overview.md) +- [Browse and customize Microsoft-provided site templates](https://support.microsoft.com/office/apply-and-customize-sharepoint-site-templates-39382463-0e45-4d1b-be27-0e96aeec8398) diff --git a/docs/declarative-customization/formatting-advanced.md b/docs/declarative-customization/formatting-advanced.md new file mode 100644 index 000000000..5a4d79813 --- /dev/null +++ b/docs/declarative-customization/formatting-advanced.md @@ -0,0 +1,376 @@ +--- +title: Advanced formatting concepts +description: Advanced formatting concepts +ms.date: 07/16/2025 +ms.localizationpriority: high +--- +# Advanced formatting concepts + +You can use some of the following features to make your view and column formatting more information-rich and interactive. + +## Create a button to launch a Flow + +The following screenshot shows a list with a Flow button added to the Action column: + + + +You can use column formatting to create buttons that, when selected, run Flows on the corresponding list item. For flows that are [solution-aware](/power-automate/overview-solution-flows), the Flow Launch Panel will be displayed after choosing the button, and you must select Run Flow to start the flow. For flows that aren't solution-aware, the Flow Launch Panel will be displayed after selecting the button, and the Flow will just run. + +To use the sample below, you must substitute the ID of the Flow you want to run. This ID is contained within the `actionParams` property of the `customRowAction` attribute inside the `button` element. + +To obtain the ID of a flow that is solution-aware: + +1. Select **Flow > See your flows** in the SharePoint list where the Flow is configured. +1. If applicable, [switch to the environment](/power-platform/admin/working-with-environments#switch-the-environment) in which the Flow is hosted. +1. Select the Solutions area. +1. Select the solution in which the Flow was created. +1. Filter for Cloud flows and select the Flow you want to run. +1. Select Export > Get flow identifier. +1. Copy the ID. + +To obtain the ID of a flow that isn't solution-aware: + +1. Switch to the environment in which the Flow is hosted. +1. Select the Flow you want to run. +1. Select Export > Get flow identifier. +1. Copy the ID. + + ```JSON + { + "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", + "elmType": "button", + "customRowAction": { + "action": "executeFlow", + "actionParams": "{\"id\": \"edf627d9-20f4-45ba-8bc9-4494bf2ff1be\"}" + }, + "attributes": { + "class": "ms-fontColor-themePrimary ms-fontColor-themeDarker--hover" + }, + "style": { + "border": "none", + "background-color": "transparent", + "cursor": "pointer" + }, + "children": [ + { + "elmType": "span", + "attributes": { + "iconName": "Flow" + }, + "style": { + "padding-right": "6px" + } + }, + { + "elmType": "span", + "txtContent": "Send to Manager" + } + ] + } + ``` + +Additionally, you can use `headerText` and `runFlowButtonText` options within the `actionParams` property to customize portions of the Flow panel itself! See the [button elements](./formatting-syntax-reference.md#customrowaction) portion of the Detailed syntax reference for more details. + +## Custom cards on hover + +The following image shows a list with a custom hover added to a List: + +On hover - Metadata on the column "Status" is made available in view formatting: + + + +On hover - Metadata on the column "Status" is made available in column formatting: + + + +You can use formatting to define a custom callout that can be commissioned user-defined basis, actions like click or hover. + +This example uses `customCardProps`, `openOnEvent`, `directionalHint`, and `isBeakVisible`: + +```JSON +{ + "elmType": "div", + "style": { + "font-size": "12px" + }, + "txtContent": "[$Status]", + "customCardProps": { + "formatter": { + "elmType": "div", + "txtContent": "Define your formatter options inside the customCardProps/formatter property" + }, + "openOnEvent": "hover", + "directionalHint": "bottomCenter", + "isBeakVisible": true, + "beakStyle" : { + "backgroundColor": "white" + } + } +} +``` + +## Default cards on hover + +Users can now have a profile card or a file hover card on formatters too. Some of the things users can now do: + +- Profile card or File Hover card on any column +- Profile card or Hover card with view formatting + +Hover on a filename with formatting with the default file card: + + + +Hover on a person column with formatting with the default Profile card: + + + +This example uses `defaultHoverField`: + +```JSON +{ + "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", + "elmType": "div", + "children": [ + { + "elmType": "img", + "style": { + "width": "32px", + "height": "32px", + "overflow": "hidden", + "border-radius": "50%", + "margin": "2px" + }, + "attributes": { + "src": "=getUserImage([$Editor.email], 's')", + "title": "[$Editor.title]" + } + }, + { + "elmType": "span", + "style": { + "vertical-align": "middle", + "margin-left": "2px" + }, + "txtContent": "[$Editor.title]" + } + ], + "defaultHoverField": "[$Editor]" +} +``` + +## Column formatter reference + +Users can refer to a column's formatter JSON inside another column/view formatter and use it along with other elements to build a custom column visualization. This can be done by using `columnFormatterReference` property. + +The following image shows a list with a Gallery layout referencing the Category column formatter: + + + + + +``` JSON +{ + "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/tile-formatting.schema.json", + "height": 127, + "width": 254, + "hideSelection": false, + "formatter": { + "elmType": "div", + "attributes": { + "class": "sp-card-container" + }, + "children": [ + { + "elmType": "button", + "attributes": { + "class": "sp-card-defaultClickButton" + }, + "customRowAction": { + "action": "defaultClick" + } + }, + { + "elmType": "div", + "attributes": { + "class": "ms-bgColor-white sp-css-borderColor-neutralLight sp-card-borderHighlight sp-card-subContainer" + }, + "children": [ + { + "elmType": "div", + "attributes": { + "class": "sp-card-displayColumnContainer" + }, + "children": [ + { + "elmType": "p", + "attributes": { + "class": "ms-fontColor-neutralSecondaryAlt sp-card-label" + }, + "txtContent": "[!Title.DisplayName]" + }, + { + "elmType": "p", + "attributes": { + "title": "[$Title]", + "class": "ms-fontColor-neutralPrimary sp-card-content sp-card-highlightedContent" + }, + "txtContent": "=if ([$Title] == '', '–', [$Title])" + } + ] + }, + { + "elmType": "div", + "attributes": { + "class": "sp-card-lastTextColumnContainer" + }, + "children": [ + { + "elmType": "p", + "attributes": { + "class": "ms-fontColor-neutralSecondaryAlt sp-card-label" + }, + "txtContent": "[!Category.DisplayName]" + }, + { + "elmType": "div", + "attributes": { + "class": "sp-card-content" + }, + "style": { + "height": "32px", + "font-size":"12px" + }, + "children": [ + { + "columnFormatterReference": "[$Category]" + } + ] + } + ] + } + ] + } + ] + } +} +``` + +## Inline Editing + +With inline editing, formatters have the ability to load field editors to edit field data on an item. +Users need to have edit permissions on the list item, and the field type should belong to a set of supported types for this feature to work. + +A special JSON property `inlineEditField` is used with value as the field internal name __`[$FieldName]`__ at the target element in the JSON. + +```json +{ + "elmType": "div", + "inlineEditField": "[$FieldName]", + "txtContent": "[$FieldName]" +} +``` + + + +This allows the users to edit items in-place, within the view, without navigating away to grid-based editing or to an item edit form. + +### Supported Field Types + +List of supported field types for inline editing: + +- Single line text +- Multiline text (without RTF) +- Number +- DateTime +- Choice and MultiChoice +- User and Multiuser +- Lookup + +### Hover Borders and Customizations + +The inline editing adds a hover border on the elements to indicate that these elements have an associated action. The default border is `neutralSecondary`, and on click, the editor appears with a `themePrimary` border. These border colors can be overridden via setting style on the same element with `inlineEditField` by using some special attributes - `--inline-editor-border-width`, `--inline-editor-border-style`, `--inline-editor-border-radius`, and `--inline-editor-border-color`. + +```json +{ + "elmType": "div", + "inlineEditField": "[$FieldName]", + "txtContent": "[$FieldName]", + "style": { + "--inline-editor-border-color": "transparent transparent red transparent", + "border-color": "gray", + "border-width": "1px", + "border-style": "solid" + } +} +``` + +## Set multiple field values of an Item using customRowAction + +With the new `setValue` and `customRowAction` properties, formatters can render action buttons that modify the item internally without opening editors or forms. `setValue` also allows setting multiple field values of the item at once. + +The below JSON will set the value of `FieldInternalName_1`, `FieldInternalName_2`, and `FieldInternalName_3`with the values provided: + +```json +{ + "elmType": "div", + "txtContent": "[$FieldName]", + "customRowAction":{ + "action": "setValue", + "actionInput": { + "FieldInternalName_1": "FieldValue_1", + "FieldInternalName_2": "FieldValue_2", + "FieldInternalName_3": "=if([$Status] == 'Completed', 'yes', 'no')" + } + } +} +``` + +### Supported Field Types + +- Single line text +- Multiline text (without RTF) +- Number +- DateTime +- Choice and MultiChoice +- User and Multiuser + +### Value Field values in `actionInput`: + +- Text values: + - a valid string like `"Choice 1"` + - value from other columns: `[$ColumnName]` + - an [expression](./formatting-syntax-reference.md#expressions) such as: + + ``` + "if([$column]> 10, "Choice A", "Choice B")" + ``` + + or + + ``` + {operator: "+", operands" : ["Choice", "A"]} + ``` + +- Number: + - a valid number + - value from other columns: `[$ColumnName]` + - an [expression](./formatting-syntax-reference.md#expressions) +- Date values: + - a date string + - `@now` token + - [expressions](./formatting-syntax-reference.md#expressions) that return a date using built-in date functions + - `addDays` and `addMinutes`, two new functions to support [expressions](./formatting-syntax-reference.md#expressions) like seven days from today + - an empty string `""` clears the field value +- Multi-Choice and Multi-Person: + - Multi-value fields are special, as they need an array value to save multiple values. + - `appendTo`, `removeFrom`, and `replace`, three functions that can operate on multivalue fields. + - `appendTo([$MultiChoiceField], 'MyValue')` + - `removeFrom([$MultiUserField], @me)`: removes all occurrences that match the second parameter + - `replace([$MultiChoiceField], 'Choice 1', 'Choice 3')`: replaces all occurrences of the second parameter with the third. +- Person field values: + - user name or email + - An empty string `""` clears the field value + - an [expression](./formatting-syntax-reference.md#expressions) which returns these values + + > [!NOTE] + > A query runs with the string value provided on the people column, and the first person in the returned results is used. diff --git a/docs/declarative-customization/formatting-syntax-reference.md b/docs/declarative-customization/formatting-syntax-reference.md new file mode 100644 index 000000000..bf3f244cf --- /dev/null +++ b/docs/declarative-customization/formatting-syntax-reference.md @@ -0,0 +1,1229 @@ +--- +title: Formatting syntax reference +description: Formatting syntax reference +ms.date: 02/19/2025 +ms.localizationpriority: high +--- + +# Formatting syntax reference + +## elmType + +Specifies the type of element to create. Valid elements include: + +- `div` +- `span` +- `a` +- [`img`](#img-src-security) +- `svg` +- `path` +- `button` +- `p` +- [`filepreview`](#filepreview) + +Any other value will result in an error. + +### filepreview + +Use the special `elmType` `filepreview` with the `src` attribute set to [`@thumbnail.
- -The previous script creates a new SharePoint list named **Customer Tracking**. It sets the description and adds four fields to the list. Note that each of these are considered an action. Site scripts are limited to 30 cumulative actions (across one or more scripts that may be called in a site design) if applied programmatically using the Invoke-SPOSiteDesign command. If they are applied through the UX or using the Add-SPOSiteDesignTask command then the limit is 300 cumulative actions (or 100K characters). - -## Add the site script - -Each site script must be registered in SharePoint so that it is available to use. Add a new site script by using the **Add-SPOSiteScript** cmdlet. The following example shows how to add the JSON script described previously. - -```powershell -C:\> Add-SPOSiteScript - -Title "Create customer tracking list" - -Content $site_script - -Description "Creates list for tracking customer contact information" -``` - -After running the cmdlet, you get a result that lists the site script **ID** of the added script. Keep track of this ID somewhere because you will need it later when you create the site design. - -The REST API to add a new site script is **CreateSiteScript**. - -## Create the site design - -Next, you need to create the site design. The site design appears in a drop-down list when someone creates a new site from one of the templates. It can run one or more site scripts that have already been added. - -- Run the following cmdlet to add a new site design. Replace `
- -Each action in a site script is specified by a **verb** value in the JSON. In the previous script, the first action is specified by the **applyTheme** verb. Next, the **createSPList** verb creates the list. Notice that the **createSPList** verb contains its own set of verbs that run additional actions on only the list. - -Available actions include: - -- Creating a new list or library (or modifying the default one created with the site) -- Creating site columns, content types, and configuring other list settings -- Set site branding properties like navigation layout, header layout and header background -- Applying a theme -- Setting a site logo -- Adding links to quick launch or hub navigation -- Triggering a Power Automate flow -- Installing a deployed solution from the app catalog -- Setting regional settings for the site -- Adding principals (users and groups) to SharePoint roles -- Setting external sharing capability for the site - -For a complete list of available actions and their parameters, see the [JSON schema](https://docs.microsoft.com/sharepoint/dev/declarative-customization/site-design-json-schema). - -> [!NOTE] -> For libraries and lists, use the PowerShell command [Get-SPOSiteScriptFromList](https://docs.microsoft.com/powershell/module/sharepoint-online/Get-SPOSiteScriptFromList?view=sharepoint-ps) to create the site script syntax from an existing SharePoint list. - -Site scripts can be run again on the same site after provisioning. Site scripts are non-destructive, so when they run again, they ensure that the site matches the configuration in the script. - -For example, if the site already has a list with the same name that the site script is creating, the site script will only add missing fields to the existing list. - -We'd previously capped the limit of site script actions to 30. This remains the limit for scripts applied synchronously using the [Invoke-SPOSiteDesign](https://docs.microsoft.com/powershell/module/sharepoint-online/Invoke-SPOSiteDesign?view=sharepoint-ps) command, but based on customer feedback and support for additional actions we have bumped this limit to 300 actions (or 100,000 characters) when the scripts are applied asynchronously (either through the UI or using the [Add-SPOSiteDesignTask](https://docs.microsoft.com/powershell/module/sharepoint-online/Add-SPOSiteDesignTask?view=sharepoint-ps) command). - -There is also a limit of 100 site scripts and 100 site designs per tenant. - -## Using PowerShell or REST to work with site designs and site scripts - -You can create site designs and site scripts by using PowerShell or the REST API. The following example creates a site script and a site design that uses the site script. - - - -```powershell -C:\> Get-Content 'c:\scripts\site-script.json' ` - -Raw | ` - Add-SPOSiteScript ` - -Title "Contoso theme and list" - -Id : 2756067f-d818-4933-a514-2a2b2c50fb06 -Title : Contoso theme and list -Description : -Content : -Version : 0 - -C:\> Add-SPOSiteDesign ` - -Title "Contoso customer tracking" ` - -WebTemplate "64" ` - -SiteScripts "2756067f-d818-4933-a514-2a2b2c50fb06" ` - -Description "Creates customer list and applies standard theme" -``` - - - -
- -In the previous example, the **Add-SPOSiteScript** cmdlet or **CreateSiteScript** REST API returns a site script id. This is used for the **SiteScripts** parameter in the subsequent call to the **Add-SPOSiteDesign** cmdlet or **CreateSiteDesign** REST API. - -The **WebTemplate** parameter set to the value 64 indicates registering this site design with the Team site template. If you have disabled modern Group creation, then publish your site designs using WebTemplate 1 so that they display for the "Group-less" Team site template. The value 68 would indicate registering with the Communication site template. The **Title** and **Description** parameters are displayed when a user views site designs as they create a new Team site. - -> [!NOTE] -> A site design can run multiple scripts. The script IDs are passed in an array, and they run in the order listed. - -For step-by-step information about creating a site design, see [Get started creating site designs](get-started-create-site-design.md). - -## PnP provisioning and customization using Power Automate - -One action provided by site scripts is the ability to trigger a Power Automate flow. This allows you to specify any custom action that you need beyond the actions provided natively in site scripts. - -If you use the PnP provisioning engine to automate site creation, you can use a Power Automate flow to integrate with site designs. You can maintain all your existing provisioning scripts as well as create new custom provisioning scripts by using this technique. - -
- - - -The process works as follows: - -1. The script instantiates your Power Automate flow using a URL with additional details. - -2. The flow sends a message to an Azure storage queue that you have configured. - -3. The message triggers a call to an Azure function that you have configured. - -4. The Azure function runs your custom script, such as the PnP provisioning engine, to apply your custom configurations. - -For a step-by-step tutorial about how to configure your own Power Automate flow with PnP provisioning, see [Build a complete site design using the PnP provisioning engine](site-design-pnp-provisioning.md). - -## Scoping - -You can configure site designs to only appear for specific groups or people in your organization. This is useful to ensure that people only see the site designs intended for them. For example, you might want the accounting department to only see site designs specifically for them. And the accounting site designs may not make sense to show to anyone else. - -By default, a site design can be viewed by everyone when it is created. Scopes are applied by using the **Grant-SPOSiteDesignRights** cmdlet or the **GrantSiteDesignRights** REST API. You can specify the scope by user or a mail-enabled security group. - -The following example shows how to add Nestor (a user at the fictional Contoso site) view rights on a site design. - -```powershell -Grant-SPOSiteDesignRights ` - -Identity 44252d09-62c4-4913-9eb0-a2a8b8d7f863 ` - -Principals "nestorw@contoso.onmicrosoft.com" ` - -Rights View -``` - - - -For more information about working with scopes, see [Scoping access to site designs](site-design-scoping.md). - -## See also - -- [Get started creating site designs](get-started-create-site-design.md) -- [Apply a scope to your site design](site-design-scoping.md) -- [Site design JSON schema](site-design-json-schema.md) -- [PowerShell cmdlets for SharePoint site designs and site scripts](site-design-powershell.md) -- [Site design and site script REST API](site-design-rest-api.md) -- [Site design examples](https://github.com/SharePoint/sp-dev-site-scripts) +--- +title: SharePoint site template and site script overview +description: Use SharePoint site scripts and site templates to provide custom configurations to apply when new sites are created. +ms.date: 01/22/2025 +ms.localizationpriority: high +--- + +# SharePoint site template and site script overview + +> [!NOTE] +> - Site templates and site scripts are currently only supported by SharePoint Online. +> - In previous versions of SharePoint, site templates were called site designs but will be referred to as site templates moving forward. +> - SharePoint has a new site template experience that will be available to all SharePoint users with permission to create SharePoint sites. [Learn more about the new site template experience](https://support.microsoft.com/office/apply-and-customize-sharepoint-site-templates-39382463-0e45-4d1b-be27-0e96aeec8398?ui=en-US&rs=en-US&ad=US). +> - As of today, the site template experience cannot be disabled. +> - Site templates created by your organization and set as the default template will automatically apply when new sites are created but can be updated by the site owner by selecting **Settings** and then **Apply a site template.** +> - Site template version history is not currently available for the new site template experience but will be included in future iterations. + +Use site templates and site scripts to automate the provisioning of new or existing modern SharePoint sites that use your own custom configurations. + +When people in your organization create new SharePoint sites, you often need to ensure some level of consistency. For example, you may need proper branding and theming applied to each new site. You may also have detailed site provisioning scripts, such as using the PnP provisioning engine, that need to be applied each time a new site is created. + +This article describes how you can use site templates and site scripts to provide custom configurations to apply when new sites are created. + +## How site templates work + +Site templates can be used each time a new site is created to apply a consistent set of actions. They can also be applied to existing modern sites (group-connected Team and Communication sites). Most actions typically affect the site itself, such as setting the theme or creating lists. But a site template can also include other actions, such as recording the new site URL to a log or sending a tweet. + +> [!NOTE] +> - Site templates created using custom site scripts will display in the **From your organization** tab in the site template gallery. +> - Custom site templates made by your organization will be displayed in the site template gallery based on the type of site chosen by the user - either a communication site or a team site. Therefore, it is likely users will not see all site templates from your organization in the site template gallery. Soon, users will have the ability to browse all site templates provided by your organization regardless of which type of site was chosen. + +You create site templates and register them in SharePoint to one of the modern template sites: the Team site or the Communication site. You can see how this works in the following steps. + +1. Go to the SharePoint start page on your developer tenant. +1. Choose **Create site**. + + You'll see the two modern template sites: **Team site** and **Communication site**. + +1. Choose the type of site needed. + + - SharePoint will automatically create a communication site using the **Standard communication** site template. + - Had you chosen the default Team site, SharePoint will create a new site using the **Standard team** template. + + For more information about how you can change the default site templates, see [Customize a default site template](customize-default-site-design.md). + +1. Navigate to the **Settings** icon, and select **Apply site template** to review Microsoft-provided site templates based on the type of site you chose in step three. + +When a site template is selected, SharePoint creates the new site and runs site scripts for the site template. The site scripts provide the details for the template such as creating new lists or applying a theme. These script actions are run in the background. When the scripts are complete the page will refresh to display the site script details. + +> [!NOTE] +> Site templates can now be applied to previously created modern site collections. For more information, see the [REST API](site-design-rest-api.md) and [PowerShell](site-design-powershell.md) articles. + +## Anatomy of a site script + +Site scripts are JSON files that specify an ordered list of actions to run when creating the new site. The actions are run in the order listed. + +The following example is a script that has two top-level actions. First, it applies a theme that was previously created named **Contoso Explorers**. It then creates a **Customer Tracking** list. + +```json +{ + "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json", + "actions": [ + { + "verb": "applyTheme", + "themeName": "Contoso Explorers" + }, + { + "verb": "createSPList", + "listName": "Customer Tracking", + "templateType": 100, + "subactions": [ + { + "verb": "setDescription", + "description": "List of Customers and Orders" + }, + { + "verb": "addSPField", + "fieldType": "Text", + "displayName": "Customer Name", + "isRequired": false, + "addToDefaultView": true + }, + { + "verb": "addSPField", + "fieldType": "Number", + "displayName": "Requisition Total", + "addToDefaultView": true, + "isRequired": true + }, + { + "verb": "addSPField", + "fieldType": "User", + "displayName": "Contact", + "addToDefaultView": true, + "isRequired": true + }, + { + "verb": "addSPField", + "fieldType": "Note", + "displayName": "Meeting Notes", + "isRequired": false + } + ] + } + ] +} +``` + +Each action in a site script is specified by a **verb** value in the JSON. In the previous script, the first action is specified by the **applyTheme** verb. Next, the **createSPList** verb creates the list. Notice that the **createSPList** verb contains its own set of verbs that run additional actions on only the list. + +**Available actions include:** + +- Creating a new list or library (or modifying the default one created with the site) +- Creating site columns, content types, and configuring other list settings +- Set site branding properties like navigation layout, header layout, and header background +- Applying a theme** +- Setting a site logo +- Adding links to quick launch or hub navigation** +- Triggering a Power Automate flow +- Installing a deployed solution from the app catalog +- Setting regional settings for the site** +- Adding principals (users and groups) to SharePoint roles** +- Setting external sharing capability for the site** + +For a complete list of available actions and their parameters, see the [JSON schema](site-design-json-schema.md). + +> [!NOTE] +> +> - Actions marked with ** are automatically blocked for [channel sites](/sharepoint/teams-connected-sites). +> - For libraries and lists, use the PowerShell command [Get-SPOSiteScriptFromList](/powershell/module/sharepoint-online/Get-SPOSiteScriptFromList) to create the site script syntax from an existing SharePoint list. + +Site scripts can be run again on the same site after provisioning. They are non-destructive, so when they are run again, they ensure that the site matches the configuration in the script. + +For example, if the site already has a list with the same name that the site script is creating, the site script will only add missing fields to the existing list. + +We'd previously capped the limit of site script actions to 30. This remains the limit for scripts applied synchronously using the [Invoke-SPOSiteDesign](/powershell/module/sharepoint-online/Invoke-SPOSiteDesign) command, but based on customer feedback and support for additional actions we have bumped this limit to 300 actions (or 100,000 characters) when the scripts are applied asynchronously (either through the UI or using the [Add-SPOSiteDesignTask](/powershell/module/sharepoint-online/Add-SPOSiteDesignTask) command). + +There is also a limit of 100 site scripts and 100 site templates per tenant. + +## Using PowerShell or REST to work with site templates and site scripts + +You can create site templates and scripts using PowerShell or the REST API. The following example creates a site script and a site template that uses the script. + + + +```powershell +C:\> Get-Content 'c:\scripts\site-script.json' ` + -Raw | ` + Add-SPOSiteScript ` + -Title "Contoso theme and list" + +Id : 2756067f-d818-4933-a514-2a2b2c50fb06 +Title : Contoso theme and list +Description : +Content : +Version : 0 + +C:\> Add-SPOSiteDesign ` + -Title "Contoso customer tracking" ` + -WebTemplate "64" ` + -SiteScripts "2756067f-d818-4933-a514-2a2b2c50fb06" ` + -Description "Creates customer list and applies standard theme" +``` + +In the previous example, the **Add-SPOSiteScript** cmdlet or **CreateSiteScript** REST API returns a site script ID. This is used for the **SiteScripts** parameter in the subsequent call to the **Add-SPOSiteDesign** cmdlet or **CreateSiteDesign** REST API. + +| Parameter | Value | Site template type | +| :------------------- | :------------------- |:----------------| +| WebTemplate | 64 | Team site template | +| WebTemplate | 1 | Team site (with group creation disabled) | +| WebTemplate | 68 | Communication site template | +| WebTemplate | 69 | Channel site template | + +For step-by-step information about creating a site template, see [Get started creating site templates.](get-started-create-site-design.md) + +> [!NOTE] +> +> - A site template can run multiple scripts. The script IDs are passed in an array, and they run in the order listed. +> - The former term for site templates may still appear in certain cmdlet and script labels as "site design." + +## PnP provisioning and customization using Power Automate + +One action provided by site scripts is the ability to trigger a Power Automate flow. This allows you to specify any custom action that you need beyond the actions provided natively in site scripts. + +If you use the PnP provisioning engine to automate site creation, you can use a Power Automate flow to integrate with site templates. You can maintain all your existing provisioning scripts as well as create new custom provisioning scripts by using this technique. + + + +The process works as follows: + +1. The script instantiates your Power Automate flow using a URL with additional details. +1. The flow sends a message to an Azure storage queue that you have configured. +1. The message triggers a call to an Azure function that you have configured. +1. The Azure function runs your custom script, such as the PnP provisioning engine, to apply your custom configurations. + +For a step-by-step tutorial about how to configure your own Power Automate flow with PnP provisioning, see [Build a complete site template using the PnP provisioning engine](site-design-pnp-provisioning.md). + +## Scoping + +You can configure site templates to only appear for specific groups or people in your organization. This is useful to ensure that people only see the site templates intended for them. For example, you might want the accounting department to only see site templates specifically for them. And the accounting site templates may not make sense to show to anyone else. + +By default, a site template can be viewed by everyone when it is created. Scopes are applied by using the **Grant-SPOSiteDesignRights** cmdlet or the **GrantSiteDesignRights** REST API. You can specify the scope by user or a mail-enabled security group. + +The following example shows how to add Nestor (a user at the fictional Contoso site) view rights on a site template. + +```powershell +Grant-SPOSiteDesignRights ` + -Identity 44252d09-62c4-4913-9eb0-a2a8b8d7f863 ` + -Principals "nestorw@onmicrosoft.com" ` + -Rights View +``` + +For more information about working with scopes, see [Scoping access to site templates](site-design-scoping.md). + +## See also + +- [Get started creating site template](get-started-create-site-design.md) +- [Apply a scope to your site template](site-design-scoping.md) +- [Site template JSON schema](site-design-json-schema.md) +- [PowerShell cmdlets for SharePoint site templates and site scripts](site-design-powershell.md) +- [Site template and site script REST API](site-design-rest-api.md) +- [Site template examples](https://github.com/SharePoint/sp-dev-site-scripts) diff --git a/docs/declarative-customization/site-design-pnp-provisioning.md b/docs/declarative-customization/site-design-pnp-provisioning.md index 7f5f2ffeb..74a7db6ef 100644 --- a/docs/declarative-customization/site-design-pnp-provisioning.md +++ b/docs/declarative-customization/site-design-pnp-provisioning.md @@ -1,13 +1,16 @@ --- title: Calling the PnP provisioning engine from a site script description: Build a complete SharePoint site design using the PnP provisioning engine -ms.date: 07/04/2020 -localization_priority: Priority +ms.date: 08/31/2023 +ms.localizationpriority: high --- # Calling the PnP provisioning engine from a site script -Site designs offer a great way to standardize the look and feel of your site collections. However, you can't do some things with site designs, like add a footer to every page. You can use the PnP provisioning engine to create a template that you can use to provision an Application Customizer to a site. This Application Customizer can then update your page design, for example to register a footer on every page. +> [!NOTE] +> This article uses the newest version of PnP PowerShell that is released in January 2021. As Azure Functions run PowerShell Core, you'll have to use this version of PnP PowerShell in your Azure Function. For more information about this version of PnP PowerShell see https://pnp.github.io/powershell. + +Site designs offer a great way to standardize the look and feel of your site collections. However, you can't do some things with site designs, like add a footer to every page. You can use the PnP provisioning engine to create a template that you can use to provision an Application Customizer to a site. This Application Customizer can then update your page design, for example, to register a footer on every page. This article describes how to create a site design that applies a PnP provisioning template to a site. The template will add an Application Customizer to render a footer. @@ -18,9 +21,9 @@ The steps in this article use the following components: - Azure Queue storage - Azure Functions - A SharePoint Framework (SPFx) solution -- A PnP provisioning template +- A PnP site template - A PnP PowerShell script -- An app ID and app secret with administrative rights on your tenant +- An Azure AD App Registration You'll use these components to trigger the PnP provisioning code after you create the site and apply the site design. @@ -28,41 +31,21 @@ You'll use these components to trigger the PnP provisioning code after you creat ## Set up app-only access to your tenant -To set up app-only access, you need to have two different pages on your tenant—one on the regular site, and the other on your SharePoint administration site. - -1. Go to following URL in your tenant: `https://[yourtenant].sharepoint.com/_layouts/15/appregnew.aspx` (you can go to any site, but for now pick the root site). - -2. Next to the **Client Id** and **Client Secret** fields, choose the **Generate** button. - -3. Enter a title for your app, such as **Site Provisioning**. - -4. In the **App Domain** box, enter **localhost**. +We are going to use authentication with a client id and a certificate in this tutorial. -5. In the **Redirect URI** box, enter **https://localhost**. +1. Create a new self-signed certificate with PnP PowerShell on your computer: -  - -6. Choose **Create**. - -7. Copy the values for **Client Id** and **Client Secret** because you will need them later. - -
- -Next, trust the app, so that it has the appropriate access to your tenant: + ```powershell + Register-PnPAzureADApp -ApplicationName "PnPFlowDemo" -Tenant "contoso.onmicrosoft.com" -DeviceLogin -Out . + ``` -1. Go to `https://[yourtenant]-admin.sharepoint.com/_layouts/appinv.aspx` (notice the `-admin` in the URL). -1. In the **App Id** field, paste the **Client ID** that you copied, and choose **Lookup**. -1. In the **Permission Request XML** field, paste the following XML: + Replace **contoso.onmicrosoft.com** with your tenant. - ```xml -
-You might want to create a new site design and grant rights at the same time, as shown in the next example. +You might want to create a new site template and grant rights at the same time, as shown in the next example. ```powershell Add-SPOSiteDesign ` @@ -47,7 +50,7 @@ Add-SPOSiteDesign ` ## Grant rights to users -The following example shows how to grant view rights on a site design to Nestor (a user at the fictional Contoso site). +The following example shows how to grant view rights on a site template to Nestor (a user at the fictional Contoso site). ```powershell PS C:\> Grant-SPOSiteDesignRights ` @@ -56,7 +59,7 @@ PS C:\> Grant-SPOSiteDesignRights ` -Rights View ``` -## View rights assigned to a site design +## View rights assigned to a site template To view rights, use the **Get-SPOSiteDesignRights** cmdlet. The following example shows how to use this cmdlet and a response in the case where only Nestor has view rights. @@ -70,16 +73,16 @@ DisplayName PrincipalName Rights Nestor Wilke i:0#.f|membership|nestorw@contoso.onmicrosoft.com View ``` -## Revoke rights from a site design +## Revoke rights from a site template -You can revoke rights for any principal. If you revoke view rights for all principles, the site design will again be available to everyone. +You can revoke rights for any principal. If you revoke view rights for all principles, the site template will again be available to everyone. The following example revokes access for the accounting mail-enabled security group and Nestor. ```powershell Revoke-SPOSiteDesignRights ` -Identity db752673-18fd-44db-865a-aa3e0b28698e ` - -Principals ("accounting@contoso.sharepoint.com","nestorw@spdfcontosodemo2.onmicrosoft.com") ` + -Principals ("accounting@contoso.sharepoint.com","nestorw@contoso.onmicrosoft.com") ` ``` ## See also diff --git a/docs/declarative-customization/site-design-trigger-flow-tutorial.md b/docs/declarative-customization/site-design-trigger-flow-tutorial.md index a46038a61..285da5ad0 100644 --- a/docs/declarative-customization/site-design-trigger-flow-tutorial.md +++ b/docs/declarative-customization/site-design-trigger-flow-tutorial.md @@ -1,133 +1,119 @@ --- title: Using site designs and Power Automate to track site creation requests description: Invoke a Power Automate flow using the site script triggerFlow action to capture the site creation event and build a site directory. This tutorial is intended to illustrate a simple example of using site designs and Power Automate. -ms.date: 06/05/2020 -localization_priority: Priority +ms.date: 06/05/2024 +ms.localizationpriority: high --- # Calling Power Automate from a site script Site designs are a powerful extensibility mechanism for customizing - and standardizing - the look and feel of your site collections. One of the script actions - **triggerFlow** - can be used to call custom solutions to apply configurations we don't support natively. Power Automate flows can also be used for business automation - in this case, used with site designs to track the creation of sites! -This article describes how to build a simple site directory using a site design and Power Automate. Whenever a site is created using this site design, details of the site are captured and written to a SharePoint list. +This article describes how to build a simple site directory using a site design and Power Automate. Whenever a site is created using this site design, details of the site are captured and written to a SharePoint list. The steps in this article illustrate the following components: -- A SharePoint list +- A SharePoint list - A site design and a site script - Power Automate -You'll first create the SharePoint list and then it will be referenced in your Power Automate flow - which will be triggered by the site design applied after the site is created. +You'll first create the SharePoint list and then it will be referenced in your Power Automate flow - which will be triggered by the site design applied after the site is created. ## Create your site directory list -You need to first set up the list that will be used to record all the sites created using this site design. +You need to first set up the list that will be used to record all the sites created using this site design. -1. Select a site collection to host your list. +1. Select a site collection to host your list. +1. Create a new list named "Site Directory" +1. Configure the following fields: -2. Create a new list named "Site Directory" - -3. Configure the following fields: - webUrl (Hyperlink or Picture) - webDescription (Single line of text) - creatorName (Single line of text) - creatorEmail (Single line of text) - createdTimeUTC (Single line of text) - ## Create the flow -In order to capture the site creation event and create the corresponding list item, you need to create a flow - which can then be referenced in your site design's site script: +In order to capture the site creation event and create the corresponding list item, you need to create a flow - which can then be referenced in your site design's site script: 1. Go to the [Power Automate](https://flow.microsoft.com) site, sign in, and choose **+ Automated—from blank* at the top of the page. +1. Click **Skip** on the next screen +1. Choose **Search connectors and triggers** to select your trigger +1. Search for **Request**, and then choose **Request - When a HTTP Request is received [PREMIUM]**. **NOTE**: The **Request** trigger is now **PREMIUM** and will therefore require additional licensing. +1. Enter the following JSON as your request body: -2. Click **Skip** on the next screen - -2. Choose **Search connectors and triggers** to select your trigger - -3. Search for **Request**, and then choose **Request - When a HTTP Request is received [PREMIUM]**. **NOTE**: The **Request** trigger is now **PREMIUM** and will therefore require additional licensing. - -4. Enter the following JSON as your request body: - - ```json - { - "type": "object", - "properties": { - "webUrl": { - "type": "string" - }, - "parameters": { - "type": "object", - "properties": { - "event": { - "type": "string" - }, - "product": { - "type": "string" + ```json + { + "type": "object", + "properties": { + "webUrl": { + "type": "string" + }, + "parameters": { + "type": "object", + "properties": { + "event": { + "type": "string" + }, + "product": { + "type": "string" + } } + }, + "webDescription": { + "type": "string" + }, + "creatorName": { + "type": "string" + }, + "creatorEmail": { + "type": ["string", "null"] + }, + "createdTimeUTC": { + "type": "string" } - }, - "webDescription": { - "type": "string" - }, - "creatorName": { - "type": "string" - }, - "creatorEmail": { - "type": "string" - }, - "createdTimeUTC": { - "type": "string" } } - } - ``` - -5. Select **+ New Step**. - -6. Search for **Create item**, and select **SharePoint - Create item**. - -7. Enter the site address where the list above was created. - -8. Select the "Site Directory" list you created in the previous step. - -9. Enter a value for the **Title** field - this will be the same value for each list item. For example: "Contoso Travel: New Project Site Created". - -10. For each field in your list form, add the corresponding element from the Dynamic Content picker. When you are done your action should look something like this: + ``` - +1. Select **+ New Step**. +1. Search for **Create item**, and select **SharePoint - Create item**. +1. Enter the site address where the list above was created. +1. Select the "Site Directory" list you created in the previous step. +1. Enter a value for the **Title** field - this will be the same value for each list item. For example: "Contoso Travel: New Project Site Created". +1. For each field in your list form, add the corresponding element from the Dynamic Content picker. When you are done your action should look something like this: -11. Choose **Save**. This generates the HTTP Post URL that you will need to copy for your site script `triggerFlow` action. +  -14. Choose the first step in your flow ('When an HTTP request is received') and copy the URL. - -15. Save your flow. +1. Choose **Save**. This generates the HTTP Post URL that you will need to copy for your site script `triggerFlow` action. +1. Choose the first step in your flow ('When an HTTP request is received') and copy the URL. +1. Save your flow. ## Create the site design 1. Open PowerShell and make sure that you have the latest [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) installed. +1. Connect to your tenant using **Connect-SPOService**. -2. Connect to your tenant using **Connect-SPOService**. - - ```powershell + ```powershell Connect-SPOService -Url https://[yourtenant]-admin.sharepoint.com - ``` + ``` -3. Now you can get the existing site designs. +1. Now you can get the existing site designs. - ```powershell + ```powershell Get-SPOSiteDesign - ``` + ``` -
+ To create a site design, you first need to create a site script. A site design is a container that refers to one or more site scripts. -To create a site design, you first need to create a site script. A site design is a container that refers to one or more site scripts. +1. Copy the following JSON code to your clipboard and modify it. Set the **url** property to the value that you copied when you created the flow. The URL looks similar to the following: -1. Copy the following JSON code to your clipboard and modify it. Set the `url` property to the value that you copied when you created the flow. The URL looks similar to the following: + ```http + https://prod-27.westus.logic.azure.com:443/workflows/ef7434cf0d704dd48ef5fb6...oke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun + ``` - `https://prod-27.westus.logic.azure.com:443/workflows/ef7434cf0d704dd48ef5fb6...oke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun` - - ```json + ```json { "$schema": "schema.json", "actions": [ @@ -142,25 +128,24 @@ To create a site design, you first need to create a site script. A site design i } ] } - ``` - -2. Select the JSON again and copy it again to your clipboard. + ``` -3. Open PowerShell and enter the following to copy the script into a variable and create the site script: +1. Select the JSON again and copy it again to your clipboard. +1. Open PowerShell and enter the following to copy the script into a variable and create the site script: - ```powershell + ```powershell $script = Get-Clipboard -Raw Add-SPOSiteScript -Title "Site Script to record site creation event" -Content $script Get-SPOSiteScript - ``` + ``` -4. You will see a list of one or more site scripts, including the site script you just created. Select the ID of the site script that you created, and copy it to the clipboard. +1. You will see a list of one or more site scripts, including the site script you just created. Select the ID of the site script that you created, and copy it to the clipboard. +1. Use the following command to create the site design: -5. Use the following command to create the site design: - - ```powershell + ```powershell Add-SPOSiteDesign -Title "Record site creation" -Description "The creation of this site will be recorded in the site directory list" -SiteScripts [Paste the ID of the Site Script here] -WebTemplate "64" - ``` + ``` + > [!NOTE] > The **Add-SPOSiteDesign** cmdlet associates the site design with the Team site. If you want to associate the design with a Communication site, use `-WebTemplate "68"`. @@ -170,9 +155,7 @@ To test the results, create a new site. In your SharePoint tenant, select **Shar Your new site design should show up as a design option. Notice that the site design is applied after the site is created. If you configured it correctly, your flow will be triggered. You can check the run history of the flow to verify that it ran correctly. - ## See also - [SharePoint site design and site script overview](site-design-overview.md) - [Calling the PnP provisioning engine from a site script](site-design-pnp-provisioning.md) - diff --git a/docs/declarative-customization/site-theming/sharepoint-site-theming-csom.md b/docs/declarative-customization/site-theming/sharepoint-site-theming-csom.md index 6daee60ec..a15b25f9c 100644 --- a/docs/declarative-customization/site-theming/sharepoint-site-theming-csom.md +++ b/docs/declarative-customization/site-theming/sharepoint-site-theming-csom.md @@ -1,13 +1,13 @@ --- title: SharePoint site theming - CSOM development -description: The SharePoint client-side object model (CSOM) provides access to the SharePoint object model from code that is running locally or on a different server than SharePoint. -ms.date: 04/19/2018 -localization_priority: Priority +description: The SharePoint client-side object model (CSOM) provides access to the SharePoint object model from code that is running locally or on a different server than SharePoint. +ms.date: 06/28/2022 +ms.localizationpriority: high --- # SharePoint site theming: CSOM development -The SharePoint client-side object model (CSOM) provides access to the SharePoint object model from code that is running locally or on a different server than SharePoint. +The SharePoint client-side object model (CSOM) provides access to the SharePoint object model from code that is running locally or on a different server than SharePoint. ## Prerequisites @@ -20,7 +20,7 @@ You also need to reference the [Microsoft.SharePointOnline.CSOM](https://www.nug ## CSOM code example -The following example shows how to create a __Microsoft.Online.SharePoint.TenantAdministration.Tenant__ object and call the __GetAllTenantThemes__ method to return a list of themes. +The following example shows how to create a __Microsoft.Online.SharePoint.TenantAdministration.Tenant__ object and call the __GetAllTenantThemes__ method to return a list of themes. > [!NOTE] > * The URL used to create the context object includes the _-admin_ suffix because **TenantAdministration** methods work with the admin site. @@ -80,7 +80,7 @@ public class SPOTheme ## Applying a theme -There's currently no supported CSOM API to programmatically apply a theme to a specific site. For information on applying custom themes to individual site collections see [SharePoint site design and site script overview](https://docs.microsoft.com/sharepoint/dev/declarative-customization/site-design-overview) +There's currently no supported CSOM API to programmatically apply a theme to a specific site. For information on applying custom themes to individual site collections see [SharePoint site design and site script overview](/sharepoint/dev/declarative-customization/site-design-overview) ## Methods/properties of the Microsoft.Online.SharePoint.TenantAdministration.Tenant class @@ -92,7 +92,7 @@ Add a theme to the tenant. __Namespace:__ Microsoft.Online.SharePoint.TenantAdministration.Tenant
__Parameters:__ string name, string themeJson
-__Return type:__ ClientResult
__Parameters:__ none
-__Return type:__ ClientObjectList
__Parameters:__ string name, string themeJson
-__Return type:__ ClientResult
__Parameters:__ string name, string themeJson
-__Return type:__ ClientResult
__Parameters:__ none
-__Return type:__ ClientObjectList
__Parameters:__ none
-__Return type:__ ClientResult
__Parameters:__ string name, string themeJson
-__Return type:__ ClientResult
| themeDarker: #751b1e | -black: #000000 | -
| themeDark: #952226 | -neutralDark: #212121 | -
| themeDarkAlt: #c02b30 | -neutralPrimary: #333 | -
| themePrimary: #d13438 | -neutralPrimaryAlt: #3c3c3c | -
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| themeSecondary: #d6494d | -neutralTertiaryAlt: #c8c8c8 | -
| themeTertiary: #ecaaac | -neutralLight: #eaeaea | -
| themeLight: #f6d6d8 | -neutralLighter: #f4f4f4 |
| themeLighter: #faebeb | -neutralLighterAlt: #f8f8f8 | -
| themeLighterAlt: #fdf5f5 | -white: #fff | -
| themeDarker: #6f2d09 | -black: #000000 | -
| themeDark: #8d390b | -neutralDark: #212121 | -
| themeDarkAlt: #b5490f | -neutralPrimary: #333 | -
| themePrimary: #ca5010 | -neutralPrimaryAlt: #3c3c3c | -
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| themeSecondary: #e55c12 | -neutralTertiaryAlt: #c8c8c8 | -
| themeTertiary: #f6b28d | -neutralLight: #eaeaea | -
| themeLight: #fbdac9 | -neutralLighter: #f4f4f4 | -
| themeLighter: #fdede4 | -neutralLighterAlt: #f8f8f8 | -
| themeLighterAlt: #fef6f1 | -white: #fff | -
| themeDarker: #094c23 | -black: #000000 | -
| themeDark: #0c602c | -neutralDark: #212121 | -
| themeDarkAlt: #0f7c39 | -neutralPrimary: #333 | -
| themePrimary: #10893e | -neutralPrimaryAlt: #3c3c3c | -
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| themeSecondary: #14a94e | -neutralTertiaryAlt: #c8c8c8 | -
| themeTertiary: #7aefa7 | -neutralLight: #eaeaea | -
| themeLight: #bff7d5 | -neutralLighter: #f4f4f4 | -
| themeLighter: #dffbea | -neutralLighterAlt: #f8f8f8 | -
| themeLighterAlt: #effdf4 | -white: #fff | -
| themeDarker: #004578 | -black: #000000 | -
| themeDark: #005a9e | -neutralDark: #212121 | -
| themeDarkAlt: #106ebe | -neutralPrimary: #333 | -
| themePrimary: #0078d7 | -neutralPrimaryAlt: #3c3c3c | -
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| themeSecondary: #2b88d8 | -neutralTertiaryAlt: #c8c8c8 | -
| themeTertiary: #71afe5 | -neutralLight: #eaeaea | -
| themeLight: #c7e0f4 | -neutralLighter: #f4f4f4 | -
| themeLighter: #deecf9 | -neutralLighterAlt: #f8f8f8 | -
| themeLighterAlt: #eff6fc | -white: #fff | -
| themeDarker: #27268a | -black: #000000 | -
| themeDark: #3230b0 | -neutralDark: #212121 | -
| themeDarkAlt: #5250cf | -neutralPrimary: #333 | -
| themePrimary: #6b69d6 | -neutralPrimaryAlt: #3c3c3c | -
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| themeSecondary: #7a78da | -neutralTertiaryAlt: #c8c8c8 | -
| themeTertiary: #c1c0ee | -neutralLight: #eaeaea | -
| themeLight: #e1e1f7 | -neutralLighter: #f4f4f4 | -
| themeLighter: #f0f0fb | -neutralLighterAlt: #f8f8f8 | -
| themeLighterAlt: #f8f7fd | -white: #fff | -
| themeDarker: #323130 | -black: #000000 | -
| themeDark: #403e3d | -neutralDark: #212121 | -
| themeDarkAlt: #53504e | -neutralPrimary: #333 | -
| themePrimary: #5d5a58 | -neutralPrimaryAlt: #3c3c3c | -
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| themeSecondary: #6d6a67 | -neutralTertiaryAlt: #c8c8c8 | -
| themeTertiary: #bbb9b8 | -neutralLight: #eaeaea | -
| themeLight: #dfdedd | -neutralLighter: #f4f4f4 | -
| themeLighter: #efeeee | -neutralLighterAlt: #f8f8f8 | -
| themeLighterAlt: #f7f7f7 | -white: #fff | -
| themeDarker: #fff171 | -black: #f8f8f8 | -
| themeDark: #ffed4b | -neutralDark: #f4f4f4 | -
| themeDarkAlt: #ffe817 | -neutralPrimary: #ffffff | -
| themePrimary: #fce100 | -neutralPrimaryAlt: #eaeaea | -
| neutralSecondary: #dadada | -|
| neutralTertiary: #c8c8c8 | -|
| themeSecondary: #e3cc00 | -neutralTertiaryAlt: #6d6d6d | -
| themeTertiary: #6a5f00 | -neutralLight: #3f3f3f | -
| themeLight: #322d00 | -neutralLighter: #313131 | -
| themeLighter: #191700 | -neutralLighterAlt: #282828 | -
| themeLighterAlt: #0d0b00 | -white: #1f1f1f | -
| themeDarker: #6cdfff | -black: #f8f8f8 | -
| themeDark: #44d6ff | -neutralDark: #f4f4f4 | -
| themeDarkAlt: #0ecbff | -neutralPrimary: #ffffff | -
| themePrimary: #00bcf2 | -neutralPrimaryAlt: #eaeaea | -
| neutralSecondary: #dadada | -|
| neutralTertiary: #c8c8c8 | -|
| themeSecondary: #00abda | -neutralTertiaryAlt: #646e8a | -
| themeTertiary: #005066 | -neutralLight: #404759 | -
| themeLight: #002630 | -neutralLighter: #353a49 | -
| themeLighter: #001318 | -neutralLighterAlt: #2e3340 | -
| themeLighterAlt: #00090c | -white: #262a35 | -
+To open the view formatting pane, open the view dropdown and choose **Format current view**.
->[!NOTE]
-> To enable the 'Tile' layout, include `tileProps` property inside the JSON.
+
-To format rows in 'List' or 'Compact List' layout, use the `rowFormatter` or `additionalRowClass` properties. To format entries in 'Tile' layout, use the `formatter` within `tileProps` property.
+The pane will look like the following depending on the current layout:
+ 
-The easiest way to use view formatting is to start from an example and edit it to apply to your specific view. The following sections contain examples that you can copy, paste, and customize for your specific needs. There are also several samples available in the [SharePoint/sp-dev-list-formatting repository](https://github.com/SharePoint/sp-dev-list-formatting).
-
-## Apply conditional classes
-
-You can use view formatting to apply one or more classes to the entire list view row depending on the value of one or more fields in the row. These examples leave the content and structure of list view rows intact.
-
-For a list of recommended classes to use inside view formats, please see the [Style Guidelines section](https://docs.microsoft.com/sharepoint/dev/declarative-customization/column-formatting#style-guidelines) in the [Column Formatting reference document](https://docs.microsoft.com/sharepoint/dev/declarative-customization/column-formatting).
-
-> [!TIP]
-> Using the `additionalRowClass` property to apply classes to list view rows will leave the formatting of individual columns in place. This allows you to combine view formats with column formatting for some powerful visualizations.
-
-### Conditional classes based on a date field
-
-The following image shows a list view with a class applied based on the value of a date column:
-
-
-This example applies the class `sp-field-severity--severeWarning` to a list view row when the item's DueDate is before the current date/time:
-
-```JSON
-{
- "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
- "additionalRowClass": "=if([$DueDate] <= @now, 'sp-field-severity--severeWarning', '')"
-}
-```
-
-### Conditional classes based on the value in a text or choice field
-
-This example was adopted from a column formatting example, [Conditional formatting based on the value in a text or choice field](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/column-samples/text-conditional-format), with some important differences to apply the concept to list view rows. The column formatting example applies both an icon and a class to a column based on the value of `@currentField`. The `additionalRowClass` attribute in view formatting, however, only allows you to specify a class and not an icon. Additionally, since `@currentField` always resolves to the value of the `Title` field when referenced inside a view format, this sample refers to the `Status` field directly (by using the [$Field] syntax inside the additionalRowClass property to determine which class to apply to the row).
-
-```JSON
-{
- "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
- "additionalRowClass": "=if([$Status] == 'Done', 'sp-field-severity--good', if([$Status] == 'In progress', 'sp-field-severity--low' ,if([$Status] == 'In review','sp-field-severity--warning', if([$Status] == 'Has issues','sp-field-severity--blocked', ''))))"
-}
-```
-
-You can find this sample with additional details here: [Conditional formatting based on choice field](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/view-samples/text-conditional-format)
-
-## Build custom row layouts
-
-You can use view formatting to define a totally custom layout of field values inside a row using the same syntax used in Column Formatting.
-
-### Multi-line view style
-
-The following image shows a list with a custom multi-line view style applied:
-
-
-This example uses the `rowFormatter` element, which totally overrides the rendering of a list view row. The `rowFormatter` in this example creates a bounding `` box for every list view row. Inside this bounding box, the `$Title` and `$Feedback` fields are displayed on separate lines. Under those fields, a `button` element is displayed that, when clicked, does the same thing as clicking the list row in an uncustomized view, which is opening the property form for the item. This `button` is displayed conditionally, when the value of the `$Assigned_x0020_To` field (assumed to be a person/group field) matches the current signed-in user:
-
-```JSON
-{
- "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
- "hideSelection": true,
- "hideColumnHeader": true,
- "rowFormatter": {
- "elmType": "div",
- "attributes": {
- "class": "sp-row-card"
- },
- "children": [
- {
- "elmType": "div",
- "style": {
- "text-align": "left"
- },
- "children": [
- {
- "elmType": "div",
- "attributes": {
- "class": "sp-row-title"
- },
- "txtContent": "[$Title]"
- },
- {
- "elmType": "div",
- "attributes": {
- "class": "sp-row-listPadding"
- },
- "txtContent": "[$Feedback]"
- },
- {
- "elmType": "button",
- "customRowAction": {
- "action": "defaultClick"
- },
- "txtContent": "Give feedback",
- "attributes": {
- "class": "sp-row-button"
- },
- "style": {
- "display": {
- "operator": "?",
- "operands": [
- {
- "operator": "==",
- "operands": [
- "@me",
- "[$Assigned_x0020_To.email]"
- ]
- },
- "",
- "none"
- ]
- }
- }
- }
- ]
- }
- ]
- }
-}
-```
-You can find this sample with additional details here: [Multi-line view rendering](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/view-samples/multi-line-view)
-
-
-Similarly, to get the below format in ‘Tile’ layout for the Feedback list, define the formatter within `tileProps`:
-
-
-```JSON
-{
- "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
- "tileProps": {
- "height": "250",
- "width": "350",
- "hideSelection": true,
- "formatter": {
- "elmType": "div",
- "style": {
- "display": "flex",
- "align-items": "stretch",
- "margin-bottom": "16px",
- "min-width": "150px",
- "flex-grow": "1",
- "justify-content": "space-around",
- "padding": "5px"
- },
- "children": [
- {
- "elmType": "div",
- "style": {
- "width": "95%",
- "height": "92%",
- "box-shadow": "0px 1.6px 3.6px 0 #00000024, 0px 0.3px 0.9px 0 #00000024",
- "overflow": "hidden",
- "border-radius": "2px",
- "padding-left": "16px",
- "padding-top": "16px"
- },
- "attributes": {
- "class": "ms-bgColor-neutralLighterAlt"
- },
- "children": [
- {
- "elmType": "div",
- "style": {
- "text-align": "left"
- },
- "children": [
- {
- "elmType": "div",
- "style": {
- "color":"#333333",
- "font-size": "16px",
- "font-weight":"600",
- "margin-bottom":"5px"
- },
- "txtContent": "[$Title]"
- },
- {
- "elmType": "div",
- "style": {
- "color":"#333333",
- "font-size": "14px",
- "line-height":"1.8"
- },
- "attributes": {
- "class": "sp-row-listPadding"
- },
- "txtContent": "[$Feedback]"
- },
- {
- "elmType": "button",
- "customRowAction": {
- "action": "defaultClick"
- },
- "txtContent": "Give feedback",
- "attributes": {
- "class": "sp-row-button"
- },
- "style": {
- "display": {
- "operator": "?",
- "operands": [
- {
- "operator": "==",
- "operands": [
- "@me",
- "[$Assigned_x0020_To.email]"
- ]
- },
- "",
- "none"
- ]
- }
- }
- }
- ]
- }
- ]
- }
- ]
- }
- }
-}
-```
-
-### Alternate Row Formatting based on Modulus
+> [!NOTE]
+> We have simplified the View formatting pane experience to separate out layout specific formatting JSON. With this change, you do not need to add layout specific props like `tileProps` anymore.
-This example applies `% (Mod)` to a list view row with alternate coloring the rows:
+To format rows in 'List' or 'Compact List' layout, select 'List' in 'Choose layout' dropdown in the formatting pane and use the `rowFormatter` or `additionalRowClass` properties. To format cards in 'Gallery' layout, select 'Gallery' in 'Choose layout' dropdown in the formatting pane and use the `formatter` property. To format cards in 'Board' view just use the `formatter` property.
-```JSON
-{
- "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
- "additionalRowClass": "=if(@rowIndex%2==0,'ms-bgColor-themeLight','')"
-}
-```
+The easiest way to use view formatting is to start from an example and edit it to apply to your specific view. The following sections contain examples that you can copy, paste, and customize for your specific needs. There are also several samples available in the [SharePoint/sp-dev-list-formatting repository](https://github.com/SharePoint/sp-dev-list-formatting).
## Creating custom JSON
-Creating custom view formatting JSON from scratch is simple if you understand the schema. To create your own custom column formatting:
-
-1. [Download Visual Studio Code](https://code.visualstudio.com/Download). It's free and fast to download.
-
-2. In Visual Studio Code, create a new file, and save the empty file with a .json file extension.
-
-3. Paste the following lines of code into your empty file.
-
- ```JSON
- {
- "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json"
- }
- ```
-
-You now have validation and autocomplete to create your JSON. You can start adding your JSON after the first line that defines the schema location.
+Creating custom view formatting JSON from scratch is simple if user understands the schema, Monaco Editor is integrated in the formatting pane with pre-filled JSON schema reference to assist in creation of view formatting, Monaco editor has validation and autocomplete to help in crafting right JSON. User can start adding JSON after the first line that defines the schema location.
> [!TIP]
-> At any point, select **Ctrl**+**Space** to have Visual Studio Code offer suggestions for properties and values. For more information, see [Editing JSON with Visual Studio Code](https://code.visualstudio.com/Docs/languages/json).
-
-## Detailed syntax reference
-
-### rowFormatter
-
-Optional element. Specifies a JSON object that describes a list view row format. The schema of this JSON object is identical to the schema of a column format. For details on this schema and its capabilities, see the [Column Format detailed syntax reference](https://docs.microsoft.com/sharepoint/dev/declarative-customization/column-formatting#detailed-syntax-reference). Only valid for 'List' and 'Compact List' layouts.
-
->[!NOTE]
-> Using the `rowFormatter` property will override anything specified in the `additionalRowClass` property. They are mutually exclusive.
-
-#### Differences in behavior between the rowFormatter element and column formatting
-
-Despite sharing the same schema, there are some differences in behavior between elements inside a `rowFormatter` element and those same elements in a column formatting object.
-
- * `@currentField` always resolves to the value of the `Title` field inside a `rowFormatter`.
-
-### additionalRowClass
-
-Optional element. Specifies a CSS class(es) that is applied to the entire row. Supports expressions. Only valid for 'List' and 'Compact List' layouts.
-
-`additionalRowClass` only takes effect when there is no `rowFormatter` element specified. If a `rowFormatter` is specified, then `additionalRowClass` is ignored.
-
-### hideSelection
-
-Optional element. Specifies whether the ability to select rows in the view is disabled or not. *false* is the default behavior inside a list view (meaning selection is visible and enabled). *true* means that users will not be able to select list items.
-
-For list & compact list layout, `hideSelection` only takes effect when there's a `rowFormatter` element specified. If no `rowFormatter` is specified, then `hideSelection` is ignored. For 'Tile' layout, `hideSelection` will only take effect if defined inside `tileProps` properties.
-
-### hideColumnHeader
-
-Optional element. Specifies whether the column headers in the view are hidden or not. *false* is the default behavior inside a list view (meaning column headers will be visible). *true* means that the view will not display column headers.
-
-### tileProps
-
-Optional element. Specifies a JSON object that describes a 'Tile' view format. Elements of this property include:
-- height – defines the height of the card in pixels.
-- width – defines the width of the card in pixels. Can go from height/2 to 3 x height.
-- hideSelection – as defined above
-- formatter – JSON object that defines the layout of tiles. The schema of this JSON object is identical to the schema of a column format (and that of rowFormatter). For details on this schema and its capabilities, see the [Column Format detailed syntax reference](https://docs.microsoft.com/sharepoint/dev/declarative-customization/column-formatting#detailed-syntax-reference).
+> At any point, select **Ctrl**+**Space** for property/value suggestions.
+> [!TIP]
+> You can start from a HTML using [**formatter helper tool**](https://pnp.github.io/List-Formatting/tools/), which can convert HTML and CSS into formatter JSON with inline styles.
+
+## See also
+- [List layout customization](./view-list-formatting.md)
+- [Gallery layout customization](./view-gallery-formatting.md)
+- [Board view customization](./view-gallery-formatting.md)
+- [Group customization syntax reference](./view-group-formatting.md)
+- [Advanced formatting concepts](./formatting-advanced.md)
+- [Formatting syntax reference](./formatting-syntax-reference.md)
diff --git a/docs/declarative-customization/view-gallery-formatting.md b/docs/declarative-customization/view-gallery-formatting.md
new file mode 100644
index 000000000..7eb60a1f5
--- /dev/null
+++ b/docs/declarative-customization/view-gallery-formatting.md
@@ -0,0 +1,366 @@
+---
+title: Format gallery view to customize SharePoint
+description: Customize how gallery views in SharePoint lists and libraries are displayed by constructing a JSON object that describes the elements and the styles to be applied to those elements.
+ms.date: 06/28/2022
+ms.localizationpriority: high
+---
+
+# Gallery layout customizations
+
+## Build custom cards
+
+You can use Gallery **`formatter`** to define a totally custom layout of field values inside a card using the same syntax used in [Column Formatting](column-formatting.md).
+
+### Example: Multi line custom card
+
+The following image shows a customized card in Gallery layout:
+
+
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/tile-formatting.schema.json",
+ "height": "250",
+ "width": "350",
+ "hideSelection": true,
+ "formatter": {
+ "elmType": "div",
+ "style": {
+ "display": "flex",
+ "align-items": "stretch",
+ "margin-bottom": "16px",
+ "min-width": "150px",
+ "flex-grow": "1",
+ "justify-content": "space-around",
+ "padding": "5px"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "width": "95%",
+ "height": "92%",
+ "box-shadow": "0px 1.6px 3.6px 0 #00000024, 0px 0.3px 0.9px 0 #00000024",
+ "overflow": "hidden",
+ "border-radius": "2px",
+ "padding-left": "16px",
+ "padding-top": "16px"
+ },
+ "attributes": {
+ "class": "ms-bgColor-neutralLighterAlt"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "text-align": "left"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "color":"#333333",
+ "font-size": "16px",
+ "font-weight":"600",
+ "margin-bottom":"5px"
+ },
+ "txtContent": "[$Title]"
+ },
+ {
+ "elmType": "div",
+ "style": {
+ "color":"#333333",
+ "font-size": "14px",
+ "line-height":"1.8"
+ },
+ "attributes": {
+ "class": "sp-row-listPadding"
+ },
+ "txtContent": "[$Feedback]"
+ },
+ {
+ "elmType": "button",
+ "customRowAction": {
+ "action": "defaultClick"
+ },
+ "txtContent": "Give feedback",
+ "attributes": {
+ "class": "sp-row-button"
+ },
+ "style": {
+ "display": {
+ "operator": "?",
+ "operands": [
+ {
+ "operator": "==",
+ "operands": [
+ "@me",
+ "[$Assigned_x0020_To.email]"
+ ]
+ },
+ "",
+ "none"
+ ]
+ }
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+
+}
+```
+
+## Build custom group headers
+
+You can use `groupProps` to format group headers with flexibility to add grouped column's data, display name and item count. You can also add group aggregates in the group headers.
+
+### Example: Color coded group header
+
+In the example below we have gallery view with formatted group headers as per column metadata.
+
+
+
+> [!NOTE]
+> Gallery card formatter is skipped in the below JSON for simplicity.
+> The example below also contains line breaks. These have been added to improve the readability of the code.
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/tile-formatting.schema.json",
+ "height": 277,
+ "width": 254,
+ "hideSelection": false,
+ "groupProps": {
+ "headerFormatter": {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "flex-wrap": "wrap",
+ "display": "flex",
+ "box-sizing": "border-box",
+ "padding": "4px 8px 5px 8px",
+ "border-radius": "6px",
+ "align-items": "center",
+ "white-space": "nowrap",
+ "overflow": "hidden",
+ "margin": "1px 4px 4px 1px"
+ },
+ "attributes": {
+ "class": "=if(@group.fieldData == 'California', 'sp-css-backgroundColor-blueBackground37',
+ if(@group.fieldData == 'Chicago', 'sp-css-backgroundColor-successBackground50',
+ if(@group.fieldData == 'New York', 'sp-css-backgroundColor-warningBackground50',
+ if(@group.fieldData == 'Seattle', 'sp-css-backgroundColor-blockingBackground50',
+ if(@group.fieldData == 'Washington DC', 'sp-css-backgroundColor-errorBackground50',
+ 'sp-field-borderAllRegular sp-field-borderAllSolid sp-css-borderColor-neutralSecondary'))))"
+ },
+ "children": [
+ {
+ "elmType": "img",
+ "attributes": {
+ "src": "=if(@group.fieldData == 'California', 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/01/Flag_of_California.svg/1920px-Flag_of_California.svg.png',
+ if(@group.fieldData == 'Chicago', 'https://upload.wikimedia.org/wikipedia/commons/thumb/9/9b/Flag_of_Chicago%2C_Illinois.svg/1920px-Flag_of_Chicago%2C_Illinois.svg.png',
+ if(@group.fieldData == 'New York', 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/ba/Flag_of_New_York_City.svg/2560px-Flag_of_New_York_City.svg.png',
+ if(@group.fieldData == 'Seattle', 'https://upload.wikimedia.org/wikipedia/en/thumb/6/6d/Flag_of_Seattle.svg/1920px-Flag_of_Seattle.svg.png',
+ if(@group.fieldData == 'Washington DC', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d4/Flag_of_the_District_of_Columbia.svg/2560px-Flag_of_the_District_of_Columbia.svg.png', '')))))"
+ },
+ "style": {
+ "max-width": "24px",
+ "max-height": "24px",
+ "margin-top": "2px",
+ "border-radius": "2px"
+ }
+ },
+ {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "span",
+ "style": {
+ "padding": "5px 5px 5px 5px",
+ "font-weight": "500"
+ },
+ "txtContent": {
+ "operator": "+",
+ "operands": [
+ "",
+ "@group.fieldData.displayValue"
+ ]
+ }
+ }
+ ]
+ },
+ {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "display": "flex",
+ "flex-direction": "row",
+ "justify-content": "center"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "txtContent": "='has ' + @group.count + if(@group.count > '1', ' employees', ' employee')",
+ "style": {
+ "font-weight": "500"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+}
+```
+
+### Example: Color coded group header with aggregate
+
+In the example below we have list with formatted group headers and group aggregates.
+
+
+
+In this example the `@aggregates` array is used to display a summary in the group header using `headerFormatter` in `groupProps`.
+
+> [!NOTE]
+> Gallery card formatter is skipped in the below JSON for simplicity.
+> The example below also contains line breaks. These have been added to improve the readability of the code.
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/tile-formatting.schema.json",
+ "height": 277,
+ "width": 254,
+ "hideSelection": false,
+ "fillHorizontally": true,
+ "groupProps": {
+ "headerFormatter": {
+ "debugMode": true,
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "flex-wrap": "wrap",
+ "display": "flex",
+ "box-sizing": "border-box",
+ "padding": "4px 8px 5px 8px",
+ "border-radius": "6px",
+ "align-items": "center",
+ "white-space": "nowrap",
+ "overflow": "hidden",
+ "margin": "1px 4px 4px 1px"
+ },
+ "attributes": {
+ "class": "=if(@group.fieldData == 'California', 'sp-css-backgroundColor-blueBackground37',
+ if(@group.fieldData == 'Chicago', 'sp-css-backgroundColor-successBackground50',
+ if(@group.fieldData == 'New York', 'sp-css-backgroundColor-warningBackground50',
+ if(@group.fieldData == 'Seattle', 'sp-css-backgroundColor-blockingBackground50',
+ if(@group.fieldData == 'Washington DC', 'sp-css-backgroundColor-errorBackground50', 'sp-field-borderAllRegular sp-field-borderAllSolid sp-css-borderColor-neutralSecondary')))))"
+ },
+ "children": [
+ {
+ "elmType": "img",
+ "attributes": {
+ "src": "=if(@group.fieldData == 'California', 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/01/Flag_of_California.svg/1920px-Flag_of_California.svg.png',
+ if(@group.fieldData == 'Chicago', 'https://upload.wikimedia.org/wikipedia/commons/thumb/9/9b/Flag_of_Chicago%2C_Illinois.svg/1920px-Flag_of_Chicago%2C_Illinois.svg.png',
+ if(@group.fieldData == 'New York', 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/ba/Flag_of_New_York_City.svg/2560px-Flag_of_New_York_City.svg.png',
+ if(@group.fieldData == 'Seattle', 'https://upload.wikimedia.org/wikipedia/en/thumb/6/6d/Flag_of_Seattle.svg/1920px-Flag_of_Seattle.svg.png',
+ if(@group.fieldData == 'Washington DC', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d4/Flag_of_the_District_of_Columbia.svg/2560px-Flag_of_the_District_of_Columbia.svg.png', '')))))"
+ },
+ "style": {
+ "max-width": "24px",
+ "max-height": "24px",
+ "margin-top": "2px",
+ "border-radius": "2px"
+ }
+ },
+ {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "span",
+ "style": {
+ "padding": "5px 5px 5px 5px",
+ "font-weight": "500"
+ },
+ "txtContent": "@group.fieldData.displayValue"
+ }
+ ]
+ },
+ {
+ "elmType": "div",
+ "forEach": "aggregate in @aggregates",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "display": "=if([$aggregate.columnDisplayName] == 'Approved' && Number([$aggregate.value]) < @group.count, 'flex', 'none')",
+ "flex-direction": "row",
+ "justify-content": "center"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "txtContent": "='has approval pending for ' + Number(@group.count - Number([$aggregate.value])) + if(@group.count - Number([$aggregate.value]) > 1 , ' employees', ' employee')",
+ "style": {
+ "font-weight": "500"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+}
+```
+
+## Detailed syntax reference
+
+### hideSelection
+
+Optional element. Specifies whether the ability to select cards in the view is disabled or not. `false` is the default behavior inside a gallery view (meaning selection is visible and enabled). `true` means that users will not be able to select list items.
+### fillHorizontally
+
+Optional element. Specifies whether the cards in the row should be stretched horizontally to fill the row. `false` is the default behavior (meaning cards in a row are stacked without resizing until they overflow). `true` means cards in the row are stretched horizontally only if necessary to fill the row.
+
+### height
+
+Optional element. Defines the height of the card in pixels.
+
+### width
+
+Optional element. Defines the width of the card in pixels. Can go from height/2 to 3 x height.
+
+### formatter
+
+JSON object that defines the layout of cards. The schema of this JSON object is identical to the schema of a column format (and that of rowFormatter). For details on this schema and its capabilities, see the [Formatting syntax reference](./formatting-syntax-reference.md).
+
+### groupProps
+
+Groups the group related customization options. For details on `groupProps`, see [Group Customization syntax reference](./view-group-formatting.md)
+
+### commandBarProps
+
+Groups the command bar customization options. For details on `commandBarProps`, see [Command bar customization syntax reference](./view-commandbar-formatting.md)
+
+## See also
+- [Group customization syntax reference](./view-group-formatting.md)
+- [Command bar customization syntax reference](./view-commandbar-formatting.md)
+- [Advanced formatting concepts](./formatting-advanced.md)
+- [Formatting syntax reference](./formatting-syntax-reference.md)
diff --git a/docs/declarative-customization/view-group-formatting.md b/docs/declarative-customization/view-group-formatting.md
new file mode 100644
index 000000000..32798d847
--- /dev/null
+++ b/docs/declarative-customization/view-group-formatting.md
@@ -0,0 +1,102 @@
+---
+title: Group customization syntax reference
+description: Group customization syntax reference
+ms.date: 06/28/2022
+ms.localizationpriority: high
+---
+
+# Group customization syntax reference
+
+## groupProps
+
+Groups the group related customization options. Valid in 'List', 'Compact List' and 'Gallery' layouts.
+
+## headerFormatter
+
+JSON object that defines the format for group header. The schema of this JSON object is identical to the schema of a column format. For details on this schema and its capabilities, see the [Formatting syntax reference](./formatting-syntax-reference.md). Valid in 'List', 'Compact List' and 'Gallery' layouts.
+
+## footerFormatter
+
+JSON object that defines the format for group and list footer. The schema of this JSON object is identical to the schema of a column format (and that of rowFormatter). For details on this schema and its capabilities, see the [Formatting syntax reference](./formatting-syntax-reference.md). Valid in 'List' and 'Compact List' layouts.
+
+## hideFooter
+
+Optional element. Specifies whether the list footers or the group footers in the view are hidden or not. `false` is the default behavior (meaning footer is visible). `true` means that view will not display footers. Valid in 'List' and 'Compact List' layouts.
+
+For list & compact list layout, `hideFooter` overrides the `footerFormatter`, if present.
+
+## Special string values
+
+The values for `txtContent`, styles, and attributes can be either strings or expression objects. A few special string patterns for retrieving values from group and aggregate are supported.
+
+### "@group"
+
+Provides access to the grouped column's data, display name and item count. Valid in 'List', 'Compact List' and 'Gallery' layouts. Available only inside `groupProps`.
+
+The `@group` object has the following properties (with example values):
+
+```JSON
+{
+ "fieldData": "California",
+ "columnDisplayName": "City",
+ "count": 3
+}
+```
+
+You can also access sub properties for fields with rich data, e.g. People field, as mentioned under [Formatting Special string values](./formatting-syntax-reference.md#special-string-values).
+
+```JSON
+{
+ "fieldData": {
+ "id": "122",
+ "title": "Kalya Tucker",
+ "email": "kaylat@contoso.com",
+ "sip": "kaylat@contoso.com",
+ "picture": "https://contoso.sharepoint.com/kaylat_contoso_com_MThumb.jpg?t=63576928822",
+ "department": "Human Resources",
+ "jobTitle": "HR Manager"
+ },
+ "columnDisplayName": "Author",
+ "count": 5
+}
+```
+
+### "@columnAggregate"
+
+Provides access to the aggregated column's value, display name and aggregate type. Valid in 'List' and 'Compact List' layouts. Available only inside `footerFormatter`.
+
+The `@columnAggregate` object has the following properties (with example values):
+
+```JSON
+{
+ "value": "3",
+ "columnDisplayName": "Approved",
+ "type": "Count"
+}
+```
+
+### "@aggregates"
+
+Provides access to array of aggregated column's value, display name and aggregate type. Valid in 'List', 'Compact List' and 'Gallery' layouts. Available only inside `groupProps`.
+
+The `@aggregates` object has the following properties (with example value), and can be iterated on using for [Formatting forEach](./formatting-syntax-reference.md#foreach) property.
+
+```JSON
+[
+ {
+ "value": "3",
+ "columnDisplayName": "Approved",
+ "type": "Count"
+ },
+ {
+ "value": "1.2",
+ "columnDisplayName": "Growth",
+ "type": "Average"
+ },
+ {
+ "value": "0.33%",
+ "columnDisplayName": "Rate of change",
+ "type": "Variance"
+ }
+]
+```
diff --git a/docs/declarative-customization/view-list-formatting.md b/docs/declarative-customization/view-list-formatting.md
new file mode 100644
index 000000000..42bc48c36
--- /dev/null
+++ b/docs/declarative-customization/view-list-formatting.md
@@ -0,0 +1,474 @@
+---
+title: Format list view to customize SharePoint
+description: Customize how list views in SharePoint lists and libraries are displayed by constructing a JSON object that describes the elements and the styles to be applied to those elements.
+ms.date: 08/10/2022
+ms.localizationpriority: high
+---
+
+# List layout customizations
+
+## Apply conditional classes on rows
+
+You can use **`additionalRowClass`** to apply one or more classes to the entire list row depending on the value of one or more fields in the row. These examples leave the content and structure of list rows intact.
+
+For a list of recommended classes to use inside view formats, please see the [Style guidelines](./column-formatting.md#style-guidelines) in the [Use column formatting to customize SharePoint](column-formatting.md).
+
+> [!TIP]
+> Using the `additionalRowClass` property to apply classes to list rows will leave the formatting of individual columns in place. This allows you to combine view formats with column formatting for some powerful visualizations.
+
+### Example: Conditional classes based on a date field
+
+The following image shows a list layout with a class applied based on the value of a date column:
+
+
+
+This example applies the class `sp-field-severity--severeWarning` to a list row when the item's DueDate is before the current date/time:
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
+ "additionalRowClass": "=if([$DueDate] <= @now, 'sp-field-severity--severeWarning', '')"
+}
+```
+
+### Example: Conditional classes based on the value in a text or choice field
+
+This example was adopted from a column formatting example, [Conditional formatting based on the value in a text or choice field](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/column-samples/text-conditional-format), with some important differences to apply the concept to list rows. The column formatting example applies both an icon and a class to a column based on the value of `@currentField`. The `additionalRowClass` attribute in view formatting, however, only allows you to specify a class and not an icon. Additionally, since `@currentField` always resolves to the value of the `Title` field when referenced inside a view format, this sample refers to the `Status` field directly (by using the [$Field] syntax inside the additionalRowClass property to determine which class to apply to the row).
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
+ "additionalRowClass": "=if([$Status] == 'Done', 'sp-field-severity--good', if([$Status] == 'In progress', 'sp-field-severity--low' ,if([$Status] == 'In review','sp-field-severity--warning', if([$Status] == 'Has issues','sp-field-severity--blocked', ''))))"
+}
+```
+
+You can find this sample with additional details here: [Conditional formatting based on choice field](https://github.com/pnp/list-formatting/tree/master/view-samples/status-rowclass)
+
+### Example: Alternate Row Formatting based on Modulus
+
+This example applies `% (Mod)` to a list row with alternate coloring the rows:
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json",
+ "additionalRowClass": "=if(@rowIndex%2==0,'ms-bgColor-themeLight','')"
+}
+```
+
+## Build custom list rows
+
+You can use **`rowFormatter`** to define a totally custom layout of field values inside a row using the same syntax used in [Column Formatting](column-formatting.md).
+
+### Example: Multi-line view style
+
+The following image shows a list with a custom multi-line view style applied:
+
+
+
+This example uses the `rowFormatter` element, which totally overrides the rendering of a list row. The `rowFormatter` in this example creates a bounding `` box for every list row. Inside this bounding box, the `$Title` and `$Feedback` fields are displayed on separate lines. Under those fields, a `button` element is displayed that, when clicked, does the same thing as clicking the list row in an uncustomized view, which is opening the property form for the item. This `button` is displayed conditionally, when the value of the `$Assigned_x0020_To` field (assumed to be a person/group field) matches the current signed-in user:
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
+ "hideSelection": true,
+ "hideColumnHeader": true,
+ "rowFormatter": {
+ "elmType": "div",
+ "attributes": {
+ "class": "sp-row-card"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "text-align": "left"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "attributes": {
+ "class": "sp-row-title"
+ },
+ "txtContent": "[$Title]"
+ },
+ {
+ "elmType": "div",
+ "attributes": {
+ "class": "sp-row-listPadding"
+ },
+ "txtContent": "[$Feedback]"
+ },
+ {
+ "elmType": "button",
+ "customRowAction": {
+ "action": "defaultClick"
+ },
+ "txtContent": "Give feedback",
+ "attributes": {
+ "class": "sp-row-button"
+ },
+ "style": {
+ "display": {
+ "operator": "?",
+ "operands": [
+ {
+ "operator": "==",
+ "operands": [
+ "@me",
+ "[$Assigned_x0020_To.email]"
+ ]
+ },
+ "",
+ "none"
+ ]
+ }
+ }
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+You can find this sample with additional details here: [Multi-line view rendering](https://github.com/SharePoint/sp-dev-list-formatting/tree/master/view-samples/multi-line-view)
+
+## Build custom group headers and footers
+
+You can use `groupProps` to format group headers with flexibility to add grouped column's data, display name and item count. You can also add group aggregates in the group headers or format it directly in the group footers.
+
+### Example: Color coded group header
+
+In the example below we have list with group headers formatted according to column metadata.
+
+
+
+In this example below, the `headerFormatter` for `groupProps` is used to format the group header and the `@group` is used to access group info.
+
+> [!NOTE]
+> The JSON below contains line breaks. These have been added to improve the readability of the code.
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
+ "groupProps": {
+ "headerFormatter": {
+ "elmType": "div",
+ "style": {
+ "flex-wrap": "wrap",
+ "display": "flex",
+ "box-sizing": "border-box",
+ "padding": "4px 8px 5px 8px",
+ "border-radius": "6px",
+ "align-items": "center",
+ "white-space": "nowrap",
+ "overflow": "hidden",
+ "margin": "1px 4px 4px 1px"
+ },
+ "attributes": {
+ "class": "=if(@group.fieldData == 'California', 'sp-css-backgroundColor-blueBackground37',
+ if(@group.fieldData == 'Chicago', 'sp-css-backgroundColor-successBackground50',
+ if(@group.fieldData == 'New York', 'sp-css-backgroundColor-warningBackground50',
+ if(@group.fieldData == 'Seattle', 'sp-css-backgroundColor-blockingBackground50',
+ if(@group.fieldData == 'Washington DC', 'sp-css-backgroundColor-errorBackground50',
+ 'sp-field-borderAllRegular sp-field-borderAllSolid sp-css-borderColor-neutralSecondary')))))"
+ },
+ "children": [
+ {
+ "elmType": "img",
+ "attributes": {
+ "src": "=if(@group.fieldData == 'California', 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/01/Flag_of_California.svg/1920px-Flag_of_California.svg.png',
+ if(@group.fieldData == 'Chicago', 'https://upload.wikimedia.org/wikipedia/commons/thumb/9/9b/Flag_of_Chicago%2C_Illinois.svg/1920px-Flag_of_Chicago%2C_Illinois.svg.png',
+ if(@group.fieldData == 'New York', 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/ba/Flag_of_New_York_City.svg/2560px-Flag_of_New_York_City.svg.png',
+ if(@group.fieldData == 'Seattle', 'https://upload.wikimedia.org/wikipedia/en/thumb/6/6d/Flag_of_Seattle.svg/1920px-Flag_of_Seattle.svg.png',
+ if(@group.fieldData == 'Washington DC', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d4/Flag_of_the_District_of_Columbia.svg/2560px-Flag_of_the_District_of_Columbia.svg.png', '')))))"
+ },
+ "style": {
+ "max-width": "24px",
+ "max-height": "24px",
+ "margin-top": "2px",
+ "border-radius": "2px"
+ }
+ },
+ {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "span",
+ "style": {
+ "padding": "5px 5px 5px 5px",
+ "font-weight": "500"
+ },
+ "txtContent": "@group.fieldData.displayValue"
+ }
+ ]
+ },
+ {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "display": "flex",
+ "flex-direction": "row",
+ "justify-content": "center"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "txtContent": "='has ' + @group.count + if(@group.count > '1', ' employees', ' employee')",
+ "style": {
+ "font-weight": "500"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+}
+```
+
+### Example: Color coded group header with aggregate
+
+In the example below we have list with group headers formatted with group aggregates.
+
+
+
+In this example the `hideFooter` for `groupProps` is set to `true` - to hide the group footer and the `@aggregates` array is used to display a summary in the group header.
+
+> [!NOTE]
+> The JSON below contains line breaks. These have been added to improve the readability of the code.
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
+ "groupProps": {
+ "hideFooter": true,
+ "headerFormatter": {
+ "elmType": "div",
+ "style": {
+ "flex-wrap": "wrap",
+ "display": "flex",
+ "box-sizing": "border-box",
+ "padding": "4px 8px 5px 8px",
+ "border-radius": "6px",
+ "align-items": "center",
+ "white-space": "nowrap",
+ "overflow": "hidden",
+ "margin": "1px 4px 4px 1px"
+ },
+ "attributes": {
+ "class": "=if(@group.fieldData == 'California', 'sp-css-backgroundColor-blueBackground37',
+ if(@group.fieldData == 'Chicago', 'sp-css-backgroundColor-successBackground50',
+ if(@group.fieldData == 'New York', 'sp-css-backgroundColor-warningBackground50',
+ if(@group.fieldData == 'Seattle', 'sp-css-backgroundColor-blockingBackground50',
+ if(@group.fieldData == 'Washington DC', 'sp-css-backgroundColor-errorBackground50',
+ 'sp-field-borderAllRegular sp-field-borderAllSolid sp-css-borderColor-neutralSecondary')))))"
+ },
+ "children": [
+ {
+ "elmType": "img",
+ "attributes": {
+ "src": "=if(@group.fieldData == 'California', 'https://upload.wikimedia.org/wikipedia/commons/thumb/0/01/Flag_of_California.svg/1920px-Flag_of_California.svg.png',
+ if(@group.fieldData == 'Chicago', 'https://upload.wikimedia.org/wikipedia/commons/thumb/9/9b/Flag_of_Chicago%2C_Illinois.svg/1920px-Flag_of_Chicago%2C_Illinois.svg.png',
+ if(@group.fieldData == 'New York', 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/ba/Flag_of_New_York_City.svg/2560px-Flag_of_New_York_City.svg.png',
+ if(@group.fieldData == 'Seattle', 'https://upload.wikimedia.org/wikipedia/en/thumb/6/6d/Flag_of_Seattle.svg/1920px-Flag_of_Seattle.svg.png',
+ if(@group.fieldData == 'Washington DC', 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d4/Flag_of_the_District_of_Columbia.svg/2560px-Flag_of_the_District_of_Columbia.svg.png', '')))))"
+ },
+ "style": {
+ "max-width": "24px",
+ "max-height": "24px",
+ "margin-top": "2px",
+ "border-radius": "2px"
+ }
+ },
+ {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "span",
+ "style": {
+ "padding": "5px 5px 5px 5px",
+ "font-weight": "500"
+ },
+ "txtContent": "@group.fieldData.displayValue"
+ }
+ ]
+ },
+ {
+ "elmType": "div",
+ "forEach": "aggregate in @aggregates",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "display": "=if([$aggregate.columnDisplayName] == 'Approved' && Number([$aggregate.value]) < @group.count, 'flex', 'none')",
+ "flex-direction": "row",
+ "justify-content": "center"
+ },
+ "children": [
+ {
+ "elmType": "div",
+ "txtContent": "='has approval pending for ' + Number(@group.count - Number([$aggregate.value])) + if(@group.count - Number([$aggregate.value]) > 1 , ' employees', ' employee')",
+ "style": {
+ "font-weight": "500"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+}
+
+```
+
+### Example: Custom group footer
+
+In the example below we have list with group footer formatted according to aggregate value.
+
+
+
+In this example the `footerFormatter` for `groupProps` are used to format the group footer and the `@columnAggregate` is used to access column aggregate.
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
+ "groupProps": {
+ "hideFooter": false,
+ "footerFormatter": {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "div",
+ "attributes": {
+ "iconName": "=if(@columnAggregate.type == 'Average' && @columnAggregate.value < 10, 'SortDown', 'SortUp')"
+ },
+ "style": {
+ "color": "=if(@columnAggregate.type == 'Average' && @columnAggregate.value < 10, '#d13438', '#107c10')",
+ "font-weight": "600",
+ "margin-top": "10px"
+ }
+ },
+ {
+ "elmType": "div",
+ "style": {
+ "color": "=if(@columnAggregate.type == 'Average' && @columnAggregate.value < 10, '#d13438', '#107c10')",
+ "font-weight": "600",
+ "margin-top": "10px",
+ "font-family": "Segoe UI"
+ },
+ "txtContent": "=@columnAggregate.type + ': ' + @columnAggregate.value"
+ }
+ ]
+ }
+ }
+}
+```
+
+## Build custom list footers
+
+You can use `footerFormatter` to format list footer with access to column aggregates.
+
+### Example: Custom list footer
+
+In the example below we have list with formatted footer as per the aggregate value.
+
+
+
+In this example the `footerFormatter` is set to format the list footer and the `@columnAggregate` is used to access column aggregate.
+
+```JSON
+{
+ "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json",
+ "hideFooter": false,
+ "footerFormatter": {
+ "elmType": "div",
+ "attributes": {
+ "class": "ms-fontColor-themePrimary"
+ },
+ "customCardProps": {
+ "formatter": {
+ "elmType": "div",
+ "children": [
+ {
+ "elmType": "div",
+ "style": {
+ "display": "flex"
+ },
+ "txtContent": "=@columnAggregate.type + ' of ' + @columnAggregate.columnDisplayName + ' is ' + @columnAggregate.value"
+ }
+ ],
+ "style": {
+ "height": "10px",
+ "width": "auto",
+ "cursor": "pointer",
+ "font-size": "14px",
+ "padding": "14px"
+ }
+ },
+ "openOnEvent": "hover",
+ "directionalHint": "bottomCenter",
+ "isBeakVisible": true,
+ "beakStyle": {
+ "backgroundColor": "white"
+ }
+ },
+ "txtContent": "View details",
+ "style": {
+ "text-decoration": "none",
+ "cursor": "pointer",
+ "font-size": "16px",
+ "margin-top": "10px"
+ }
+ }
+}
+```
+
+## Detailed syntax reference
+
+### rowFormatter
+
+Optional element. Specifies a JSON object that describes a list row format. The schema of this JSON object is identical to the schema of a column format. For details on this schema and its capabilities, see [Formatting syntax reference](./formatting-syntax-reference.md).
+
+> [!NOTE]
+> Using the `rowFormatter` property will override anything specified in the `additionalRowClass` property. They are mutually exclusive.
+
+#### Differences in behavior between the rowFormatter element and column formatting
+
+Despite sharing the same schema, there are some differences in behavior between elements inside a `rowFormatter` element and those same elements in a column formatting object.
+
+- `@currentField` always resolves to the value of the `Title` field inside a `rowFormatter`.
+
+### additionalRowClass
+
+Optional element. Specifies a CSS class(es) that is applied to the entire row. Supports expressions.
+
+`additionalRowClass` only takes effect when there is no `rowFormatter` element specified. If a `rowFormatter` is specified, then `additionalRowClass` is ignored.
+
+### hideSelection
+
+Optional element. Specifies whether the ability to select rows in the view is disabled or not. `false` is the default behavior inside a list view (meaning selection is visible and enabled). `true` means that users will not be able to select list items.
+
+### hideColumnHeader
+
+Optional element. Specifies whether the column headers in the view are hidden or not. `false` is the default behavior inside a list view (meaning column headers will be visible). `true` means that the view will not display column headers.
+
+### groupProps
+
+Groups the group related customization options. For details on `groupProps`, see [Group Customization syntax reference](./view-group-formatting.md)
+
+### commandBarProps
+
+Groups the command bar customization options. For details on `commandBarProps`, see [Command bar customization syntax reference](./view-commandbar-formatting.md)
+
+## See also
+- [Group customization syntax reference](./view-group-formatting.md)
+- [Command bar customization syntax reference](./view-commandbar-formatting.md)
+- [Advanced formatting concepts](./formatting-advanced.md)
+- [Formatting syntax reference](./formatting-syntax-reference.md)
diff --git a/docs/design/accessibility.md b/docs/design/accessibility.md
index 217609c09..393091803 100644
--- a/docs/design/accessibility.md
+++ b/docs/design/accessibility.md
@@ -1,10 +1,9 @@
---
title: Accessibility in SharePoint web part design
description: Guidelines for adding accessibility to your web part.
-ms.date: 03/22/2018
-localization_priority: Normal
+ms.date: 06/13/2022
+ms.localizationpriority: medium
---
-
# Accessibility in SharePoint web part design
Developing an experience that meets all users' unique visual, hearing, dexterity, cognitive, and speech needs is an important component of SharePoint web part design. Accessible design applies not only to people with disabilities, but also to potential situational impairments. Accessible design is good design.
@@ -15,7 +14,7 @@ All Microsoft products must meet the requirements listed in the [Microsoft Acces
## Making web parts accessible
-The SharePoint Framework provides a structure to help make all web parts accessible. The web part container provides keyboard navigation defaults for the web part toolbar to edit, move, and delete the web part, a method to select the web part, and a keyboard short cut (Ctrl+P) to open the property pane. However, you still need to specify additional keyboard and screen reader navigation for the other aspects of the UI in the web part and in the property pane.
+The SharePoint Framework provides a structure to help make all web parts accessible. The web part container provides keyboard navigation defaults for the web part toolbar to edit, move, and delete the web part, a method to select the web part, and a keyboard short cut (Ctrl+P) to open the property pane. However, you still need to specify additional keyboard and screen reader navigation for the other aspects of the UI in the web part and in the property pane.
In addition, many [Office UI Fabric components](https://developer.microsoft.com/fabric#/components) have built-in support for accessibility options, to make it quick to configure keyboard and screen reader navigation when you use the components in a web part.
@@ -27,9 +26,9 @@ The following image shows keyboard navigation on a web part.
Test your web part first with [Narrator](https://support.microsoft.com/help/22798/windows-10-narrator-get-started) and Microsoft Edge, and then verify the accessibility experience with [JAWS](http://www.freedomscientific.com/Products/Blindness/JAWS).
-Narrator and Microsoft Edge are standards compliant. When you test with that combination, you are more likely to find issues, and you can validate that your site meets accessibility standards.
+Narrator and Microsoft Edge are standards compliant. When you test with that combination, you are more likely to find issues, and you can validate that your site meets accessibility standards.
-JAWS is the market leader in screen readers. JAWS includes features that can improve the accessibility of some websites that aren't as accessible in other screen readers. Therefore, testing in JAWS might not ensure that your site meets all accessibility requirements.
+JAWS is the market leader in screen readers. JAWS includes features that can improve the accessibility of some websites that aren't as accessible in other screen readers. Therefore, testing in JAWS might not ensure that your site meets all accessibility requirements.
You might also want to test for whatever combination of browser and screen reader has the greatest market share for your website.
@@ -45,13 +44,6 @@ Each control is a tab stop. Within a control, the following rules apply:
- For modal surfaces, the last tab stop should be the commit actions.
- For lists, the first tab stop should be the first item in the list, the next should be the commands, and then the navigation, settings, and so on.
-
### Navigation within a control
@@ -92,7 +84,7 @@ Users who have vision impairments rely on screen readers to navigate the site UI
## Alt text and transcripts
-Use alt text to provide descriptions of images that can be consumed by screen readers. This is useful for vision-impaired users who cannot consume information visually. Make sure that your alt text is descriptive, keeping in mind that some readers are relying on a screen reader to access the information conveyed in the image.
+Use alt text to provide descriptions of images that can be consumed by screen readers. This is useful for users who have visual impairments who cannot consume information visually. Make sure that your alt text is descriptive, keeping in mind that some readers are relying on a screen reader to access the information conveyed in the image.
Don't rely only on color to convey meaning; rely on both color and shape.
@@ -100,9 +92,9 @@ To be fully compliant with accessibility standards, include alt text and a compl
## Minimum readable contrast
-A minimum level of contrast is essential to help users with vision impairments consume the content on the page. It is also important to aid readability in low light and glare situations.
+A minimum level of contrast is essential to help users who have visual impairments consume the content on the page. It is also important to aid readability in low light and glare situations.
-The following image shows theme colors on the left and neutral colors on the right.
+The following image shows theme colors on the left and neutral colors on the right.
@@ -162,19 +154,14 @@ The following image shows theme colors on the left and neutral colors on the rig
- ## High contrast Use high contrast colors as a guide for color choices for components and states on the web. Windows computers only have the ability to detect whether a PC is running high contrast or high contrast white. For this reason, use the default high contrast black setting for any high contrast, non-white theme.  - ## See also - [SharePoint themes and colors](themes-colors.md) - [Design a web part](design-a-web-part.md) - [Designing great SharePoint experiences](design-guidance-overview.md) - - - diff --git a/docs/design/authoring-pages.md b/docs/design/authoring-pages.md index 6264e6fe5..49002ad83 100644 --- a/docs/design/authoring-pages.md +++ b/docs/design/authoring-pages.md @@ -1,62 +1,48 @@ --- title: Authoring pages in a SharePoint site description: Author pages using Edit mode, Published mode, and consider the mobile view. -ms.date: 1/23/2018 -localization_priority: Priority +ms.date: 03/08/2023 +ms.localizationpriority: high --- # Authoring pages in a SharePoint site -Authoring pages in SharePoint is a simple process, but it does require some familiarity with the SharePoint environment, as well as an understanding of what and who you are designing the page for. A few basic principles, such as remembering to "Start simple" and "Build on what's working," are valuable things to consider as you start authoring. It's also a good idea to consistently remind yourself of your audience and the goals that you are trying to help them achieve. +Authoring pages in SharePoint is a simple process, but it does require some familiarity with the SharePoint environment, and an understanding of what and who you are designing the page for. A few basic principles, such as remembering to "Start simple" and "Build on what's working," are valuable things to consider as you start authoring. It's also a good idea to consistently remind yourself of your audience and the goals that you're trying to help them achieve. - - -The SharePoint page authoring experience has two modes: +The SharePoint page authoring experience has two modes: - **Edit**. Allows page authors to add and configure web parts to add content to a page. -- **Published**. Allows your team or audience to view content and interact with web parts. +- **Published**. Allows your team or audience to view content and interact with web parts. ## Edit mode -When creating a new page, users have access to the authoring UI to add content to and customize the page content. - -
-
-+When creating a new page, users have access to the authoring UI to add content to and customize the page content. -
+
-+ ### Add hint and Toolbox The add hint is a horizontal line with a plus icon that is visible when a web part is selected and on hover to indicate where page authors can add new web parts to their page. The Toolbox opens when a user selects the plus icon. The Toolbox contains all the web parts that can be added to a page. -
-
-+ ### Toolbar -A vertical toolbar and bounding box is part of the framework for every web part and is provided by the page. Each web part has an edit and delete action in the toolbar. - -
+A vertical toolbar and bounding box is part of the framework for every web part and is provided by the page. Each web part has an edit and delete action in the toolbar.
-+ ### Active and hover states On hover/active, the hint bars are primary blue or the primary theme color for the site. -
-
-+ The bounding box for a web part is gray by default, but picks up the primary blue or primary theme color for the site on hover or when the web part is selected. -
-
-+ ### Contextual edits @@ -64,35 +50,27 @@ Design a WYSIWYG experience for web parts so that users can fill in information  -
- ### Item-level edits UI can change within the web part; for example, text can become a text field, or you can display UI to reorder items or to check off tasks in a web part. You can enable interactive functionality for web parts in edit mode, in read mode, or in both, depending on your design intent.  -
- ### Property panes -Property panes are invoked via the **Edit** icon on the toolbar. Property panes should primarily contain configuration settings that enable or disable features that either show on the page, or make a call to a service to display content. +Property panes are invoked via the **Edit** icon on the toolbar. Property panes should primarily contain configuration settings that enable or disable features that either show on the page, or make a call to a service to display content.  -
- ## Published mode After the page is published, all editing UI is disabled for the viewer or reader of the page. To continue editing the page, the user selects the **Edit** button on the top right corner of the command bar.  -
- ## Mobile view -All SharePoint pages are [responsive](grid-and-responsive-design.md) to allow the content of the page to be viewed on mobile devices. While designing a web part, it is important to understand how the new SharePoint site pages render across different devices. +All SharePoint pages are [responsive](grid-and-responsive-design.md) to allow the content of the page to be viewed on mobile devices. While designing a web part, it's important to understand how the new SharePoint site pages render across different devices.  diff --git a/docs/design/design-a-web-part.md b/docs/design/design-a-web-part.md index a7671229f..72c3a4bc6 100644 --- a/docs/design/design-a-web-part.md +++ b/docs/design/design-a-web-part.md @@ -1,8 +1,8 @@ --- title: Designing a SharePoint web part description: Use three types of property panes to design and develop web parts that fit your business or customer needs. -ms.date: 01/23/2018 -localization_priority: Priority +ms.date: 06/28/2022 +ms.localizationpriority: high --- # Designing a SharePoint web part @@ -57,7 +57,7 @@ Use accordion panes when you need to apply categorization for a complex web part ### Steps pane -Use a steps pane to group properties in multiple steps or pages when you need the web part to be configured in a linear order, or when choices in the first step affect the options that display in the second or third step. +Use a steps pane to group properties in multiple steps or pages when you need the web part to be configured in a linear order, or when choices in the first step affect the options that display in the second or third step. **Step 1 of the steps pane** @@ -67,7 +67,7 @@ In step 1, the back button is disabled and the next button is enabled.
-**Step 2 of the steps pane** +**Step 2 of the steps pane** In step 2, the back and next buttons are enabled. @@ -75,7 +75,7 @@ In step 2, the back and next buttons are enabled.
-**Step 3 of the steps pane** +**Step 3 of the steps pane** In step 3, the next button is disabled and the back button is enabled. @@ -85,5 +85,3 @@ In step 3, the next button is disabled and the back button is enabled. ## See also - [Designing great SharePoint experiences](design-guidance-overview.md) - - diff --git a/docs/design/design-guidance-overview.md b/docs/design/design-guidance-overview.md index 9ff8c935b..1566fe91e 100644 --- a/docs/design/design-guidance-overview.md +++ b/docs/design/design-guidance-overview.md @@ -1,8 +1,8 @@ --- title: Designing great SharePoint experiences description: Create compelling SharePoint experiences and effectively communicate your brand and message to your audience. -ms.date: 1/23/2018 -localization_priority: Priority +ms.date: 06/28/2022 +ms.localizationpriority: high --- # Designing great SharePoint experiences @@ -14,7 +14,7 @@ SharePoint is a platform that delivers content to more than 200,000 organization  -## SharePoint design principles +## SharePoint design principles SharePoint builds on the design principles that shape the Office and Microsoft product families. These principles help the design stay true to our product goals and user needs. @@ -38,7 +38,45 @@ We search for what’s possible beyond today’s way of getting things done. We Accessibility is developing an equal experience for all users that enables individuals to adjust their user experience to meet their unique visual, hearing, dexterity, cognitive, and speech needs. SharePoint believes strongly in providing accessible experiences for everyone, everywhere, and in optimizing our experiences to reflect the needs of all of our customers. - + + +## SharePoint Web UI Kit in Figma + + + +The SharePoint Web UI Kit empowers you to design communication and team sites for desktop, tablet and mobile in Figma. This kit delivers a set of web parts, style options, templates, and detailed guidance so you can quickly design engaging sites and pages in Figma. Figma is a subscription-based application that is the industry standard tool for web design, and provides an alternative to designing sites and pages outside of SharePoint. + +[Access the kit in Figma Community](https://aka.ms/SPWebUIkit) + +[Watch a live demo on YouTube with the product team](https://youtu.be/2UPchEYhuxI?si=x8ZWEBe3YZQL3Dkp) + +### Design without organizational limitations + +This UI kit provides SharePoint users with another tool in their toolbox. While building a page in SharePoint is easy, we wanted to provide the ability to mockup sites and pages. It allows you to explore different design options for your site without the limitation of admin privileges and tenant restrictions, and doesn’t expose organization data. + +Figma mockups provide a quick snapshot of SharePoint updates which business stakeholders can use to plan and make decisions. They can provide appropriate requirements and use this UI kit in collaboration with their design team to iterate in the life cycle of your organization's intranet. + +### Share designs with ease + +This UI kit provides you with page layouts and a selection of web parts to allow you to mockup and share new ideas across organizations and companies. Figma gives you the flexibility of reviewing and sharing your designs without having to spend time and resources creating it in SharePoint. Figma also allows you to download your designs into easy-to-use formats that can be used in documentation and presentations. Learn more at https://www.figma.com/ + +Note that Figma does not build the pages in SharePoint, so once you finalize a design in Figma, you will need to build it in SharePoint. You should evaluate if Figma is the right solution for mocking up sites and pages for SharePoint. + +### Community feedback + +Please tell us what’s missing, what doesn’t work for you, and where your biggest challenges are by leaving a comment on the [Figma SharePoint Web UI kit page](https://aka.ms/SPWebUIkit). + +### Past Tech Community blog posts for each SharePoint Web UI Kit release + +v3.0: [Figma Variables and new components available (v3.0.0) in the SharePoint Web UI Kit](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/figma-variables-and-new-components-available-v3-0-0-in-the/ba-p/4180339) + +v2.2: [SharePoint Web UI Kit - New Figma web part components available (v2.2) and feedback requested](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/sharepoint-web-ui-kit-new-figma-web-part-components-available-v2/ba-p/4031084) + +v2.1: [New web parts available in the SharePoint Web UI kit!](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/new-web-parts-available-in-the-sharepoint-web-ui-kit/ba-p/3956251) + +v2.0: [Updated content for the SharePoint Web UI kit!](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/updated-content-for-the-sharepoint-web-ui-kit/ba-p/3905250) + +v1.0: [Introducing a new SharePoint Web UI kit!](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/introducing-a-new-sharepoint-web-ui-kit/ba-p/3870293) ## See also diff --git a/docs/design/designing-a-web-part-icon.md b/docs/design/designing-a-web-part-icon.md index 9b784b9ce..fd9b128ae 100644 --- a/docs/design/designing-a-web-part-icon.md +++ b/docs/design/designing-a-web-part-icon.md @@ -1,8 +1,8 @@ --- title: Designing a web part icon description: Learn how to design a web part icon that will look great in SharePoint. -ms.date: 08/24/2018 -localization_priority: Normal +ms.date: 06/28/2022 +ms.localizationpriority: medium --- # Designing a SharePoint web part icon @@ -13,13 +13,13 @@ Web part icons are designed to be simple, representative, and symbolic. Every ic ## Grid keyline shapes -Web part icons are displayed at 32x32 px but are designed at twice the size, or 64x64 px. Create icons at 100% to ensure that pixels are accurate. +Web part icons are displayed at 32x32 px but are designed at twice the size, or 64x64 px. Create icons at 100% to ensure that pixels are accurate.  ## Layout -Design icons within the 64x64 px container area. This ensures that the icon renders correctly. +Design icons within the 64x64 px container area. This ensures that the icon renders correctly.  @@ -32,7 +32,7 @@ Not all icons or logos are designed in a perfect square. Use this guide of basic ## Pixel clarity -Try to avoid any icon distortion by snapping your edges to the X and Y coordinates. Use whole numbers when possible. +Try to avoid any icon distortion by snapping your edges to the X and Y coordinates. Use whole numbers when possible.  @@ -49,4 +49,3 @@ Web part icons can contain one color or be full color. Most icons work best when Export icons as SVGs at 64x64 px with transparent backgrounds. You can find the icon grid in the [SharePoint Design toolkit](https://developer.microsoft.com/fabric#/resources). - diff --git a/docs/design/empty-states.md b/docs/design/empty-states.md index 25217f409..dc78df4c2 100644 --- a/docs/design/empty-states.md +++ b/docs/design/empty-states.md @@ -1,13 +1,13 @@ --- title: Empty states for web parts description: The empty state is a visual representation of a web part, pre-configured to a content source like a list or with placeholder content, such as images and text. -ms.date: 4/16/2018 -localization_priority: Normal +ms.date: 06/28/2022 +ms.localizationpriority: medium --- # Empty state of a web part -The empty state is a visual representation of a web part, pre-configured to a content source like a list or with placeholder content, such as images and text. +The empty state is a visual representation of a web part, pre-configured to a content source like a list or with placeholder content, such as images and text. The following web parts have a content source set by default but no content to show for a newly created Communication site (that is, they feature an empty state): @@ -18,7 +18,7 @@ The following web parts have a content source set by default but no content to s - Hero - Image gallery -Empty states are designed to convey the purpose, structure, and layout options of web parts before the web part is configured or content is added. The empty state is also a perfect way to illustrate the vertical rhythm and layout of a page that starts from a template. Empty states behave similarly to fully configured web parts, and reflow to accommodate available space. They should support author-configured web part layouts. +Empty states are designed to convey the purpose, structure, and layout options of web parts before the web part is configured or content is added. The empty state is also a perfect way to illustrate the vertical rhythm and layout of a page that starts from a template. Empty states behave similarly to fully configured web parts, and reflow to accommodate available space. They should support author-configured web part layouts.  @@ -26,9 +26,9 @@ Empty states are different from placeholders in that the latter are meant to be ## Empty state and editing rights -Web parts with empty states can change interaction options and display text depending on the permission level and mode of the page. +Web parts with empty states can change interaction options and display text depending on the permission level and mode of the page. -In the following example (left to right), a person with editing rights sees an empty state of the Events web part in Edit and Read modes. The last image shows a simplified empty state view for page readers that have no editing rights, with a message appropriate to their permission level. +In the following example (left to right), a person with editing rights sees an empty state of the Events web part in Edit and Read modes. The last image shows a simplified empty state view for page readers that have no editing rights, with a message appropriate to their permission level.  @@ -38,7 +38,7 @@ The following are layout options for the Events web part in an empty state. ## Interactions with an empty state -Empty states are designed primarily for people with editing rights and change interaction options based on the current page mode. Authors can manually add content to web parts in the Read mode, such as adding a new event or new news post. +Empty states are designed primarily for people with editing rights and change interaction options based on the current page mode. Authors can manually add content to web parts in the Read mode, such as adding a new event or new news post. The following example shows an empty state with multiple items stacked vertically, where the first item acts as a call to action (CTA) to learn more or create an event. diff --git a/docs/design/grid-and-responsive-design.md b/docs/design/grid-and-responsive-design.md index 9aba73a1d..7e12fd385 100644 --- a/docs/design/grid-and-responsive-design.md +++ b/docs/design/grid-and-responsive-design.md @@ -1,85 +1,72 @@ --- title: SharePoint grid and responsive design -description: The underlying page grid system and the breakpoints, or key screen sizes where the layout of the pages will change. -ms.date: 01/23/2018 -localization_priority: Priority +description: The underlying page grid system and the breakpoints, or key screen sizes where the layout of the pages will change. +ms.date: 06/28/2022 +ms.localizationpriority: high --- # SharePoint grid and responsive design - -Responsive experiences seamlessly scale across devices to better display your content on a range of different screen sizes. Responsive design also eliminates the need to build multiple versions of your site pages to support different devices. -The design guidance for responsive pages in the SharePoint authoring environment incorporates a responsive grid system that is based on [Office UI Fabric](https://developer.microsoft.com/fabric). This article describes the underlying page grid system and the breakpoints, or key screen sizes where the layout of the pages will change. +Responsive experiences seamlessly scale across devices to better display your content on a range of different screen sizes. Responsive design also eliminates the need to build multiple versions of your site pages to support different devices. +The design guidance for responsive pages in the SharePoint authoring environment incorporates a responsive grid system that is based on [Office UI Fabric](https://developer.microsoft.com/fabric). This article describes the underlying page grid system and the breakpoints, or key screen sizes where the layout of the pages will change.  +## Page type grids - -## Page type grids - -Each page type in the SharePoint authoring experience can have its own rules for how it applies the Fabric responsive grid. This is to ensure that each page looks great, regardless of what device it's designed for, and that the experience is optimized for that environment. The basic grid in the SharePoint desktop experiences is a 12-column structure. The number of columns and gutter width adjust based on the screen width. +Each page type in the SharePoint authoring experience can have its own rules for how it applies the Fabric responsive grid. This is to ensure that each page looks great, regardless of what device it's designed for, and that the experience is optimized for that environment. The basic grid in the SharePoint desktop experiences is a 12-column structure. The number of columns and gutter width adjust based on the screen width. The following sections show the basic grid structure applied across different types of SharePoint pages, to help you better understand how the grid adjusts to support the experience and device needs. -  -
- ### Team sites The content area for a team site is locked to the left. Team sites have a left navigation; therefore, the space that web parts occupy on the grid and the reflow behavior respects the space given to the navigation. The max width of the content area of a Team site is 1204 px and the minimum size is 320 px for mobile support.  -
- The following examples show how the grid adjusts between key breakpoints on a team site. #### Small 320 x 568 + The small size has a single centered column area, with 20 px margins left and right.  -
- #### Medium 480 x 854 + The medium size has 12 columns, with 16 px gutters.  -
- #### Large 640 x 1024 + The large size has 12 columns, with 24 px gutters.  -
- #### XL 1024 x 768 + The XL size has 12 columns, with 24 px gutters.  -
- #### XXL 1366 x 768 + The XXL size has 12 columns, with 32 px gutters.  -
- #### XXXL 1920 x 1080 + The XXXL size has 12 columns, with 32 px gutters.  -
- #### Team site multicolumn pages and web parts + Web parts scale horizontally depending on the page layout. The following example shows how the size of a web part adjusts to accommodate the left navigation.  @@ -91,75 +78,64 @@ Communication sites have a top navigation and a centered content area. The maxim  -
- The following examples show how the grid adjusts between key breakpoints on a communication site. #### Small 320 x 568 + The small size has a single centered column area, with 20 px margins left and right.  -
- #### Medium 480 x 854 + The medium size has 12 columns, with 16 px gutters.  -
- #### Large 640 x 1024 + The large size has 12 columns, with 24 px gutters.  -
- #### XL 1024 x 768 + The XL size has 12 columns, with 24 px gutters.  -
- #### XXL 1366 x 768 + The XXL size has 12 columns, with 32 px gutters.  -
- #### XXXL 1920 x 1080 + The XXXL size has 12 columns, with 32 px gutters.  -
- #### Communication site multicolumn pages and web parts + Web parts scale horizontally depending on the page layout. This example shows a communication site and web parts for single to three column layouts.  +## Breakpoints - -## Breakpoints - -To create a smooth flowing experience between screen sizes, the SharePoint UI should adapt layouts for the following breakpoint widths: +To create a smooth flowing experience between screen sizes, the SharePoint UI should adapt layouts for the following breakpoint widths: - 320 px - 1024 px - 1366 px - 1920 px - + Within these breakpoints, you should take into consideration how your content shifts when the viewport size becomes optimized for the nearest breakpoint. Note that this diagram is for illustration only and is not pixel accurate.  -
- The responsive grid for both team sites and communication sites adjusts when going from large breakpoints to mobile breakpoints. This optimizes the site for the device and screen size. The following table describes the grid sizes at various breakpoints based on popular device sizes. @@ -176,11 +152,7 @@ The responsive grid for both team sites and communication sites adjusts when goi | 1600 | Web 1600x900 | XX-Large | 12 | 32 | 3 | | 1920 | Web 1920x1080 | XXX-Large | 12 | 32 | 3 | -
- ## See also - [Design toolkit and assets](https://developer.microsoft.com/fabric#/resources) - [Designing great SharePoint experiences](design-guidance-overview.md) - - diff --git a/docs/design/key-web-part-examples.md b/docs/design/key-web-part-examples.md index ab599f1db..e1ba4a44b 100644 --- a/docs/design/key-web-part-examples.md +++ b/docs/design/key-web-part-examples.md @@ -1,15 +1,15 @@ --- title: Key web part examples -description: A visual overview of Communication site and Team site templates. -ms.date: 5/08/2018 -localization_priority: Priority +description: A visual overview of Communication site and Team site templates. +ms.date: 06/28/2022 +ms.localizationpriority: high --- # Key web part examples -Web parts are the building blocks of your page. +Web parts are the building blocks of your page. -This is a visual overview of Communication site and Team site templates, highlighting how web parts work together to create a coherent overall design. Use these pages as reference when designing a SharePoint web part. +This is a visual overview of Communication site and Team site templates, highlighting how web parts work together to create a coherent overall design. Use these pages as reference when designing a SharePoint web part. It is important to consider how the web part will look and function when sitting next to other web parts on a page. Follow the patterns in this documentation and on the [Office UI Fabric site](https://developer.microsoft.com/fabric) to ensure consistency in layout and grid alignment, font size and hierarchy, commanding, empty states, and more. @@ -19,22 +19,20 @@ It is important to consider how the web part will look and function when sitting The Topic design is used when you have a lot of information to share, such as news, events, reports, and other content. It is built from the Hero, News, Events, Highlighted content, Quick links, and People web parts. - + ### Showcase design The Showcase design is used to feature a product, team, or event. It leverages the Hero and Image gallery web parts to show rich visual content. - + ## Team sites The Team site design is the default layout for any new team. It features the News, Quick links, Highlighted content, and Document library web parts. - + These example site and web part designs have been added to the SharePoint toolkit and can be used as reference when designing web parts. For more information, see the [SharePoint toolkit](https://developer.microsoft.com/fabric#/resources). - - diff --git a/docs/design/layout-patterns.md b/docs/design/layout-patterns.md index 699db6cc8..0d8891ca4 100644 --- a/docs/design/layout-patterns.md +++ b/docs/design/layout-patterns.md @@ -1,13 +1,13 @@ --- title: Layout patterns description: Find common SharePoint web part layout types and responsive patterns. -ms.date: 08/24/2018 -localization_priority: Priority +ms.date: 06/28/2022 +ms.localizationpriority: high --- # SharePoint web part layouts -SharePoint uses a number of different layout types for web parts. The most common are grid, list, filmstrip, carousel, and compact. Each one of these five layouts serves a different purpose, depending on the layout, breakpoints, and content density of a page. +SharePoint uses a number of different layout types for web parts. The most common are grid, list, filmstrip, carousel, and compact. Each one of these five layouts serves a different purpose, depending on the layout, breakpoints, and content density of a page. When selecting a layout that works best for your web part, consider the type of content you are displaying. Is it highly visual or rich in text and data? Determine how much space is needed on the page for enough content to be displayed. Consider shortening long descriptions to optimize for displaying more items to the user. Remember that you can use the [property pane](reactive-and-nonreactive-web-parts.md) to let authors have control over how much content is displayed. diff --git a/docs/design/placeholders-and-fallbacks.md b/docs/design/placeholders-and-fallbacks.md index 41140447f..5354450c2 100644 --- a/docs/design/placeholders-and-fallbacks.md +++ b/docs/design/placeholders-and-fallbacks.md @@ -1,14 +1,14 @@ --- title: Placeholders and fallbacks in SharePoint web parts description: Add placeholders to SharePoint web parts as a fallback if an issue occurs loading content or data. -ms.date: 01/23/2018 -localization_priority: Normal +ms.date: 06/28/2022 +ms.localizationpriority: medium --- # Placeholders and fallbacks in SharePoint web parts -You can add placeholders to SharePoint web parts that can also be used as a fallback if an issue occurs loading content or data for a web part. The web part name and description are automatically added from the metadata submitted with the web part. +You can add placeholders to SharePoint web parts that can also be used as a fallback if an issue occurs loading content or data for a web part. The web part name and description are automatically added from the metadata submitted with the web part. You can add a button that users can select to return to a state where they can configure the web part. diff --git a/docs/design/reactive-and-nonreactive-web-parts.md b/docs/design/reactive-and-nonreactive-web-parts.md index 87a981c83..38935ba67 100644 --- a/docs/design/reactive-and-nonreactive-web-parts.md +++ b/docs/design/reactive-and-nonreactive-web-parts.md @@ -1,47 +1,41 @@ --- title: Reactive and nonreactive SharePoint web parts description: Reactive web parts are client-side only; nonreactive web parts have elements that require a server to operate. -ms.date: 01/23/2018 -localization_priority: Priority +ms.date: 03/08/2023 +ms.localizationpriority: high --- # Reactive and nonreactive SharePoint web parts Reactive web parts are client-side only; nonreactive web parts have elements that require a server to operate. We recommend that you build your SharePoint web parts to be reactive because that best fits the UX model and WYSIWYG principles for authoring. However, it might not be possible or cost-effective in all cases to build reactive web parts. - ## Reactive web parts Reactive web parts are fully client-side web parts. This means that each component configured in the property pane reflects the change made within the web part on the page. For example, for the To-Do List web part, unchecking “Completed Tasks” hides this view in the web part. -
+
## Nonreactive web parts
-Nonreactive web parts are not fully client-side; generally, one or more properties need to make a call to set/pull or store data on a server. For nonreactive web parts, you should enable the **Apply** button at the bottom of the property pane.
-You can also customize the **Apply** button to be a more specific action.
+Nonreactive web parts aren't fully client-side; generally, one or more properties need to make a call to set/pull or store data on a server. For nonreactive web parts, you should enable the **Apply** button at the bottom of the property pane.
-
+You can also customize the **Apply** button to be a more specific action.
-+ The following examples show nonreactive web parts in the context of the [three property pane structures](design-a-web-part.md). -**Single pane example** - -
-
-+### Single pane example -**Accordion groups example** + -
+### Accordion groups example
-+ -**Steps pane example** +### Steps pane example -
+
## See also
diff --git a/docs/design/semantic_slots.md b/docs/design/semantic_slots.md
index b9c5d064c..a6e5632b2 100644
--- a/docs/design/semantic_slots.md
+++ b/docs/design/semantic_slots.md
@@ -1,13 +1,13 @@
---
title: Designing for section backgrounds using semantic slots
description: Learn how to design your web part to take advantage of section backgrounds using semantic slots.
-ms.date: 12/06/2018
-localization_priority: Normal
+ms.date: 06/28/2022
+ms.localizationpriority: medium
---
# Designing for section backgrounds using semantic slots
-When designing web parts for section backgrounds, you can use Office UI Fabric’s semantic slot system to guarantee accessibility and to enforce consistency across SharePoint sites. Semantic slots target customizations of specific page elements in order to align color usage and interaction patterns. They also allow you the flexibility to add or assign multiple palette colors for your components so they look great on all section backgrounds. This article will provide examples for semantic slots and how to incorporate them into your web part designs. Before getting started, you should be familiar with [how to design a SharePoint web part](https://docs.microsoft.com/sharepoint/dev/design/design-a-web-part) in order to understand the basic structure of web parts. You should also be familiar with [themes and colors in SharePoint](https://docs.microsoft.com/sharepoint/dev/design/themes-colors).
+When designing web parts for section backgrounds, you can use Office UI Fabric’s semantic slot system to guarantee accessibility and to enforce consistency across SharePoint sites. Semantic slots target customizations of specific page elements in order to align color usage and interaction patterns. They also allow you the flexibility to add or assign multiple palette colors for your components so they look great on all section backgrounds. This article will provide examples for semantic slots and how to incorporate them into your web part designs. Before getting started, you should be familiar with [how to design a SharePoint web part](design-a-web-part.md) in order to understand the basic structure of web parts. You should also be familiar with [themes and colors in SharePoint](themes-colors.md).
## Section background
@@ -15,7 +15,7 @@ Section background is a feature that applies background color to a canvas secti
## Variant vs. Section background
-A variant describes different values of color generated from an existing theme. A variant will share the same set of colors as the original theme it was generated from, but will apply those colors differently. See [Office UI Fabric variant documentation](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/variants/README.md) for more detail.
+A variant describes different values of color generated from an existing theme. A variant will share the same set of colors as the original theme it was generated from, but will apply those colors differently. See [@fluentui/scheme-utilities](https://github.com/microsoft/fluentui/blob/master/packages/scheme-utilities/README.md) for more detail.
A Section Background allows the user to apply a variant color from the theme to a canvas section. Both concepts share "Neutral", "Soft", and "Strong" options and can be used interchangeably when describing color usage.
@@ -25,48 +25,25 @@ A semantic slot is a theming slot that targets specific page elements. A Offic
For example, default text uses the "bodyText" semantic slot. On the None, Neutral, and Soft section backgrounds, bodyText is assigned neutralPrimary. On the Strong section background, the palette color of bodyText changes to white. Semantic slots can be assigned palette colors for all variants in dark themes as well.
-In the table below, you can see all eight palette colors defined for the bodyText slot.
+In the table below, you can see all eight palette colors defined for the bodyText slot.
--
| - | Light themes | -Dark themes | -
| None | -neutralPrimary #333333 | -neutralPrimary #ffffff | -
| Neutral | -neutralPrimary #333333 | -neutralPrimary #ffffff | -
| Soft | -neutralPrimary #333333 | -neutralPrimary #ffffff | -
| Strong | -white #ffffff | -white #1f1f1f | -
- -! Note -The current semantic slot list is defined by commonly used design patterns in SharePoint. We want to avoid creating case-specific semantic slots. When designing a new web part, consider aligning to an existing design pattern. Office UI Fabric's policy is that semantic slots may never be removed from the list, so any additions are permanent. +| Weight | Light themes | Dark themes | +| ------- | ---------------------- | ---------------------- | +| None | neutralPrimary #333333 | neutralPrimary #ffffff | +| Neutral | neutralPrimary #333333 | neutralPrimary #ffffff | +| Soft | neutralPrimary #333333 | neutralPrimary #ffffff | +| Strong | white #ffffff | white #ffffff | + +> [!NOTE] +> The current semantic slot list is defined by commonly used design patterns in SharePoint. We want to avoid creating case-specific semantic slots. When designing a new web part, consider aligning to an existing design pattern. Office UI Fabric's policy is that semantic slots may never be removed from the list, so any additions are permanent. ## Identifying semantic slots in your designs -Semantic slots should be assigned based on the function of a page element. The name of a semantic slot can quickly tell you how it’s meant to be used. You can find all existing semantic slots and their use case examples in the [Fabric semantic colors documentation](https://github.com/OfficeDev/office-ui-fabric-react/blob/master/packages/styling/src/interfaces/ISemanticColors.ts). +Semantic slots should be assigned based on the function of a page element. The name of a semantic slot can quickly tell you how it’s meant to be used. You can find all existing semantic slots and their use case examples in the [Fabric semantic colors documentation](https://developer.microsoft.com/fluentui#/styles/web/colors/theme-slots). -Fabric palette colors should be referenced from your site theme’s color ramp. If your site is using a SharePoint out of the box theme, you can reference [SharePoint theme color ramps](https://fluentfabric.azurewebsites.net/#/color/products). If your site is using a custom theme, you can generate a unique color ramp using the [Fabric theme generator](https://aka.ms/themedesigner). +Fabric palette colors should be referenced from your site theme’s color ramp. If your site is using a SharePoint out of the box theme, you can reference [SharePoint theme color ramps](https://fluentfabric.azurewebsites.net/#/color/products). If your site is using a custom theme, you can generate a unique color ramp using the [Fluent UI Theme Designer](https://aka.ms/themedesigner).  diff --git a/docs/design/showcase-web-part.md b/docs/design/showcase-web-part.md index ce8eb74f0..09965c263 100644 --- a/docs/design/showcase-web-part.md +++ b/docs/design/showcase-web-part.md @@ -1,86 +1,61 @@ --- title: "SharePoint web part design showcase: Create a To-Do list property pane" description: Create a To-Do list web part that uses a single pane and is reactive. -ms.date: 01/23/2018 -localization_priority: Priority +ms.date: 06/28/2022 +ms.localizationpriority: high --- # SharePoint web part design showcase: Create a To-Do list property pane This article describes how to create a To-Do list web part. This example uses the single pane [property pane type](design-a-web-part.md) and is [reactive](reactive-and-nonreactive-web-parts.md) and based on the [Office UI Fabric](https://developer.microsoft.com/fabric) responsive grid. - ## Create a To-Do list web part 1. Add a description to help users understand more about the web part and its properties. - In this example, the description is "Select a source for your to-dos and customize the display for the list of tasks." - -  - -
- -2. Add a Fabric [drop-down component](https://developer.microsoft.com/fabric#/components/dropdown) connected to a list. - -  - -
- -3. Add a Fabric [checkbox component](https://developer.microsoft.com/fabric#/components/checkbox) to display completed tasks. - -  - -
+ In this example, the description is "Select a source for your to-dos and customize the display for the list of tasks." -4. Add two more check boxes to control display options. +  -  +1. Add a Fabric [drop-down component](https://developer.microsoft.com/fabric#/components/dropdown) connected to a list. -
+  -5. Add a Fabric [slider](https://developer.microsoft.com/fabric#/components/slider) for the maximum number of items to display. +1. Add a Fabric [checkbox component](https://developer.microsoft.com/fabric#/components/checkbox) to display completed tasks. -  +  -
+1. Add two more check boxes to control display options. -6. Next, the author of the page selects a list or manually adds tasks to prepopulate the To-Do list web part. +  -  +1. Add a Fabric [slider](https://developer.microsoft.com/fabric#/components/slider) for the maximum number of items to display. -
+  -  +1. Next, the author of the page selects a list or manually adds tasks to prepopulate the To-Do list web part. -
+  -  +  -
+  -7. The web part shows an indicator of items loading onto the page. +1. The web part shows an indicator of items loading onto the page. -  +  -
+1. Items from the list load. -8. Items from the list load. +  -  + When the new tasks are loaded, they fade into view by using animation components from Office UI Fabric. -
+  - When the new tasks are loaded, they fade into view by using animation components from Office UI Fabric. +1. The property pane controls the UI. Tasks with pivots enabled are displayed via the Display check boxes in the property pane. -  - -
- -9. The property pane controls the UI. Tasks with pivots enabled are displayed via the Display check boxes in the property pane. - -  - -
+  ## Responsive views @@ -88,20 +63,14 @@ The following example shows the 2/3 column view of the web part.  -
- The following example shows the 1/3 column view of the web part.  -
- The following example shows the mobile (read-only) view of the web part.  -
- ## See also - [Designing great SharePoint experiences](design-guidance-overview.md) diff --git a/docs/design/themes-colors.md b/docs/design/themes-colors.md index e8dfac7c5..d2eee4ec8 100644 --- a/docs/design/themes-colors.md +++ b/docs/design/themes-colors.md @@ -1,8 +1,8 @@ --- title: SharePoint themes and colors description: Design principles that help form the current SharePoint themes and color palette. -ms.date: 05/21/2018 -localization_priority: Priority +ms.date: 09/04/2024 +ms.localizationpriority: high --- # SharePoint themes and colors @@ -19,90 +19,13 @@ The SharePoint color palette is now optimized for screens and devices. In additi Neutral colors recede into the background to let our products shine. They allow brand colors to pop when we need to draw attention to content. When coupling neutrals with brand colors, make sure there is suitable contrast between them. -
-
 |
-black: #000000 | -
| neutralDark: #212121 | -|
| neutralPrimary: #333333 | -|
| neutralPrimaryAlt: #3c3c3c | -|
| neutralSecondary: #666666 | -|
| neutralTertiary: #a6a6a6 | -|
| neutralTertiaryAlt: #c8c8c8 | -|
| neutralQuaternary: #d0d0d0 | -|
| neutralQuaternaryAlt: #dadada | -|
| neutralLight: #eaeaea | -|
| neutralLighter: #f4f4f4 | -|
| neutralLighterAlt: #f8f8f8 | -|
| white: #ffffff | -
+ ## Shades and tints After you select a color, light and dark shades of the accent color are created based on HSB values of color luminosity. Web parts and apps can use shade variations to create visual hierarchy and provide an indication of interaction. -
- -
 |
-themeDarker: #004578 | -
| themeDark: #005a9e | -|
| themeDarkAlt: #106ebe | -|
| themePrimary: #0078d4 | -|
| themeSecondary: #2b88d8 | -|
| themeTertiary: #71afe5 | -|
| themeLight: #c7e0f4 | -|
| themeLighter: #deecf9 | -|
| themeLighterAlt: #eff6fc | -
- + ## Dark themes @@ -110,22 +33,6 @@ SharePoint includes a palette that supports dark themes. The SharePoint-provided  -## Principles - -The following design principles helped form the current SharePoint themes and color palette. - -### Guided -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. - -### Smart and efficient -Our theming system expedites the site creation process by using smart algorithms to generate options that maximize aesthetic choices. - -### Professional -Our themes embody a professional look and feel that ensures coherency and conveys the brand of our enterprise audiences. - -### 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. - ## See also - [Accessibility](accessibility.md) diff --git a/docs/design/ui-text-for-web-parts.md b/docs/design/ui-text-for-web-parts.md index 9be1c6ec3..5dfd50870 100644 --- a/docs/design/ui-text-for-web-parts.md +++ b/docs/design/ui-text-for-web-parts.md @@ -1,64 +1,56 @@ --- title: UI text guidelines for SharePoint web parts description: Use simple, understandable, and concise UI text to create effective web parts in SharePoint. -ms.date: 01/23/2018 -localization_priority: Normal +ms.date: 03/08/2023 +ms.localizationpriority: medium --- # UI text guidelines for SharePoint web parts - -One aspect of creating effective web parts in SharePoint is to use simple, understandable, and concise UI text. By keeping your message clear and easy to understand, you ensure that customers move through your experiences quickly and can identify the content they are looking for. This article provides guidance for writing UI text for key areas within SharePoint web parts. +One aspect of creating effective web parts in SharePoint is to use simple, understandable, and concise UI text. By keeping your message clear and easy to understand, you ensure that customers move through your experiences quickly and can identify the content they're looking for. This article provides guidance for writing UI text for key areas within SharePoint web parts. ## Capitalization -Use sentence casing (first letter of first word is capitalized, the rest all lowercase) for all UI elements, including buttons, page titles, and control labels. - +Use sentence casing (first letter of first word is capitalized, the rest all lowercase) for all UI elements, including buttons, page titles, and control labels. Always capitalize: - The first word of a new sentence. - The word following a colon in a title or heading. For example, "Step 1: Begin by entering your account information." -- Proper nouns, such as the names of people, cities, and so on. - -
+- Proper nouns, such as the names of people, cities, and so on.
-+ -
+
## Punctuation
Follow the basic rules of punctuation to avoid grammatical errors in your experience. The following table provides guidance and reminders about what punctuation to use when, and why.
-|Punctuation |Guidance |Example |
-|-------------|------------------------------------------------|-----------------|
-|Colons (:) | Use colons if you are introducing a list in the web part description.Don't use colons in UI labels.| Choose one of the following: Cats, Dogs, Quokkas | -|Commas (,) | Use serial commas (including before the word "and"). |I like cats, birds, and dogs. | -|Ellipses (…)| Use ellipses to show truncation and for progress indicator strings.
Don't use ellipses to indicate that the user must make further choices.|Truncation: Last modified by John Armstr…
Progress indicator: Uploading… | -|Periods (.) | Use periods as you normally would for descriptions.
Don't use periods in titles, headings, or labels. Don't use periods for radio button options or check boxes. | Select the content that you want to highlight and how you want it displayed. Use a filter to narrow your selection. | - - +| Punctuation | Guidance | Example | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| Colons (:) | Use colons if you're introducing a list in the web part description.
Don't use colons in UI labels. | Choose one of the following: Cats, Dogs, Quokkas | +| Commas (,) | Use serial commas (including before the word "and"). | I like cats, birds, and dogs. | +| Ellipses (…) | Use ellipses to show truncation and for progress indicator strings.
Don't use ellipses to indicate that the user must make further choices. | Truncation: Last modified by John Armstr…
Progress indicator: Uploading… | +| Periods (.) | Use periods as you normally would for descriptions.
Don't use periods in titles, headings, or labels. Don't use periods for radio button options or check boxes. | Select the content that you want to highlight and how you want it displayed. Use a filter to narrow your selection. | ## Voice and tone Crafting the right tone in your product communication is essential to building a strong, lasting relationship with your audience. Try to keep your words crisp and clear, warm and relaxed, and approachable. How you talk to your audience influences how they engage with your site and content, and how much value they derive from it. -**Do:** +### Do -- Use a casual, conversational tone in the UI. -- Use contractions. For example, use "can't" instead of "cannot". +- Use a casual, conversational tone in the UI. +- Use contractions. For example, use "can't" instead of "can't". - Read your UI text out loud to test the tone. Does it sound like everyday language? -- Use simple words. -- Remove technical details if they're not relevant to the user experience. -- Use "Please" only if you are inconveniencing the user. Avoid overuse. -- Use "Sorry" only in error messages in SharePoint that result in serious problems for the customer. +- Use simple words. +- Remove technical details if they're not relevant to the user experience. +- Use "Please" only if you're inconveniencing the user. Avoid overuse. +- Use "Sorry" only in error messages in SharePoint that result in serious problems for the customer. +### Don't -**Don't:** - -- Clutter the UI text with unnecessary repetition. Make every word meaningful. - +- Clutter the UI text with unnecessary repetition. Make every word meaningful. ## Pronouns @@ -66,25 +58,21 @@ Avoid pronouns in UI elements if possible. If you can say something equally well If your design does warrant using pronouns, apply the following guidelines to make sure that you're using them correctly. -**Do:** +### Do - Use second person ("you" or "your") when you're presenting something that belongs to the user. For example, "Your drafts" or "Your images". - Use first person ("me" or "my") for UI in which the user instructs the service to do something. For example, "Alert me when someone responds to my post." - Use "they" or "their" as a singular possessive modifier to avoid awkward "he/she" or "his/her" constructs. Ideally, rewrite the sentence as plural if possible. - Avoid using "them"; instead, use words like "someone" or "people". For example, "Enter a user name and domain to give someone permission to use this PC." -
-
-+ -
+
-**Don't:**
+### Don't
- Use third person references, as they sound impersonal and can create a disconnected customer experience. Instead of saying "Users can change the layout", use a phrase like "You can change the layout".
-
-
## Error messages
Error conditions are inherent in any software or service. Your error messages can affect the overall user satisfaction with the product. A good error message should do the following:
@@ -93,50 +81,44 @@ Error conditions are inherent in any software or service. Your error messages ca
- Provide a workaround or resolution suggestions.
- Show empathy.
-
-
The following is an example of an error message that occurs when a user tries to edit a page that's checked out by another user.
-
-| You can't edit right now |
-|-------------------------------------------------------------------------|
+| You can't edit right now |
+| ------------------------------------------------------------------------------- |
| Another user is currently editing this page. Please try again in a few minutes. |
-
## Links to help articles
Make an effort to link strategically to help articles. Try to anticipate where the user might need help, and then include a link to the help article close to that UI element. The following are some key things to remember when you place help article links in your UI.
-**Do:**
-
-- Keep the in-product help links specific. Ensure that the target article is appropriate. When the user opens the article, they should be able to locate the information they need.
-- Use natural language for your hyperlinks.
+### Do
-
+- Keep the in-product help links specific. Ensure that the target article is appropriate. When the user opens the article, they should be able to locate the information they need.
+- Use natural language for your hyperlinks.
-**Don’t:**
+### Don't
- Put a help article link next to every UI element. This results in visual noise.
- Include multiple links that go to the same target in the same UI.
-- Use "click here" for the text for your hyperlink.
+- Use "click here" for the text for your hyperlink.
-
+
## Hint text
Hint text, or ghost text, is the text element you display in a UI element, typically a text box, to help the user interact with the UI. The hint text gives information about what the user should enter. For example, it might mention field restrictions or show an example.
-**Do:**
+### Do
- Use hint text sparingly, and only if it helps the user. Not all UI elements require hint text. For some complex fields, hint text can help provide more context and clarity. For example, if you have a field that requires the user to enter a secured URL, the hint text https://www.example.com might be more helpful than the text **Enter secure URL here.**
-**Don't**
+### Don't
- Repeat the label. For example, if you have a text box with the label **Name**, the hint text **Enter name** is redundant and potentially confusing.
-The following hint text is for the embed web part. The text field can accept a secure website address or an iframe embed code. The text shows an example of both.
+The following hint text is for the embed web part. The text field can accept a secure website address or an `
+