apostrophe 3.40.2-alpha → 3.41.0

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## UNRELEASED
+## 3.41.0 (2023-03-06)
+
+### Adds
+
+* Handle external conditions to display fields according to the result of a module method, or multiple methods from different modules.  
+This can be useful for displaying fields according to the result of an external API or any business logic run on the server.
 
 ### Fixes
 

package/modules/@apostrophecms/doc/index.js

@@ -1014,7 +1014,7 @@ module.exports = {
       // }
       // All properties are required.
       // The only supported `context` for now is `update`.
-      // `action` is the operation idefntifier and should be globally unique.
+      // `action` is the operation identifier and should be globally unique.
       // Overriding existing custom actions is possible (the last wins).
       // `modal` is the name of the modal component to be opened.
       // `label` is the menu label to be shown when expanding the context menu.

package/modules/@apostrophecms/i18n/i18n/en.json

@@ -149,6 +149,7 @@
   "errorCount": "{{ count }} error remaining",
   "errorCount_plural": "{{ count }} errors remaining",
   "errorCreatingNewContent": "Error while creating new, empty content.",
+  "errorEvaluatingExternalCondition": "An error occurred while evaluating the external condition for the field \"{{ name }}\"",
   "errorFetchingTitleFieldChoicesByMethod": "An error occurred while fetching the choices for the titleField {{ name }}",
   "errorWhileRestoring": "An error occurred while restoring the previously published version.",
   "errorWhileUnpublishing": "An error occurred while unpublishing the document.",

package/modules/@apostrophecms/modal/ui/apos/mixins/AposEditorMixin.js

@@ -24,7 +24,8 @@ export default {
       },
       serverErrors: null,
       restoreOnly: false,
-      changed: []
+      changed: [],
+      externalConditionsResults: {}
     };
   },
 
@@ -43,7 +44,91 @@ export default {
     }
   },
 
