Project

General

Profile

Actions

Feature #43259

open

Replace jsToolBar with a server-rendered wiki toolbar handled by a Stimulus controller

Feature #43259: Replace jsToolBar with a server-rendered wiki toolbar handled by a Stimulus controller

Added by Takashi Kato about 1 year ago. Updated 17 days ago.

Status:
New
Priority:
Normal
Category:
Code cleanup/refactoring
Target version:
Resolution:

Description

This patch is based on a branch from #43165, with minor modifications.

  • Converting the entire library to ES modules eliminates the risk of variable name collisions.
  • Refactored jstoolbar from the old prototype-based syntax to a more readable class syntax.
  • Switched DOM element creation from JavaScript to ERB, which makes preparing and cloning DOM elements easier by using the <template> element.
  • Moved all jstoolbar locales to config/locales to simplify i18n. * Added the missing tasklist locale for both ja and en.
  • Integrated the list-autofill controller into jstoolbar as both controllers are used in the same places.

Applying this patch along with #42521 enables the implementation of #40310.

This patch can be applied to r24014


Files

0001-Convert-jstoolbar-to-ES-Module.patch (227 KB) 0001-Convert-jstoolbar-to-ES-Module.patch Takashi Kato, 2025-09-28 06:01
0001-wip.patch (44.8 KB) 0001-wip.patch Marius BĂLTEANU, 2026-02-21 19:43
0001-jstoolbar-to-stimulus.patch (46.9 KB) 0001-jstoolbar-to-stimulus.patch Takashi Kato, 2026-03-01 03:14
0001-Define-the-wiki-toolbar-markup-in-JavaScript-for-eac.patch (26.1 KB) 0001-Define-the-wiki-toolbar-markup-in-JavaScript-for-eac.patch Marius BĂLTEANU, 2026-10-28 22:52
0001-wiki-toolbar-keep-textarea-focus.patch (1.01 KB) 0001-wiki-toolbar-keep-textarea-focus.patch Florian Walchshofer, 2026-10-30 21:58
0002-wiki-toolbar-keep-menus-in-viewport.patch (1003 Bytes) 0002-wiki-toolbar-keep-menus-in-viewport.patch Florian Walchshofer, 2026-10-30 21:58
0003-wiki-toolbar-return-focus-after-escape.patch (1.98 KB) 0003-wiki-toolbar-return-focus-after-escape.patch Florian Walchshofer, 2026-10-30 21:58
0004-wiki-toolbar-allow-plugins-to-add-buttons.patch (5.48 KB) 0004-wiki-toolbar-allow-plugins-to-add-buttons.patch Florian Walchshofer, 2026-10-30 21:58
0001-Keep-wiki-toolbar-menus-from-being-clipped-by-the-fo.patch (4.21 KB) 0001-Keep-wiki-toolbar-menus-from-being-clipped-by-the-fo.patch Go MAEDA, 2026-11-03 09:10
0002-Find-wiki-toolbar-buttons-defined-in-modules-include.patch (2.02 KB) 0002-Find-wiki-toolbar-buttons-defined-in-modules-include.patch Go MAEDA, 2026-11-03 09:10
0003-Fix-error-in-deprecated-wikitoolbar_for-when-the-for.patch (2.12 KB) 0003-Fix-error-in-deprecated-wikitoolbar_for-when-the-for.patch Go MAEDA, 2026-11-03 09:10
0004-Let-text-formatters-without-toolbar-buttons-render-t.patch (2.59 KB) 0004-Let-text-formatters-without-toolbar-buttons-render-t.patch Go MAEDA, 2026-11-03 09:10
0005-Fix-JavaScript-error-on-wiki-toolbar-shortcuts-when-.patch (1.45 KB) 0005-Fix-JavaScript-error-on-wiki-toolbar-shortcuts-when-.patch Go MAEDA, 2026-11-03 09:10

Related issues 1 (1 open — 0 closed)

Related to Redmine - Patch #37559: Use meta element instead of javascript objectNewMarius BĂLTEANUActions

Updated by Marius BĂLTEANU about 1 year ago Actions #1

  • Assignee set to Marius BĂLTEANU
  • Target version set to 7.0.0

