diff options
Diffstat (limited to 'doc/development/fe_guide/editor_lite.md')
| -rw-r--r-- | doc/development/fe_guide/editor_lite.md | 265 |
1 files changed, 5 insertions, 260 deletions
diff --git a/doc/development/fe_guide/editor_lite.md b/doc/development/fe_guide/editor_lite.md index f28588c23e9..5020bf9eeeb 100644 --- a/doc/development/fe_guide/editor_lite.md +++ b/doc/development/fe_guide/editor_lite.md @@ -1,264 +1,9 @@ --- -stage: Create -group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'source_editor.md' +remove_date: '2021-09-19' --- -# Editor Lite **(FREE)** +This document was moved to [another location](source_editor.md). -**Editor Lite** provides the editing experience at GitLab. This thin wrapper around -[the Monaco editor](https://microsoft.github.io/monaco-editor/) provides necessary -helpers and abstractions, and extends Monaco [using extensions](#extensions). Multiple -GitLab features use it, including: - -- [Web IDE](../../user/project/web_ide/index.md) -- [CI Linter](../../ci/lint.md) -- [Snippets](../../user/snippets.md) -- [Web Editor](../../user/project/repository/web_editor.md) -- [Security Policies](../../user/application_security/threat_monitoring/index.md) - -## How to use Editor Lite - -Editor Lite is framework-agnostic and can be used in any application, including both -Rails and Vue. To help with integration, we have the dedicated `<editor-lite>` -Vue component, but the integration of Editor Lite is generally straightforward: - -1. Import Editor Lite: - - ```javascript - import EditorLite from '~/editor/editor_lite'; - ``` - -1. Initialize global editor for the view: - - ```javascript - const editor = new EditorLite({ - // Editor Options. - // The list of all accepted options can be found at - // https://microsoft.github.io/monaco-editor/api/enums/monaco.editor.editoroption.html - }); - ``` - -1. Create an editor's instance: - - ```javascript - editor.createInstance({ - // Editor Lite configuration options. - }) - ``` - -An instance of Editor Lite accepts the following configuration options: - -| Option | Required? | Description | -| -------------- | ------- | ---- | -| `el` | `true` | `HTML Node`: The element on which to render the editor. | -| `blobPath` | `false` | `String`: The name of a file to render in the editor, used to identify the correct syntax highlighter to use with that file, or another file type. Can accept wildcards like `*.js` when the actual filename isn't known or doesn't play any role. | -| `blobContent` | `false` | `String`: The initial content to render in the editor. | -| `extensions` | `false` | `Array`: Extensions to use in this instance. | -| `blobGlobalId` | `false` | `String`: An auto-generated property.<br>**Note:** This property may go away in the future. Do not pass `blobGlobalId` unless you know what you're doing.| -| Editor Options | `false` | `Object(s)`: Any property outside of the list above is treated as an Editor Option for this particular instance. Use this field to override global Editor Options on the instance level. A full [index of Editor Options](https://microsoft.github.io/monaco-editor/api/enums/monaco.editor.editoroption.html) is available. | - -## API - -The editor uses the same public API as -[provided by Monaco editor](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html) -with additional functions on the instance level: - -| Function | Arguments | Description -| --------------------- | ----- | ----- | -| `updateModelLanguage` | `path`: String | Updates the instance's syntax highlighting to follow the extension of the passed `path`. Available only on the instance level.| -| `use` | Array of objects | Array of extensions to apply to the instance. Accepts only the array of _objects_. You must fetch the extensions' ES6 modules must be fetched and resolved in your views or components before they are passed to `use`. This property is available on _instance_ (applies extension to this particular instance) and _global editor_ (applies the same extension to all instances) levels. | -| Monaco Editor options | See [documentation](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html) | Default Monaco editor options | - -## Tips - -1. Editor's loading state. - - The loading state is built in to Editor Lite, making spinners and loaders - rarely needed in HTML. To benefit the built-in loading state, set the `data-editor-loading` - property on the HTML element that should contain the editor. When bootstrapping, - Editor Lite shows the loader automatically. - -  - -1. Update syntax highlighting if the filename changes. - - ```javascript - // fileNameEl here is the HTML input element that contains the file name - fileNameEl.addEventListener('change', () => { - this.editor.updateModelLanguage(fileNameEl.value); - }); - ``` - -1. Get the editor's content. - - We may set up listeners on the editor for every change, but it rapidly can become - an expensive operation. Instead, get the editor's content when it's needed. - For example, on a form's submission: - - ```javascript - form.addEventListener('submit', () => { - my_content_variable = this.editor.getValue(); - }); - ``` - -1. Performance - - Even though Editor Lite itself is extremely slim, it still depends on Monaco editor, - which adds weight. Every time you add Editor Lite to a view, the JavaScript bundle's - size significantly increases, affecting your view's loading performance. We recommend - you import the editor on demand if either: - - - You're uncertain if the view needs the editor. - - The editor is a secondary element of the view. - - Loading Editor Lite on demand is handled like loading any other module: - - ```javascript - someActionFunction() { - import(/* webpackChunkName: 'EditorLite' */ '~/editor/editor_lite'). - then(({ default: EditorLite }) => { - const editor = new EditorLite(); - ... - }); - ... - } - ``` - -## Extensions - -Editor Lite provides a universal, extensible editing tool to the whole product, -and doesn't depend on any particular group. Even though the Editor Lite's core is owned by -[Create::Editor FE Team](https://about.gitlab.com/handbook/engineering/development/dev/create-editor/), -any group can own the extensions—the main functional elements. The goal of -Editor Lite extensions is to keep the editor's core slim and stable. Any -needed features can be added as extensions to this core. Any group can -build and own new editing features without worrying about changes to Editor Lite -breaking or overriding them. - -You can depend on other modules in your extensions. This organization helps keep -the size of Editor Lite's core at bay by importing dependencies only when needed. - -Structurally, the complete implementation of Editor Lite can be presented as this diagram: - -```mermaid -graph TD; - B[Extension 1]---A[Editor Lite] - C[Extension 2]---A[Editor Lite] - D[Extension 3]---A[Editor Lite] - E[...]---A[Editor Lite] - F[Extension N]---A[Editor Lite] - A[Editor Lite]---Z[Monaco] -``` - -An extension is an ES6 module that exports a JavaScript object: - -```javascript -import { Position } from 'monaco-editor'; - -export default { - navigateFileStart() { - this.setPosition(new Position(1, 1)); - }, -}; - -``` - -In the extension's functions, `this` refers to the current Editor Lite instance. -Using `this`, you get access to the complete instance's API, such as the -`setPosition()` method in this particular case. - -### Using an existing extension - -Adding an extension to Editor Lite's instance requires the following steps: - -```javascript -import EditorLite from '~/editor/editor_lite'; -import MyExtension from '~/my_extension'; - -const editor = new EditorLite().createInstance({ - ... -}); -editor.use(MyExtension); -``` - -### Creating an extension - -Let's create our first Editor Lite extension. Extensions are -[ES6 modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/) exporting a -basic `Object`, used to extend Editor Lite's features. As a test, let's -create an extension that extends Editor Lite with a new function that, when called, -outputs the editor's content in `alert`. - -`~/my_folder/my_fancy_extension.js:` - -```javascript -export default { - throwContentAtMe() { - alert(this.getValue()); - }, -}; -``` - -In the code example, `this` refers to the instance. By referring to the instance, -we can access the complete underlying -[Monaco editor API](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html), -which includes functions like `getValue()`. - -Now let's use our extension: - -`~/my_folder/component_bundle.js`: - -```javascript -import EditorLite from '~/editor/editor_lite'; -import MyFancyExtension from './my_fancy_extension'; - -const editor = new EditorLite().createInstance({ - ... -}); -editor.use(MyFancyExtension); -... -someButton.addEventListener('click', () => { - editor.throwContentAtMe(); -}); -``` - -First of all, we import Editor Lite and our new extension. Then we create the -editor and its instance. By default Editor Lite has no `throwContentAtMe` method. -But the `editor.use(MyFancyExtension)` line brings that method to our instance. -After that, we can use it any time we need it. In this case, we call it when some -theoretical button has been clicked. - -This script would result in an alert containing the editor's content when `someButton` is clicked. - - - -### Tips - -1. Performance - - Just like Editor Lite itself, any extension can be loaded on demand to not harm - loading performance of the views: - - ```javascript - const EditorPromise = import( - /* webpackChunkName: 'EditorLite' */ '~/editor/editor_lite' - ); - const MarkdownExtensionPromise = import('~/editor/editor_markdown_ext'); - - Promise.all([EditorPromise, MarkdownExtensionPromise]) - .then(([{ default: EditorLite }, { default: MarkdownExtension }]) => { - const editor = new EditorLite().createInstance({ - ... - }); - editor.use(MarkdownExtension); - }); - ``` - -1. Using multiple extensions - - Just pass the array of extensions to your `use` method: - - ```javascript - editor.use([FileTemplateExtension, MyFancyExtension]); - ``` +<!-- This redirect file can be deleted after <2021-09-19>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> |