From 3641e0168f2eb598bb5ca3bde9339c363fd41606 Mon Sep 17 00:00:00 2001
From: Denys Vuika <denys.vuika@gmail.com>
Date: Wed, 6 Mar 2019 14:28:57 +0000
Subject: [PATCH] update evaluator docs, workspace snippet (#995)

* add missing docs and code hints

* update app evaluator docs and code hints
---
 .gitignore                                    |  1 +
 .vscode/typescript.code-snippets              | 19 ++++
 docs/extending/rules.md                       | 48 ++++-----
 src/app/extensions/core.extensions.module.ts  |  1 +
 .../extensions/evaluators/app.evaluators.ts   | 97 +++++++++++++++++++
 .../evaluators/navigation.evaluators.ts       | 72 ++++++++++++++
 .../evaluators/repository.evaluators.ts       |  4 +
 7 files changed, 220 insertions(+), 22 deletions(-)
 create mode 100644 .vscode/typescript.code-snippets

diff --git a/.gitignore b/.gitignore
index a5dfadcc8d..082d3efc13 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,6 +23,7 @@
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json
+!.vscode/*.code-snippets
 .history
 
 # misc
diff --git a/.vscode/typescript.code-snippets b/.vscode/typescript.code-snippets
new file mode 100644
index 0000000000..35f475e7dd
--- /dev/null
+++ b/.vscode/typescript.code-snippets
@@ -0,0 +1,19 @@
+{
+  "ext-evaluator": {
+    "description": "Generate a new evaluator.",
+    "scope": "typescript",
+    "prefix": "ext-evaluator",
+    "body": [
+      "/**",
+      " * Checks if ${2:<description>}.",
+      " * JSON ref: `app.$1`",
+      " */",
+      "export function ${1:name}(",
+      "\tcontext: AppRuleContext,",
+      "\t...args: RuleParameter[]",
+      "): boolean {",
+      "\treturn ${3:true};${0}",
+      "}"
+    ]
+  }
+}
diff --git a/docs/extending/rules.md b/docs/extending/rules.md
index 00076b7cb5..b8ce11fcac 100644
--- a/docs/extending/rules.md
+++ b/docs/extending/rules.md
@@ -140,9 +140,10 @@ The button will be visible only when the linked rule evaluates to `true`.
 | app.selection.first.canUpdate       | User has permission to update selected node(s).              |
 | app.selection.file                  | A single File node is selected.                              |
 | app.selection.file.canShare         | User is able to share the selected file.                     |
-| app.selection.file.isShared         | A shared node is selected                                    |
-| app.selection.file.isLocked         | File is locked for editing                                   |
-| app.selection.file.canUploadVersion | User can update file version                                 |
+| app.selection.file.isShared         | A shared node is selected.                                   |
+| app.selection.file.isLocked         | File is locked for editing.                                  |
+| app.selection.file.isLockOwner      | File is locked and current user is the lock owner.           |
+| app.selection.file.canUploadVersion | User can update file version.                                |
 | app.selection.library               | A single Library node is selected.                           |
 | app.selection.isPrivateLibrary      | A private Library node is selected.                          |
 | app.selection.hasLibraryRole        | The selected Library node has a role property.               |
@@ -164,25 +165,28 @@ for example mixing `core.every` and `core.not`.
 **Tip:** You can also negate any rule by utilizing a `!` prefix:
 `!app.navigation.isTrashcan` is the opposite of the `app.navigation.isTrashcan`.
 