I'm assigning this 7.0.0 in order to review the changes.

Updated by Marius BĂLTEANU 9 months ago Actions #2

  • File 0001-wip.patch added

user:tohosaku, I started to work on rewriting the toolbar in order to render most of the elements on the backend and connect to Stimulus JS for the actions. Here is a prof of concept only for testing purposes, it still need some work.

Any feedback is welcome!

Updated by Marius BĂLTEANU 9 months ago Actions #3

  • File deleted (0001-wip.patch)

Updated by Marius BĂLTEANU 9 months ago Actions #5

  • Related to Patch #37559: Use meta element instead of javascript object added

Updated by Takashi Kato 9 months ago Actions #6

I applied the patch. I think the new toolbar design is simpler and better than before.

  • Toolbar generation is now separated into its own class
    • This has the benefit of allowing shorter method names
    • Memoization speeds up rendering on subsequent runs.
  • Key binding configuration has been moved from JavaScript to the data-action attribute in Stimulus.
  • Added configuration for a hotkey to toggle the preview.

Updated by Takashi Kato 9 months ago Actions #7

I confirmed that subsequent renderings within the same request become faster with code like the following.

require 'test_helper'
require 'benchmark/ips'

class ViewPerformanceTest < ActionDispatch::IntegrationTest
  def setup
    @controller = ApplicationController.new
    @controller.request = ActionDispatch::TestRequest.create
    @view_context = @controller.view_context
  end

  def test_view_benchmarks
    puts "\n--- Benchmarking Render Methods ---" 

    Benchmark.ips do |x|
      x.report('Helper (Cold Start)') do
        controller = ApplicationController.new
        controller.request = ActionDispatch::TestRequest.create
        view_context = controller.view_context
        view_context.wikitoolbar(preview_url: "/users/1"){'<textarea></textarea>'}
      end

      # Execute it once beforehand to memoize it.
      @view_context.wikitoolbar(preview_url: "/users/1"){'<textarea></textarea>'}

      x.report("Helper (Memoized)") do
        @view_context.wikitoolbar(preview_url: "/users/1"){'<textarea></textarea>'}
      end

      x.compare!
    end
  end
end
--- Benchmarking Render Methods ---
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [x86_64-linux]
Warming up --------------------------------------
 Helper (Cold Start)    40.000 i/100ms
   Helper (Memoized)   439.000 i/100ms
Calculating -------------------------------------
 Helper (Cold Start)    401.374 (±12.7%) i/s    (2.49 ms/i) -      2.000k in   5.073074s
   Helper (Memoized)      5.138k (±11.7%) i/s  (194.61 μs/i) -     25.462k in   5.033269s

Comparison:
   Helper (Memoized):     5138.4 i/s
 Helper (Cold Start):      401.4 i/s - 12.80x  slower

Updated by Marius BĂLTEANU 5 months ago Actions #8

  • Target version changed from 7.0.0 to 7.1.0

Updated by Marius BĂLTEANU 22 days ago Actions #9

  • Tracker changed from Patch to Feature
  • Subject changed from Convert jstoolbar to ES modules and class syntax. to Replace jsToolBar with a server-rendered wiki toolbar handled by a Stimulus controller

I've committed a combined patch built on the work of user:tohosaku and me. It's the first in a series of changes I'd like to commit before finishing the refactoring of the wiki toolbar.

Changes made in r25352:
  • Redmine::WikiToolbar renders the toolbar: the edit/preview tabs, the buttons and the menus (code highlighting languages, table generator). Each text formatter (Textile, CommonMark) describes its buttons in Ruby.
  • One Stimulus controller handles the buttons, the menus (keyboard navigation, Escape and outside click), the keyboard shortcuts (Ctrl/Cmd+B/I/U, Ctrl/Cmd+Shift+P to toggle preview) and the preview. The preview sends the attachments and the data-preview-param fields.
  • The toolbar translations move from the jstoolbar-*.js language files to config/locales (label_wiki_toolbar_*).
  • Removed: jsToolBar (jstoolbar.js, textile.js, common_mark.js), the 49 language files and the jQuery preview handler.
