Updated Yeoman generator

GENERATOR_DOC.md

@@ -0,0 +1,72 @@
+# generator-joplin
+
+Scaffolds out a new Joplin plugin
+
+## Installation
+
+First, install [Yeoman](http://yeoman.io) and generator-joplin using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).
+
+```bash
+npm install -g yo
+npm install -g generator-joplin
+```
+
+Then generate your new project:
+
+```bash
+yo joplin
+```
+
+## Development
+
+To test the generator for development purposes, follow the instructions there: https://yeoman.io/authoring/#running-the-generator
+This is a template to create a new Joplin plugin.
+
+## Structure
+
+The main two files you will want to look at are:
+
+- `/src/index.ts`, which contains the entry point for the plugin source code.
+- `/src/manifest.json`, which is the plugin manifest. It contains information such as the plugin a name, version, etc.
+
+The file `/plugin.config.json` could also be useful if you intend to use [external scripts](#external-script-files), such as content scripts or webview scripts.
+
+## Building the plugin
+
+The plugin is built using Webpack, which creates the compiled code in `/dist`. A JPL archive will also be created at the root, which can use to distribute the plugin.
+
+To build the plugin, simply run `npm run dist`.
+
+The project is setup to use TypeScript, although you can change the configuration to use plain JavaScript.
+
+## Publishing the plugin
+
+To publish the plugin, add it to npmjs.com by running `npm publish`. Later on, a script will pick up your plugin and add it automatically to the Joplin plugin repository as long as the package satisfies these conditions:
+
+- In `package.json`, the name starts with "joplin-plugin-". For example, "joplin-plugin-toc".
+- In `package.json`, the keywords include "joplin-plugin".
+- In the `publish/` directory, there should be a .jpl and .json file (which are built by `npm run dist`)
+
+In general all this is done automatically by the plugin generator, which will set the name and keywords of package.json, and will put the right files in the "publish" directory. But if something doesn't work and your plugin doesn't appear in the repository, double-check the above conditions.
+
+## Updating the plugin framework
+
+To update the plugin framework, run `npm run update`.
+
+In general this command tries to do the right thing - in particular it's going to merge the changes in package.json and .gitignore instead of overwriting. It will also leave "/src" as well as README.md untouched.
+
+The file that may cause problem is "webpack.config.js" because it's going to be overwritten. For that reason, if you want to change it, consider creating a separate JavaScript file and include it in webpack.config.js. That way, when you update, you only have to restore the line that include your file.
+
+## External script files
+
+By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
+
+- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
+
+- The script requires modules you've added to package.json. In that case, the script, whether JS or TS, must be compiled so that the dependencies are bundled with the JPL file.
+
+To get such an external script file to compile, you need to add it to the `extraScripts` array in `plugin.config.json`. The path you add should be relative to /src. For example, if you have a file in "/src/webviews/index.ts", the path should be set to "webviews/index.ts". Once compiled, the file will always be named with a .js extension. So you will get "webviews/index.js" in the plugin package, and that's the path you should use to reference the file.
+
+## License
+
+MIT © Laurent Cozic

api/Global.d.ts

@@ -1,15 +1,14 @@
 import Plugin from '../Plugin';
 import Joplin from './Joplin';
-import Logger from 'lib/Logger';
+/**
+ * @ignore
+ */
 /**
  * @ignore
  */
 export default class Global {
     private joplin_;
-    private requireWhiteList_;
-    constructor(logger: Logger, implementation: any, plugin: Plugin, store: any);
+    constructor(implementation: any, plugin: Plugin, store: any);
     get joplin(): Joplin;
-    private requireWhiteList;
-    require(filePath: string): any;
     get process(): any;
 }

api/Joplin.d.ts

@@ -7,9 +7,21 @@ import JoplinCommands from './JoplinCommands';
 import JoplinViews from './JoplinViews';
 import JoplinInterop from './JoplinInterop';
 import JoplinSettings from './JoplinSettings';
-import Logger from 'lib/Logger';
+import JoplinContentScripts from './JoplinContentScripts';
 /**
  * This is the main entry point to the Joplin API. You can access various services using the provided accessors.
+ *
+ * **This is a beta API**
+ *
+ * Please note that the plugin API is relatively new and should be considered Beta state. Besides possible bugs, what it means is that there might be necessary breaking changes from one version to the next. Whenever such change is needed, best effort will be done to:
+ *
+ * - Maintain backward compatibility;
+ * - When possible, deprecate features instead of removing them;
+ * - Document breaking changes in the changelog;
+ *
+ * So if you are developing a plugin, please keep an eye on the changelog as everything will be in there with information about how to update your code. There won't be any major API rewrite or architecture changes, but possibly small tweaks like function signature change, type change, etc.
+ *
+ * Eventually, the plugin API will be versioned to make this process smoother.
  */
 export default class Joplin {
     private data_;
@@ -20,10 +32,12 @@ export default class Joplin {
     private views_;
     private interop_;
     private settings_;
-    constructor(logger: Logger, implementation: any, plugin: Plugin, store: any);
+    private contentScripts_;
+    constructor(implementation: any, plugin: Plugin, store: any);
     get data(): JoplinData;
     get plugins(): JoplinPlugins;
     get workspace(): JoplinWorkspace;
+    get contentScripts(): JoplinContentScripts;
     /**
      * @ignore
      *
@@ -35,4 +49,17 @@ export default class Joplin {
     get views(): JoplinViews;
     get interop(): JoplinInterop;
     get settings(): JoplinSettings;
+    /**
+     * It is not possible to bundle native packages with a plugin, because they
+     * need to work cross-platforms. Instead access to certain useful native
+     * packages is provided using this function.
+     *
+     * Currently these packages are available:
+     *
+     * - [sqlite3](https://www.npmjs.com/package/sqlite3)
+     * - [fs-extra](https://www.npmjs.com/package/fs-extra)
+     *
+     * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/nativeModule)
+     */
+    require(_path: string): any;
 }

api/JoplinCommands.d.ts

@@ -1,25 +1,63 @@
 import { Command } from './types';
 /**
- * This class allows executing or registering new Joplin commands. Commands can be executed or associated with
- * {@link JoplinViewsToolbarButtons | toolbar buttons} or {@link JoplinViewsMenuItems | menu items}.
+ * This class allows executing or registering new Joplin commands. Commands
+ * can be executed or associated with
+ * {@link JoplinViewsToolbarButtons | toolbar buttons} or
+ * {@link JoplinViewsMenuItems | menu items}.
  *
- * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/CliClient/tests/support/plugins/register_command)
+ * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/register_command)
  *
  * ## Executing Joplin's internal commands
  *
- * It is also possible to execute internal Joplin's commands which, as of now, are not well documented.
- * You can find the list directly on GitHub though at the following locations:
+ * It is also possible to execute internal Joplin's commands which, as of
+ * now, are not well documented. You can find the list directly on GitHub
+ * though at the following locations:
  *
- * https://github.com/laurent22/joplin/tree/dev/ElectronClient/gui/MainScreen/commands
- * https://github.com/laurent22/joplin/tree/dev/ElectronClient/commands
- * https://github.com/laurent22/joplin/tree/dev/ElectronClient/gui/NoteEditor/commands/editorCommandDeclarations.ts
+ * * [Main screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/MainScreen/commands)
+ * * [Global commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/commands)
+ * * [Editor commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/NoteEditor/commands/editorCommandDeclarations.ts)
+ *
+ * To view what arguments are supported, you can open any of these files
+ * and look at the `execute()` command.
+ *
+ * ## Executing editor commands
+ *
+ * There might be a situation where you want to invoke editor commands
+ * without using a {@link JoplinContentScripts | contentScript}. For this
+ * reason Joplin provides the built in `editor.execCommand` command.
+ *
+ * `editor.execCommand`  should work with any core command in both the
+ * [CodeMirror](https://codemirror.net/doc/manual.html#execCommand) and
+ * [TinyMCE](https://www.tiny.cloud/docs/api/tinymce/tinymce.editorcommands/#execcommand) editors,
+ * as well as most functions calls directly on a CodeMirror editor object (extensions).
+ *
+ * * [CodeMirror commands](https://codemirror.net/doc/manual.html#commands)
+ * * [TinyMCE core editor commands](https://www.tiny.cloud/docs/advanced/editor-command-identifiers/#coreeditorcommands)
+ *
+ * `editor.execCommand` supports adding arguments for the commands.
+ *
+ * ```typescript
+ * await joplin.commands.execute('editor.execCommand', {
+ *     name: 'madeUpCommand', // CodeMirror and TinyMCE
+ *     args: [], // CodeMirror and TinyMCE
+ *     ui: false, // TinyMCE only
+ *     value: '', // TinyMCE only
+ * });
+ * ```
+ *
+ * [View the example using the CodeMirror editor](https://github.com/laurent22/joplin/blob/dev/packages/app-cli/tests/support/plugins/codemirror_content_script/src/index.ts)
  *
- * To view what arguments are supported, you can open any of these files and look at the `execute()` command.
  */
 export default class JoplinCommands {
-    /**
-     * <span class="platform-desktop">desktop</span> Executes the given command.
-     * The `props` are the arguments passed to the command, and they vary based on the command
+	/**
+     * <span class="platform-desktop">desktop</span> Executes the given
+     * command.
+     *
+     * The command can take any number of arguments, and the supported
+     * arguments will vary based on the command. For custom commands, this
+     * is the `args` passed to the `execute()` function. For built-in
+     * commands, you can find the supported arguments by checking the links
+     * above.
      *
      * ```typescript
      * // Create a new note in the current notebook:
@@ -30,8 +68,8 @@ export default class JoplinCommands {
      * await joplin.commands.execute('newFolder', "SOME_FOLDER_ID");
      * ```
      */
-    execute(commandName: string, ...args: any[]): Promise<any | void>;
-    /**
+	execute(commandName: string, ...args: any[]): Promise<any | void>;
+	/**
      * <span class="platform-desktop">desktop</span> Registers a new command.
      *
      * ```typescript
@@ -47,5 +85,5 @@ export default class JoplinCommands {
      * });
      * ```
      */
-    register(command: Command): Promise<void>;
+	register(command: Command): Promise<void>;
 }

api/JoplinContentScripts.d.ts

@@ -0,0 +1,40 @@
+import Plugin from '../Plugin';
+import { ContentScriptType } from './types';
+export default class JoplinContentScripts {
+    private plugin;
+    constructor(plugin: Plugin);
+    /**
+     * Registers a new content script. Unlike regular plugin code, which runs in
+     * a separate process, content scripts run within the main process code and
+     * thus allow improved performances and more customisations in specific
+     * cases. It can be used for example to load a Markdown or editor plugin.
+     *
+     * Note that registering a content script in itself will do nothing - it
+     * will only be loaded in specific cases by the relevant app modules (eg.
+     * the Markdown renderer or the code editor). So it is not a way to inject
+     * and run arbitrary code in the app, which for safety and performance
+     * reasons is not supported.
+     *
+     * The plugin generator provides a way to build any content script you might
+     * want to package as well as its dependencies. See the [Plugin Generator
+     * doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
+     * for more information.
+     *
+     * * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
+     * * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
+     *
+     * See also the [postMessage demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages)
+     *
+     * @param type Defines how the script will be used. See the type definition for more information about each supported type.
+     * @param id A unique ID for the content script.
+     * @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
+     */
+    register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
+    /**
+     * Listens to a messages sent from the content script using postMessage().
+     * See {@link ContentScriptType} for more information as well as the
+     * [postMessage
+     * demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages)
+     */
+    onMessage(contentScriptId: string, callback: any): Promise<void>;
+}

api/JoplinData.d.ts

@@ -6,7 +6,7 @@ import { Path } from './types';
  *
  * This is also what you would use to search notes, via the `search` endpoint.
  *
- * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/CliClient/tests/support/plugins/simple)
+ * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/simple)
  *
  * In general you would use the methods in this class as if you were using a REST API. There are four methods that map to GET, POST, PUT and DELETE calls.
  * And each method takes these parameters:

api/JoplinFilters.d.ts

@@ -5,6 +5,6 @@
  * so for now disable filters.
  */
 export default class JoplinFilters {
-    on(name: string, callback: Function): Promise<void>;
-    off(name: string, callback: Function): Promise<void>;
+	on(name: string, callback: Function): Promise<void>;
+	off(name: string, callback: Function): Promise<void>;
 }

api/JoplinInterop.d.ts

@@ -2,7 +2,7 @@ import { ExportModule, ImportModule } from './types';
 /**
  * Provides a way to create modules to import external data into Joplin or to export notes into any arbitrary format.
  *
- * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/CliClient/tests/support/plugins/json_export)
+ * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/json_export)
  *
  * To implement an import or export module, you would simply define an object with various event handlers that are called
  * by the application during the import/export process.
@@ -12,6 +12,6 @@ import { ExportModule, ImportModule } from './types';
  * You may also want to refer to the Joplin API documentation to see the list of properties for each item (note, notebook, etc.) - https://joplinapp.org/api/references/rest_api/
  */
 export default class JoplinInterop {
-    registerExportModule(module: ExportModule): Promise<void>;
-    registerImportModule(module: ImportModule): Promise<void>;
+	registerExportModule(module: ExportModule): Promise<void>;
+	registerImportModule(module: ImportModule): Promise<void>;
 }

api/JoplinPlugins.d.ts

@@ -1,13 +1,11 @@
 import Plugin from '../Plugin';
-import Logger from 'lib/Logger';
 import { ContentScriptType, Script } from './types';
 /**
  * This class provides access to plugin-related features.
  */
 export default class JoplinPlugins {
-    private logger;
     private plugin;
-    constructor(logger: Logger, plugin: Plugin);
+    constructor(plugin: Plugin);
     /**
      * Registers a new plugin. This is the entry point when creating a plugin. You should pass a simple object with an `onStart` method to it.
      * That `onStart` method will be executed as soon as the plugin is loaded.
@@ -22,17 +20,24 @@ export default class JoplinPlugins {
      */
     register(script: Script): Promise<void>;
     /**
-     * Registers a new content script. Unlike regular plugin code, which runs in a separate process, content scripts run within the main process code
-     * and thus allow improved performances and more customisations in specific cases. It can be used for example to load a Markdown or editor plugin.
-     *
-     * Note that registering a content script in itself will do nothing - it will only be loaded in specific cases by the relevant app modules
-     * (eg. the Markdown renderer or the code editor). So it is not a way to inject and run arbitrary code in the app, which for safety and performance reasons is not supported.
-     *
-     * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/CliClient/tests/support/plugins/content_script)
-     *
-     * @param type Defines how the script will be used. See the type definition for more information about each supported type.
-     * @param id A unique ID for the content script.
-     * @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
+     * @deprecated Use joplin.contentScripts.register()
      */
     registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
+    /**
+     * Gets the plugin own data directory path. Use this to store any
+     * plugin-related data. Unlike [[installationDir]], any data stored here
+     * will be persisted.
+     */
+    dataDir(): Promise<string>;
+    /**
+     * Gets the plugin installation directory. This can be used to access any
+     * asset that was packaged with the plugin. This directory should be
+     * considered read-only because any data you store here might be deleted or
+     * re-created at any time. To store new persistent data, use [[dataDir]].
+     */
+    installationDir(): Promise<string>;
+    /**
+     * @deprecated Use joplin.require()
+     */
+    require(_path: string): any;
 }