-| Key                               | Description                                             |
-| --------------------------------- | ------------------------------------------------------- |
-| app.navigation.folder.canCreate   | User can create content in the currently opened folder. |
-| app.navigation.folder.canUpload   | User can upload content to the currently opened folder. |
-| app.navigation.isTrashcan         | User is using the **Trashcan** page.                    |
-| app.navigation.isNotTrashcan      | Current page is not a **Trashcan**.                     |
-| app.navigation.isLibraries        | User is using a **Libraries** page.                     |
-| app.navigation.isNotLibraries     | Current page is not a **Libraries** page.               |
-| app.navigation.isSharedFiles      | User is using the **Shared Files** page.                |
-| app.navigation.isNotSharedFiles   | Current page is not **Shared Files**.                   |
-| app.navigation.isFavorites        | User is using the **Favorites** page.                   |
-| app.navigation.isNotFavorites     | Current page is not **Favorites**                       |
-| app.navigation.isRecentFiles      | User is using the **Recent Files** page.                |
-| app.navigation.isNotRecentFiles   | Current page is not **Recent Files**.                   |
-| app.navigation.isSearchResults    | User is using the **Search Results** page.              |
-| app.navigation.isNotSearchResults | Current page is not the **Search Results**.             |
-| app.navigation.isSharedPreview    | Current page is preview **Shared Files**                |
-| app.navigation.isFavoritesPreview | Current page is preview **Favorites**                   |
-| app.navigation.isSharedFileViewer | Current page is shared file preview page                |
+| Key                               | Description                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| app.navigation.folder.canCreate   | User can create content in the currently opened folder.          |
+| app.navigation.folder.canUpload   | User can upload content to the currently opened folder.          |
+| app.navigation.isTrashcan         | User is using the **Trashcan** page.                             |
+| app.navigation.isNotTrashcan      | Current page is not a **Trashcan**.                              |
+| app.navigation.isLibraries        | User is using a **Libraries** or **Library Search Result** page. |
+| app.navigation.isNotLibraries     | Current page is not a **Libraries** page.                        |
+| app.navigation.isSharedFiles      | User is using the **Shared Files** page.                         |
+| app.navigation.isNotSharedFiles   | Current page is not **Shared Files**.                            |
+| app.navigation.isFavorites        | User is using the **Favorites** page.                            |
+| app.navigation.isNotFavorites     | Current page is not **Favorites**.                               |
+| app.navigation.isRecentFiles      | User is using the **Recent Files** page.                         |
+| app.navigation.isNotRecentFiles   | Current page is not **Recent Files**.                            |
+| app.navigation.isSearchResults    | User is using the **Search Results** page.                       |
+| app.navigation.isNotSearchResults | Current page is not the **Search Results**.                      |
+| app.navigation.isSharedPreview    | Current page is preview **Shared Files**.                        |
+| app.navigation.isFavoritesPreview | Current page is preview **Favorites**.                           |
+| app.navigation.isSharedFileViewer | Current page is shared file preview page.                        |
+| app.navigation.isPreview          | Current page is **Preview**.                                     |
+| app.navigation.isPersonalFiles    | Current page is **Personal Files**.                              |
+| app.navigation.isLibraryFiles     | Current page is **Library Files**.                               |
 
 **Tip:** See the [Registration](/extending/registration) section for more details
 on how to register your own entries to be re-used at runtime.
