Merge pull request #3615 from nextcloud/enh/editor-api

README.md

@@ -28,18 +28,20 @@ occ config:app:set text workspace_available --value=0
 
 ## 🏗 Development setup
 
-Currently this app requires the main branch of the [Viewer app](https://github.com/nextcloud/viewer).
+Currently, this app requires the main branch of the [Viewer app](https://github.com/nextcloud/viewer).
 
 1. ☁ Clone this app into the `apps` folder of your Nextcloud: `git clone https://github.com/nextcloud/text.git`
 2. 👩‍💻 In the folder of the app, run the command `make` to install dependencies and build the Javascript.
 3. ✅ Enable the app through the app management of your Nextcloud
 4. 🎉 Partytime! Help fix [some issues](https://github.com/nextcloud/text/issues) and [review pull requests](https://github.com/nextcloud/text/pulls) 👍
 
 ### 🧙 Advanced development stuff
+
 To build the Javascript whenever you make changes, instead of the full `make` you can also run `npm run build`. Or run `npm run watch` to rebuild on every file save.
 
 #### 🐞 Testing the app
-Currently this app uses three different kinds of tests:
+
+Currently, this app uses three different kinds of tests:
 
 For testing the backend (PHP) [Psalm](https://psalm.dev/) and [PHPUnit](https://phpunit.de/) are used,
 you can run the testcases (placed in `tests/`) using the composer scripts `psalm` and `test:unit`.
@@ -57,3 +59,56 @@ Or you might set the `CYPRESS_baseUrl` environment variable for a custom nextclo
 - The mime type needs to be known by Nextcloud server (see https://github.com/nextcloud/server/pull/24488 for how this can be added)
 - Once that is there, please open a pull request to add them to https://github.com/nextcloud/text/blob/12df66ffdd3d71cc696438e2e4ec60fa17b89a64/src/helpers/mime.js#L35-L61
 - You can test them like other mime types in cypress/e2e/files.spec.js
+
+
+## 🛠️ Integrate text in your app
+
+## Load the editor
+
+In order to load the editor in your app, you'll need to dispatch an event.
+
+```php
+if (class_exists(LoadEditor::class)) {
+	$this->eventDispatcher->dispatchTyped(new LoadEditor());
+}
+```
+
+### Integrate a file editor
+
+Make sure to check if OCA.Text is available as the Text app needs to be enabled. If you want your app to work without Text being installed, you will need to provide an editor fallback on your own.
+
+
+```js
+window.OCA.Text.createEditor({
+	el: document.getElementById('my-editor-div'),
+	fileId: 12345,
+	filePath: '/Readme.md',
+}).then((editor) => {
+	// Once ready you can access the editor instance and call methods like:
+
+	editor.setContent('new content') // Beware: this will overwrite the content read from the source file
+	editor.setReadOnly(true)
+	editor.insertAtCursor('<h1>Heading</h1>')
+
+	// Make sure to destory the editor instance once you remove the dom element
+	editor.destroy()
+})
+```
+
+### Markdown based content editor
+
+```js
+window.OCA.Text.createEditor({
+	el: document.getElementById('my-editor-div'),
+	content: 'initial content',
+}).then((editor) => {
+	// Once ready you can access the editor instance and call methods like:
+
+	editor.setContent('new content')
+	editor.setReadOnly(true)
+	editor.insertAtCursor('<h1>Heading</h1>')
+
+	// Make sure to destory the editor instance once you remove the dom element
+	editor.destroy()
+})
+```

composer/composer/autoload_classmap.php

@@ -26,6 +26,7 @@
     'OCA\\Text\\Db\\StepMapper' => $baseDir . '/../lib/Db/StepMapper.php',
     'OCA\\Text\\DirectEditing\\TextDirectEditor' => $baseDir . '/../lib/DirectEditing/TextDirectEditor.php',
     'OCA\\Text\\DirectEditing\\TextDocumentCreator' => $baseDir . '/../lib/DirectEditing/TextDocumentCreator.php',
+    'OCA\\Text\\Event\\LoadEditor' => $baseDir . '/../lib/Event/LoadEditor.php',
     'OCA\\Text\\Exception\\DocumentHasUnsavedChangesException' => $baseDir . '/../lib/Exception/DocumentHasUnsavedChangesException.php',
     'OCA\\Text\\Exception\\DocumentSaveConflictException' => $baseDir . '/../lib/Exception/DocumentSaveConflictException.php',
     'OCA\\Text\\Exception\\UploadException' => $baseDir . '/../lib/Exception/UploadException.php',
@@ -34,6 +35,7 @@
     'OCA\\Text\\Listeners\\BeforeNodeRenamedListener' => $baseDir . '/../lib/Listeners/BeforeNodeRenamedListener.php',
     'OCA\\Text\\Listeners\\FilesLoadAdditionalScriptsListener' => $baseDir . '/../lib/Listeners/FilesLoadAdditionalScriptsListener.php',
     'OCA\\Text\\Listeners\\FilesSharingLoadAdditionalScriptsListener' => $baseDir . '/../lib/Listeners/FilesSharingLoadAdditionalScriptsListener.php',
+    'OCA\\Text\\Listeners\\LoadEditorListener' => $baseDir . '/../lib/Listeners/LoadEditorListener.php',
     'OCA\\Text\\Listeners\\LoadViewerListener' => $baseDir . '/../lib/Listeners/LoadViewerListener.php',
     'OCA\\Text\\Listeners\\NodeCopiedListener' => $baseDir . '/../lib/Listeners/NodeCopiedListener.php',
     'OCA\\Text\\Listeners\\RegisterDirectEditorEventListener' => $baseDir . '/../lib/Listeners/RegisterDirectEditorEventListener.php',

composer/composer/autoload_static.php

@@ -41,6 +41,7 @@ class ComposerStaticInitText
         'OCA\\Text\\Db\\StepMapper' => __DIR__ . '/..' . '/../lib/Db/StepMapper.php',
         'OCA\\Text\\DirectEditing\\TextDirectEditor' => __DIR__ . '/..' . '/../lib/DirectEditing/TextDirectEditor.php',
         'OCA\\Text\\DirectEditing\\TextDocumentCreator' => __DIR__ . '/..' . '/../lib/DirectEditing/TextDocumentCreator.php',
+        'OCA\\Text\\Event\\LoadEditor' => __DIR__ . '/..' . '/../lib/Event/LoadEditor.php',
         'OCA\\Text\\Exception\\DocumentHasUnsavedChangesException' => __DIR__ . '/..' . '/../lib/Exception/DocumentHasUnsavedChangesException.php',
         'OCA\\Text\\Exception\\DocumentSaveConflictException' => __DIR__ . '/..' . '/../lib/Exception/DocumentSaveConflictException.php',
         'OCA\\Text\\Exception\\UploadException' => __DIR__ . '/..' . '/../lib/Exception/UploadException.php',
@@ -49,6 +50,7 @@ class ComposerStaticInitText
         'OCA\\Text\\Listeners\\BeforeNodeRenamedListener' => __DIR__ . '/..' . '/../lib/Listeners/BeforeNodeRenamedListener.php',
         'OCA\\Text\\Listeners\\FilesLoadAdditionalScriptsListener' => __DIR__ . '/..' . '/../lib/Listeners/FilesLoadAdditionalScriptsListener.php',
         'OCA\\Text\\Listeners\\FilesSharingLoadAdditionalScriptsListener' => __DIR__ . '/..' . '/../lib/Listeners/FilesSharingLoadAdditionalScriptsListener.php',
+        'OCA\\Text\\Listeners\\LoadEditorListener' => __DIR__ . '/..' . '/../lib/Listeners/LoadEditorListener.php',
         'OCA\\Text\\Listeners\\LoadViewerListener' => __DIR__ . '/..' . '/../lib/Listeners/LoadViewerListener.php',
         'OCA\\Text\\Listeners\\NodeCopiedListener' => __DIR__ . '/..' . '/../lib/Listeners/NodeCopiedListener.php',
         'OCA\\Text\\Listeners\\RegisterDirectEditorEventListener' => __DIR__ . '/..' . '/../lib/Listeners/RegisterDirectEditorEventListener.php',