Merge pull request #867 from pnp/site-picker

Site picker

Author: AJIXuMuK

docs/documentation/docs/assets/site-picker-multi-select.gif

@@ -0,0 +1,72 @@
+# SitePicker control
+
+This control allows you to select one or multiple available sites, site collections or hub sites.
+
+Here is an example of the control.
+
+`SitePicker` single selection mode:
+
+![SitePicker Single Select](../assets/site-picker-single-select.gif)
+
+`SitePicker` multi-selection mode
+
+![SitePicker Multi Select](../assets/site-picker-multi-select.gif)
+
+## 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 control into your component:
+
+```TypeScript
+import { SitePicker } from "@pnp/spfx-controls-react/lib/SitePicker";
+```
+
+- Use the `SitePicker` control in your code as follows:
+
+```TypeScript
+<SitePicker
+  context={this.props.context}
+  label={'Select sites'}
+  mode={'site'}
+  allowSearch={true}
+  multiSelect={false}
+  onChange={(sites) => { console.log(sites); }}
+  placeholder={'Select sites'}
+  searchPlaceholder={'Filter sites'} />
+```
+
+- The `onChange` change event returns the selected site(s).
+
+## Implementation
+
+The `SitePicker` control can be configured with the following properties:
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| allowSearch | boolean | no | Specifies if search box is displayed for the component. Default: `true`. |
+| context | BaseComponentContext | yes | The context object of the SPFx loaded webpart or customizer. |
+| deferredSearchTime | number | no | The list will be filtered after users stop typing for `deferredSearchTime` milliseconds. Default: 200. |
+| className | string | no | If provided, additional class name to provide on the dropdown element. |
+| disabled | boolean | no | Whether or not the control is disabled. |
+| initialSites | ISite[] | no | Intial data to load in the 'Selected sites' area (optional). |
+| isDesc | boolean | no | Specifies if the list is sorted in descending order. Default: `false`. |
+| label | string | no | Label to use for the control. |
+| limitToCurrentSiteCollection | boolean | no | Specifies if the options should be limited by the current site collections. Taken into consideration if selectionMode is set to `web`. |
+| mode | `'site' \| 'web' \| 'hub'` | no | Defines what entities are available for selection: site collections, sites, hub sites. Default: `web`. |
+| multiSelect | boolean | no | Optional mode indicates if multi-choice selections is allowed. Default: `true`. |
+| onChange | `(selectedSites: ISite[]) => void` | yes | Selection change handler. | 
+| orderBy | `'title' \| 'url'` | no | Specifices if the list is sorted by title or url. Default: `title`. |
+| placeholder | string | no | Placeholder label to show in the dropdown. |
+| searchPlaceholder | string | no | Search input placeholder text. Displayed until search text is entered. |
+
+Interface `ISite`
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| id | string | no | ID of the site collection. |
+| title | string | no | Title of the site. |
+| url | string | no | URL of the site. |
+| webId | string | no | ID of the site. **Note: the value is not populated if the `mode` is set to `hub`. |
+| hubSiteId | string | no | ID of the hub site. |
+
+![](https://telemetry.sharepointpnp.com/sp-dev-fx-controls-react/wiki/controls/SitePicker)

docs/documentation/docs/assets/site-picker-single-select.gif

@@ -77,8 +77,9 @@ The following controls are currently available:
 - [PeoplePicker](./controls/PeoplePicker) (People Picker)
 - [Placeholder](./controls/Placeholder) (shows an initial placeholder if the web part has to be configured)
 - [Progress](./controls/Progress) (shows progress of multiple SEQUENTIALLY executed actions)
-- [SiteBreadcrumb](./controls/SiteBreadcrumb) (Breadcrumb control)
 - [SecurityTrimmedControl](./controls/SecurityTrimmedControl) (intended to be used when you want to show or hide components based on the user permissions)
+- [SiteBreadcrumb](./controls/SiteBreadcrumb) (Breadcrumb control)
+- [SitePicker](./controls/SitePicker) (Site Picker control)
 - [TaxonomyPicker](./controls/TaxonomyPicker) (Taxonomy Picker)
 - [Toolbar](./controls/Toolbar) (Control to render Toolbar in Microsoft Teams)
 - [TreeView](./controls/TreeView) (Tree View)

docs/documentation/docs/controls/SitePicker.md

@@ -47,8 +47,9 @@ nav:
     - Placeholder: 'controls/Placeholder.md'
     - Progress: 'controls/Progress.md'
     - RichText: 'controls/RichText.md'
-    - SiteBreadcrumb: 'controls/SiteBreadcrumb.md'
     - SecurityTrimmedControl: 'controls/SecurityTrimmedControl.md'
+    - SiteBreadcrumb: 'controls/SiteBreadcrumb.md'
+    - SitePicker: 'controls/SitePicker.md'
     - TaxonomyPicker: 'controls/TaxonomyPicker.md'
     - Toolbar: 'controls/Toolbar.md'
     - TreeView: 'controls/TreeView.md'

docs/documentation/docs/index.md

@@ -0,0 +1 @@
+export * from './controls/sitePicker/index';

docs/documentation/mkdocs.yml

@@ -351,3 +351,12 @@ export function urlCombine(urlStart: string, urlFinish: string, escapeFinish: bo
 
   return url;
 }
+
+export const toRelativeUrl = (absoluteUrl: string): string => {
+
+  if (!absoluteUrl) {
+    return '';
+  }
+
+  return absoluteUrl.replace(/^(?:\/\/|[^/]+)*\//, '/');
+};

src/SitePicker.ts

@@ -0,0 +1,99 @@
+import { BaseComponentContext } from '@microsoft/sp-component-base';
+
+export interface ISite {
+  /**
+   * ID of the site
+   */
+  id?: string;
+  /**
+   * Title
+   */
+  title?: string;
+  /**
+  * Base URL
+  */
+  url?: string;
+
+  /**
+   * ID of the web
+   */
+  webId?: string;
+
+  /**
+   * ID of the hub site
+   */
+  hubSiteId?: string;
+}
+
+export interface ISitePickerProps {
+  /**
+   * Site picker label
+   */
+  label?: string;
+  /**
+   * Specify if the control needs to be disabled
+   */
+  disabled?: boolean;
+  /**
+   * Web Part context
+   */
+  context: BaseComponentContext;
+  /**
+   * Intial data to load in the 'Selected sites' area (optional)
+   */
+  initialSites?: ISite[];
+  /**
+   * Define if you want to allow multi site selection. True by default.
+   */
+  multiSelect?: boolean;
+  /**
+   * Defines what entities are available for selection: site collections, sites, hub sites.
+   */
+  mode?: 'site' | 'web' | 'hub';
+
+  /**
+   * Specifies if the options should be limited by the current site collections. Taken into consideration if selectionMode is set to 'web'
+   */
+  limitToCurrentSiteCollection?: boolean;
+
+  /**
+   * Specifies if search box is displayed for the component. Default: true
+   */
+  allowSearch?: boolean;
+
+  /**
+   * Specifices if the list is sorted by title or url. Default: title
+   */
+  orderBy?: 'title' | 'url';
+
+  /**
+   * Specifies if the list is sorted in descending order. Default: false
+   */
+  isDesc?: boolean;
+
+  /**
+   * Selection change handler
+   */
+  onChange: (selectedSites: ISite[]) => void;
+
+  /**
+   * Input placeholder text. Displayed until option is selected.
+   */
+  placeholder?: string;
+
+  /**
+   * Search input placeholder text. Displayed until search text is entered.
+   */
+  searchPlaceholder?: string;
+
+  /**
+   * The list will be filtered after users stop typing for `deferredSearchTime` milliseconds.
+   * Default value is 200.
+   */
+  deferredSearchTime?: number;
+
+  /**
+   * If provided, additional class name to provide on the dropdown element.
+   */
+  className?: string;
+}