Merge branch 'siata13-dev' into dev

Author: estruyf

docs/documentation/docs/assets/term-action.png

@@ -34,15 +34,13 @@ import { TaxonomyPicker, IPickerTerms } from "@pnp/spfx-controls-react/lib/Taxon
 - Use the `TaxonomyPicker` control in your code as follows:
 
 ```TypeScript
-<TaxonomyPicker
-  allowMultipleSelections={true}
-  termsetNameOrID="Countries"
-  panelTitle="Select Term"
-  label="Taxonomy Picker"
-  context={this.props.context}
-  onChange={this.onTaxPickerChange}
-  isTermSetSelectable={false}
-/>
+<TaxonomyPicker allowMultipleSelections={true}
+                termsetNameOrID="Countries"
+                panelTitle="Select Term"
+                label="Taxonomy Picker"
+                context={this.props.context}
+                onChange={this.onTaxPickerChange}
+                isTermSetSelectable={false} />
 ```
 
 - With the `onChange` property you can capture the event of when the terms in the picker has changed:
@@ -53,6 +51,51 @@ private onTaxPickerChange(terms : IPickerTerms) {
 }
 ```
 
+## Term actions
+
+Since version `1.12.0`, you can apply term actions to all terms or specific ones. Term actions could for instance be used to retrieve the labels of the term, or retrieve other information. These term actions can be implemented as follows:
+
+```typescript
+<TaxonomyPicker allowMultipleSelections={true}
+                termsetNameOrID="Countries"
+                panelTitle="Select Term"
+                label="Taxonomy Picker"
+                context={this.props.context}
+                onChange={this.onServicePickerChange}
+                isTermSetSelectable={false}
+                termActions={{
+                  actions: [{
+                    title: "Update term label",
+                    iconName: "LocaleLanguage",
+                    id: "UpdateTermLabel",
+                    actionCallback: async (taxService: SPTermStorePickerService, term: ITerm) => {
+                      return {
+                        updateActionType: UpdateType.updateTermLabel,
+                        value: `${term.Name} (updated)`
+                      };
+                    },
+                    applyToTerm: (term: ITerm) => (true) // Applying the action to all terms
+                  }]
+                }} />
+```
+
+![Term action sample](../assets/term-action.png)
+
+We also provided a default term action which you can use to retrieve the term its labels and will update the term text in the TaxonomyPicker hierarchy.
+
+```typescript
+<TaxonomyPicker allowMultipleSelections={true}
+                termsetNameOrID="Countries"
+                panelTitle="Select Term"
+                label="Taxonomy Picker"
+                context={this.props.context}
+                onChange={this.onServicePickerChange}
+                isTermSetSelectable={false}
+                termActions={{
+                  actions: [new TermLabelAction("Get Labels")]
+                }} />
+```
+
 ## Implementation
 
 The TaxonomyPicker control can be configured with the following properties:
@@ -71,6 +114,7 @@ The TaxonomyPicker control can be configured with the following properties:
 | disabledTermIds | string[] | no | Specify which terms should be disabled in the term set so that they cannot be selected. |
 | disableChildrenOfDisabledParents | boolean | no | Specify if you want to disable the child terms when their parent is disabled. |
 | anchorId | string | no | Set the anchorid to a child term in the TermSet to be able to select terms from that level and below. |
+| termActions | ITermActions | no | Allows to execute custom action on the term like e.g. get other term labelsITermActions. |
 
 Interface `IPickerTerm`
 
@@ -86,4 +130,39 @@ Interface `IPickerTerms`
 
 An Array of IPickerTerm
 
+Interface `ITermActions`
+
+| Property | Type | Required | Description | Default |
+| ---- | ---- | ---- | ---- | ---- |
+| actions | ITermAction[] | yes | The array of supported actions | |
+| termActionsDisplayStyle | TermActionsDisplayStyle | no | Defines how to display term action button, available options: text, icon, text and icon | text |
+| termActionsDisplayMode | TermActionsDisplayMode | no | Defines how to display term actions, as buttons or dropdown | buttons |
+| initialize | (spTermService: SPTermStorePickerService) => Promise\<void\> | no | Initializes the term action with the taxonomy service |
+
+Interface `ITermAction`
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| id | string | yes | Unique id of the term action |
+| title | string | yes | Action title |
+| iconName | string | no | Name of the icon to be used to display action |
+| applyToTerm | (currentTerm: ITerm) => Promise\<boolean\> \| boolean | yes | Method checks if the current term is supported |
+| actionCallback | (spTermService: SPTermStorePickerService, currentTerm: ITerm) => Promise\<UpdateAction\> | yes | Method to be executed when action is fired |
+| initialize | (spTermService: SPTermStorePickerService) => Promise\<void\> | no | Initializes the term action with the taxonomy service |
+
+
+Interface `UpdateAction`
+
+| Property | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| updateActionType | UpdateType | yes | Defines the type of update you want to perform |
+| value | string | no | New term label value to update. Only required when you want to update the term |
+
+Enum `UpdateType`
+
+| Value |
+| ---- |
+| updateTermLabel |
+| updateTermsTree |
+
 ![](https://telemetry.sharepointpnp.com/sp-dev-fx-controls-react/wiki/controls/Placeholder)

docs/documentation/docs/controls/TaxonomyPicker.md

@@ -1,8 +1,9 @@
 import { ApplicationCustomizerContext } from '@microsoft/sp-application-base';
 import { IPickerTerms } from './ITermPicker';
-import { ITermStore, IGroup, ITermSet, ITerm } from '../../services/ISPTermStorePickerService';
-import SPTermStorePickerService from '../../services/SPTermStorePickerService';
+import { ITermSet, ITerm } from '../../services/ISPTermStorePickerService';
 import { IWebPartContext } from '@microsoft/sp-webpart-base';
+import { ITermActions } from './termActions/ITermsActions';
+import SPTermStorePickerService from '../../services/SPTermStorePickerService';
 
 /**
  * PropertyFieldTermPickerHost properties interface
@@ -52,6 +53,17 @@ export interface ITaxonomyPickerProps  {
    * Whether the property pane field is enabled or not.
    */
   disabled?: boolean;
+
+  /**
+   * Include standard term actions.
+   */
+  includeDefaultTermActions?: boolean;
+
+  /**
+   * Specifies the available term actions and their basic properties.
+   */
+  termActions?: ITermActions;
+
   /**
    * The method is used to get the validation error message and determine whether the input value is valid or not.
    *
@@ -77,7 +89,6 @@ export interface ITaxonomyPickerProps  {
  * PropertyFieldTermPickerHost state interface
  */
 export interface ITaxonomyPickerState {
-
   termSetAndTerms? : ITermSet;
   errorMessage?: string;
   openPanel?: boolean;
@@ -98,8 +109,11 @@ export interface ITermParentProps extends ITermChanges {
   multiSelection: boolean;
   anchorId? : string;
   isTermSetSelectable?: boolean;
+  termActions?: ITermActions;
+  spTermService: SPTermStorePickerService;
 
   autoExpand: () => void;
+  updateTaxonomyTree: () => void;
   termSetSelectedChange?: (termSet: ITermSet, isChecked: boolean) => void;
 }
 
@@ -114,8 +128,13 @@ export interface ITermProps extends ITermChanges {
   term: ITerm;
   multiSelection: boolean;
   disabled: boolean;
+  termActions?: ITermActions;
+  spTermService: SPTermStorePickerService;
+
+  updateTaxonomyTree: () => void;
 }
 
 export interface ITermState {
   selected?: boolean;
+  termLabel: string;
 }

src/controls/taxonomyPicker/ITaxonomyPicker.ts

@@ -1,8 +1,6 @@
 import { ApplicationCustomizerContext } from '@microsoft/sp-application-base';
 import { IWebPartContext } from '@microsoft/sp-webpart-base';
 
-
-
 /**
  * Selected terms
  */

src/controls/taxonomyPicker/ITermPicker.ts

@@ -1,3 +1,7 @@
+.contextualMenu {
+  display: inline-block
+}
+
 .listItem {
   height: 36px;
   line-height: 36px;

src/controls/taxonomyPicker/TaxonomyPicker.module.scss

@@ -7,13 +7,14 @@ import TermPicker from './TermPicker';
 import { IPickerTerms, IPickerTerm } from './ITermPicker';
 import { ITaxonomyPickerProps, ITaxonomyPickerState } from './ITaxonomyPicker';
 import SPTermStorePickerService from './../../services/SPTermStorePickerService';
-import { ITermSet, IGroup, ITerm } from './../../services/ISPTermStorePickerService';
+import { ITermSet, ITerm } from './../../services/ISPTermStorePickerService';
+
 import styles from './TaxonomyPicker.module.scss';
 import { sortBy, uniqBy, cloneDeep, isEqual } from '@microsoft/sp-lodash-subset';
 import TermParent from './TermParent';
 import FieldErrorMessage from './ErrorMessage';
-import * as telemetry from '../../common/telemetry';
 
+import * as telemetry from '../../common/telemetry';
 
 /**
  * Image URLs / Base64
@@ -81,19 +82,30 @@ export class TaxonomyPicker extends React.Component<ITaxonomyPickerProps, ITaxon
    */
   private loadTermStores(): void {
     this.termsService = new SPTermStorePickerService(this.props, this.props.context);
+
+    if (this.props.termActions && this.props.termActions.initialize) {
+      this.props.termActions.initialize(this.termsService);
+      // this.props.termActions.actions.forEach(x => {
+      //   x.initialize(this.termsService);
+      // });
+    }
+
     this.termsService.getAllTerms(this.props.termsetNameOrID).then((response: ITermSet) => {
       // Check if a response was retrieved
-      if (response !== null) {
-        this.setState({
-          termSetAndTerms: response,
-          loaded: true
-        });
-      } else {
-        this.setState({
-          termSetAndTerms: null,
-          loaded: true
-        });
-      }
+      let termSetAndTerms = response ? response : null;
+      this.setState({
+        termSetAndTerms,
+        loaded: true
+      });
+    });
+  }
+
+  /**
+   * Force update of the taxonomy tree - required by term action in case the term has been added, deleted or moved.
+   */
+  private updateTaxonomyTree(): void {
+    this.setState({
+      termSetAndTerms: this.state.termSetAndTerms
     });
   }
 
@@ -304,7 +316,12 @@ export class TaxonomyPicker extends React.Component<ITaxonomyPickerProps, ITaxon
                             disabledTermIds={this.props.disabledTermIds}
                             disableChildrenOfDisabledParents={this.props.disableChildrenOfDisabledParents}
                             changedCallback={this.termsChanged}
-                            multiSelection={this.props.allowMultipleSelections} />
+                            multiSelection={this.props.allowMultipleSelections}
+                            spTermService={this.termsService}
+
+                            updateTaxonomyTree={this.updateTaxonomyTree}
+                            termActions={this.props.termActions}
+                            />
               </div>
             )
           }

src/controls/taxonomyPicker/TaxonomyPicker.tsx

@@ -3,21 +3,25 @@ import { Checkbox } from 'office-ui-fabric-react/lib/Checkbox';
 import { ITermProps, ITermState } from './ITaxonomyPicker';
 
 import styles from './TaxonomyPicker.module.scss';
+import TermActionsControl from './termActions/TermActionsControl';
+import { UpdateAction, UpdateType } from './termActions';
 
 
 /**
  * Term component
  * Renders a selectable term
  */
 export default class Term extends React.Component<ITermProps, ITermState> {
+
   constructor(props: ITermProps) {
     super(props);
 
     // Check if current term is selected
     let active = this.props.activeNodes.filter(item => item.key === this.props.term.Id);
 
     this.state = {
-      selected: active.length > 0
+      selected: active.length > 0,
+      termLabel: this.props.term.Name
     };
 
     this._handleChange = this._handleChange.bind(this);
@@ -43,7 +47,8 @@ export default class Term extends React.Component<ITermProps, ITermState> {
     if (!this.props.multiSelection) {
       let active = nextProps.activeNodes.filter(item => item.key === this.props.term.Id);
       this.state = {
-        selected: active.length > 0
+        selected: active.length > 0,
+        termLabel: this.state.termLabel
       };
     }
   }
@@ -63,23 +68,55 @@ export default class Term extends React.Component<ITermProps, ITermState> {
     return styles.termEnabled;
   }
 
+  private termActionCallback = (updateAction: UpdateAction): void => {
+    if (updateAction == null) {
+      return;
+    }
+
+    if (updateAction.updateActionType === UpdateType.updateTermLabel) {
+      this.props.term.Name = updateAction.value;
+      this.setState({
+        termLabel: updateAction.value
+      });
+    }
+    else {
+      this.props.updateTaxonomyTree();
+    }
+  }
+
   /**
    * Default React render
    */
   public render(): JSX.Element {
     const styleProps: React.CSSProperties = {
       marginLeft: `${(this.props.term.PathDepth * 30)}px`
     };
+    const checkBoxStyle: React.CSSProperties = {
+      display: "inline-flex"
+    };
 
     return (
-      <div className={`${styles.listItem} ${styles.term}`} style={styleProps}>
-        <Checkbox
-          checked={this.state.selected}
-          disabled={this.props.term.IsDeprecated || !this.props.term.IsAvailableForTagging || this.props.disabled}
-          className={this.getClassName()}
-          label={this.props.term.Name}
-          onChange={this._handleChange} />
+      <div>
+        <div className={`${styles.listItem} ${styles.term}`} style={styleProps}>
+          <div>
+            <Checkbox
+              checked={this.state.selected}
+              style={checkBoxStyle}
+              disabled={this.props.term.IsDeprecated || !this.props.term.IsAvailableForTagging || this.props.disabled}
+              className={this.getClassName()}
+              label={this.state.termLabel}
+              onChange={this._handleChange} />
+          </div>
+          {
+            this.props.termActions &&
+            <TermActionsControl term={this.props.term}
+                                termActions={this.props.termActions}
+                                termActionCallback={this.termActionCallback}
+                                spTermService={this.props.spTermService} />
+          }
+        </div>
       </div>
+
     );
   }
 }

src/controls/taxonomyPicker/Term.tsx

@@ -106,7 +106,16 @@ export default class TermParent extends React.Component<ITermParentProps, ITermP
                   disabled = parentPath && parentPath.length > 0;
                 }
 
-                return <Term key={term.Id} term={term} termset={this.props.termset.Id} activeNodes={this.props.activeNodes} changedCallback={this.props.changedCallback} multiSelection={this.props.multiSelection} disabled={disabled} />;
+                return <Term key={term.Id}
+                             term={term}
+                             termset={this.props.termset.Id}
+                             activeNodes={this.props.activeNodes}
+                             changedCallback={this.props.changedCallback}
+                             multiSelection={this.props.multiSelection}
+                             disabled={disabled}
+                             termActions={this.props.termActions}
+                             updateTaxonomyTree={this.props.updateTaxonomyTree}
+                             spTermService={this.props.spTermService} />;
               })
             }
           </div>