From 649f96034187390dae1143d3b54da1f0c6183ae1 Mon Sep 17 00:00:00 2001 From: John McLear Date: Tue, 14 Apr 2026 13:48:33 +0100 Subject: [PATCH] Add docs for aceRegisterLineAttributes hook (#7512) * Add docs for aceRegisterLineAttributes hook Documents the new hook in both .md and .adoc client-side hook references. Co-Authored-By: Claude Opus 4.6 (1M context) * Fix: correct source file path from .js to .ts Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- doc/api/hooks_client-side.adoc | 28 ++++++++++++++++++++++++++++ doc/api/hooks_client-side.md | 27 +++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/doc/api/hooks_client-side.adoc b/doc/api/hooks_client-side.adoc index 9b0e0d18c..842d50e04 100644 --- a/doc/api/hooks_client-side.adoc +++ b/doc/api/hooks_client-side.adoc @@ -211,6 +211,34 @@ The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements. +=== aceRegisterLineAttributes + +Called from: `src/static/js/ace2_inner.ts` + +Things in context: None + +Tells Etherpad which line attributes should be preserved when a user presses +Enter to split a line. Without this hook, custom line attributes (such as +headings or alignment) are lost when a line is split. + +The return value should be an array of attribute names: + +[source,javascript] +---- +exports.aceRegisterLineAttributes = function(){ + return [ 'heading' ]; +} +---- + +When Enter is pressed on a line that has a registered attribute: + +* **Middle or end of line:** the attribute is copied to the new line below. +* **Start of line (column 0):** the attribute moves down with the text content, + and the now-empty line above is cleared. + +This is backwards compatible — on Etherpad versions that do not have this hook, +the registration is silently ignored. + === aceInitialized Called from: `src/static/js/ace2_inner.js` diff --git a/doc/api/hooks_client-side.md b/doc/api/hooks_client-side.md index e7d039e50..4b0f1cce6 100644 --- a/doc/api/hooks_client-side.md +++ b/doc/api/hooks_client-side.md @@ -207,6 +207,33 @@ The return value of this hook will add elements into the "lineMarkerAttribute" category, making the aceDomLineProcessLineAttributes hook (documented below) call for those elements. +## aceRegisterLineAttributes + +Called from: `src/static/js/ace2_inner.ts` + +Things in context: None + +Tells Etherpad which line attributes should be preserved when a user presses +Enter to split a line. Without this hook, custom line attributes (such as +headings or alignment) are lost when a line is split. + +The return value should be an array of attribute names: + +``` +exports.aceRegisterLineAttributes = function(){ + return [ 'heading' ]; +} +``` + +When Enter is pressed on a line that has a registered attribute: + +* **Middle or end of line:** the attribute is copied to the new line below. +* **Start of line (column 0):** the attribute moves down with the text content, + and the now-empty line above is cleared. + +This is backwards compatible — on Etherpad versions that do not have this hook, +the registration is silently ignored. + ## aceInitialized Called from: `src/static/js/ace2_inner.js`