#235 - documentation updates + code refactoring

Author: estruyf

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

@@ -34,16 +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}
-  termActions={termActions}
-/>
+<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:
@@ -54,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:
@@ -89,17 +131,38 @@ Interface `IPickerTerms`
 An Array of IPickerTerm
 
 Interface `ITermActions`
-| Property | Type | Required | Description |
-| ---- | ---- | ---- | ---- |
-| actions | ITermAction[] | yes | The array of supported actions |
-| termActionsDisplayStyle | TermActionsDisplayStyle | no | Defines how to display term action button, available options: text (default), icon, text and icon |
-| termActionsDisplayMode | TermActionsDisplayMode | no | Defines how to display term actions, as buttons (default) or dropdown |
+
+| 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 |
-| displayText | string | no | Name of the 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

@@ -3,6 +3,7 @@ import { IPickerTerms } from './ITermPicker';
 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
@@ -108,8 +109,9 @@ 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;
@@ -127,6 +129,7 @@ export interface ITermProps extends ITermChanges {
   multiSelection: boolean;
   disabled: boolean;
   termActions?: ITermActions;
+  spTermService: SPTermStorePickerService;
 
   updateTaxonomyTree: () => void;
 }

src/controls/taxonomyPicker/ITaxonomyPicker.ts

@@ -8,7 +8,6 @@ import { IPickerTerms, IPickerTerm } from './ITermPicker';
 import { ITaxonomyPickerProps, ITaxonomyPickerState } from './ITaxonomyPicker';
 import SPTermStorePickerService from './../../services/SPTermStorePickerService';
 import { ITermSet, ITerm } from './../../services/ISPTermStorePickerService';
-import { TermLabelAction, ITermActions } from './termActions';
 
 import styles from './TaxonomyPicker.module.scss';
 import { sortBy, uniqBy, cloneDeep, isEqual } from '@microsoft/sp-lodash-subset';
@@ -84,11 +83,13 @@ 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.actions.map(x => {
-        x.initialize(this.termsService);
-      });
+    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
       let termSetAndTerms = response ? response : null;
@@ -316,6 +317,7 @@ export class TaxonomyPicker extends React.Component<ITaxonomyPickerProps, ITaxon
                             disableChildrenOfDisabledParents={this.props.disableChildrenOfDisabledParents}
                             changedCallback={this.termsChanged}
                             multiSelection={this.props.allowMultipleSelections}
+                            spTermService={this.termsService}
 
                             updateTaxonomyTree={this.updateTaxonomyTree}
                             termActions={this.props.termActions}

src/controls/taxonomyPicker/TaxonomyPicker.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Checkbox, ICheckboxStyles } from 'office-ui-fabric-react/lib/Checkbox';
+import { Checkbox } from 'office-ui-fabric-react/lib/Checkbox';
 import { ITermProps, ITermState } from './ITaxonomyPicker';
 
 import styles from './TaxonomyPicker.module.scss';
