Code merge + refactoring for #230

pnp · Mar 29, 2019 · e387370 · e387370
2 parents 134bfec + 35d3aaf
commit e387370
Show file tree

Hide file tree

Showing 17 changed files with 3,040 additions and 2,316 deletions.
diff --git a/docs/documentation/docs/assets/Progress.png b/docs/documentation/docs/assets/Progress.png
diff --git a/docs/documentation/docs/controls/Map.md b/docs/documentation/docs/controls/Map.md
@@ -1,6 +1,6 @@
 # Map control
 
-This control renders can be used to render a map in your solution. The control has also the ability to search for new locations.
+This control renders a map in your solution. The control has also the ability to search for new locations.
 
 Here is an example of the control in action:
 

diff --git a/docs/documentation/docs/controls/Progress.md b/docs/documentation/docs/controls/Progress.md
@@ -0,0 +1,120 @@
+# Progress control
+
+This control shows progress of multiple SEQUENTIALLY executed actions.
+
+Here is an example of the control in action:
+
+![Progress control](../assets/Progress.png)
+
+## 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 { Progress } from "@pnp/spfx-controls-react/lib/Progress";
+```
+
+- Use the `Progress` control in your code as follows:
+
+```TypeScript
+<Progress title={'Progress Test'}
+          showOverallProgress={true}
+          showIndeterminateOverallProgress={false}
+          hideNotStartedActions={false}
+          actions={this.state.progressActions}
+          currentActionIndex={this.state.currentProgressActionIndex}
+          longRunningText={'This operation takes longer than expected'}
+          longRunningTextDisplayDelay={7000}
+          height={'350px'} />
+```
+
+**Note**: the control itself is not responsible for actions' execution. It only renders the actions, overall progress and actions' execution states.
+When using the control, you should implement actions execution.
+As example, you can have a base class that implements `IProgressAction` interface and has an `execute` method:
+
+```TypeScript
+class BaseAction implements IProgressAction {
+  public get title(): string { ... }
+  public get subActionsTitles(): string[] { ... }
+  public get hasError(): boolean { ... }
+  public get errorMessage(): string { ... }
+  public async execute(): Promise<void> { ... }
+}
+```
+
+Then, you have multiple actions derived from the base one:
+
+```TypeScript
+class FirstAction extends BaseAction {
+  public async execute(): Promise<void> { 
+    // implementation for FirstAction
+  }
+}
+
+class SecondAction extends BaseAction {
+  public async execute(): Promise<void> {
+    // implementation for SecondAction
+  }
+}
+```
+
+Now, in a component, where `Progress` is used you can have code as below:
+
+```TypeScript
+export interface IYourComponentState {
+  actions: IProgressAction[];
+  currentActionIndex?: number;
+  // other state properties
+}
+
+// ...
+
+export class YourComponent extends React.Component<IYourComponentProps, IYourComponentState> {
+  // all other code, including render with Progress reference listed above
+
+  private _initActions() {
+    this.setState({
+      actions: [
+        new FirstAction(),
+        new SecondAction()
+      ]
+    });
+  }
+
+  private async _execute() {
+    for (let i = 0; i <= this.state.actions.length; i++) {
+      this.setState(currentActionIndex: i);
+
+      if (i < this.state.actions.length) {
+        await this.state.actions[i].execute();
+      }
+    }
+  }
+}
+```
+
+## Implementation
+
+The `Progress` component can be configured with the following properties:
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| title | string | no | Title, or header, of the progress. |
+| showOverallProgress | boolean | true | Specifies if overall progress indicator should be shown. |
+| showIndeterminateOverallProgress | boolean | no | Specifies if indeterminate overall progress animation will be shown. |
+| hideNotStartedActions | boolean | yes | Specifies if not started actions should not be rendered. |
+| actions | IProgressAction[] | yes | Progress actions |
+| currentActionIndex | number | no | Index of currently executing action |
+| heigth | string | no | Height of the component |
+| longRunningText | string | no | Text to be displayed for long running operations |
+| longRunningTextDisplayDelay | number | no | Delay until longRunningText is displayed im milliseconds. If not set or 0 longRunningText is displayed right away. |
+| className | string | no | Class name to be applied to the component |
+| headerClassName | string | no | Header class name. Header contains title, progress indicator, and delay text |
+| actionsContainerClassName | string | no | Actions container class name |
+| actionClassName | string | no | Single action class name |
+| successIconName | string | no | Success icon name. Default is CheckMark |
+| errorIconName | string | no | Error icon name. Default is Error |
+| inProgressIconName | string | no | InProgress icon name. Default is '', spinner is displayed. |
+
+![](https://telemetry.sharepointpnp.com/sp-dev-fx-controls-react/wiki/controls/Progress)
diff --git a/docs/documentation/docs/controls/SecurityTrimmedControl.md b/docs/documentation/docs/controls/SecurityTrimmedControl.md
@@ -1,6 +1,6 @@
 # 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 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.
 
 ## How to use this control in your solutions
 

diff --git a/docs/documentation/docs/index.md b/docs/documentation/docs/index.md
@@ -34,14 +34,20 @@ Once the package is installed, you will have to configure the resource file of t
 
 The following controls are currently available:
 
+- [Charts](./controls/ChartControls) (makes it easy to integrate [Chart.js](https://www.chartjs.org/) charts into web part)
 - [FileTypeIcon](./controls/FileTypeIcon) (Control that shows the icon of a specified file path or application)
+- [IFrameDialog](./controls/IFrameDialog) (renders a Dialog with an iframe as a content)
+- [ListItemPicker](./controls/ListItemPicker) (allows to select one or more items from a list)
+- [ListPicker](./controls/ListPicker) (allows to select one or multiple available lists/libraries of the current site)
 - [ListView](./controls/ListView) (List view control)
-- [Placeholder](./controls/Placeholder) (Control that can be used to show an initial placeholder if the web part has to be configured)
+- [Map](./controls/Map) (renders a map in a web part)
+- [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)
 - [TaxonomyPicker](./controls/TaxonomyPicker) (Taxonomy Picker)
-- [PeoplePicker](./controls/PeoplePicker) (People Picker)
 - [WebPartTitle](./controls/WebPartTitle) (Customizable web part title control)
-- [IFrameDialog](./controls/IFrameDialog) (renders a Dialog with an iframe as a content)
 
 Field customizer controls:
 

diff --git a/docs/documentation/mkdocs.yml b/docs/documentation/mkdocs.yml
@@ -13,21 +13,22 @@ nav:
       - "Radar Chart": 'controls/charts/RadarChart.md'
       - "Scatter Chart": 'controls/charts/ScatterChart.md'
     - FileTypeIcon: 'controls/FileTypeIcon.md'
+    - IFrameDialog: 'controls/IFrameDialog.md'
+    - IFramePanel: 'controls/IFramePanel.md'
     - ListItemAttachments: 'controls/ListItemAttachments.md'
     - ListItemPicker: 'controls/ListItemPicker.md'
     - ListPicker: 'controls/ListPicker.md'
     - ListView: 'controls/ListView.md'
     - "ListView: add a contextual menu": 'controls/ListView.ContextualMenu.md'
     - Map: 'controls/Map.md'
+    - PeoplePicker: 'controls/PeoplePicker.md'
     - Placeholder: 'controls/Placeholder.md'
+    - Progress: 'controls/Progress.md'
     - RichText: 'controls/RichText.md'
     - SiteBreadcrumb: 'controls/SiteBreadcrumb.md'
-    - WebPartTitle: 'controls/WebPartTitle.md'
     - SecurityTrimmedControl: 'controls/SecurityTrimmedControl.md'
     - TaxonomyPicker: 'controls/TaxonomyPicker.md'
-    - PeoplePicker: 'controls/PeoplePicker.md'
-    - IFrameDialog: 'controls/IFrameDialog.md'
-    - IFramePanel: 'controls/IFramePanel.md'
+    - WebPartTitle: 'controls/WebPartTitle.md'
   - 'Field Controls':
     - 'Getting started': 'controls/fields/main.md'
     - FieldRendererHelper: 'controls/fields/FieldRendererHelper.md'