From e32b762c383e2233eb8cb17def4438ef1d259fcf Mon Sep 17 00:00:00 2001 From: Tom Elliott Date: Tue, 17 Nov 2026 06:07:22 -0600 Subject: [PATCH] Add the FOG settings catalog and a settings read helper (#198) config/fog-settings.js (sails.config.fogSettings) is the one code-side list of the runtime settings: category, description, type, options, default, normalize and reload per key. The database holds only the values an admin changed; fog-node seeds no rows (migrate: 'safe'). sails.helpers.settings.get(key) reads the key's Setting record and returns normalize(value), or the default for a missing record or a bad value. It never creates a record. An unknown key throws "Unknown setting: ". The catalog starts with the two table settings, FOG_TABLE_SCROLL_MODE and FOG_VIEW_DEFAULT_SCREEN, with their 1.6 descriptions as plain text and their current reader rules. api/helpers/table-settings.js now reads both through the helper; its output shape is unchanged. Co-Authored-By: Claude Opus 5.5 --- api/helpers/settings/get.js | 41 ++++++++++++ api/helpers/table-settings.js | 35 ++-------- config/fog-settings.js | 94 +++++++++++++++++++++++++++ test/helpers/settings-catalog.test.js | 68 +++++++++++++++++++ 4 files changed, 210 insertions(+), 28 deletions(-) create mode 100644 api/helpers/settings/get.js create mode 100644 config/fog-settings.js create mode 100644 test/helpers/settings-catalog.test.js diff --git a/api/helpers/settings/get.js b/api/helpers/settings/get.js new file mode 100644 index 0000000..1387ca8 --- /dev/null +++ b/api/helpers/settings/get.js @@ -0,0 +1,41 @@ +/** + * Reads one runtime setting from the FOG settings catalog + * (config/fog-settings.js, sails.config.fogSettings). + * + * It reads the key's Setting record and returns the entry's normalize() of + * the stored value. A missing record, or a stored value that normalize() + * rejects, gives the entry's default. It only reads: it never creates a + * record, so an install with no record keeps the default. + * + * A key that is not in the catalog throws "Unknown setting: ", so a + * typo in a reader fails loudly instead of reading a default forever. + * + * Usage: await sails.helpers.settings.get('FOG_VIEW_DEFAULT_SCREEN') + * -> 25 + */ +module.exports = { + friendlyName: 'Get a setting', + description: 'The normalized value of one catalog setting, or its default.', + inputs: { + key: {type: 'string', required: true, description: 'The setting name, e.g. FOG_TABLE_SCROLL_MODE.'} + }, + exits: { + success: {outputType: 'ref', description: 'The normalized value, or the default.'} + }, + fn: async function ({key}) { + let catalog = sails.config.fogSettings; + // Own keys only, so a name such as 'constructor' is not a setting. + if (!Object.hasOwn(catalog, key)) { + throw new Error(`Unknown setting: ${key}`); + } + let entry = catalog[key]; + let row = await sails.models.setting.findOne({name: key}); + if (row) { + let value = entry.normalize(row.value); + if (value !== undefined) { + return value; + } + } + return entry.default; + } +}; diff --git a/api/helpers/table-settings.js b/api/helpers/table-settings.js index 2bcabc8..8737883 100644 --- a/api/helpers/table-settings.js +++ b/api/helpers/table-settings.js @@ -1,22 +1,19 @@ /** - * The list page table settings (issue #150), read from two Setting records: + * The list page table settings (issue #150), read through the settings + * catalog (config/fog-settings.js) with sails.helpers.settings.get: * * FOG_TABLE_SCROLL_MODE 'infinite' or 'paged' (any case). Default 'infinite'. * FOG_VIEW_DEFAULT_SCREEN A positive whole number of rows per page, or -1 * for all rows. A numeric string such as '50' counts. * Default 25. * - * A missing record or a bad value falls back to its default. The helper only - * reads: it never creates a record, so an install with no record keeps the - * defaults. The value column is type json, so a value can be a string or a - * number. + * The catalog entries hold the defaults and the validation. A missing record + * or a bad value falls back to its default. The helper only reads: it never + * creates a record, so an install with no record keeps the defaults. * * Usage: await sails.helpers.tableSettings() * -> {scrollMode: 'infinite', pageLength: 25} */ -const DEFAULT_SCROLL_MODE = 'infinite'; -const DEFAULT_PAGE_LENGTH = 25; - module.exports = { friendlyName: 'Table settings', description: 'The list page scroll mode and page length, from the Setting records.', @@ -25,26 +22,8 @@ module.exports = { success: {outputType: 'ref', description: '{scrollMode, pageLength}'} }, fn: async function () { - let scrollSetting = await sails.models.setting.findOne({name: 'FOG_TABLE_SCROLL_MODE'}); - let lengthSetting = await sails.models.setting.findOne({name: 'FOG_VIEW_DEFAULT_SCREEN'}); - - let scrollMode = DEFAULT_SCROLL_MODE; - if (scrollSetting) { - let mode = String(scrollSetting.value).trim().toLowerCase(); - if (mode === 'infinite' || mode === 'paged') { - scrollMode = mode; - } - } - - let pageLength = DEFAULT_PAGE_LENGTH; - if (lengthSetting) { - let text = String(lengthSetting.value).trim(); - // Whole numbers only: a positive count, or -1 for all rows. - if (/^(-1|[1-9][0-9]*)$/.test(text)) { - pageLength = Number(text); - } - } - + let scrollMode = await sails.helpers.settings.get('FOG_TABLE_SCROLL_MODE'); + let pageLength = await sails.helpers.settings.get('FOG_VIEW_DEFAULT_SCREEN'); return {scrollMode, pageLength}; } }; diff --git a/config/fog-settings.js b/config/fog-settings.js new file mode 100644 index 0000000..2c96559 --- /dev/null +++ b/config/fog-settings.js @@ -0,0 +1,94 @@ +/** + * The FOG settings catalog + * (sails.config.fogSettings) + * + * The one code-side list of the runtime settings an admin may change while + * fog-node runs. The database holds only the values an admin changed: one + * Setting record per changed key. A key with no record, or with a bad stored + * value, reads as its `default`. Read a value with + * `await sails.helpers.settings.get(key)` (api/helpers/settings/get.js). + * + * FOG 1.6 keeps the same facts in `globalSettings` rows that + * commons/schema.php seeds, plus a per-key switch in + * FOGConfigurationPage.php. fog-node seeds no rows (`migrate: 'safe'`), so + * the types, choices and validation live here, next to the readers. + * + * What goes in: + * + * - A key enters the catalog in the same change as the code that reads it, + * or in the change that moves its reader onto `sails.helpers.settings.get`. + * No key is listed for later: a listed key with no reader is a control + * that does nothing. + * - Install-time configuration (the database URL, ports, paths, secrets) + * stays in config/local.js, which `npm run setup` writes. The catalog + * holds only what an admin may change while fog-node runs. + * - A credential or a secret never goes in the catalog. + * - The `schema` record (written by tools/setup/lib/schema.js, read by + * `npm run migrate`) is not a setting, and is never a catalog key. + * + * Each entry, keyed by the FOG 1.6 setting name: + * + * category the FOG 1.6 category name, e.g. 'FOG View Settings' + * description the FOG 1.6 settingDesc text, as plain text (no HTML) + * type 'select', 'number', 'text' or 'checkbox' + * options for a 'select' only: an array of {value, label} + * default the value when no record exists or the stored value is bad + * normalize (value) => the cleaned value, or undefined for a bad value. + * The Setting value column is type json, so a stored value + * can be a string or a number. + * reload true when the change takes effect after a page reload + * (the FOG 1.6 reload flag) + */ + +module.exports.fogSettings = { + + // The list page tables (api/helpers/table-settings.js, issue #150). + // 1.6 schema.php step 296. + FOG_TABLE_SCROLL_MODE: { + category: 'FOG View Settings', + description: 'This setting defines how the management tables page through ' + + 'records. infinite loads rows as you scroll; paged uses the classic ' + + 'page-number bar.', + type: 'select', + options: [ + {value: 'infinite', label: 'Infinite scroll'}, + {value: 'paged', label: 'Paged'} + ], + default: 'infinite', + // 'infinite' or 'paged', in any case and with surrounding spaces. + normalize: (value) => { + let mode = String(value).trim().toLowerCase(); + return (mode === 'infinite' || mode === 'paged') ? mode : undefined; + }, + reload: true + }, + + // The rows per page of a list table with no saved per-user layout + // (api/helpers/table-settings.js, issue #150). The description is the + // repaired text of 1.6 schema.php step 397. + FOG_VIEW_DEFAULT_SCREEN: { + category: 'FOG View Settings', + description: 'This setting defines how many rows a management list shows ' + + 'to a user who has not yet saved a layout of their own. Column order, ' + + 'visibility, sort and row count are remembered per user once changed, ' + + 'so this is the starting default rather than a fixed limit.', + type: 'select', + options: [ + {value: 10, label: '10'}, + {value: 25, label: '25'}, + {value: 50, label: '50'}, + {value: 100, label: '100'}, + {value: -1, label: 'All'} + ], + default: 25, + // Whole numbers only: a positive count, or -1 for all rows. A numeric + // string such as '50' counts. A count the picker does not offer stays + // valid, as in 1.6. + normalize: (value) => { + let text = String(value).trim(); + return /^(-1|[1-9][0-9]*)$/.test(text) ? Number(text) : undefined; + }, + reload: true + } + +}; diff --git a/test/helpers/settings-catalog.test.js b/test/helpers/settings-catalog.test.js new file mode 100644 index 0000000..a110770 --- /dev/null +++ b/test/helpers/settings-catalog.test.js @@ -0,0 +1,68 @@ +const assert = require('assert'); + +// The FOG settings catalog (config/fog-settings.js) and its read helper +// (api/helpers/settings/get.js), issue #198. +describe('Settings catalog::', () => { + const KEY = 'FOG_VIEW_DEFAULT_SCREEN'; + const TYPES = ['select', 'number', 'text', 'checkbox']; + const catalog = () => sails.config.fogSettings; + const get = (key) => sails.helpers.settings.get(key); + + // The test owns the FOG_VIEW_DEFAULT_SCREEN record: none before, none after. + const cleanup = () => sails.models.setting.destroy({name: KEY}); + before(cleanup); + afterEach(cleanup); + + it('holds the two table settings', () => { + ['FOG_TABLE_SCROLL_MODE', 'FOG_VIEW_DEFAULT_SCREEN'].forEach((key) => assert.ok(Object.hasOwn(catalog(), key), `no ${key}`)); + }); + + it('gives every entry the full shape, and a default that normalizes to itself', () => { + for (const [key, entry] of Object.entries(catalog())) { + assert.strictEqual(typeof entry.category, 'string', `${key}.category`); + assert.ok(entry.category.length, `${key}.category is empty`); + assert.strictEqual(typeof entry.description, 'string', `${key}.description`); + assert.ok(entry.description.length, `${key}.description is empty`); + assert.ok(!/[<>]/.test(entry.description), `${key}.description has HTML`); + assert.ok(TYPES.includes(entry.type), `${key}.type is ${entry.type}`); + assert.strictEqual(typeof entry.normalize, 'function', `${key}.normalize`); + assert.strictEqual(typeof entry.reload, 'boolean', `${key}.reload`); + assert.ok('default' in entry, `${key}.default`); + assert.strictEqual(entry.normalize(entry.default), entry.default, `${key}.default does not normalize to itself`); + if (entry.type === 'select') { + assert.ok(Array.isArray(entry.options) && entry.options.length, `${key}.options`); + for (const option of entry.options) { + assert.ok('value' in option && typeof option.label === 'string', `${key} option ${JSON.stringify(option)}`); + assert.strictEqual(entry.normalize(option.value), option.value, `${key} option ${option.value} does not normalize to itself`); + } + } + } + }); + + it('has no schema key', () => { + assert.strictEqual(catalog().schema, undefined); + }); + + it('returns the default with no record, and creates none', async () => { + assert.strictEqual(await get(KEY), 25); + assert.strictEqual(await sails.models.setting.count({name: KEY}), 0); + }); + + it('returns the normalized value of a good record', async () => { + await sails.models.setting.create({name: KEY, value: '50'}); + assert.strictEqual(await get(KEY), 50); + }); + + it('returns the default for a bad record', async () => { + await sails.models.setting.create({name: KEY, value: 'abc'}); + assert.strictEqual(await get(KEY), 25); + }); + + it('rejects an unknown key, naming it', async () => { + await assert.rejects(get('NOPE'), (err) => err.message.includes('Unknown setting: NOPE')); + }); + + it('rejects an inherited property name as unknown', async () => { + await assert.rejects(get('constructor'), /Unknown setting: constructor/); + }); +});