+  watch: {
+    docType: {
+      // Evaluate external conditions found in current page-type's schema
+      async handler() {
+        if (this.moduleName === '@apostrophecms/page') {
+          await this.evaluateExternalConditions();
+        }
+      }
+    }
+  },
+
+  async created() {
+    await this.evaluateExternalConditions();
+  },
+
   methods: {
+    // Evaluate the external conditions found in each field
+    // via API calls -made in parallel for performance-
+    // and store their result for reusability.
+    async evaluateExternalConditions() {
+      const self = this;
+      for (const field of this.schema) {
+        if (field.if) {
+          const externalConditionKeys = Object
+            .entries(field.if)
+            .flatMap(getExternalConditionKeys)
+            .filter(Boolean);
+
+          const uniqExternalConditionKeys = [ ...new Set(externalConditionKeys) ];
+
+          let results = [];
+
+          try {
+            const docOrContextDocId = this.docId || this.docFields.data._docId;
+            const promises = uniqExternalConditionKeys
+              .map(key => this.externalConditionsResults[key] !== undefined
+                ? null
+                : this.evaluateExternalCondition(key, field._id, docOrContextDocId)
+              )
+              .filter(Boolean);
+
+            results = await Promise.all(promises);
+
+            this.externalConditionsResults = {
+              ...this.externalConditionsResults,
+              ...Object.fromEntries(results)
+            };
+          } catch (error) {
+            await apos.notify(this.$t('apostrophe:errorEvaluatingExternalCondition', { name: field.name }), {
+              type: 'danger',
+              icon: 'alert-circle-icon',
+              dismiss: true,
+              localize: false
+            });
+          }
+        }
+      }
+
+      function getExternalConditionKeys([ key, val ]) {
+        if (key === '$or') {
+          return val.flatMap(nested => Object.entries(nested).map(getExternalConditionKeys));
+        }
+        if (self.isExternalCondition(key)) {
+          return key;
+        }
+        return null;
+      }
+    },
+
+    async evaluateExternalCondition(conditionKey, fieldId, docId) {
+      const response = await apos.http.get(
+        `${apos.schema.action}/evaluate-external-condition`,
+        {
+          qs: {
+            fieldId,
+            docId,
+            conditionKey
+          },
+          busy: true
+        }
+      );
+
+      return [ conditionKey, response ];
+    },
+
     // followedByCategory may be falsy (all fields), "other" or "utility". The returned
     // object contains properties named for each field in that category that
     // follows other fields. For instance if followedBy is "utility" then in our
@@ -93,8 +178,22 @@ export default {
     // in that category, although they may be conditional upon fields in either
     // category.
 
-    conditionalFields(followedByCategory) {
+    // Checking if key ends with a closing parenthesis here to throw later if any argument is passed.
+    isExternalCondition(conditionKey) {
+      if (!conditionKey.endsWith(')')) {
+        return false;
+      }
+
+      const [ methodDefinition ] = conditionKey.split('(');
+
+      if (!conditionKey.endsWith('()')) {
+        console.warn(`Warning in \`if\` definition: "${methodDefinition}()" should not be passed any argument.`);
+      }
 
+      return true;
+    },
+
+    conditionalFields(followedByCategory) {
       const self = this;
       const conditionalFields = {};
 
@@ -128,8 +227,26 @@ export default {
         let result = true;
         for (const [ key, val ] of Object.entries(clause)) {
           if (key === '$or') {
-            return val.some(clause => evaluate(clause));
+            if (!val.some(clause => evaluate(clause))) {
+              result = false;
+              break;
+            }
+
+            // No need to go further here, the key is an "$or" condition...
+            continue;
           }
+
+          if (self.isExternalCondition(key)) {
+            if (self.externalConditionsResults[key] !== val) {
+              result = false;
+              break;
+            }
+
+            // Stop there, this is an external condition thus
+            // does not need to be checked against doc fields.
+            continue;
+          }
+
           if (conditionalFields[key] === false) {
             result = false;
             break;
@@ -145,7 +262,6 @@ export default {
         }
         return result;
       }
-
     },
 
     // Overridden by components that split the fields into several AposSchemas

package/modules/@apostrophecms/schema/index.js

@@ -487,18 +487,21 @@ module.exports = {
           throw new Error('convert invoked without a req, do you have one in your context?');
         }
 
-        let errors = [];
+        const errors = [];
 
         for (const field of schema) {
           if (field.readOnly) {
             continue;
           }
+
           // Fields that are contextual are left alone, not blanked out, if
           // they do not appear at all in the data object.
           if (field.contextual && !_.has(data, field.name)) {
             continue;
           }
-          const convert = self.fieldTypes[field.type].convert;
+
+          const { convert } = self.fieldTypes[field.type];
+
           if (convert) {
             try {
               await convert(req, field, data, destination);
@@ -520,15 +523,21 @@ module.exports = {
           }
         }
 
-        errors = errors.filter(error => {
-          if ((error.name === 'required' || error.name === 'mandatory') && !self.isVisible(schema, destination, error.path)) {
+        const errorsList = [];
+
+        for (const error of errors) {
+          const isVisible = await self.isVisible(req, schema, destination, error.path);
+
+          if ((error.name === 'required' || error.name === 'mandatory') && !isVisible) {
             // It is not reasonable to enforce required for
             // fields hidden via conditional fields
-            return false;
+            continue;
           }
-          return true;
-        });
-        if (errors.length) {
+
+          errorsList.push(error);
+        }
+
+        if (errorsList.length) {
           throw errors;
         }
       },
@@ -536,13 +545,13 @@ module.exports = {
       // Determine whether the given field is visible
       // based on `if` conditions of all fields
 
-      isVisible(schema, object, name) {
+      async isVisible(req, schema, object, name) {
         const conditionalFields = {};
         while (true) {
           let change = false;
           for (const field of schema) {
             if (field.if) {
-              const result = evaluate(field.if);
+              const result = await evaluate(field.if, field.name, field.moduleName);
               const previous = conditionalFields[field.name];
               if (previous !== result) {
                 change = true;
@@ -559,12 +568,38 @@ module.exports = {
         } else {
           return true;
         }
-        function evaluate(clause) {
+        async function evaluate(clause, fieldName, fieldModuleName) {
           let result = true;
           for (const [ key, val ] of Object.entries(clause)) {
             if (key === '$or') {
-              return val.some(clause => evaluate(clause));
+              const results = await Promise.all(val.map(clause => evaluate(clause, fieldName, fieldModuleName)));
+
+              if (!results.some(({ value }) => value)) {
+                result = false;
+                break;
+              }
+
+              // No need to go further here, the key is an "$or" condition...
+              continue;
+            }
+
+            // Handle external conditions:
+            //  - `if: { 'methodName()': true }`
+            //  - `if: { 'moduleName:methodName()': 'expected value' }`
+            // Checking if key ends with a closing parenthesis here to throw later if any argument is passed.
+            if (key.endsWith(')')) {
+              const externalConditionResult = await self.evaluateExternalCondition(req, key, fieldName, fieldModuleName, object._id);
+
+              if (externalConditionResult !== val) {
+                result = false;
+                break;
+              };
+
+              // Stop there, this is an external condition thus
+              // does not need to be checked against doc fields.
+              continue;
             }
+
             if (conditionalFields[key] === false) {
               result = false;
               break;
@@ -578,6 +613,28 @@ module.exports = {
         }
       },
 
+      async evaluateExternalCondition(req, conditionKey, fieldName, fieldModuleName, docId = null) {
+        const [ methodDefinition ] = conditionKey.split('(');
+
+        if (!conditionKey.endsWith('()')) {
+          self.apos.util.warn(`Warning in the \`if\` definition of the "${fieldName}" field: "${methodDefinition}()" should not be passed any argument.`);
+        }
+
+        const [ methodName, moduleName = fieldModuleName ] = methodDefinition
+          .split(':')
+          .reverse();
+
+        const module = self.apos.modules[moduleName];
+
+        if (!module) {
+          throw new Error(`Error in the \`if\` definition of the "${fieldName}" field: "${moduleName}" module not found.`);
+        } else if (!module[methodName]) {
+          throw new Error(`Error in the \`if\` definition of the "${fieldName}" field: "${methodName}" method not found in "${moduleName}" module.`);
+        }
+
+        return module[methodName](req, { docId });
+      },
+
       // Driver invoked by the "relationship" methods of the standard
       // relationship field types.
       //
@@ -1493,6 +1550,20 @@ module.exports = {
           } else {
             throw self.apos.error('invalid', `The method ${field.choices} from the module ${field.moduleName} did not return an array`);
           }
+        },
+        async evaluateExternalCondition(req) {
+          const fieldId = self.apos.launder.string(req.query.fieldId);
+          const docId = self.apos.launder.string(req.query.docId, null);
+          const conditionKey = self.apos.launder.string(req.query.conditionKey);
+
+          const field = self.getFieldById(fieldId);
+
+          try {
+            const result = await self.evaluateExternalCondition(req, conditionKey, field.name, field.moduleName, docId);
+            return result;
+          } catch (error) {
+            throw self.apos.error('invalid', error.message);
+          }
         }
       }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apostrophe",
-  "version": "3.40.2-alpha",
+  "version": "3.41.0",
   "description": "The Apostrophe Content Management System.",
   "main": "index.js",
   "scripts": {

package/test/schemas.js

@@ -235,6 +235,8 @@ const hasAreaWithoutWidgets = {
   ]
 };
 
+const warnMessages = [];
+
 describe('Schemas', function() {
 
   this.timeout(t.timeout);
@@ -249,7 +251,31 @@ describe('Schemas', function() {
 
   it('should be a property of the apos object', async function() {
     apos = await t.create({
-      root: module
+      root: module,
+      modules: {
+        '@apostrophecms/util': {
+          extendMethods() {
+            return {
+              warn(_super, ...args) {
+                warnMessages.push(...args);
+                return _super(...args);
+              }
+            };
+          }
+        },
+        'external-condition': {
+          methods() {
+            return {
+              async externalCondition() {
+                return 'yes';
+              },
+              async externalCondition2(req, { docId }) {
+                return `yes - ${req.someReqAttr} - ${docId}`;
+              }
+            };
+          }
+        }
+      }
     });
     assert(apos.schema);
     apos.argv._ = [];
@@ -1805,6 +1831,163 @@ describe('Schemas', function() {
     }, 'age', 'required');
   });
 
+  it('should ignore required property when external condition does not match', async function() {
+    const req = apos.task.getReq();
+    const schema = apos.schema.compose({
+      addFields: [
+        {
+          name: 'age',
+          type: 'integer',
+          required: true,
+          if: {
+            'external-condition:externalCondition()': 'no'
+          }
+        },
+        {
+          name: 'shoeSize',
+          type: 'integer',
+          required: false
+        }
+      ]
+    });
+    const output = {};
+    await apos.schema.convert(req, schema, {
+      shoeSize: 20
+    }, output);
+    assert(output.shoeSize === 20);
+  });
+
+  it('should enforce required property when external condition matches', async function() {
+    const schema = apos.schema.compose({
+      addFields: [
+        {
+          name: 'age',
+          type: 'integer',
+          required: true,
+          if: {
+            'external-condition:externalCondition()': 'yes'
+          }
+        }
+      ]
+    });
+
+    await testSchemaError(schema, {}, 'age', 'required');
+  });
+
+  it('should use the field module name by default when the external condition key does not contain it', async function() {
+    const req = apos.task.getReq();
+    const conditionKey = 'externalCondition()';
+    const fieldName = 'someField';
+    const fieldModuleName = 'external-condition';
+    const docId = 'some-doc-id';
+
+    const result = await apos.schema.evaluateExternalCondition(req, conditionKey, fieldName, fieldModuleName, docId);
+
+    assert(result === 'yes');
+  });
+
+  it('should pass req and the doc ID to the external condition method', async function() {
+    const someReqAttr = 'some-attribute-on-req';
+    const req = apos.task.getReq({
+      someReqAttr
+    });
+    const conditionKey = 'external-condition:externalCondition2()';
+    const fieldName = 'someField';
+    const fieldModuleName = 'external-condition';
+    const docId = 'some-doc-id';
+
+    const result = await apos.schema.evaluateExternalCondition(req, conditionKey, fieldName, fieldModuleName, docId);
+
+    assert(result === `yes - ${someReqAttr} - ${docId}`);
+  });
+
+  it('should warn when an argument is passed in the external condition key', async function() {
+    const req = apos.task.getReq();
+    const conditionKey = 'external-condition:externalCondition(letsNotArgue)';
+    const fieldName = 'someField';
+    const fieldModuleName = 'external-condition';
+    const docId = 'some-doc-id';
+
+    const result = await apos.schema.evaluateExternalCondition(req, conditionKey, fieldName, fieldModuleName, docId);
+
+    assert(warnMessages.includes('Warning in the `if` definition of the "someField" field: "external-condition:externalCondition()" should not be passed any argument.'));
+    assert(result === 'yes');
+  });
+
+  it('should throw when the module defined in the external condition key is not found', async function() {
+    const req = apos.task.getReq();
+    const conditionKey = 'unknown-module:externalCondition()';
+    const fieldName = 'someField';
+    const fieldModuleName = 'unknown-module';
+    const docId = 'some-doc-id';
+
+    try {
+      await apos.schema.evaluateExternalCondition(req, conditionKey, fieldName, fieldModuleName, docId);
+    } catch (error) {
+      assert(error.message === 'Error in the `if` definition of the "someField" field: "unknown-module" module not found.');
+      return;
+    }
+    throw new Error('should have thrown');
+  });
+
+  it('should throw when the method defined in the external condition key is not found', async function() {
+    const req = apos.task.getReq();
+    const conditionKey = 'external-condition:unknownMethod()';
+    const fieldName = 'someField';
+    const fieldModuleName = 'external-condition';
+    const docId = 'some-doc-id';
+
+    try {
+      await apos.schema.evaluateExternalCondition(req, conditionKey, fieldName, fieldModuleName, docId);
+    } catch (error) {
+      assert(error.message === 'Error in the `if` definition of the "someField" field: "unknownMethod" method not found in "external-condition" module.');
+      return;
+    }
+    throw new Error('should have thrown');
+  });
+
+  it('should call the evaluate-external-condition API successfully', async function() {
+    apos.schema.fieldsById['some-field-id'] = {
+      name: 'someField',
+      moduleName: 'external-condition'
+    };
+
+    const res = await apos.http.get('/api/v1/@apostrophecms/schema/evaluate-external-condition?fieldId=some-field-id&docId=some-doc-id&conditionKey=externalCondition()', {});
+    assert(res === 'yes');
+  });
+
+  it('should receive a clean error response when the evaluate-external-condition API call fails (module not found)', async function() {
+    apos.schema.fieldsById['some-field-id'] = {
+      name: 'someField',
+      moduleName: 'unknown-module'
+    };
+
+    try {
+      await apos.http.get('/api/v1/@apostrophecms/schema/evaluate-external-condition?fieldId=some-field-id&docId=some-doc-id&conditionKey=externalCondition()', {});
+    } catch (error) {
+      assert(error.status = 400);
+      assert(error.body.message === 'Error in the `if` definition of the "someField" field: "unknown-module" module not found.');
+      return;
+    }
+    throw new Error('should have thrown');
+  });
+
+  it('should receive a clean error response when the evaluate-external-condition API call fails (external method not found)', async function() {
+    apos.schema.fieldsById['some-field-id'] = {
+      name: 'someField',
+      moduleName: 'external-condition'
+    };
+
+    try {
+      await apos.http.get('/api/v1/@apostrophecms/schema/evaluate-external-condition?fieldId=some-field-id&docId=some-doc-id&conditionKey=unknownMethod()', {});
+    } catch (error) {
+      assert(error.status = 400);
+      assert(error.body.message === 'Error in the `if` definition of the "someField" field: "unknownMethod" method not found in "external-condition" module.');
+      return;
+    }
+    throw new Error('should have thrown');
+  });
+
   it('should save date and time with the right format', async function () {
     const req = apos.task.getReq();
     const schema = apos.schema.compose({