Compatibility:
  • wikitoolbar_for(field_id, preview_url) is unchanged, so views and plugins that call it keep working.
  • The markup and CSS classes (jstBlock, jstTabs, jstEditor, jstElements, jstb_*, wiki-preview) are unchanged, so themes keep working.
Next changes in the series:
  • define the markup inserted by the buttons in JavaScript, per text formatter;
  • render the toolbar around its textarea with partials and a form builder method (wiki_textarea), deprecating wikitoolbar_for;

This change breaks plugins that use the jsToolBar JavaScript object directly (for example, to add buttons) and they need to be updated. Please expect a few days to finish this.

Updated by Marius BĂLTEANU 22 days ago Actions #10

Next changes in the series:
  • define the markup inserted by the buttons in JavaScript, per text formatter;

Attached the patch that moves the markup of toolbar buttons from Ruby action parameters to app/javascript/wiki_formatting/<format>.js. Redmine::WikiToolbar will only describes the layout of the buttons.

Please let me know what do you think about this approach.

Updated by Florian Walchshofer 20 days ago Actions #11

I tested r25355 and 0001-Define-the-wiki-toolbar-markup-in-JavaScript-for-eac.patch in the browser and compared them with the version before r25352.
I think moving the markup to JavaScript is a good approach: the inserted text and the cursor position are identical for all buttons with Textile and CommonMark.

I found two regressions from r25352. The attached patches apply on top of 0001-Define-the-wiki-toolbar-markup-in-JavaScript-for-eac.patch, the changed lines are the same for the current trunk:

Two additions:

document.addEventListener('wiki-toolbar:button', ({ detail: { button, editor } }) => {
  if (button === 'mark') editor.wrap('%{background:yellow}', '%')
})

With the patches applied, the unit, integration and system tests of the toolbar pass.

Updated by Marius BĂLTEANU 18 days ago Actions #12

Thanks user:amiswalc for testing the changes!

I have committed 4 follow-up patches to improve the current implementation and to provide a proper API for plugins:

1. Render the wiki toolbar around its textarea using partials and a form builder method:

  • Instead of building the HTML markup in WikiToolbarHelper and moving the <textarea> into div.jstBlock from JavaScript on connect(), the toolbar now wraps the textarea directly on the server side using partials under app/views/wiki_toolbar/ (_toolbar.html.erb, _button.html.erb, _precode_menu.html.erb, _table_menu.html.erb).
  • Added f.wiki_textarea (aliased as f.wiki_text_area) to LabelledFormBuilder and €wiki_textarea_tag@ to @WikiToolbarHelper:
<%= f.wiki_textarea :description, :rows => 10, :preview_url => preview_news_path(:project_id => @project, :id => @news) %>
<%= wiki_textarea_tag 'notes', @notes, :cols => 60, :rows => 10, :preview_url => preview_issue_path(:project_id => @project, :issue_id => @issue) %>
  • Replaced <p> wrappers around wiki textareas in .tabular forms with <div class="form-field"> so we don't render block-level <div> elements inside <p>.
  • wikitoolbar_for is kept for backward compatibility and deprecated for removal in Redmine 8.0 (wiki_toolbar_controller.js still supports adopting an external textarea when data-wiki-toolbar-field-id-value is set).
2. Allow plugins to add buttons and menus to the wiki toolbar:
  • Added two view hooks in app/views/wiki_toolbar/_toolbar.html.erb: view_wiki_toolbar_buttons and view_wiki_toolbar_menus.
  • Added wiki_toolbar_button helper and WikiToolbarController.registerAction(name, fn) so plugins can register custom buttons and actions without monkey-patching core files:
<%# In a view_wiki_toolbar_buttons hook %>
<%= wiki_toolbar_button :highlight, title: 'Highlight' %>
import WikiToolbarController from "controllers/wiki_toolbar_controller" 
WikiToolbarController.registerAction("highlight", function() {
  this.encloseSelection("==", "==")
})
  • Plugins can also bind buttons to their own Stimulus controllers via the action: option (e.g. wiki_toolbar_button :macro, action: 'my-plugin#open').

