Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions api/helpers/settings/get.js
Original file line number Diff line number Diff line change
@@ -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: <key>", 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;
}
};
35 changes: 7 additions & 28 deletions api/helpers/table-settings.js
Original file line number Diff line number Diff line change
@@ -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.',
Expand All @@ -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};
}
};
94 changes: 94 additions & 0 deletions config/fog-settings.js
Original file line number Diff line number Diff line change
@@ -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
}

};
68 changes: 68 additions & 0 deletions test/helpers/settings-catalog.test.js
Original file line number Diff line number Diff line change
@@ -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/);
});
});
Loading