@saltcorn/server 0.8.9 → 0.9.0-beta.0

package/help/Table constraints.tmd

@@ -0,0 +1,23 @@
+Table constraints in Saltcorn are used to impose constraints on the data that
+can be held in individual rows or to alter the performance characteristics of
+the table. 
+
+There are three types of table constraints: 
+
+A __unique constraint__ can be used to impose a restriction that a combination 
+of fields is unique
+across the whole table. For instance, if you have a table for people and you
+mark `name` and `age` as jointly unique using a unique constraint then you cannot
+have two rows with the same name and age; but you could have two rows with the
+same name. 
+
+A __formula constraint__ is used to impose restrictions on the content of
+each row which can use several Fields. For instance if you have from and to
+date fields, you can use the formula constraint to ensure that the to date is
+always after the from date.
+
+An __index__ does not put any limitations or constraints
+on the table data. It adds an index to the table to accelerate queries from
+individual fields, at the expense of using more disk space. You should put an
+index on fields in large tables that are frequently queried either through
+filters or aggregations.

package/help/Table formula constraint.tmd

@@ -0,0 +1,43 @@
+The constraint formula should be a JavaScript expression which evaluates to a 
+boolean (true or false). If the formula evaluates to false then the row is not
+valid and will not be accepted in the table. If you are editing an existing row 
+then the edit will not be accepted. The supplied error message text will be shown 
+to the user. 
+
+Some examples: 
+
+{{# for (const fml of table.getFormulaExamples("Bool")) { }} * `{{= fml}}`
+{{# } }}
+
+This formula can use any of the fields in table {{= table.name }} as variables:
+
+| Field | Variable name | Type |
+| ----- | ------------- | ---- |
+{{# for (const field of table.fields) { }} | {{= field.label }} | `{{= field.name }}` | {{= field.pretty_type }} | 
+{{# } }}
+
+
+
+
+{{# if(table.fields.some(f=>f.is_fkey)) { }}
+
+You can also use join fields on related tables. These are accessed with the dot object access 
+notation, in the form:
+
+```
+{key field}.{field on referenced table}
+```
+
+The first-order join fields you can use in the constraint formula are:
+
+{{# for (const field of table.fields.filter(f=>f.is_fkey && f.reftable_name)) { }}
+{{#  const reftable = Table.findOne( field.reftable_name); }}
+* Through {{=field.label}} key field: {{= table.fields.map(jf=>`\`${field.name}.${jf.name}\``).join(", ") }}
+
+
+{{# } }}
+
+If you use join fields, Saltcorn is not able to create a constraint in the SQL database. In that case, it will not check existing 
+rows, and it will also not be able to enforce constraints involving the primary key value on newly created rows.
+
+{{# } }}

package/help/index.js

@@ -0,0 +1,42 @@
+const Table = require("@saltcorn/data/models/table");
+const File = require("@saltcorn/data/models/file");
+const _ = require("underscore");
+const fs = require("fs").promises;
+const MarkdownIt = require("markdown-it"),
+  md = new MarkdownIt();
+
+const { pre } = require("@saltcorn/markup/tags");
+
+const get_md_file = async (topic) => {
+  try {
+    const fp = require.resolve(`./${File.normalise(topic)}.tmd`);
+    const fileBuf = await fs.readFile(fp);
+    return fileBuf.toString();
+  } catch (e) {
+    return false;
+  }
+};
+
+_.templateSettings = {
+  evaluate: /\{\{#(.+?)\}\}/g,
+  interpolate: /\{\{=(.+?)\}\}/g,
+};
+
+const get_help_markup = async (topic, query, req) => {
+  try {
+    const context = { user: req.user, Table };
+    if (query.table) {
+      context.table = Table.findOne({ name: query.table });
+    }
+    const mdTemplate = await get_md_file(topic);
+    if (!mdTemplate) return { markup: "Topic not found" };
+    const template = _.template(mdTemplate);
+    const mdTopic = template(context);
+    const markup = md.render(mdTopic);
+    return { markup };
+  } catch (e) {
+    return { markup: pre(e.toString()) };
+  }
+};
+
+module.exports = { get_help_markup };

package/markup/expression_blurb.js

@@ -22,144 +22,21 @@ const toJsType = (type) =>
     Color: "string",
   }[type] || type);
 
-/**
- * @param {*} type
- * @param {object[]} fields
- * @returns {string[]}
- */
-const intExamples = (type, fields) => {
-  const boolFields = fields.filter((f) => f.type && f.type.name === "Bool");
-  const intFields = fields.filter((f) => f.type && f.type.name === "Integer");
-  const exs = ["3"];
-  if (boolFields.length > 0) {
-    const b = is.one_of(boolFields).generate();
-    exs.push(`${b.name} ? 6 : 9`);
-  }
-  if (intFields.length > 0) {
-    const b = is.one_of(intFields).generate();
-    exs.push(`${b.name} + 5`);
-  }
-  return exs;
-};
-
-/**
- * @param {*} type
- * @param {object[]} fields
- * @returns {string[]}
- */
-const colorExamples = (type, fields) => {
-  const boolFields = fields.filter((f) => f.type && f.type.name === "Bool");
-  const exs = [`"#06ab6d1"`];
-  if (boolFields.length > 0) {
-    const b = is.one_of(boolFields).generate();
-    exs.push(`${b.name} ? "#000000" : "#ffffff"`);
-  }
-  return exs;
-};
-
-/**
- * @param {*} type
- * @param {object[]} fields
- * @returns {string[]}
- */
-const stringExamples = (type, fields) => {
-  const boolFields = fields.filter((f) => f.type && f.type.name === "Bool");
-  const strFields = fields.filter((f) => f.type && f.type.name === "String");
-  const exs = [`"Hello world!"`];
-  if (boolFields.length > 0) {
-    const b = is.one_of(boolFields).generate();
-    exs.push(`${b.name} ? "Squish" : "Squash"`);
-  }
-  if (strFields.length > 0) {
-    const b = is.one_of(strFields).generate();
-    exs.push(`${b.name}.toUpperCase()`);
-  }
-  return exs;
-};
-
-/**
- * @param {*} type
- * @param {object[]} fields
- * @returns {string[]}
- */
-const floatExamples = (type, fields) => {
-  const boolFields = fields.filter((f) => f.type && f.type.name === "Bool");
-  const numFields = fields.filter(
-    (f) => f.type && (f.type.name === "Integer" || f.type.name === "Float")
-  );
-  const exs = ["3.14"];
-  if (boolFields.length > 0) {
-    const b = is.one_of(boolFields).generate();
-    exs.push(`${b.name} ? 2.78 : 99`);
-  }
-  if (numFields.length > 0) {
-    const b = is.one_of(numFields).generate();
-    exs.push(`Math.pow(${b.name}, 2)`);
-  }
-  if (numFields.length > 1) {
-    const n1 = numFields[0];
-    const n2 = numFields[1];
-    exs.push(
-      `${n1.name}>${n2.name} ? Math.sqrt(${n1.name}) : ${n1.name}*${n2.name}`
-    );
-  }
-  return exs;
-};
-
-/**
- * @param {*} type
- * @param {object[]} fields
- * @returns {string[]}
- */
-const boolExamples = (type, fields) => {
-  const boolFields = fields.filter((f) => f.type && f.type.name === "Bool");
-  const numFields = fields.filter(
-    (f) => (f.type && f.type.name === "Integer") || f.type.name === "Float"
-  );
-  const exs = ["true"];
-  if (boolFields.length > 0) {
-    const b = is.one_of(boolFields).generate();
-    exs.push(`!${b.name}`);
-  }
-  if (boolFields.length > 1) {
-    const b1 = boolFields[0];
-    const b2 = boolFields[1];
-    exs.push(`${b1.name} && ${b2.name}`);
-  }
-  if (numFields.length > 0) {
-    const b = is.one_of(numFields).generate();
-    exs.push(`${b.name}<3`);
-  }
-  if (numFields.length > 1) {
-    const n1 = numFields[0];
-    const n2 = numFields[1];
-    exs.push(`${n1.name}>${n2.name}`);
-  }
-  return exs;
-};
-
 /**
  * @param {string} type
  * @param {*} stored
- * @param {object[]} allFields
+ * @param {Table} table
  * @param {object} req
  * @returns {p[]}
  */
-const expressionBlurb = (type, stored, allFields, req) => {
+const expressionBlurb = (type, stored, table, req) => {
+  const allFields = table.fields;
   const fields = allFields.filter((f) => !f.calculated);
   const funs = getState().functions;
   const funNames = Object.entries(funs)
     .filter(([k, v]) => !(!stored && v.isAsync))
     .map(([k, v]) => k);
-  const examples = (
-    {
-      Integer: () => intExamples(type, fields),
-      Float: () => floatExamples(type, fields),
-      Bool: () => boolExamples(type, fields),
-      Color: () => colorExamples(type, fields),
-      String: () => stringExamples(type, fields),
-    }[type] || (() => [])
-  )();
+  const examples = table.getFormulaExamples(type);
   return [
     p(
       req.__(

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@saltcorn/server",
-  "version": "0.8.9",
+  "version": "0.9.0-beta.0",
   "description": "Server app for Saltcorn, open-source no-code platform",
   "homepage": "https://saltcorn.com",
   "main": "index.js",
   "license": "MIT",
   "dependencies": {
-    "@saltcorn/base-plugin": "0.8.9",
-    "@saltcorn/builder": "0.8.9",
-    "@saltcorn/data": "0.8.9",
-    "@saltcorn/admin-models": "0.8.9",
-    "@saltcorn/filemanager": "0.8.9",
-    "@saltcorn/markup": "0.8.9",
-    "@saltcorn/sbadmin2": "0.8.9",
+    "@saltcorn/base-plugin": "0.9.0-beta.0",
+    "@saltcorn/builder": "0.9.0-beta.0",
+    "@saltcorn/data": "0.9.0-beta.0",
+    "@saltcorn/admin-models": "0.9.0-beta.0",
+    "@saltcorn/filemanager": "0.9.0-beta.0",
+    "@saltcorn/markup": "0.9.0-beta.0",
+    "@saltcorn/sbadmin2": "0.9.0-beta.0",
     "@socket.io/cluster-adapter": "^0.2.1",
     "@socket.io/sticky": "^1.0.1",
     "adm-zip": "0.5.10",
@@ -32,11 +32,13 @@
     "express-session": "^1.17.1",
     "greenlock": "^4.0.4",
     "greenlock-express": "^4.0.3",
+    "underscore": "1.13.6",
     "helmet": "^3.23.3",
     "i18n": "^0.15.1",
     "imapflow": "1.0.123",
     "jsonwebtoken": "^9.0.0",
     "live-plugin-manager": "^0.17.1",
+    "markdown-it": "^13.0.2",
     "moment": "^2.29.4",
     "multer": "1.4.5-lts.1",
     "multer-s3": "^2.10.0",

package/routes/admin.js

@@ -56,6 +56,7 @@ const {
   li,
   ol,
   script,
+  text,
   domReady,
 } = require("@saltcorn/markup/tags");
 const db = require("@saltcorn/data/db");
@@ -104,6 +105,7 @@ const Page = require("@saltcorn/data/models/page");
 const { getSafeSaltcornCmd } = require("@saltcorn/data/utils");
 const stream = require("stream");
 const Crash = require("@saltcorn/data/models/crash");
+const { get_help_markup } = require("../help/index.js");
 
 const router = new Router();
 module.exports = router;
@@ -240,6 +242,22 @@ router.get(
   })
 );
 
+/**
+ * @name get/send-test-email
+ * @function
+ * @memberof module:routes/admin~routes/adminRouter
+ */
+router.get(
+  "/help/:topic",
+  isAdmin,
+  error_catcher(async (req, res) => {
+    const { topic } = req.params;
+    const { markup } = await get_help_markup(topic, req.query, req);
+
+    res.sendWrap(`Help: ${topic}`, { above: [markup] });
+  })
+);
+
 /**
  * @name get/backup
  * @function
@@ -538,6 +556,7 @@ router.get(
   error_catcher(async (req, res) => {
     const { type, name } = req.params;
     const snaps = await Snapshot.entity_history(type, name);
+    res.set("Page-Title", `Restore ${text(name)}`);
     res.send(
       mkTable(
         [

package/routes/api.js

@@ -140,7 +140,7 @@ router.post(
     const view = await View.findOne({ name: viewName });
     const db = require("@saltcorn/data/db");
     if (!view) {
-      getState().log(3, `API viewQuery ${view.name} not found`);
+      getState().log(3, `API viewQuery ${viewName} not found`);
       res.status(404).json({
         error: req.__("View %s not found", viewName),
         view: viewName,

package/routes/fields.js

@@ -165,6 +165,7 @@ const fieldForm = async (req, fkey_opts, existing_names, id, hasData) => {
         name: "protected",
         sublabel: req.__("Set role to access"),
         type: "Bool",
+        showIf: { calculated: false },
       }),
       {
         label: req.__("Minimum role to write"),
@@ -460,7 +461,7 @@ const fieldFlow = (req) =>
                   html: expressionBlurb(
                     context.type,
                     context.stored,
-                    fields,
+                    table,
                     req
                   ),
                 },

package/routes/tables.js

@@ -1378,6 +1378,12 @@ router.get(
             link(`/table/add-constraint/${id}/Formula`, req.__("Formula")),
             " | ",
             link(`/table/add-constraint/${id}/Index`, req.__("Index")),
+            a(
+              {
+                href: `javascript:ajax_modal('/admin/help/Table%20constraints?table=${table.name}')`,
+              },
+              i({ class: "fas fa-question-circle ms-1" })
+            ),
           ],
         },
       ],
@@ -1392,11 +1398,11 @@ router.get(
  * @param {object[]} fields
  * @returns {Form}
  */
-const constraintForm = (req, table_id, fields, type) => {
+const constraintForm = (req, table, fields, type) => {
   switch (type) {
     case "Formula":
       return new Form({
-        action: `/table/add-constraint/${table_id}/${type}`,
+        action: `/table/add-constraint/${table.id}/${type}`,
 
         fields: [
           {
@@ -1405,6 +1411,10 @@ const constraintForm = (req, table_id, fields, type) => {
             validator: expressionValidator,
             type: "String",
             class: "validate-expression",
+            help: {
+              topic: "Table formula constraint",
+              context: { table: table.name },
+            },
             sublabel:
               req.__(
                 "Formula must evaluate to true for valid rows. In scope: "
@@ -1417,14 +1427,14 @@ const constraintForm = (req, table_id, fields, type) => {
           {
             name: "errormsg",
             label: "Error message",
-            sublabel: "Shown the user if formula is false",
+            sublabel: "Shown to the user if formula is false",
             type: "String",
           },
         ],
       });
     case "Unique":
       return new Form({
-        action: `/table/add-constraint/${table_id}/${type}`,
+        action: `/table/add-constraint/${table.id}/${type}`,
         blurb: req.__(
           "Tick the boxes for the fields that should be jointly unique"
         ),
@@ -1437,14 +1447,14 @@ const constraintForm = (req, table_id, fields, type) => {
           {
             name: "errormsg",
             label: "Error message",
-            sublabel: "Shown the user if joint uniqueness is violated",
+            sublabel: "Shown to the user if joint uniqueness is violated",
             type: "String",
           },
         ],
       });
     case "Index":
       return new Form({
-        action: `/table/add-constraint/${table_id}/${type}`,
+        action: `/table/add-constraint/${table.id}/${type}`,
         blurb: req.__(
           "Choose the field to be indexed. This make searching the table faster."
         ),
@@ -1483,7 +1493,7 @@ router.get(
       return;
     }
     const fields = table.getFields();
-    const form = constraintForm(req, table.id, fields, type);
+    const form = constraintForm(req, table, fields, type);
     res.sendWrap(req.__(`Add constraint to %s`, table.name), {
       above: [
         {
@@ -1527,7 +1537,7 @@ router.post(
       return;
     }
     const fields = table.getFields();
-    const form = constraintForm(req, table.id, fields, type);
+    const form = constraintForm(req, table, fields, type);
     form.validate(req.body);
     if (form.hasErrors) req.flash("error", req.__("An error occurred"));
     else {