X-Git-Url: http://source.bookstackapp.com/bookstack/blobdiff_plain/c74f7cc62854516f812573333b8ae0aad5970f78..refs/pull/5280/head:/dev/docs/javascript-public-events.md diff --git a/dev/docs/javascript-public-events.md b/dev/docs/javascript-public-events.md index 6bc11dbcd..4f68daaeb 100644 --- a/dev/docs/javascript-public-events.md +++ b/dev/docs/javascript-public-events.md @@ -1,7 +1,7 @@ # JavaScript Public Events -There are a range of available events that are emitted as part of a public & supported API for accessing or extending JavaScript libraries and components used in the system. -These are emitted via standard DOM events so can be listened to using standard APIs like so: +There are a range of available events emitted as part of a public & [supported](#support) API for accessing or extending JavaScript libraries and components used in the system. +These are emitted via standard DOM events so can be consumed using standard DOM APIs like so: ```javascript window.addEventListener('event-name', event => { @@ -15,8 +15,8 @@ For most use-cases you can probably just listen on the `window` as shown above. ## Support This event system, and the events emitted, are considered semi-supported. -Breaking changes of the event API, event names or event properties, will be documented in update notes but may change. -Upon that, the detail provided within the events, and the libraries made accessible, are not considered supported nor stable, and changes to these won't be clearly documented within changelogs. +Breaking changes of the event API, event names, or event properties, are possible but will be documented in update notes. +The detail provided within the events, and the libraries made accessible, are not considered supported nor stable, and changes to these won't be clearly documented changelogs. ## Event Naming Scheme @@ -30,9 +30,9 @@ editor-tinymce::setup library-cm6::configure-theme ``` -If the event is generic in use but specific to a library, the name `` will start with `library-` followed by the library name. Otherwise `` may reflect the UI context/component. +If the event is generic in use but specific to a library, the `` will start with `library-` followed by the library name. Otherwise `` may reflect the UI context/component. -The `` reflects the lifecycle stage of the context, or a specific action to perform if the event is very specific to a certain use-case. +The `` reflects the lifecycle stage of the context, or a specific action to perform if the event is specific to a certain use-case. ## Event Listing @@ -42,7 +42,7 @@ This event is called before the markdown input editor CodeMirror instance is cre #### Event Data -- `editorViewConfig` - An [EditorViewConfig](https://codemirror.net/docs/ref/#view.EditorViewConfig) object that will eventially be passed when creating the CodeMirror EditorView instance. +- `editorViewConfig` - An [EditorViewConfig](https://codemirror.net/docs/ref/#view.EditorViewConfig) object that will eventually be passed when creating the CodeMirror EditorView instance. ##### Example @@ -61,7 +61,7 @@ This event is called when the markdown editor loads, post configuration but befo #### Event Data - `markdownIt` - A references to the [MarkdownIt](https://markdown-it.github.io/markdown-it/#MarkdownIt) instance used to render markdown to HTML (Just for the preview). -- `displayEl` - The DOM Element that wraps the HTML preview display. +- `displayEl` - The IFrame Element that wraps the HTML preview display. - `cmEditorView` - The CodeMirror [EditorView](https://codemirror.net/docs/ref/#view.EditorView) instance used for the markdown input editor. ##### Example @@ -70,14 +70,13 @@ This event is called when the markdown editor loads, post configuration but befo // Set all text in the display to be red by default. window.addEventListener('editor-markdown::setup', event => { const display = event.detail.displayEl; - display.style.color = 'red'; + display.contentDocument.body.style.color = 'red'; }); ``` ### `editor-drawio::configure` -This event is called as the embedded diagrams.net drawing editor loads, as a means to allow configuration of the diagrams.net interface. - +This event is called as the embedded diagrams.net drawing editor loads, to allow configuration of the diagrams.net interface. See [this diagrams.net page](https://www.diagrams.net/doc/faq/configure-diagram-editor) for details on the available options for the configure event. If using a custom diagrams.net instance, via the `DRAWIO` option, you will need to ensure your DRAWIO option URL has the `configure=1` query parameter. @@ -93,7 +92,7 @@ If using a custom diagrams.net instance, via the `DRAWIO` option, you will need // Set only the "general" and "android" libraries to show by default window.addEventListener('editor-drawio::configure', event => { const config = event.detail.config; - config.defaultLibraries = "general;android"; + config.enabledLibraries = ["general", "android"]; }); ``` @@ -117,7 +116,7 @@ window.addEventListener('editor-tinymce::pre-init', event => { ### `editor-tinymce::setup` -This event is called during the `setup` lifecycle stage of the TinyMCE editor used as the BookStack WYSIWYG editor. This is post configuration, but before the editor is typically visible. +This event is called during the `setup` lifecycle stage of the TinyMCE editor used as the BookStack WYSIWYG editor. This is after configuration, but before the editor is fully loaded and ready to use. ##### Event Data @@ -253,4 +252,70 @@ window.addEventListener('library-cm6::configure-theme', event => { detail.registerHighlightStyle(highlightStyleBuilder); }); ``` + + +### `library-cm6::pre-init` + +This event is called just before any CodeMirror instances are initialised so that the instance configuration can be viewed and altered before the instance is created. + +#### Event Data + +- `usage` - A string label to identify the usage type of the CodeMirror instance in BookStack. +- `editorViewConfig` - A reference to the [EditorViewConfig](https://codemirror.net/docs/ref/#view.EditorViewConfig) that will be used to create the instance. +- `libEditorView` - The CodeMirror [EditorView](https://codemirror.net/docs/ref/#view.EditorView) class object, provided for convenience. +- `libEditorState` - The CodeMirror [EditorState](https://codemirror.net/docs/ref/#state.EditorState) class object, provided for convenience. +- `libCompartment` - The CodeMirror [Compartment](https://codemirror.net/docs/ref/#state.Compartment) class object, provided for convenience. + +##### Example + +The below shows how you'd enable the built-in line wrapping extension for page content code blocks: + +
+Show Example + +```javascript +window.addEventListener('library-cm6::pre-init', event => { + const detail = event.detail; + const config = detail.editorViewConfig; + const EditorView = detail.libEditorView; + + if (detail.usage === 'content-code-block') { + config.extensions.push(EditorView.lineWrapping); + } +}); +``` +
+ +### `library-cm6::post-init` + +This event is called just after any CodeMirror instances are initialised so that you're able to gain a reference to the CodeMirror EditorView instance. + +#### Event Data + +- `usage` - A string label to identify the usage type of the CodeMirror instance in BookStack. +- `editorView` - A reference to the [EditorView](https://codemirror.net/docs/ref/#view.EditorView) instance that has been created. +- `editorViewConfig` - A reference to the [EditorViewConfig](https://codemirror.net/docs/ref/#view.EditorViewConfig) that was used to create the instance. +- `libEditorView` - The CodeMirror [EditorView](https://codemirror.net/docs/ref/#view.EditorView) class object, provided for convenience. +- `libEditorState` - The CodeMirror [EditorState](https://codemirror.net/docs/ref/#state.EditorState) class object, provided for convenience. +- `libCompartment` - The CodeMirror [Compartment](https://codemirror.net/docs/ref/#state.Compartment) class object, provided for convenience. + +##### Example + +The below shows how you'd prepend some default text to all content (page) code blocks. + +
+Show Example + +```javascript +window.addEventListener('library-cm6::post-init', event => { + const detail = event.detail; + const editorView = detail.editorView; + + if (detail.usage === 'content-code-block') { + editorView.dispatch({ + changes: {from: 0, to: 0, insert: 'Copyright 2023\n\n'} + }); + } +}); +```
\ No newline at end of file