SecurityTrimmedControl documentation

Author: estruyf

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Releases
 
+## 1.4.0
+
+**New Controls**
+
+- `SecurityTrimmedControl` control got added [#74](https://github.com/SharePoint/sp-dev-fx-controls-react/issues/74)
+
 ## 1.3.0
 
 **New Controls**

docs/documentation/docs/about/release-notes.md

@@ -1,5 +1,11 @@
 # Releases
 
+## 1.4.0
+
+**New Controls**
+
+- `SecurityTrimmedControl` control got added [#74](https://github.com/SharePoint/sp-dev-fx-controls-react/issues/74)
+
 ## 1.3.0
 
 **New Controls**

docs/documentation/docs/controls/SecurityTrimmedControl.md

@@ -1,28 +1,41 @@
 # SecurityTrimmedControl
 
-This control is intended to be used when you want to show or hide components based on the user its permissions. The control can be used to check the user’s permissions on the current site / list were the solution is loaded, or on a remote site / list. 
+This control is intended to be used when you want to show or hide components based on the user its permissions. The control can be used to check the user’s permissions on the current site / list were the solution is loaded, or on a remote site / list.
 
-## Usage
-### Checking permissions on the current site
+## How to use this control in your solutions
+
+- Check that you installed the `@pnp/spfx-controls-react` dependency. Check out the [getting started](../#getting-started) page for more information about installing the dependency.
+- Import the following modules to your component:
+
+```TypeScript
+import { SecurityTrimmedControl } from "@pnp/spfx-controls-react/lib/SecurityTrimmedControl";
 ```
+
+- You can use the `SecurityTrimmedControl` as follows in your solutions:
+
+**Checking permissions on the current site**
+
+```jsx
 <SecurityTrimmedControl context={this.props.context}
                         level={PermissionLevel.currentWeb}
                         permissions={[SPPermission.viewPages]}>
   {/* Specify the components to load when user has the required permissions */}
 </SecurityTrimmedControl>
 ```
 
-### Checking permissions on the current list
-```
+**Checking permissions on the current list**
+
+```jsx
 <SecurityTrimmedControl context={this.props.context}
                         level={PermissionLevel.currentList}
                         permissions={[SPPermission.addListItems]}>
   {/* Specify the components to load when user has the required permissions */}
 </SecurityTrimmedControl>
 ```
 
-### Checking permissions on remote site
-```
+**Checking permissions on remote site**
+
+```jsx
 <SecurityTrimmedControl context={this.props.context}
                         level={PermissionLevel.remoteWeb}
                         remoteSiteUrl="https://<tenant>.sharepoint.com/sites/<siteName>"
@@ -31,8 +44,9 @@ This control is intended to be used when you want to show or hide components bas
 </SecurityTrimmedControl>
 ```
 
-### Checking permissions on remote list / library
-```
+**Checking permissions on remote list / library**
+
+```jsx
 <SecurityTrimmedControl context={this.props.context}
                         level={PermissionLevel.remoteListOrLib}
                         remoteSiteUrl="https://<tenant>.sharepoint.com/sites/<siteName>"
@@ -41,3 +55,18 @@ This control is intended to be used when you want to show or hide components bas
   {/* Specify the components to load when user has the required permissions */}
 </SecurityTrimmedControl>
 ```
+
+## Implementation
+
+The `SecurityTrimmedControl` can be configured with the following properties:
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| context | WebPartContext or ApplicationCustomizerContext or FieldCustomizerContext or ListViewCommandSetContext | yes | Context of the web part, application customizer, field customizer, or list view command set. |
+| permissions | SPPermission[] | yes | The permissions to check for the user. |
+| level | PermissionLevel | yes | Specify where to check the user permissions: current site or list / remote site or list. |
+| remoteSiteUrl | string | no | The URL of the remote site. Required when you want to check permissions on remote site or list. |
+| relativeLibOrListUrl | string | no | The relative URL of the list or library. Required when you want to check permissions on remote list. |
+
+
+![](https://telemetry.sharepointpnp.com/sp-dev-fx-controls-react/wiki/controls/SecurityTrimmedControl)

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pnp/spfx-controls-react",
   "description": "Reusable React controls for SharePoint Framework solutions",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=0.10.0"
   },

src/controls/securityTrimmedControl/ISecurityTrimmedControlProps.ts

@@ -6,11 +6,11 @@ import { PermissionLevel } from '.';
 
 export interface ISecurityTrimmedControlProps {
   /**
-   * Context of the web part, application customizer, field customizer, or list view command set
+   * Context of the web part, application customizer, field customizer, or list view command set.
    */
   context: WebPartContext | ApplicationCustomizerContext | FieldCustomizerContext | ListViewCommandSetContext;
   /**
-   * The permissions to check for the user
+   * The permissions to check for the user.
    */
   permissions: SPPermission[];
   /**

src/webparts/controlsTest/components/ControlsTest.tsx

@@ -15,6 +15,8 @@ import { TaxonomyPicker, IPickerTerms } from '../../../TaxonomyPicker';
 import { ListPicker } from '../../../ListPicker';
 import { IFrameDialog } from '../../../IFrameDialog';
 import { Environment, EnvironmentType } from '@microsoft/sp-core-library';
+import { SecurityTrimmedControl, PermissionLevel } from '../../../SecurityTrimmedControl';
+import { SPPermission } from '@microsoft/sp-page-context';
 
 /**
  * Component that can be used to test out the React controls from this project
@@ -177,6 +179,10 @@ export default class ControlsTest extends React.Component<IControlsTestProps, IC
             <div className="ms-Grid-col ms-lg10 ms-xl8 ms-xlPush2 ms-lgPush1">
               <span className="ms-font-xl">Controls testing</span>
 
+              <SecurityTrimmedControl context={this.props.context} level={PermissionLevel.currentWeb} permissions={[SPPermission.viewListItems]}>
+                <p>You have permissions to view list items.</p>
+              </SecurityTrimmedControl>
+
               <p className="ms-font-l">
                 File type icon control
               </p>