@@ -12,6 +12,7 @@ import { UpdateAction, UpdateType } from './termActions';
  * Renders a selectable term
  */
 export default class Term extends React.Component<ITermProps, ITermState> {
+
   constructor(props: ITermProps) {
     super(props);
 
@@ -108,7 +109,10 @@ export default class Term extends React.Component<ITermProps, ITermState> {
           </div>
           {
             this.props.termActions &&
-            <TermActionsControl term={this.props.term} termActions={this.props.termActions} termActionCallback={this.termActionCallback} />
+            <TermActionsControl term={this.props.term}
+                                termActions={this.props.termActions}
+                                termActionCallback={this.termActionCallback}
+                                spTermService={this.props.spTermService} />
           }
         </div>
       </div>

src/controls/taxonomyPicker/Term.tsx

@@ -106,10 +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}
-                                  termActions={this.props.termActions} updateTaxonomyTree={this.props.updateTaxonomyTree}/>;
+                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>

src/controls/taxonomyPicker/TermParent.tsx

@@ -1,26 +1,30 @@
 import * as React from 'react';
 import { CommandBarButton } from 'office-ui-fabric-react/lib/Button';
-import { ITermAction, TermActionsDisplayStyle, IConreteTermActionProps } from './ITermsActions';
+import { ITermAction, TermActionsDisplayStyle, IConcreteTermActionProps } from './ITermsActions';
 
-export default class ButtonTermAction extends React.Component<IConreteTermActionProps> {
-  public render(): React.ReactElement<IConreteTermActionProps> {
+export default class ButtonTermAction extends React.Component<IConcreteTermActionProps> {
+  public render(): React.ReactElement<IConcreteTermActionProps> {
     const { term, termActions } = this.props;
 
     return (
       <div style={{ display: 'flex', alignItems: 'stretch', height: '32px' }}>
         {
           termActions &&
           termActions.map(termAction => {
-            const { name, text, iconName } = this._prepareCommandBarButton(termAction);
+            const { name, text, iconName, btnTitle } = this._prepareCommandBarButton(termAction);
             return (
               <div>
                 <CommandBarButton split={true}
-                  onClick={() => { this._onActionExecute(termAction); }}
-                  iconProps={{ iconName: iconName }}
-                  text={text}
-                  name={name}
-                  key={term.Id}
-                  style={this._getTermActionActionButtonStyle()}
+                                  onClick={() => { this._onActionExecute(termAction); }}
+                                  iconProps={{
+                                    iconName: iconName || null,
+                                    style: { display: iconName ? null : "none"}
+                                  }}
+                                  text={text}
+                                  title={btnTitle}
+                                  name={name}
+                                  key={term.Id}
+                                  style={this._getTermActionActionButtonStyle()}
                 />
               </div>
             );
@@ -31,32 +35,37 @@ export default class ButtonTermAction extends React.Component<IConreteTermAction
   }
 
 
-  private _prepareCommandBarButton = (termAction: ITermAction): { name: string, text: string, iconName: string } => {
-    let name, text, iconName = "";
+  private _prepareCommandBarButton = (termAction: ITermAction): { name: string, text: string, iconName: string, btnTitle: string } => {
+    let name: string = "";
+    let text: string = "";
+    let iconName: string = "";
+    let btnTitle: string = "";
 
-    if (this.props.displayStyle && (this.props.displayStyle === TermActionsDisplayStyle.text || this.props.displayStyle === TermActionsDisplayStyle.textAndIcon)) {
-      name = termAction.displayText;
-      text = termAction.displayText;
+    if ((this.props.displayStyle && (this.props.displayStyle === TermActionsDisplayStyle.text || this.props.displayStyle === TermActionsDisplayStyle.textAndIcon))) {
+      name = termAction.title;
+      text = termAction.title;
     }
     if (this.props.displayStyle && (this.props.displayStyle === TermActionsDisplayStyle.icon || this.props.displayStyle === TermActionsDisplayStyle.textAndIcon)) {
       iconName = termAction.iconName;
     }
 
-    return { name, text, iconName };
+    btnTitle = termAction.title;
+
+    return { name, text, iconName, btnTitle };
   }
 
   private _getTermActionActionButtonStyle = (): React.CSSProperties => {
     let result: React.CSSProperties = {
       backgroundColor: "transparent",
-      width: "32px",
+      width: this.props.displayStyle === TermActionsDisplayStyle.icon ? "32px" : null,
       height: "32px"
     };
 
     return result;
   }
 
   private _onActionExecute = async (termAction: ITermAction) => {
-    const updateAction = await termAction.actionCallback(this.props.term);
+    const updateAction = await termAction.actionCallback(this.props.spTermService, this.props.term);
     this.props.termActionCallback(updateAction);
   }
 }

src/controls/taxonomyPicker/termActions/ButtonTermAction.tsx

@@ -1,11 +1,11 @@
 import * as React from 'react';
 import { DefaultButton } from 'office-ui-fabric-react/lib/Button';
 import { ITerm } from '../../../services/ISPTermStorePickerService';
-import { ITermAction, TermActionsDisplayStyle, UpdateAction, IConreteTermActionProps } from './ITermsActions';
+import { ITermAction, TermActionsDisplayStyle, IConcreteTermActionProps } from './ITermsActions';
 import { IContextualMenuItem, IContextualMenuProps } from 'office-ui-fabric-react/lib/ContextualMenu';
 
-export class DropdownTermAction extends React.Component<IConreteTermActionProps> {
-  public render(): React.ReactElement<IConreteTermActionProps> {
+export class DropdownTermAction extends React.Component<IConcreteTermActionProps> {
+  public render(): React.ReactElement<IConcreteTermActionProps> {
     const { term, termActions } = this.props;
 
     const termActionButtonStyle = this._getTermActionActionButtonStyle();
@@ -33,8 +33,8 @@ export class DropdownTermAction extends React.Component<IConreteTermActionProps>
       };
 
       if (displayStyle && (displayStyle === TermActionsDisplayStyle.text || displayStyle === TermActionsDisplayStyle.textAndIcon)) {
-        termActionMenuItem.text = termAction.displayText;
-        termActionMenuItem.name = termAction.displayText;
+        termActionMenuItem.text = termAction.title;
+        termActionMenuItem.name = termAction.title;
         useTargetWidth = false;
       }
       if (displayStyle && (displayStyle === TermActionsDisplayStyle.icon || displayStyle === TermActionsDisplayStyle.textAndIcon)) {
@@ -69,7 +69,7 @@ export class DropdownTermAction extends React.Component<IConreteTermActionProps>
    * Handler to execute selected action.
    */
   private _onActionExecute = async (termAction: ITermAction) => {
-    const updateAction = await termAction.actionCallback(this.props.term);
+    const updateAction = await termAction.actionCallback(this.props.spTermService, this.props.term);
     this.props.termActionCallback(updateAction);
   }
 }