# 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 => {
## 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
library-cm6::configure-theme
```
-If the event is generic in use but specific to a library, the name `<context>` will start with `library-` followed by the library name. Otherwise `<context>` may reflect the UI context/component.
+If the event is generic in use but specific to a library, the `<context>` will start with `library-` followed by the library name. Otherwise `<context>` may reflect the UI context/component.
-The `<action/lifecycle>` 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 `<action/lifecycle>` 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
#### 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
#### 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
// 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.
// 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"];
});
```
### `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
detail.registerHighlightStyle(highlightStyleBuilder);
});
```
+</details>
+
+### `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:
+
+<details>
+<summary>Show Example</summary>
+
+```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);
+ }
+});
+```
+</details>
+
+### `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.
+
+<details>
+<summary>Show Example</summary>
+
+```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'}
+ });
+ }
+});
+```
</details>
\ No newline at end of file
projects / bookstack / blobdiff