Skip to content

docs: reflect ether/etherpad#7841 default-true flag flip #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JohnMcLear merged 1 commit into from
May 25, 2026
Merged

docs: reflect ether/etherpad#7841 default-true flag flip #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 3 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,10 +184,11 @@ const state = myToggle.init(); // reads cookie, binds checkbox

Parallel checkboxes in **both** the User Settings panel and the Pad Wide Settings panel — matching how native settings (sticky chat, line numbers, etc.) work. The pad-wide value rides Etherpad's existing `padoptions` broadcast/persist rail, so changes propagate to every connected client and are remembered across reloads. The pad creator can `enforceSettings` to lock the user-side checkbox for everyone.

Requires Etherpad with the `ep_*` padOptions passthrough patch ([PR #7698](https://github.com/ether/etherpad/pull/7698), shipped in `>= 3.0.0`) AND the runtime flag `settings.enablePluginPadOptions = true` in `settings.json` (default false). When either is missing the pad-wide column is hidden automatically and the user-side cookie toggle keeps working — plugins built on this helper run everywhere. The console warning logged on degradation names the specific cause so an admin can tell whether to upgrade the core or to flip the runtime flag.
Requires Etherpad with the `ep_*` padOptions passthrough patch ([PR #7698](https://github.com/ether/etherpad/pull/7698), shipped in `>= 3.0.0`) AND the runtime flag `settings.enablePluginPadOptions` not set to `false` (default `true` on current cores; earlier 3.x releases shipped it default `false` so operators on those versions need to flip it explicitly). When pad-wide is unavailable the column is hidden automatically and the user-side cookie toggle keeps working — plugins built on this helper run everywhere. The console warning logged on degradation names the specific cause so an admin can tell whether to upgrade the core or to flip the runtime flag.

```json
// settings.json
// settings.json — only needed on older 3.x cores that shipped this opt-in,
// or to explicitly disable the passthrough on current cores.
{
"enablePluginPadOptions": true
}
Expand Down
3 changes: 2 additions & 1 deletion pad-select-server.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,8 @@ const padSelectServer = (rawConfig) => {
padWideSupported: isPadWideActive(),
// Granular flags so the client's degradation warning can
// name the specific cause — missing patch (Etherpad <
// 3.0.0) vs. missing runtime flag (default false). See
// 3.0.0) vs. explicit operator opt-out
// (settings.enablePluginPadOptions = false). See
// pad-toggle-server.js for the same rationale.
patchPresent: padOptionsPluginPassthrough,
runtimeEnabled: runtimeFlagEnabled,
Expand Down
9 changes: 5 additions & 4 deletions pad-toggle-server.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,11 @@ const padToggleServer = (rawConfig) => {
const {pluginName, settingId, l10nId, defaultLabel, defaultEnabled} = validateConfig(rawConfig);
let cachedDefaultEnabled = defaultEnabled;
// Etherpad >= 3.0.0 introduced settings.enablePluginPadOptions as a runtime
// gate on the ep_* passthrough (default false per AGENTS.MD §52). We grab
// it from loadSettings so eejsBlock_padSettings + clientVars correctly
// no-op when an admin hasn't opted in, even though PluginCapabilities
// reports the patch is present in the core.
// gate on the ep_* passthrough (default true since the flag-flip; older 3.x
// releases shipped with it default false). We grab it from loadSettings so
// eejsBlock_padSettings + clientVars correctly no-op when an admin has
// opted out, even though PluginCapabilities reports the patch is present
// in the core.
let runtimeFlagEnabled = false;

const isPadWideActive = () => padOptionsPluginPassthrough && runtimeFlagEnabled;
Expand Down
11 changes: 6 additions & 5 deletions pad-toggle.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,11 +160,12 @@ const padToggleClient = (rawConfig) => {
} else if (!isSupportedClient()) {
if (typeof console !== 'undefined' && !init._warned) {
// The patch shipped in Etherpad 3.0.0 (PR #7698) and is enabled at
// runtime via `settings.enablePluginPadOptions` (default false per
// AGENTS.MD §52). Either condition can flip padWideSupported off
// — surface the specific cause so the admin knows whether to
// upgrade or to flip a settings flag. Falls back to a generic
// line on older servers that don't ship the capability fields.
// runtime via `settings.enablePluginPadOptions` (default true on
// current cores; earlier 3.x releases shipped it default false).
// Either condition can flip padWideSupported off — surface the
// specific cause so the admin knows whether to upgrade or to flip
// a settings flag. Falls back to a generic line on older servers
// that don't ship the capability fields.
const block = getCapabilityBlock();
const patchPresent = block && block.patchPresent === true;
const runtimeEnabled = block && block.runtimeEnabled === true;
Expand Down