mirror of
https://github.com/laurent22/joplin.git
synced 2024-11-24 08:12:24 +02:00
Generator: Resolves #4229: Add support for compiling content script
This commit is contained in:
Laurent Cozic
parent
8492a7ee26
commit
3e948146cd
@ -155,6 +155,9 @@ packages/app-cli/tests/support/plugins/content_script/api/types.js.map
|
||||
packages/app-cli/tests/support/plugins/content_script/src/index.d.ts
|
||||
packages/app-cli/tests/support/plugins/content_script/src/index.js
|
||||
packages/app-cli/tests/support/plugins/content_script/src/index.js.map
|
||||
packages/app-cli/tests/support/plugins/content_script/src/markdownItTestPlugin.d.ts
|
||||
packages/app-cli/tests/support/plugins/content_script/src/markdownItTestPlugin.js
|
||||
packages/app-cli/tests/support/plugins/content_script/src/markdownItTestPlugin.js.map
|
||||
packages/app-cli/tests/support/plugins/dialog/api/index.d.ts
|
||||
packages/app-cli/tests/support/plugins/dialog/api/index.js
|
||||
packages/app-cli/tests/support/plugins/dialog/api/index.js.map
|
||||
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@ -144,6 +144,9 @@ packages/app-cli/tests/support/plugins/content_script/api/types.js.map
|
||||
packages/app-cli/tests/support/plugins/content_script/src/index.d.ts
|
||||
packages/app-cli/tests/support/plugins/content_script/src/index.js
|
||||
packages/app-cli/tests/support/plugins/content_script/src/index.js.map
|
||||
packages/app-cli/tests/support/plugins/content_script/src/markdownItTestPlugin.d.ts
|
||||
packages/app-cli/tests/support/plugins/content_script/src/markdownItTestPlugin.js
|
||||
packages/app-cli/tests/support/plugins/content_script/src/markdownItTestPlugin.js.map
|
||||
packages/app-cli/tests/support/plugins/dialog/api/index.d.ts
|
||||
packages/app-cli/tests/support/plugins/dialog/api/index.js
|
||||
packages/app-cli/tests/support/plugins/dialog/api/index.js.map
|
||||
|
||||
@ -171,7 +171,7 @@ describe('services_PluginService', function() {
|
||||
|
||||
const contentScriptPath = `${tempDir}/markdownItTestPlugin.js`;
|
||||
const contentScriptCssPath = `${tempDir}/markdownItTestPlugin.css`;
|
||||
await shim.fsDriver().copy(`${testPluginDir}/content_script/src/markdownItTestPlugin.js`, contentScriptPath);
|
||||
await shim.fsDriver().copy(`${testPluginDir}/markdownItTestPlugin.js`, contentScriptPath);
|
||||
await shim.fsDriver().copy(`${testPluginDir}/content_script/src/markdownItTestPlugin.css`, contentScriptCssPath);
|
||||
|
||||
const service = newPluginService();
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -492,6 +492,16 @@
|
||||
"dev": true,
|
||||
"optional": true
|
||||
},
|
||||
"bindings": {
|
||||
"version": "1.5.0",
|
||||
"resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
|
||||
"integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==",
|
||||
"dev": true,
|
||||
"optional": true,
|
||||
"requires": {
|
||||
"file-uri-to-path": "1.0.0"
|
||||
}
|
||||
},
|
||||
"bluebird": {
|
||||
"version": "3.7.2",
|
||||
"resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz",
|
||||
@ -1436,6 +1446,13 @@
|
||||
"integrity": "sha512-0btnI/H8f2pavGMN8w40mlSKOfTK2SVJmBfBeVIj3kNw0swwgzyRq0d5TJVOwodFmtvpPeWPN/MCcfuWF0Ezbw==",
|
||||
"dev": true
|
||||
},
|
||||
"file-uri-to-path": {
|
||||
"version": "1.0.0",
|
||||
"resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz",
|
||||
"integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==",
|
||||
"dev": true,
|
||||
"optional": true
|
||||
},
|
||||
"fill-range": {
|
||||
"version": "7.0.1",
|
||||
"resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz",
|
||||
@ -2192,6 +2209,11 @@
|
||||
"integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
|
||||
"dev": true
|
||||
},
|
||||
"left-pad": {
|
||||
"version": "1.3.0",
|
||||
"resolved": "https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz",
|
||||
"integrity": "sha512-XI5MPzVNApjAyhQzphX8BkmKsKUxD4LdyK24iZeQGinBN9yTQT3bFlCBy/aVx2HrNcqQGsdot8ghrjyrvMCoEA=="
|
||||
},
|
||||
"loader-runner": {
|
||||
"version": "2.4.0",
|
||||
"resolved": "https://registry.npmjs.org/loader-runner/-/loader-runner-2.4.0.tgz",
|
||||
@ -2464,6 +2486,13 @@
|
||||
"integrity": "sha1-VgiurfwAvmwpAd9fmGF4jeDVl8g=",
|
||||
"dev": true
|
||||
},
|
||||
"nan": {
|
||||
"version": "2.14.2",
|
||||
"resolved": "https://registry.npmjs.org/nan/-/nan-2.14.2.tgz",
|
||||
"integrity": "sha512-M2ufzIiINKCuDfBSAUr1vWQ+vuVcA9kqx8JJUsbQi6yf1uGRyb7HfpdfUr5qLXf3B/t8dPvcjhKMmlfnP47EzQ==",
|
||||
"dev": true,
|
||||
"optional": true
|
||||
},
|
||||
"nanomatch": {
|
||||
"version": "1.2.13",
|
||||
"resolved": "https://registry.npmjs.org/nanomatch/-/nanomatch-1.2.13.tgz",
|
||||
@ -4086,7 +4115,11 @@
|
||||
"resolved": "https://registry.npmjs.org/fsevents/-/fsevents-1.2.13.tgz",
|
||||
"integrity": "sha512-oWb1Z6mkHIskLzEJ/XWX0srkpkTQ7vaopMQkyaEIoq0fmtFVxOthb8cCxeT+p3ynTdkk/RZwbgG4brR5BeWECw==",
|
||||
"dev": true,
|
||||
"optional": true
|
||||
"optional": true,
|
||||
"requires": {
|
||||
"bindings": "^1.5.0",
|
||||
"nan": "^2.12.1"
|
||||
}
|
||||
},
|
||||
"glob-parent": {
|
||||
"version": "3.1.0",
|
||||
|
||||
@ -19,5 +19,8 @@
|
||||
"typescript": "^3.9.3",
|
||||
"webpack": "^4.43.0",
|
||||
"webpack-cli": "^3.3.11"
|
||||
},
|
||||
"dependencies": {
|
||||
"left-pad": "^1.3.0"
|
||||
}
|
||||
}
|
||||
@ -6,5 +6,8 @@
|
||||
"description": "",
|
||||
"version": "1.0.0",
|
||||
"author": "",
|
||||
"homepage_url": ""
|
||||
"homepage_url": "",
|
||||
"content_scripts": [
|
||||
"markdownItTestPlugin"
|
||||
]
|
||||
}
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
const leftPad = require('left-pad');
|
||||
|
||||
function plugin(markdownIt, _options) {
|
||||
const defaultRender = markdownIt.renderer.rules.fence || function(tokens, idx, options, env, self) {
|
||||
return self.renderToken(tokens, idx, options, env, self);
|
||||
@ -8,7 +10,7 @@ function plugin(markdownIt, _options) {
|
||||
if (token.info !== 'justtesting') return defaultRender(tokens, idx, options, env, self);
|
||||
return `
|
||||
<div class="just-testing">
|
||||
<p>JUST TESTING: ${token.content}</p>
|
||||
<p>JUST TESTING: <pre>${leftPad(token.content.trim(), 10, 'x')}</pre></p>
|
||||
<p><a href="#" onclick="webviewApi.executeCommand('testCommand', 'one', 'two'); return false;">Click to send "testCommand" to plugin</a></p>
|
||||
<p><a href="#" onclick="webviewApi.executeCommand('testCommandNoArgs'); return false;">Click to send "testCommandNoArgs" to plugin</a></p>
|
||||
</div>
|
||||
@ -16,15 +18,13 @@ function plugin(markdownIt, _options) {
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
default: function(_context) {
|
||||
return {
|
||||
plugin: plugin,
|
||||
assets: function() {
|
||||
return [
|
||||
{ name: 'markdownItTestPlugin.css' }
|
||||
];
|
||||
},
|
||||
}
|
||||
},
|
||||
export default function(_context) {
|
||||
return {
|
||||
plugin: plugin,
|
||||
assets: function() {
|
||||
return [
|
||||
{ name: 'markdownItTestPlugin.css' }
|
||||
];
|
||||
},
|
||||
}
|
||||
}
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,28 @@
|
||||
function plugin(markdownIt, _options) {
|
||||
const defaultRender = markdownIt.renderer.rules.fence || function(tokens, idx, options, env, self) {
|
||||
return self.renderToken(tokens, idx, options, env, self);
|
||||
};
|
||||
|
||||
markdownIt.renderer.rules.fence = function(tokens, idx, options, env, self) {
|
||||
const token = tokens[idx];
|
||||
if (token.info !== 'justtesting') return defaultRender(tokens, idx, options, env, self);
|
||||
return `
|
||||
<div class="just-testing">
|
||||
<p>JUST TESTING: ${token.content}</p>
|
||||
</div>
|
||||
`;
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
default: function(_context) {
|
||||
return {
|
||||
plugin: plugin,
|
||||
assets: function() {
|
||||
return [
|
||||
{ name: 'markdownItTestPlugin.css' }
|
||||
];
|
||||
},
|
||||
}
|
||||
},
|
||||
}
|
||||
83
packages/app-cli/tests/support/plugins/menu/GENERATOR_DOC.md
Normal file
83
packages/app-cli/tests/support/plugins/menu/GENERATOR_DOC.md
Normal file
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
83
packages/app-cli/tests/support/plugins/toc/GENERATOR_DOC.md
Normal file
83
packages/app-cli/tests/support/plugins/toc/GENERATOR_DOC.md
Normal file
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
@ -20,6 +20,63 @@ 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ function mergePackageKey(parentKey, source, dest) {
|
||||
// If we are dealing with the dependencies, overwrite with the
|
||||
// version from source.
|
||||
output[k] = source[k];
|
||||
} else if (typeof source[k] === 'object' && !Array.isArray(k) && source[k] !== null) {
|
||||
} else if (typeof source[k] === 'object' && !Array.isArray(source[k]) && source[k] !== null) {
|
||||
// If it's an object, recursively process it
|
||||
output[k] = mergePackageKey(k, source[k], output[k]);
|
||||
} else {
|
||||
@ -116,6 +116,7 @@ module.exports = class extends Generator {
|
||||
'.gitignore_TEMPLATE',
|
||||
'package_TEMPLATE.json',
|
||||
'README.md',
|
||||
'GENERATOR_DOC.md',
|
||||
'tsconfig.json',
|
||||
'webpack.config.js',
|
||||
];
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `yo joplin --update`
|
||||
|
||||
Keep in mind that doing so will overwrite all the framework-related files **outside of the "src/" directory** (your source code will not be touched). So if you have modified any of the framework-related files, such as package.json or .gitignore, make sure your code is under version control so that you can check the diff and re-apply your changes.
|
||||
|
||||
For that reason, it's generally best not to change any of the framework files or to do so in a way that minimises the number of changes. For example, if you want to modify the Webpack config, create a new 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.
|
||||
|
||||
## Content scripts
|
||||
|
||||
A plugin that uses [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) must declare them under the `content_scripts` key of [manifest.json](https://joplinapp.org/api/references/plugin_manifest/).
|
||||
|
||||
Each entry must be a path **relative to /src**, and **without extension**. The extension should not be included because it might change once the script is compiled. Each of these scripts will then be compiled to JavaScript and packaged into the plugin file. The content script files can be TypeScript (.ts or .tsx) or JavaScript.
|
||||
|
||||
For example, assuming these files:
|
||||
|
||||
```bash
|
||||
/src
|
||||
index.ts # Main plugin script
|
||||
myContentScript.js # One content script (JS)
|
||||
otherContentScript.ts # Another content script (TypeScript)
|
||||
vendor/
|
||||
test.ts # Sub-directories are also supported
|
||||
```
|
||||
|
||||
The `manifest.json` file would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"manifest_version": 1,
|
||||
"name": "Testing Content Scripts",
|
||||
content_scripts: [
|
||||
"myContentScript",
|
||||
"otherContentScript",
|
||||
"vendor/test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note in particular how the file path is relative to /src and the extensions removed.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -20,17 +20,21 @@ 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -47,6 +47,10 @@ export default class JoplinViewsDialogs {
|
||||
* Sets the dialog HTML content
|
||||
*/
|
||||
setHtml(handle: ViewHandle, html: string): Promise<string>;
|
||||
/**
|
||||
* Adds and loads a new JS or CSS files into the dialog.
|
||||
*/
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Sets the dialog buttons.
|
||||
*/
|
||||
|
||||
@ -1,12 +1,10 @@
|
||||
{
|
||||
"name": "joplin_plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"dist": "webpack",
|
||||
"postinstall": "npm run dist"
|
||||
},
|
||||
"keywords": [],
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"@types/node": "^14.0.14",
|
||||
|
||||
@ -39,17 +39,17 @@ function createPluginArchive(sourceDir, destPath) {
|
||||
console.info(`Plugin archive has been created in ${destPath}`);
|
||||
}
|
||||
|
||||
const distDir = path.resolve(__dirname, 'dist');
|
||||
const srcDir = path.resolve(__dirname, 'src');
|
||||
const rootDir = path.resolve(__dirname);
|
||||
const distDir = path.resolve(rootDir, 'dist');
|
||||
const srcDir = path.resolve(rootDir, 'src');
|
||||
const manifestPath = `${srcDir}/manifest.json`;
|
||||
const manifest = readManifest(manifestPath);
|
||||
const archiveFilePath = path.resolve(__dirname, `${manifest.id}.jpl`);
|
||||
|
||||
fs.removeSync(distDir);
|
||||
|
||||
module.exports = {
|
||||
const baseConfig = {
|
||||
mode: 'production',
|
||||
entry: './src/index.ts',
|
||||
target: 'node',
|
||||
module: {
|
||||
rules: [
|
||||
@ -60,6 +60,10 @@ module.exports = {
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
const pluginConfig = Object.assign({}, baseConfig, {
|
||||
entry: './src/index.ts',
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
@ -70,6 +74,9 @@ module.exports = {
|
||||
filename: 'index.js',
|
||||
path: distDir,
|
||||
},
|
||||
});
|
||||
|
||||
const lastStepConfig = {
|
||||
plugins: [
|
||||
new CopyPlugin({
|
||||
patterns: [
|
||||
@ -79,8 +86,17 @@ module.exports = {
|
||||
to: path.resolve(__dirname, 'dist'),
|
||||
globOptions: {
|
||||
ignore: [
|
||||
// All TypeScript files are compiled to JS and
|
||||
// already copied into /dist so we don't copy them.
|
||||
'**/*.ts',
|
||||
'**/*.tsx',
|
||||
|
||||
// Currently we don't support JS files for the main
|
||||
// plugin script. We support it for content scripts,
|
||||
// but theyr should be declared in manifest.json,
|
||||
// and then they are also compiled and copied to
|
||||
// /dist. So wse also don't need to copy JS files.
|
||||
'**/*.js',
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -91,3 +107,62 @@ module.exports = {
|
||||
}),
|
||||
],
|
||||
};
|
||||
|
||||
const contentScriptConfig = Object.assign({}, baseConfig, {
|
||||
resolve: {
|
||||
alias: {
|
||||
api: path.resolve(__dirname, 'api'),
|
||||
},
|
||||
extensions: ['.tsx', '.ts', '.js'],
|
||||
},
|
||||
});
|
||||
|
||||
function resolveContentScriptPaths(name) {
|
||||
if (['.js', '.ts', '.tsx'].includes(path.extname(name).toLowerCase())) {
|
||||
throw new Error(`Content script path must not include file extension: ${name}`);
|
||||
}
|
||||
|
||||
const pathsToTry = [
|
||||
`./src/${name}.ts`,
|
||||
`${'./src/' + '/'}${name}.js`,
|
||||
];
|
||||
|
||||
for (const pathToTry of pathsToTry) {
|
||||
if (fs.pathExistsSync(`${rootDir}/${pathToTry}`)) {
|
||||
return {
|
||||
entry: pathToTry,
|
||||
output: {
|
||||
filename: `${name}.js`,
|
||||
path: distDir,
|
||||
library: 'default',
|
||||
libraryTarget: 'commonjs',
|
||||
libraryExport: 'default',
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
throw new Error(`Could not find content script "${name}" at locations ${JSON.stringify(pathsToTry)}`);
|
||||
}
|
||||
|
||||
function createContentScriptConfigs() {
|
||||
if (!manifest.content_scripts) return [];
|
||||
|
||||
const output = [];
|
||||
|
||||
for (const contentScriptName of manifest.content_scripts) {
|
||||
const scriptPaths = resolveContentScriptPaths(contentScriptName);
|
||||
output.push(Object.assign({}, contentScriptConfig, {
|
||||
entry: scriptPaths.entry,
|
||||
output: scriptPaths.output,
|
||||
}));
|
||||
}
|
||||
|
||||
return output;
|
||||
}
|
||||
|
||||
const exportedConfigs = [pluginConfig].concat(createContentScriptConfigs());
|
||||
|
||||
exportedConfigs[exportedConfigs.length - 1] = Object.assign({}, exportedConfigs[exportedConfigs.length - 1], lastStepConfig);
|
||||
|
||||
module.exports = exportedConfigs;
|
||||
|
||||
2
packages/generator-joplin/package-lock.json
generated
2
packages/generator-joplin/package-lock.json
generated
@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "generator-joplin",
|
||||
"version": "1.6.0",
|
||||
"version": "1.6.1",
|
||||
"lockfileVersion": 1,
|
||||
"requires": true,
|
||||
"dependencies": {
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "generator-joplin",
|
||||
"version": "1.6.0",
|
||||
"version": "1.6.1",
|
||||
"description": "Scaffolds out a new Joplin plugin",
|
||||
"homepage": "https://joplinapp.org",
|
||||
"author": {
|
||||
|
||||
@ -51,17 +51,21 @@ export default class JoplinPlugins {
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* 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.
|
||||
* 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)
|
||||
|
||||
@ -2,6 +2,9 @@ import { PluginStates } from '../reducer';
|
||||
import { ContentScriptType } from '../api/types';
|
||||
import { dirname } from '@joplin/renderer/pathUtils';
|
||||
import shim from '../../../shim';
|
||||
import Logger from '../../../Logger';
|
||||
|
||||
const logger = Logger.create('loadContentScripts');
|
||||
|
||||
export interface ExtraContentScript {
|
||||
id: string;
|
||||
@ -28,17 +31,24 @@ function loadContentScripts(plugins: PluginStates, scriptType: ContentScriptType
|
||||
if (!contentScripts) continue;
|
||||
|
||||
for (const contentScript of contentScripts) {
|
||||
const module = shim.requireDynamic(contentScript.path);
|
||||
if (!module.default || typeof module.default !== 'function') throw new Error(`Content script must export a function under the "default" key: Plugin: ${pluginId}: Script: ${contentScript.id}`);
|
||||
try {
|
||||
const module = shim.requireDynamic(contentScript.path);
|
||||
if (!module.default || typeof module.default !== 'function') throw new Error(`Content script must export a function under the "default" key: Plugin: ${pluginId}: Script: ${contentScript.id}`);
|
||||
|
||||
const loadedModule = module.default({});
|
||||
if (!loadedModule.plugin && !loadedModule.codeMirrorResources && !loadedModule.codeMirrorOptions) throw new Error(`Content script must export a "plugin" key or a list of CodeMirror assets or define a CodeMirror option: Plugin: ${pluginId}: Script: ${contentScript.id}`);
|
||||
const loadedModule = module.default({});
|
||||
if (!loadedModule.plugin && !loadedModule.codeMirrorResources && !loadedModule.codeMirrorOptions) throw new Error(`Content script must export a "plugin" key or a list of CodeMirror assets or define a CodeMirror option: Plugin: ${pluginId}: Script: ${contentScript.id}`);
|
||||
|
||||
output.push({
|
||||
id: contentScript.id,
|
||||
module: loadedModule,
|
||||
assetPath: dirname(contentScript.path),
|
||||
});
|
||||
output.push({
|
||||
id: contentScript.id,
|
||||
module: loadedModule,
|
||||
assetPath: dirname(contentScript.path),
|
||||
});
|
||||
} catch (error) {
|
||||
// This function must not throw as doing so would crash the
|
||||
// application, which we want to avoid for plugins. Instead log
|
||||
// the error, and continue loading the other content scripts.
|
||||
logger.error(error.message);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -2,17 +2,18 @@
|
||||
|
||||
The manifest file is a JSON file that describes various properties of the plugin. If you use the Yeoman generator, it should be automatically generated based on the answers you've provided. The supported properties are:
|
||||
|
||||
Name | Required? | Description
|
||||
--- | --- | ---
|
||||
`manifest_version` | **Yes** | For now should always be "1".
|
||||
`name` | **Yes** | Name of the plugin. Should be a user-friendly string, as it will be displayed in the UI.
|
||||
`version` | **Yes** | Version number such as "1.0.0".
|
||||
`app_min_version` | **Yes** | Minimum version of Joplin that the plugin is compatible with. In general it should be whatever version you are using to develop the plugin.
|
||||
`description` | No | Detailed description of the plugin.
|
||||
`author` | No | Plugin author name.
|
||||
`homepage_url` | No | Homepage URL of the plugin. It can also be, for example, a link to a GitHub repository.
|
||||
Name | Type | Required? | Description
|
||||
--- | --- | --- | ---
|
||||
`manifest_version` | number | **Yes** | For now should always be "1".
|
||||
`name` | string | **Yes** | Name of the plugin. Should be a user-friendly string, as it will be displayed in the UI.
|
||||
`version` | string | **Yes** | Version number such as "1.0.0".
|
||||
`app_min_version` | string | **Yes** | Minimum version of Joplin that the plugin is compatible with. In general it should be whatever version you are using to develop the plugin.
|
||||
`description` | string | No | Detailed description of the plugin.
|
||||
`author` | string | No | Plugin author name.
|
||||
`homepage_url` | string | No | Homepage URL of the plugin. It can also be, for example, a link to a GitHub repository.
|
||||
`content_scripts` | string[] | No | List of [content scripts](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md#content-scripts) used by the plugin.
|
||||
|
||||
Here's a complete example:
|
||||
## Manifest example
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user