diff --git a/src/app/extensions/core.extensions.module.ts b/src/app/extensions/core.extensions.module.ts
index e69335d460..74a4b64ff5 100644
--- a/src/app/extensions/core.extensions.module.ts
+++ b/src/app/extensions/core.extensions.module.ts
@@ -123,6 +123,7 @@ export class CoreExtensionsModule {
       'app.selection.file.canShare': app.canShareFile,
       'app.selection.file.isShared': app.isShared,
       'app.selection.file.isLocked': app.hasLockedFiles,
+      'app.selection.file.isLockOwner': app.isUserWriteLockOwner,
       'app.selection.file.canUploadVersion': app.canUploadVersion,
       'app.selection.library': app.hasLibrarySelected,
       'app.selection.isPrivateLibrary': app.isPrivateLibrary,
diff --git a/src/app/extensions/evaluators/app.evaluators.ts b/src/app/extensions/evaluators/app.evaluators.ts
index 0d3577b657..2a65a530f9 100644
--- a/src/app/extensions/evaluators/app.evaluators.ts
+++ b/src/app/extensions/evaluators/app.evaluators.ts
@@ -36,6 +36,10 @@ import {
   isPreview
 } from './navigation.evaluators';
 
+/**
+ * Checks if user can mark selected nodes as **Favorite**.
+ * JSON ref: `app.selection.canAddFavorite`
+ */
 export function canAddFavorite(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -53,6 +57,10 @@ export function canAddFavorite(
   return false;
 }
 
+/**
+ * Checks if user can un-mark selected nodes as **Favorite**.
+ * JSON ref: `app.selection.canRemoveFavorite`
+ */
 export function canRemoveFavorite(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -66,6 +74,10 @@ export function canRemoveFavorite(
   return false;
 }
 
+/**
+ * Checks if user can share selected file.
+ * JSON ref: `app.selection.file.canShare`
+ */
 export function canShareFile(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -76,6 +88,10 @@ export function canShareFile(
   return false;
 }
 
+/**
+ * Checks if the selected file is already shared.
+ * JSON ref: `app.selection.file.isShared`
+ */
 export function isShared(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -98,6 +114,10 @@ export function isShared(
   return false;
 }
 
+/**
+ * Checks if user can delete selected nodes.
+ * JSON ref: `app.selection.canDelete`
+ */
 export function canDeleteSelection(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -133,6 +153,10 @@ export function canDeleteSelection(
   return false;
 }
 
+/**
+ * Checks if user can un-share selected nodes.
+ * JSON ref: `app.selection.canUnshare`
+ */
 export function canUnshareNodes(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -145,6 +169,10 @@ export function canUnshareNodes(
   return false;
 }
 
+/**
+ * Checks if user selected anything.
+ * JSON ref: `app.selection.notEmpty`
+ */
 export function hasSelection(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -152,6 +180,10 @@ export function hasSelection(
   return !context.selection.isEmpty;
 }
 
+/**
+ * Checks if user can create a new folder with current path.
+ * JSON ref: `app.navigation.folder.canCreate`
+ */
 export function canCreateFolder(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -163,6 +195,10 @@ export function canCreateFolder(
   return false;
 }
 
+/**
+ * Checks if user can upload content to current folder.
+ * JSON ref: `app.navigation.folder.canUpload`
+ */
 export function canUpload(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -174,6 +210,10 @@ export function canUpload(
   return false;
 }
 
+/**
+ * Checks if user can download selected nodes (either files or folders).
+ * JSON ref: `app.selection.canDownload`
+ */
 export function canDownloadSelection(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -189,6 +229,10 @@ export function canDownloadSelection(
   return false;
 }
 
+/**
+ * Checks if user has selected a folder.
+ * JSON ref: `app.selection.folder`
+ */
 export function hasFolderSelected(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -197,6 +241,10 @@ export function hasFolderSelected(
   return folder ? true : false;
 }
 
+/**
+ * Checks if user has selected a library (site).
+ * JSON ref: `app.selection.library`
+ */
 export function hasLibrarySelected(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -205,6 +253,10 @@ export function hasLibrarySelected(
   return library ? true : false;
 }
 
+/**
+ * Checks if user has selected a **private** library (site)
+ * JSON ref: `app.selection.isPrivateLibrary`
+ */
 export function isPrivateLibrary(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -219,6 +271,10 @@ export function isPrivateLibrary(
     : false;
 }
 
+/**
+ * Checks if the selected library has a **role** property defined.
+ * JSON ref: `app.selection.hasLibraryRole`
+ */
 export function hasLibraryRole(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -227,6 +283,10 @@ export function hasLibraryRole(
   return library ? !!(library.entry && library.entry.role) : false;
 }
 
+/**
+ * Checks if the selected library has no **role** property defined.
+ * JSON ref: `app.selection.hasNoLibraryRole`
+ */
 export function hasNoLibraryRole(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -234,6 +294,10 @@ export function hasNoLibraryRole(
   return !hasLibraryRole(context, ...args);
 }
 
+/**
+ * Checks if user has selected a file.
+ * JSON ref: `app.selection.file`
+ */
 export function hasFileSelected(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -242,6 +306,10 @@ export function hasFileSelected(
   return file ? true : false;
 }
 
+/**
+ * Checks if user can update the first selected node.
+ * JSON ref: `app.selection.first.canUpdate`
+ */
 export function canUpdateSelectedNode(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -264,6 +332,10 @@ export function canUpdateSelectedNode(
   return false;
 }
 
+/**
+ * Checks if user can update the first selected folder.
+ * JSON ref: `app.selection.folder.canUpdate`
+ */
 export function canUpdateSelectedFolder(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -279,6 +351,10 @@ export function canUpdateSelectedFolder(
   return false;
 }
 
+/**
+ * Checks if user has selected a **locked** file node.
+ * JSON ref: `app.selection.file.isLocked`
+ */
 export function hasLockedFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -300,6 +376,10 @@ export function hasLockedFiles(
   return false;
 }
 
+/**
+ * Checks if the selected file has **write** or **read-only** locks specified.
+ * JSON ref: `app.selection.file.isLocked`
+ */
 export function isWriteLocked(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -316,6 +396,11 @@ export function isWriteLocked(
   );
 }
 
+/**
+ * Checks if the selected file has **write** or **read-only** locks specified,
+ * and that current user is the owner of the lock.
+ * JSON ref: `app.selection.file.isLockOwner`
+ */
 export function isUserWriteLockOwner(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -328,6 +413,10 @@ export function isUserWriteLockOwner(
   );
 }
 
+/**
+ * Checks if user can lock selected file.
+ * JSON ref: `app.selection.file.canLock`
+ */
 export function canLockFile(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -337,6 +426,10 @@ export function canLockFile(
   );
 }
 
+/**
+ * Checks if user can unlock selected file.
+ * JSON ref: `app.selection.file.canLock`
+ */
 export function canUnlockFile(
   context: AppRuleContext,
   ...args: RuleParameter[]
@@ -349,6 +442,10 @@ export function canUnlockFile(
   );
 }
 
+/**
+ * Checks if user can upload a new version of the file.
+ * JSON ref: `app.selection.file.canUploadVersion`
+ */
 export function canUploadVersion(
   context: AppRuleContext,
   ...args: RuleParameter[]
diff --git a/src/app/extensions/evaluators/navigation.evaluators.ts b/src/app/extensions/evaluators/navigation.evaluators.ts
index e21d25a7b3..137d0bbc8a 100644
--- a/src/app/extensions/evaluators/navigation.evaluators.ts
+++ b/src/app/extensions/evaluators/navigation.evaluators.ts
@@ -25,6 +25,10 @@
 
 import { RuleContext, RuleParameter } from '@alfresco/adf-extensions';
 
+/**
+ * Checks if a Preview route is activated.
+ * JSON ref: `app.navigation.isPreview`
+ */
 export function isPreview(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -33,6 +37,10 @@ export function isPreview(
   return url && url.includes('/preview/');
 }
 
+/**
+ * Checks if a **Favorites** route is activated.
+ * JSON ref: `app.navigation.isFavorites`
+ */
 export function isFavorites(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -41,6 +49,10 @@ export function isFavorites(
   return url && url.startsWith('/favorites') && !isPreview(context, ...args);
 }
 
+/**
+ * Checks if the activated route is not **Favorites**.
+ * JSON ref: `app.navigation.isNotFavorites`
+ */
 export function isNotFavorites(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -48,6 +60,10 @@ export function isNotFavorites(
   return !isFavorites(context, ...args);
 }
 
+/**
+ * Checks if a **Shared Files** route is activated.
+ * JSON ref: `app.navigation.isSharedFiles`
+ */
 export function isSharedFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -56,6 +72,10 @@ export function isSharedFiles(
   return url && url.startsWith('/shared') && !isPreview(context, ...args);
 }
 
+/**
+ * Checks if the activated route is not **Shared Files**.
+ * JSON ref: `app.navigation.isNotSharedFiles`
+ */
 export function isNotSharedFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -63,6 +83,10 @@ export function isNotSharedFiles(
   return !isSharedFiles(context, ...args);
 }
 
+/**
+ * Checks if a **Trashcan** route is activated.
+ * JSON ref: `app.navigation.isTrashcan`
+ */
 export function isTrashcan(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -71,6 +95,10 @@ export function isTrashcan(
   return url && url.startsWith('/trashcan');
 }
 
+/**
+ * Checks if the activated route is not **Trashcan**.
+ * JSON ref: `app.navigation.isNotTrashcan`
+ */
 export function isNotTrashcan(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -78,6 +106,10 @@ export function isNotTrashcan(
   return !isTrashcan(context, ...args);
 }
 
+/**
+ * Checks if a **Personal Files** route is activated.
+ * JSON ref: `app.navigation.isPersonalFiles`
+ */
 export function isPersonalFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -86,6 +118,10 @@ export function isPersonalFiles(
   return url && url.startsWith('/personal-files');
 }
 
+/**
+ * Checks if a **Library Files** route is activated.
+ * JSON ref: `app.navigation.isLibraryFiles`
+ */
 export function isLibraryFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -94,6 +130,10 @@ export function isLibraryFiles(
   return url && url.startsWith('/libraries');
 }
 
+/**
+ * Checks if a **Library Files** or **Library Search Result** route is activated.
+ * JSON ref: `app.navigation.isLibraryFiles`
+ */
 export function isLibraries(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -104,6 +144,10 @@ export function isLibraries(
   );
 }
 
+/**
+ * Checks if the activated route is neither **Libraries** nor **Library Search Results**.
+ * JSON ref: `app.navigation.isNotLibraries`
+ */
 export function isNotLibraries(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -111,6 +155,10 @@ export function isNotLibraries(
   return !isLibraries(context, ...args);
 }
 
+/**
+ * Checks if a **Recent Files** route is activated.
+ * JSON ref: `app.navigation.isRecentFiles`
+ */
 export function isRecentFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -119,6 +167,10 @@ export function isRecentFiles(
   return url && url.startsWith('/recent-files');
 }
 
+/**
+ * Checks if the activated route is not **Recent Files**.
+ * JSON ref: `app.navigation.isNotRecentFiles`
+ */
 export function isNotRecentFiles(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -126,6 +178,10 @@ export function isNotRecentFiles(
   return !isRecentFiles(context, ...args);
 }
 
+/**
+ * Checks if a **Search Results** route is activated.
+ * JSON ref: `app.navigation.isSearchResults`
+ */
 export function isSearchResults(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -134,6 +190,10 @@ export function isSearchResults(
   return url && url.startsWith('/search');
 }
 
+/**
+ * Checks if the activated route is not **Search Results**.
+ * JSON ref: `app.navigation.isNotSearchResults`
+ */
 export function isNotSearchResults(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -141,6 +201,10 @@ export function isNotSearchResults(
   return !isSearchResults(context, ...args);
 }
 
+/**
+ * Checks if a **Shared Preview** route is activated.
+ * JSON ref: `app.navigation.isSharedPreview`
+ */
 export function isSharedPreview(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -149,6 +213,10 @@ export function isSharedPreview(
   return url && url.startsWith('/shared/preview/');
 }
 
+/**
+ * Checks if a **Favorites Preview** route is activated.
+ * JSON ref: `app.navigation.isFavoritesPreview`
+ */
 export function isFavoritesPreview(
   context: RuleContext,
   ...args: RuleParameter[]
@@ -157,6 +225,10 @@ export function isFavoritesPreview(
   return url && url.startsWith('/favorites/preview/');
 }
 
+/**
+ * Checks if a **Shared File Preview** route is activated.
+ * JSON ref: `app.navigation.isFavoritesPreview`
+ */
 export function isSharedFileViewer(
   context: RuleContext,
   ...args: RuleParameter[]
diff --git a/src/app/extensions/evaluators/repository.evaluators.ts b/src/app/extensions/evaluators/repository.evaluators.ts
index b03cb9a55e..9d2d2c1e7b 100644
--- a/src/app/extensions/evaluators/repository.evaluators.ts
+++ b/src/app/extensions/evaluators/repository.evaluators.ts
@@ -26,6 +26,10 @@
 import { RuleParameter } from '@alfresco/adf-extensions';
 import { AppRuleContext } from '../app.interface';
 
+/**
+ * Checks if the quick share repository option is enabled or not.
+ * JSON ref: `repository.isQuickShareEnabled`
+ */
 export function hasQuickShareEnabled(
   context: AppRuleContext,
   ...args: RuleParameter[]