3. Abort in-flight preview requests when leaving preview mode
4. Keep wiki toolbar menus inside the toolbar bounds:* based on the patch posted by Florian.

With these changes, the toolbar rendering and the plugin API are in their final form. The main goal of this refactoring was to move away from the legacy two-step pattern (textarea + wikitoolbar_for that mutates the DOM from JavaScript) to a single, self-contained component rendered directly from ERB partials via standard form helpers (f.wiki_textarea / wiki_textarea_tag), producing valid HTML without layout shifts on page load and giving plugins a clean, supported way to extend the toolbar for Redmine 7.1 while keeping backward compatibility until 8.0.

I have a few more commits in the queue with internal improvements and small fixes, without any other major changes.

Please let me know what do you think.

Updated by Go MAEDA 17 days ago Actions #13

Thank you to user#486714 and Marius BĂLTEANU for the new wiki toolbar.

While testing it on trunk, I found the following issues and have attached a patch for each of them. Patch 4 depends on patch 3; the others are independent.

1. The code language menu is clipped in most forms (r25352)

With the old toolbar, the whole "Highlighted code" menu was visible in any form because jsToolBar appended the menus to body. The menus are now appended inside div.jstBlock. In most forms, such as the new issue form, the toolbar is inside div.form-field, which has overflow: hidden, so the lower part of the menu is cut off and the last languages can no longer be selected.

0001-Keep-wiki-toolbar-menus-from-being-clipped-by-the-fo.patch gives the menus a fixed position, and they follow the button when the page is scrolled or resized.

2. A formatter helper that includes a core formatter helper no longer gets the toolbar (r25407)

With the old toolbar, a third-party text formatter (registered with wiki_format_provider) could reuse the toolbar of a core formatter by including its helper, such as Redmine::WikiFormatting::CommonMark::Helper, because the included wikitoolbar_for set up the toolbar. Now Redmine::WikiToolbar.buttons looks up WIKI_TOOLBAR_BUTTONS with const_defined?(:WIKI_TOOLBAR_BUTTONS, false), which ignores constants defined in included modules, so such a formatter gets no toolbar at all.

0002-Find-wiki-toolbar-buttons-defined-in-modules-include.patch also looks up the constant in included modules.

3. The deprecated wikitoolbar_for raises an error when the formatter has no toolbar buttons (r25407)

Redmine::WikiToolbar::Helper#wikitoolbar_for renders the toolbar partial without checking that the current text formatter defines buttons. If it does not, the page fails with NoMethodError (undefined method each_with_index for nil). With patch 4, this would also happen in core views for formatters whose helper reuses this method.

0003-Fix-error-in-deprecated-wikitoolbar_for-when-the-for.patch makes it render nothing in that case, as wiki_toolbar does.

4. Text formatter plugins can no longer provide their own editor (r25407)

Text formatter plugins such as redmine_ckeditor5 set up their own editor in wikitoolbar_for of their helper. With the old toolbar, core views called this method after each textarea, so the plugin's editor was displayed in all forms. Now the views use wiki_textarea and wiki_toolbar instead, which render a plain textarea when the formatter does not define toolbar buttons.

Such plugins will need to be updated for the removal of jsToolBar anyway, but they currently have no way to set up their editor. 0004-Let-text-formatters-without-toolbar-buttons-render-t.patch makes wiki_toolbar call wikitoolbar_for of the formatter helper after the textarea when the formatter does not define toolbar buttons. This is a suggestion; if another extension point is preferred for such plugins, please feel free to take a different approach.

5. JavaScript error on Ctrl/Cmd+Shift+P when a toolbar has no textarea (r25407)

With the old toolbar, calling wikitoolbar_for with the ID of a textarea that is not on the page did nothing. Now the hidden toolbar still listens to Ctrl/Cmd+Shift+P on the window, and every press of the shortcut raises a "Missing target element" error.

0005-Fix-JavaScript-error-on-wiki-toolbar-shortcuts-when-.patch makes the shortcut handlers do nothing when the toolbar has no textarea.

Actions

Also available in: PDF Atom