mirror of
https://github.com/laurent22/joplin.git
synced 2024-12-24 10:27:10 +02:00
Doc: Updated doc and tests for plugin postMessage() update
This commit is contained in:
Laurent Cozic
parent
2489409abb
commit
79dde365f0
@ -22,7 +22,8 @@ module.exports = {
|
||||
|
||||
return `joplin.${camelCaseToDots(p)
|
||||
.replace(/menu\.items/, 'menuItems')
|
||||
.replace(/toolbar\.buttons/, 'toolbarButtons')}`;
|
||||
.replace(/toolbar\.buttons/, 'toolbarButtons')
|
||||
.replace(/content\.scripts/, 'contentScripts')}`;
|
||||
},
|
||||
|
||||
jpIsAllowedGroup: function(name) {
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -102,6 +102,7 @@
|
||||
<h3>Accessors</h3>
|
||||
<ul class="tsd-index-list">
|
||||
<li class="tsd-kind-get-signature tsd-parent-kind-class"><a href="joplin.html#commands" class="tsd-kind-icon">commands</a></li>
|
||||
<li class="tsd-kind-get-signature tsd-parent-kind-class"><a href="joplin.html#contentscripts" class="tsd-kind-icon">content<wbr>Scripts</a></li>
|
||||
<li class="tsd-kind-get-signature tsd-parent-kind-class"><a href="joplin.html#data" class="tsd-kind-icon">data</a></li>
|
||||
<li class="tsd-kind-get-signature tsd-parent-kind-class"><a href="joplin.html#interop" class="tsd-kind-icon">interop</a></li>
|
||||
<li class="tsd-kind-get-signature tsd-parent-kind-class"><a href="joplin.html#plugins" class="tsd-kind-icon">plugins</a></li>
|
||||
@ -131,6 +132,24 @@
|
||||
<h4 class="tsd-returns-title">Returns <a href="joplincommands.html" class="tsd-signature-type">joplin.commands</a></h4>
|
||||
|
||||
|
||||
-->
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-get-signature tsd-parent-kind-class">
|
||||
<a name="contentscripts" class="tsd-anchor"></a>
|
||||
<h3>content<wbr>Scripts</h3>
|
||||
<ul class="tsd-signatures tsd-kind-get-signature tsd-parent-kind-class">
|
||||
<li class="tsd-signature tsd-kind-icon"><span class="tsd-signature-symbol">get</span> contentScripts<span class="tsd-signature-symbol">(</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><a href="joplincontentscripts.html" class="tsd-signature-type">joplin.contentScripts</a></li>
|
||||
</ul>
|
||||
<ul class="tsd-descriptions">
|
||||
<li class="tsd-description">
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<!-- JOPLINCHANGE
|
||||
<h4 class="tsd-returns-title">Returns <a href="joplincontentscripts.html" class="tsd-signature-type">joplin.contentScripts</a></h4>
|
||||
|
||||
|
||||
-->
|
||||
</li>
|
||||
</ul>
|
||||
@ -268,6 +287,9 @@
|
||||
<li class=" tsd-kind-get-signature tsd-parent-kind-class">
|
||||
<a href="joplin.html#commands" class="tsd-kind-icon">commands</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-get-signature tsd-parent-kind-class">
|
||||
<a href="joplin.html#contentscripts" class="tsd-kind-icon">content<wbr>Scripts</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-get-signature tsd-parent-kind-class">
|
||||
<a href="joplin.html#data" class="tsd-kind-icon">data</a>
|
||||
</li>
|
||||
|
||||
256
docs/api/references/plugin_api/classes/joplincontentscripts.html
Normal file
256
docs/api/references/plugin_api/classes/joplincontentscripts.html
Normal file
@ -0,0 +1,256 @@
|
||||
<!doctype html>
|
||||
<html class="default no-js">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<title>joplin.contentScripts | Joplin Plugin API Documentation</title>
|
||||
<meta name="description" content="Documentation for Joplin Plugin API Documentation">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<link rel="stylesheet" href="../assets/css/main.css">
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<div class="tsd-page-toolbar">
|
||||
<div class="container">
|
||||
<div class="table-wrap">
|
||||
<div class="table-cell" id="tsd-search" data-index="../assets/js/search.json" data-base="..">
|
||||
<div class="field">
|
||||
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
|
||||
<input id="tsd-search-field" type="text" />
|
||||
</div>
|
||||
<ul class="results">
|
||||
<li class="state loading">Preparing search index...</li>
|
||||
<li class="state failure">The search index is not available</li>
|
||||
</ul>
|
||||
<a href="joplin.html" class="title">Joplin Plugin API Documentation</a>
|
||||
</div>
|
||||
<div class="table-cell" id="tsd-widgets">
|
||||
<div id="tsd-filter">
|
||||
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
|
||||
<div class="tsd-filter-group">
|
||||
<div class="tsd-select" id="tsd-filter-visibility">
|
||||
<span class="tsd-select-label">All</span>
|
||||
<ul class="tsd-select-list">
|
||||
<li data-value="public">Public</li>
|
||||
<li data-value="protected">Public/Protected</li>
|
||||
<li data-value="private" class="selected">All</li>
|
||||
</ul>
|
||||
</div>
|
||||
<input type="checkbox" id="tsd-filter-inherited" checked />
|
||||
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
|
||||
</div>
|
||||
</div>
|
||||
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="tsd-page-title">
|
||||
<div class="container">
|
||||
<ul class="tsd-breadcrumb">
|
||||
<!--
|
||||
<li>
|
||||
<a href="../globals.html">Globals</a>
|
||||
</li>
|
||||
-->
|
||||
<li>
|
||||
<a href="joplincontentscripts.html">joplin.contentScripts</a>
|
||||
</li>
|
||||
</ul>
|
||||
<h1><!-- Class -->joplin.contentScripts</h1>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<div class="container container-main">
|
||||
<div class="row">
|
||||
<div class="col-8 col-content">
|
||||
<!--
|
||||
<section class="tsd-panel tsd-hierarchy">
|
||||
<h3>Hierarchy</h3>
|
||||
<ul class="tsd-hierarchy">
|
||||
<li>
|
||||
<span class="target">JoplinContentScripts</span>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</section>
|
||||
-->
|
||||
<section class="tsd-panel-group tsd-index-group">
|
||||
<h2>Index</h2>
|
||||
<section class="tsd-panel tsd-index-panel">
|
||||
<div class="tsd-index-content">
|
||||
<section class="tsd-index-section ">
|
||||
</section>
|
||||
<section class="tsd-index-section ">
|
||||
<h3>Methods</h3>
|
||||
<ul class="tsd-index-list">
|
||||
<li class="tsd-kind-method tsd-parent-kind-class"><a href="joplincontentscripts.html#onmessage" class="tsd-kind-icon">on<wbr>Message</a></li>
|
||||
<li class="tsd-kind-method tsd-parent-kind-class"><a href="joplincontentscripts.html#register" class="tsd-kind-icon">register</a></li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
<section class="tsd-panel-group tsd-member-group ">
|
||||
</section>
|
||||
<section class="tsd-panel-group tsd-member-group ">
|
||||
<h2>Methods</h2>
|
||||
<section class="tsd-panel tsd-member tsd-kind-method tsd-parent-kind-class">
|
||||
<a name="onmessage" class="tsd-anchor"></a>
|
||||
<h3>on<wbr>Message</h3>
|
||||
<ul class="tsd-signatures tsd-kind-method tsd-parent-kind-class">
|
||||
<li class="tsd-signature tsd-kind-icon">on<wbr>Message<span class="tsd-signature-symbol">(</span>contentScriptId<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span>, callback<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">></span></li>
|
||||
</ul>
|
||||
<ul class="tsd-descriptions">
|
||||
<li class="tsd-description">
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>Listens to a messages sent from the content script using postMessage().
|
||||
See <a href="../enums/contentscripttype.html">ContentScriptType</a> for more information as well as the
|
||||
<a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages">postMessage
|
||||
demo</a></p>
|
||||
</div>
|
||||
</div>
|
||||
<h4 class="tsd-parameters-title">Parameters</h4>
|
||||
<ul class="tsd-parameters">
|
||||
<li>
|
||||
<h5>contentScriptId: <span class="tsd-signature-type">string</span></h5>
|
||||
</li>
|
||||
<li>
|
||||
<h5>callback: <span class="tsd-signature-type">any</span></h5>
|
||||
</li>
|
||||
</ul>
|
||||
<!-- JOPLINCHANGE
|
||||
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">></span></h4>
|
||||
|
||||
|
||||
-->
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-method tsd-parent-kind-class">
|
||||
<a name="register" class="tsd-anchor"></a>
|
||||
<h3>register</h3>
|
||||
<ul class="tsd-signatures tsd-kind-method tsd-parent-kind-class">
|
||||
<li class="tsd-signature tsd-kind-icon">register<span class="tsd-signature-symbol">(</span>type<span class="tsd-signature-symbol">: </span><a href="../enums/contentscripttype.html" class="tsd-signature-type">ContentScriptType</a>, id<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span>, scriptPath<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">></span></li>
|
||||
</ul>
|
||||
<ul class="tsd-descriptions">
|
||||
<li class="tsd-description">
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>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.</p>
|
||||
</div>
|
||||
<p>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.</p>
|
||||
<p>The plugin generator provides a way to build any content script you might
|
||||
want to package as well as its dependencies. See the <a href="https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md">Plugin Generator
|
||||
doc</a>
|
||||
for more information.</p>
|
||||
<ul>
|
||||
<li><a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script">View the renderer demo plugin</a></li>
|
||||
<li><a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script">View the editor demo plugin</a></li>
|
||||
</ul>
|
||||
<p>See also the <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages">postMessage demo</a></p>
|
||||
</div>
|
||||
<h4 class="tsd-parameters-title">Parameters</h4>
|
||||
<ul class="tsd-parameters">
|
||||
<li>
|
||||
<h5>type: <a href="../enums/contentscripttype.html" class="tsd-signature-type">ContentScriptType</a></h5>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<p>Defines how the script will be used. See the type definition for more information about each supported type.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<h5>id: <span class="tsd-signature-type">string</span></h5>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<p>A unique ID for the content script.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<h5>scriptPath: <span class="tsd-signature-type">string</span></h5>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<p>Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set <code>scriptPath</code> to <code>"./content_script.js</code>.</p>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
<!-- JOPLINCHANGE
|
||||
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">></span></h4>
|
||||
|
||||
|
||||
-->
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
</section>
|
||||
</div>
|
||||
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
|
||||
<!--
|
||||
<nav class="tsd-navigation primary">
|
||||
<ul>
|
||||
<li class="globals ">
|
||||
<a href="../globals.html"><em>Globals</em></a>
|
||||
</li>
|
||||
</ul>
|
||||
</nav>
|
||||
-->
|
||||
<nav class="tsd-navigation secondary menu-sticky">
|
||||
<ul class="before-current">
|
||||
</ul>
|
||||
<ul class="current">
|
||||
<li class="current tsd-kind-class">
|
||||
<a href="joplincontentscripts.html" class="tsd-kind-icon">joplin.contentScripts</a>
|
||||
<ul>
|
||||
<li class=" tsd-kind-constructor tsd-parent-kind-class">
|
||||
<a href="joplincontentscripts.html#constructor" class="tsd-kind-icon">constructor</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-method tsd-parent-kind-class">
|
||||
<a href="joplincontentscripts.html#onmessage" class="tsd-kind-icon">on<wbr>Message</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-method tsd-parent-kind-class">
|
||||
<a href="joplincontentscripts.html#register" class="tsd-kind-icon">register</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul class="after-current">
|
||||
</ul>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- JOPLINCHANGE
|
||||
<footer class="with-border-bottom">
|
||||
<div class="container">
|
||||
<h2>Legend</h2>
|
||||
<div class="tsd-legend-group">
|
||||
<ul class="tsd-legend">
|
||||
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
|
||||
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
|
||||
</ul>
|
||||
<ul class="tsd-legend">
|
||||
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
|
||||
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
<div class="container tsd-generator">
|
||||
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
|
||||
</div>
|
||||
-->
|
||||
<div class="overlay"></div>
|
||||
<script src="../assets/js/main.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@ -149,45 +149,22 @@
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>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.</p>
|
||||
</div>
|
||||
<p>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.</p>
|
||||
<p>The plugin generator provides a way to build any content script you might
|
||||
want to package as well as its dependencies. See the <a href="https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md">Plugin Generator
|
||||
doc</a>
|
||||
for more information.</p>
|
||||
<ul>
|
||||
<li><a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script">View the renderer demo plugin</a></li>
|
||||
<li><a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script">View the editor demo plugin</a></li>
|
||||
</ul>
|
||||
<dl class="tsd-comment-tags">
|
||||
<dt>deprecated</dt>
|
||||
<dd><p>Use joplin.contentScripts.register()</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
<h4 class="tsd-parameters-title">Parameters</h4>
|
||||
<ul class="tsd-parameters">
|
||||
<li>
|
||||
<h5>type: <a href="../enums/contentscripttype.html" class="tsd-signature-type">ContentScriptType</a></h5>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<p>Defines how the script will be used. See the type definition for more information about each supported type.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<h5>id: <span class="tsd-signature-type">string</span></h5>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<p>A unique ID for the content script.</p>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<h5>scriptPath: <span class="tsd-signature-type">string</span></h5>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<p>Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set <code>scriptPath</code> to <code>"./content_script.js</code>.</p>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
<!-- JOPLINCHANGE
|
||||
|
||||
@ -217,6 +217,16 @@
|
||||
<div class="lead">
|
||||
<p>Called when a message is sent from the webview (using postMessage).</p>
|
||||
</div>
|
||||
<p>To post a message from the webview to the plugin use:</p>
|
||||
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> response = <span class="hljs-keyword">await</span> webviewApi.postMessage(message);</code></pre>
|
||||
<ul>
|
||||
<li><code>message</code> can be any JavaScript object, string or number</li>
|
||||
<li><code>response</code> is whatever was returned by the <code>onMessage</code> handler</li>
|
||||
</ul>
|
||||
<p>Using this mechanism, you can have two-way communication between the
|
||||
plugin and webview.</p>
|
||||
<p>See the <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages">postMessage
|
||||
demo</a> for more details.</p>
|
||||
</div>
|
||||
<h4 class="tsd-parameters-title">Parameters</h4>
|
||||
<ul class="tsd-parameters">
|
||||
|
||||
@ -108,42 +108,56 @@
|
||||
}
|
||||
}</code></pre>
|
||||
<ul>
|
||||
<li><p>The <code>context</code> argument is currently unused but could be used later
|
||||
on to provide access to your own plugin so that the content script
|
||||
and plugin can communicate.</p>
|
||||
<li><p>The <code>context</code> argument is currently unused but could be used later on
|
||||
to provide access to your own plugin so that the content script and
|
||||
plugin can communicate.</p>
|
||||
</li>
|
||||
<li><p>The <code>plugin</code> key is your CodeMirror plugin. This is where you can
|
||||
register new commands with CodeMirror or interact with the
|
||||
CodeMirror instance as needed.</p>
|
||||
register new commands with CodeMirror or interact with the CodeMirror
|
||||
instance as needed.</p>
|
||||
</li>
|
||||
<li><p>The <code>codeMirrorResources</code> key is an array of CodeMirror resources
|
||||
that will be loaded and attached to the CodeMirror module. These
|
||||
are made up of addons, keymaps, and modes. For example, for a
|
||||
plugin that want's to enable clojure highlighting in code blocks.
|
||||
<code>codeMirrorResources</code> would be set to <code>['mode/clojure/clojure']</code>.</p>
|
||||
<li><p>The <code>codeMirrorResources</code> key is an array of CodeMirror resources that
|
||||
will be loaded and attached to the CodeMirror module. These are made up
|
||||
of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
enable clojure highlighting in code blocks. <code>codeMirrorResources</code> would
|
||||
be set to <code>['mode/clojure/clojure']</code>.</p>
|
||||
</li>
|
||||
<li><p>The <code>codeMirrorOptions</code> key contains all the
|
||||
<a href="https://codemirror.net/doc/manual.html#config">CodeMirror</a>
|
||||
options that will be set or changed by this plugin. New options
|
||||
can alse be declared via
|
||||
<a href="https://codemirror.net/doc/manual.html#config">CodeMirror</a> options
|
||||
that will be set or changed by this plugin. New options can alse be
|
||||
declared via
|
||||
<a href="https://codemirror.net/doc/manual.html#defineOption"><code>CodeMirror.defineOption</code></a>,
|
||||
and then have their value set here. For example, a plugin that
|
||||
enables line numbers would set <code>codeMirrorOptions</code> to
|
||||
<code>{'lineNumbers': true}</code>.</p>
|
||||
and then have their value set here. For example, a plugin that enables
|
||||
line numbers would set <code>codeMirrorOptions</code> to <code>{'lineNumbers': true}</code>.</p>
|
||||
</li>
|
||||
<li><p>Using the <strong>optional</strong> <code>assets</code> key you may specify <strong>only</strong> CSS
|
||||
assets that should be loaded in the rendered HTML document. Check
|
||||
for example the Joplin [Mermaid
|
||||
<li><p>Using the <strong>optional</strong> <code>assets</code> key you may specify <strong>only</strong> CSS assets
|
||||
that should be loaded in the rendered HTML document. Check for example
|
||||
the Joplin [Mermaid
|
||||
plugin](<a href="https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts">https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts</a>)
|
||||
to see how the data should be structured.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>One of the <code>plugin</code>, <code>codeMirrorResources</code>, or <code>codeMirrorOptions</code>
|
||||
keys must be provided for the plugin to be valid. Having multiple or
|
||||
all provided is also okay.</p>
|
||||
<p>See the <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script">demo
|
||||
<p>One of the <code>plugin</code>, <code>codeMirrorResources</code>, or <code>codeMirrorOptions</code> keys
|
||||
must be provided for the plugin to be valid. Having multiple or all
|
||||
provided is also okay.</p>
|
||||
<p>See also the <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script">demo
|
||||
plugin</a>
|
||||
for an example of all these keys being used in one plugin.</p>
|
||||
<a href="#posting-messages-from-the-content-script-to-your-plugin" id="posting-messages-from-the-content-script-to-your-plugin" style="color: inherit; text-decoration: none;">
|
||||
<h2>Posting messages from the content script to your plugin</h2>
|
||||
</a>
|
||||
<p>In order to post messages to the plugin, you can use the postMessage
|
||||
function passed to the <a href="../interfaces/contentscriptcontext.html">context</a>.</p>
|
||||
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> response = <span class="hljs-keyword">await</span> context.postMessage(<span class="hljs-string">'messageFromCodeMirrorContentScript'</span>);</code></pre>
|
||||
<p>When you post a message, the plugin can send back a <code>response</code> thus
|
||||
allowing two-way communication:</p>
|
||||
<pre><code class="language-javascript"><span class="hljs-keyword">await</span> joplin.contentScripts.onMessage(contentScriptId, <span class="hljs-function">(<span class="hljs-params">message</span>) =></span> {
|
||||
<span class="hljs-comment">// Process message</span>
|
||||
<span class="hljs-keyword">return</span> response; <span class="hljs-comment">// Can be any object, string or number</span>
|
||||
});</code></pre>
|
||||
<p>See <a href="../classes/joplincontentscripts.html#onmessage">JoplinContentScripts.onMessage</a> for more details, as well as
|
||||
the <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages">postMessage
|
||||
demo</a>.</p>
|
||||
</div>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-enum-member tsd-parent-kind-enum">
|
||||
@ -176,43 +190,51 @@
|
||||
<h2>Exported members</h2>
|
||||
</a>
|
||||
<ul>
|
||||
<li><p>The <code>context</code> argument is currently unused but could be used later
|
||||
on to provide access to your own plugin so that the content script
|
||||
and plugin can communicate.</p>
|
||||
<li><p>The <code>context</code> argument is currently unused but could be used later on
|
||||
to provide access to your own plugin so that the content script and
|
||||
plugin can communicate.</p>
|
||||
</li>
|
||||
<li><p>The <strong>required</strong> <code>plugin</code> key is the actual Markdown-It plugin -
|
||||
check the [official
|
||||
doc](<a href="https://github.com/markdown-it/markdown-it">https://github.com/markdown-it/markdown-it</a>) for more
|
||||
<li><p>The <strong>required</strong> <code>plugin</code> key is the actual Markdown-It plugin - check
|
||||
the <a href="https://github.com/markdown-it/markdown-it">official doc</a> for more
|
||||
information. The <code>options</code> parameter is of type
|
||||
<a href="https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts">RuleOptions</a>,
|
||||
which contains a number of options, mostly useful for Joplin's
|
||||
internal code.</p>
|
||||
which contains a number of options, mostly useful for Joplin's internal
|
||||
code.</p>
|
||||
</li>
|
||||
<li><p>Using the <strong>optional</strong> <code>assets</code> key you may specify assets such as
|
||||
JS or CSS that should be loaded in the rendered HTML document.
|
||||
Check for example the Joplin [Mermaid
|
||||
<li><p>Using the <strong>optional</strong> <code>assets</code> key you may specify assets such as JS
|
||||
or CSS that should be loaded in the rendered HTML document. Check for
|
||||
example the Joplin [Mermaid
|
||||
plugin](<a href="https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts">https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts</a>)
|
||||
to see how the data should be structured.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<a href="#passing-messages-from-the-content-script-to-your-plugin" id="passing-messages-from-the-content-script-to-your-plugin" style="color: inherit; text-decoration: none;">
|
||||
<h2>Passing messages from the content script to your plugin</h2>
|
||||
<a href="#posting-messages-from-the-content-script-to-your-plugin" id="posting-messages-from-the-content-script-to-your-plugin" style="color: inherit; text-decoration: none;">
|
||||
<h2>Posting messages from the content script to your plugin</h2>
|
||||
</a>
|
||||
<p>The application provides the following function to allow executing
|
||||
commands from the rendered HTML code:</p>
|
||||
<p><code>webviewApi.executeCommand(commandName, ...args)</code></p>
|
||||
<p>So you can use this mechanism to pass messages from the note viewer
|
||||
to your own plugin. To do so you would define a command, using
|
||||
<code>joplin.commands.register</code>, then you would call this command using
|
||||
the <code>webviewApi</code> object. See again <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script">the
|
||||
demo</a>
|
||||
to see how this can be done.</p>
|
||||
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> response = <span class="hljs-keyword">await</span> webviewApi.postMessage(contentScriptId, message);</code></pre>
|
||||
<ul>
|
||||
<li><code>contentScriptId</code> is the ID you've defined when you registered the
|
||||
content script. You can retrieve it from the
|
||||
<a href="../interfaces/contentscriptcontext.html">context</a>.</li>
|
||||
<li><code>message</code> can be any basic JavaScript type (number, string, plain
|
||||
object), but it cannot be a function or class instance.</li>
|
||||
</ul>
|
||||
<p>When you post a message, the plugin can send back a <code>response</code> thus
|
||||
allowing two-way communication:</p>
|
||||
<pre><code class="language-javascript"><span class="hljs-keyword">await</span> joplin.contentScripts.onMessage(contentScriptId, <span class="hljs-function">(<span class="hljs-params">message</span>) =></span> {
|
||||
<span class="hljs-comment">// Process message</span>
|
||||
<span class="hljs-keyword">return</span> response; <span class="hljs-comment">// Can be any object, string or number</span>
|
||||
});</code></pre>
|
||||
<p>See <a href="../classes/joplincontentscripts.html#onmessage">JoplinContentScripts.onMessage</a> for more details, as well as
|
||||
the <a href="https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages">postMessage
|
||||
demo</a>.</p>
|
||||
<a href="#registering-an-existing-markdown-it-plugin" id="registering-an-existing-markdown-it-plugin" style="color: inherit; text-decoration: none;">
|
||||
<h2>Registering an existing Markdown-it plugin</h2>
|
||||
</a>
|
||||
<p>To include a regular Markdown-It plugin, that doesn't make use of
|
||||
any Joplin-specific features, you would simply create a file such as
|
||||
this:</p>
|
||||
<p>To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
Joplin-specific features, you would simply create a file such as this:</p>
|
||||
<pre><code class="language-javascript"><span class="hljs-built_in">module</span>.exports = {
|
||||
<span class="hljs-attr">default</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">context</span>) </span>{
|
||||
<span class="hljs-keyword">return</span> {
|
||||
|
||||
@ -82,6 +82,7 @@
|
||||
<ul class="tsd-index-list">
|
||||
<li class="tsd-kind-class"><a href="classes/joplin.html" class="tsd-kind-icon">Joplin</a></li>
|
||||
<li class="tsd-kind-class"><a href="classes/joplincommands.html" class="tsd-kind-icon">Joplin<wbr>Commands</a></li>
|
||||
<li class="tsd-kind-class"><a href="classes/joplincontentscripts.html" class="tsd-kind-icon">Joplin<wbr>Content<wbr>Scripts</a></li>
|
||||
<li class="tsd-kind-class"><a href="classes/joplindata.html" class="tsd-kind-icon">Joplin<wbr>Data</a></li>
|
||||
<li class="tsd-kind-class"><a href="classes/joplininterop.html" class="tsd-kind-icon">Joplin<wbr>Interop</a></li>
|
||||
<li class="tsd-kind-class"><a href="classes/joplinplugins.html" class="tsd-kind-icon">Joplin<wbr>Plugins</a></li>
|
||||
@ -101,6 +102,7 @@
|
||||
<li class="tsd-kind-interface"><a href="interfaces/buttonspec.html" class="tsd-kind-icon">Button<wbr>Spec</a></li>
|
||||
<li class="tsd-kind-interface"><a href="interfaces/changeevent.html" class="tsd-kind-icon">Change<wbr>Event</a></li>
|
||||
<li class="tsd-kind-interface"><a href="interfaces/command.html" class="tsd-kind-icon">Command</a></li>
|
||||
<li class="tsd-kind-interface"><a href="interfaces/contentscriptcontext.html" class="tsd-kind-icon">Content<wbr>Script<wbr>Context</a></li>
|
||||
<li class="tsd-kind-interface"><a href="interfaces/createmenuitemoptions.html" class="tsd-kind-icon">Create<wbr>Menu<wbr>Item<wbr>Options</a></li>
|
||||
<li class="tsd-kind-interface"><a href="interfaces/dialogresult.html" class="tsd-kind-icon">Dialog<wbr>Result</a></li>
|
||||
<li class="tsd-kind-interface"><a href="interfaces/disposable.html" class="tsd-kind-icon">Disposable</a></li>
|
||||
@ -125,6 +127,7 @@
|
||||
<li class="tsd-kind-type-alias"><a href="globals.html#changehandler" class="tsd-kind-icon">Change<wbr>Handler</a></li>
|
||||
<li class="tsd-kind-type-alias"><a href="globals.html#itemchangehandler" class="tsd-kind-icon">Item<wbr>Change<wbr>Handler</a></li>
|
||||
<li class="tsd-kind-type-alias"><a href="globals.html#path" class="tsd-kind-icon">Path</a></li>
|
||||
<li class="tsd-kind-type-alias"><a href="globals.html#postmessagehandler" class="tsd-kind-icon">Post<wbr>Message<wbr>Handler</a></li>
|
||||
<li class="tsd-kind-type-alias"><a href="globals.html#syncstarthandler" class="tsd-kind-icon">Sync<wbr>Start<wbr>Handler</a></li>
|
||||
<li class="tsd-kind-type-alias"><a href="globals.html#viewhandle" class="tsd-kind-icon">View<wbr>Handle</a></li>
|
||||
</ul>
|
||||
@ -234,6 +237,41 @@
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-type-alias">
|
||||
<a name="postmessagehandler" class="tsd-anchor"></a>
|
||||
<h3>Post<wbr>Message<wbr>Handler</h3>
|
||||
<div class="tsd-signature tsd-kind-icon">Post<wbr>Message<wbr>Handler<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span>id<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span>, message<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> => </span><span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">></span></div>
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-type-declaration">
|
||||
<h4>Type declaration</h4>
|
||||
<ul class="tsd-parameters">
|
||||
<li class="tsd-parameter-signature">
|
||||
<ul class="tsd-signatures tsd-kind-type-literal tsd-parent-kind-type-alias">
|
||||
<li class="tsd-signature tsd-kind-icon"><span class="tsd-signature-symbol">(</span>id<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span>, message<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">></span></li>
|
||||
</ul>
|
||||
<ul class="tsd-descriptions">
|
||||
<li class="tsd-description">
|
||||
<h4 class="tsd-parameters-title">Parameters</h4>
|
||||
<ul class="tsd-parameters">
|
||||
<li>
|
||||
<h5>id: <span class="tsd-signature-type">string</span></h5>
|
||||
</li>
|
||||
<li>
|
||||
<h5>message: <span class="tsd-signature-type">any</span></h5>
|
||||
</li>
|
||||
</ul>
|
||||
<!-- JOPLINCHANGE
|
||||
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol"><</span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">></span></h4>
|
||||
|
||||
|
||||
-->
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-type-alias">
|
||||
<a name="syncstarthandler" class="tsd-anchor"></a>
|
||||
<h3>Sync<wbr>Start<wbr>Handler</h3>
|
||||
@ -351,6 +389,9 @@
|
||||
<li class=" tsd-kind-class">
|
||||
<a href="classes/joplincommands.html" class="tsd-kind-icon">joplin.commands</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-class">
|
||||
<a href="classes/joplincontentscripts.html" class="tsd-kind-icon">joplin.contentScripts</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-class">
|
||||
<a href="classes/joplindata.html" class="tsd-kind-icon">joplin.data</a>
|
||||
</li>
|
||||
@ -393,6 +434,9 @@
|
||||
<li class=" tsd-kind-interface">
|
||||
<a href="interfaces/command.html" class="tsd-kind-icon">Command</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-interface">
|
||||
<a href="interfaces/contentscriptcontext.html" class="tsd-kind-icon">ContentScriptContext</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-interface">
|
||||
<a href="interfaces/createmenuitemoptions.html" class="tsd-kind-icon">CreateMenuItemOptions</a>
|
||||
</li>
|
||||
@ -450,6 +494,9 @@
|
||||
<li class=" tsd-kind-type-alias">
|
||||
<a href="globals.html#path" class="tsd-kind-icon">Path</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-type-alias">
|
||||
<a href="globals.html#postmessagehandler" class="tsd-kind-icon">PostMessageHandler</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-type-alias">
|
||||
<a href="globals.html#syncstarthandler" class="tsd-kind-icon">SyncStartHandler</a>
|
||||
</li>
|
||||
|
||||
@ -107,6 +107,9 @@
|
||||
<li class=" tsd-kind-class">
|
||||
<a href="classes/joplincommands.html" class="tsd-kind-icon">joplin.commands</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-class">
|
||||
<a href="classes/joplincontentscripts.html" class="tsd-kind-icon">joplin.contentScripts</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-class">
|
||||
<a href="classes/joplindata.html" class="tsd-kind-icon">joplin.data</a>
|
||||
</li>
|
||||
@ -149,6 +152,9 @@
|
||||
<li class=" tsd-kind-interface">
|
||||
<a href="interfaces/command.html" class="tsd-kind-icon">Command</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-interface">
|
||||
<a href="interfaces/contentscriptcontext.html" class="tsd-kind-icon">ContentScriptContext</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-interface">
|
||||
<a href="interfaces/createmenuitemoptions.html" class="tsd-kind-icon">CreateMenuItemOptions</a>
|
||||
</li>
|
||||
@ -206,6 +212,9 @@
|
||||
<li class=" tsd-kind-type-alias">
|
||||
<a href="globals.html#path" class="tsd-kind-icon">Path</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-type-alias">
|
||||
<a href="globals.html#postmessagehandler" class="tsd-kind-icon">PostMessageHandler</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-type-alias">
|
||||
<a href="globals.html#syncstarthandler" class="tsd-kind-icon">SyncStartHandler</a>
|
||||
</li>
|
||||
|
||||
@ -0,0 +1,200 @@
|
||||
<!doctype html>
|
||||
<html class="default no-js">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<title>ContentScriptContext | Joplin Plugin API Documentation</title>
|
||||
<meta name="description" content="Documentation for Joplin Plugin API Documentation">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<link rel="stylesheet" href="../assets/css/main.css">
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<div class="tsd-page-toolbar">
|
||||
<div class="container">
|
||||
<div class="table-wrap">
|
||||
<div class="table-cell" id="tsd-search" data-index="../assets/js/search.json" data-base="..">
|
||||
<div class="field">
|
||||
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
|
||||
<input id="tsd-search-field" type="text" />
|
||||
</div>
|
||||
<ul class="results">
|
||||
<li class="state loading">Preparing search index...</li>
|
||||
<li class="state failure">The search index is not available</li>
|
||||
</ul>
|
||||
<a href="../classes/joplin.html" class="title">Joplin Plugin API Documentation</a>
|
||||
</div>
|
||||
<div class="table-cell" id="tsd-widgets">
|
||||
<div id="tsd-filter">
|
||||
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
|
||||
<div class="tsd-filter-group">
|
||||
<div class="tsd-select" id="tsd-filter-visibility">
|
||||
<span class="tsd-select-label">All</span>
|
||||
<ul class="tsd-select-list">
|
||||
<li data-value="public">Public</li>
|
||||
<li data-value="protected">Public/Protected</li>
|
||||
<li data-value="private" class="selected">All</li>
|
||||
</ul>
|
||||
</div>
|
||||
<input type="checkbox" id="tsd-filter-inherited" checked />
|
||||
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
|
||||
</div>
|
||||
</div>
|
||||
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="tsd-page-title">
|
||||
<div class="container">
|
||||
<ul class="tsd-breadcrumb">
|
||||
<!--
|
||||
<li>
|
||||
<a href="../globals.html">Globals</a>
|
||||
</li>
|
||||
-->
|
||||
<li>
|
||||
<a href="contentscriptcontext.html">ContentScriptContext</a>
|
||||
</li>
|
||||
</ul>
|
||||
<h1><!-- Interface -->ContentScriptContext</h1>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<div class="container container-main">
|
||||
<div class="row">
|
||||
<div class="col-8 col-content">
|
||||
<section class="tsd-panel tsd-comment">
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>When a content script is initialised, it receives a <code>context</code> object.</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<!--
|
||||
<section class="tsd-panel tsd-hierarchy">
|
||||
<h3>Hierarchy</h3>
|
||||
<ul class="tsd-hierarchy">
|
||||
<li>
|
||||
<span class="target">ContentScriptContext</span>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</section>
|
||||
-->
|
||||
<section class="tsd-panel-group tsd-index-group">
|
||||
<h2>Index</h2>
|
||||
<section class="tsd-panel tsd-index-panel">
|
||||
<div class="tsd-index-content">
|
||||
<section class="tsd-index-section ">
|
||||
<h3>Properties</h3>
|
||||
<ul class="tsd-index-list">
|
||||
<li class="tsd-kind-property tsd-parent-kind-interface"><a href="contentscriptcontext.html#contentscriptid" class="tsd-kind-icon">content<wbr>Script<wbr>Id</a></li>
|
||||
<li class="tsd-kind-property tsd-parent-kind-interface"><a href="contentscriptcontext.html#pluginid" class="tsd-kind-icon">plugin<wbr>Id</a></li>
|
||||
<li class="tsd-kind-property tsd-parent-kind-interface"><a href="contentscriptcontext.html#postmessage" class="tsd-kind-icon">post<wbr>Message</a></li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
<section class="tsd-panel-group tsd-member-group ">
|
||||
<h2>Properties</h2>
|
||||
<section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface">
|
||||
<a name="contentscriptid" class="tsd-anchor"></a>
|
||||
<h3>content<wbr>Script<wbr>Id</h3>
|
||||
<div class="tsd-signature tsd-kind-icon">content<wbr>Script<wbr>Id<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div>
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>The content script ID, which may be necessary to post messages</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface">
|
||||
<a name="pluginid" class="tsd-anchor"></a>
|
||||
<h3>plugin<wbr>Id</h3>
|
||||
<div class="tsd-signature tsd-kind-icon">plugin<wbr>Id<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div>
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>The plugin ID that registered this content script</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
<section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface">
|
||||
<a name="postmessage" class="tsd-anchor"></a>
|
||||
<h3>post<wbr>Message</h3>
|
||||
<div class="tsd-signature tsd-kind-icon">post<wbr>Message<span class="tsd-signature-symbol">:</span> <a href="../globals.html#postmessagehandler" class="tsd-signature-type">PostMessageHandler</a></div>
|
||||
<aside class="tsd-sources">
|
||||
</aside>
|
||||
<div class="tsd-comment tsd-typography">
|
||||
<div class="lead">
|
||||
<p>Can be used by CodeMirror content scripts to post a message to the plugin</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
</div>
|
||||
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
|
||||
<!--
|
||||
<nav class="tsd-navigation primary">
|
||||
<ul>
|
||||
<li class="globals ">
|
||||
<a href="../globals.html"><em>Globals</em></a>
|
||||
</li>
|
||||
</ul>
|
||||
</nav>
|
||||
-->
|
||||
<nav class="tsd-navigation secondary menu-sticky">
|
||||
<ul class="before-current">
|
||||
</ul>
|
||||
<ul class="current">
|
||||
<li class="current tsd-kind-interface">
|
||||
<a href="contentscriptcontext.html" class="tsd-kind-icon">ContentScriptContext</a>
|
||||
<ul>
|
||||
<li class=" tsd-kind-property tsd-parent-kind-interface">
|
||||
<a href="contentscriptcontext.html#contentscriptid" class="tsd-kind-icon">content<wbr>Script<wbr>Id</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-property tsd-parent-kind-interface">
|
||||
<a href="contentscriptcontext.html#pluginid" class="tsd-kind-icon">plugin<wbr>Id</a>
|
||||
</li>
|
||||
<li class=" tsd-kind-property tsd-parent-kind-interface">
|
||||
<a href="contentscriptcontext.html#postmessage" class="tsd-kind-icon">post<wbr>Message</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul class="after-current">
|
||||
</ul>
|
||||
</nav>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- JOPLINCHANGE
|
||||
<footer class="with-border-bottom">
|
||||
<div class="container">
|
||||
<h2>Legend</h2>
|
||||
<div class="tsd-legend-group">
|
||||
<ul class="tsd-legend">
|
||||
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
|
||||
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
|
||||
</ul>
|
||||
<ul class="tsd-legend">
|
||||
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
|
||||
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
<div class="container tsd-generator">
|
||||
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
|
||||
</div>
|
||||
-->
|
||||
<div class="overlay"></div>
|
||||
<script src="../assets/js/main.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@ -3,5 +3,8 @@ node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
dist/*
|
||||
*.jpl
|
||||
|
||||
@ -8,3 +8,6 @@ tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/codemirror_content_script/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/codemirror_content_script/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -24,4 +24,4 @@
|
||||
"webpack-cli": "^3.3.11",
|
||||
"chalk": "^4.1.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -5,7 +5,7 @@ import { MenuItemLocation } from 'api/types';
|
||||
joplin.plugins.register({
|
||||
onStart: async function() {
|
||||
console.info('Match Highlighter started!');
|
||||
await joplin.plugins.registerContentScript(
|
||||
await joplin.contentScripts.register(
|
||||
ContentScriptType.CodeMirrorPlugin,
|
||||
'matchHighlighter',
|
||||
'./joplinMatchHighlighter.js'
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/content_script/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/content_script/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -711,14 +711,39 @@
|
||||
"dev": true
|
||||
},
|
||||
"chalk": {
|
||||
"version": "2.4.2",
|
||||
"resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz",
|
||||
"integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==",
|
||||
"version": "4.1.0",
|
||||
"resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.0.tgz",
|
||||
"integrity": "sha512-qwx12AxXe2Q5xQ43Ac//I6v5aXTipYrSESdOgzrN+9XjgEpyjpKuvSGaN4qE93f7TQTlerQQ8S+EQ0EyDoVL1A==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"ansi-styles": "^3.2.1",
|
||||
"escape-string-regexp": "^1.0.5",
|
||||
"supports-color": "^5.3.0"
|
||||
"ansi-styles": "^4.1.0",
|
||||
"supports-color": "^7.1.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"ansi-styles": {
|
||||
"version": "4.3.0",
|
||||
"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
|
||||
"integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"color-convert": "^2.0.1"
|
||||
}
|
||||
},
|
||||
"color-convert": {
|
||||
"version": "2.0.1",
|
||||
"resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
|
||||
"integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"color-name": "~1.1.4"
|
||||
}
|
||||
},
|
||||
"color-name": {
|
||||
"version": "1.1.4",
|
||||
"resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
|
||||
"integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
|
||||
"dev": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"chokidar": {
|
||||
@ -3471,12 +3496,20 @@
|
||||
}
|
||||
},
|
||||
"supports-color": {
|
||||
"version": "5.5.0",
|
||||
"resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
|
||||
"integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==",
|
||||
"version": "7.2.0",
|
||||
"resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
|
||||
"integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"has-flag": "^3.0.0"
|
||||
"has-flag": "^4.0.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"has-flag": {
|
||||
"version": "4.0.0",
|
||||
"resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
|
||||
"integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
|
||||
"dev": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"tapable": {
|
||||
@ -3778,6 +3811,17 @@
|
||||
"semver": "^6.0.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"chalk": {
|
||||
"version": "2.4.2",
|
||||
"resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz",
|
||||
"integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"ansi-styles": "^3.2.1",
|
||||
"escape-string-regexp": "^1.0.5",
|
||||
"supports-color": "^5.3.0"
|
||||
}
|
||||
},
|
||||
"json5": {
|
||||
"version": "1.0.1",
|
||||
"resolved": "https://registry.npmjs.org/json5/-/json5-1.0.1.tgz",
|
||||
@ -3797,6 +3841,15 @@
|
||||
"emojis-list": "^3.0.0",
|
||||
"json5": "^1.0.1"
|
||||
}
|
||||
},
|
||||
"supports-color": {
|
||||
"version": "5.5.0",
|
||||
"resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
|
||||
"integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"has-flag": "^3.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
@ -4428,6 +4481,28 @@
|
||||
"yargs": "^13.3.2"
|
||||
},
|
||||
"dependencies": {
|
||||
"chalk": {
|
||||
"version": "2.4.2",
|
||||
"resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz",
|
||||
"integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"ansi-styles": "^3.2.1",
|
||||
"escape-string-regexp": "^1.0.5",
|
||||
"supports-color": "^5.3.0"
|
||||
},
|
||||
"dependencies": {
|
||||
"supports-color": {
|
||||
"version": "5.5.0",
|
||||
"resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
|
||||
"integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"has-flag": "^3.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"json5": {
|
||||
"version": "1.0.1",
|
||||
"resolved": "https://registry.npmjs.org/json5/-/json5-1.0.1.tgz",
|
||||
|
||||
@ -19,10 +19,14 @@ joplin.plugins.register({
|
||||
},
|
||||
});
|
||||
|
||||
await joplin.plugins.registerContentScript(
|
||||
await joplin.contentScripts.register(
|
||||
ContentScriptType.MarkdownItPlugin,
|
||||
'justtesting',
|
||||
'./markdownItTestPlugin.js'
|
||||
);
|
||||
|
||||
await joplin.contentScripts.onMessage('justtesting', (message:any) => {
|
||||
return message + '+response';
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
@ -1,26 +1,33 @@
|
||||
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);
|
||||
};
|
||||
|
||||
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: <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>
|
||||
`;
|
||||
};
|
||||
}
|
||||
|
||||
export default function(_context) {
|
||||
export default function(context) {
|
||||
return {
|
||||
plugin: plugin,
|
||||
plugin: function(markdownIt, _options) {
|
||||
const pluginId = context.pluginId;
|
||||
|
||||
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);
|
||||
|
||||
const postMessageWithResponseTest = `
|
||||
webviewApi.postMessage('${pluginId}', 'justtesting').then(function(response) {
|
||||
console.info('Got response in content script: ' + response);
|
||||
});
|
||||
return false;
|
||||
`;
|
||||
|
||||
return `
|
||||
<div class="just-testing">
|
||||
<p>JUST TESTING: <pre>${leftPad(token.content.trim(), 10, 'x')}</pre></p>
|
||||
<p><a href="#" onclick="${postMessageWithResponseTest.replace(/\n/g, ' ')}">Click to post a message "justtesting" to plugin and check the response in the console</a></p>
|
||||
</div>
|
||||
`;
|
||||
};
|
||||
},
|
||||
assets: function() {
|
||||
return [
|
||||
{ name: 'markdownItTestPlugin.css' }
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/dialog/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/dialog/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/editor_context_menu/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/editor_context_menu/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/events/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/events/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/jpl_test/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/jpl_test/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/json_export/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/json_export/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/menu/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/menu/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
@ -2,3 +2,6 @@ dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -7,3 +7,6 @@
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ The file that may cause problem is "webpack.config.js" because it's going to be
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinplugins.html#registercontentscript) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ import JoplinCommands from './JoplinCommands';
|
||||
import JoplinViews from './JoplinViews';
|
||||
import JoplinInterop from './JoplinInterop';
|
||||
import JoplinSettings from './JoplinSettings';
|
||||
import JoplinContentScripts from './JoplinContentScripts';
|
||||
/**
|
||||
* This is the main entry point to the Joplin API. You can access various services using the provided accessors.
|
||||
*
|
||||
@ -31,10 +32,12 @@ export default class Joplin {
|
||||
private views_;
|
||||
private interop_;
|
||||
private settings_;
|
||||
private contentScripts_;
|
||||
constructor(implementation: any, plugin: Plugin, store: any);
|
||||
get data(): JoplinData;
|
||||
get plugins(): JoplinPlugins;
|
||||
get workspace(): JoplinWorkspace;
|
||||
get contentScripts(): JoplinContentScripts;
|
||||
/**
|
||||
* @ignore
|
||||
*
|
||||
|
||||
32
packages/app-cli/tests/support/plugins/multi_selection/api/JoplinContentScripts.d.ts
vendored
Normal file
32
packages/app-cli/tests/support/plugins/multi_selection/api/JoplinContentScripts.d.ts
vendored
Normal file
@ -0,0 +1,32 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { ContentScriptType } from './types';
|
||||
export default class JoplinContentScripts {
|
||||
private plugin;
|
||||
constructor(plugin: Plugin);
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* The plugin generator provides a way to build any content script you might
|
||||
* want to package as well as its dependencies. See the [Plugin Generator
|
||||
* doc](https://github.com/laurent22/joplin/blob/dev/packages/generator-joplin/README.md)
|
||||
* for more information.
|
||||
*
|
||||
* * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
*/
|
||||
register(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
onMessage(id: string, callback: any): Promise<void>;
|
||||
}
|
||||
@ -20,28 +20,7 @@ export default class JoplinPlugins {
|
||||
*/
|
||||
register(script: Script): Promise<void>;
|
||||
/**
|
||||
* Registers a new content script. Unlike regular plugin code, which runs in
|
||||
* a separate process, content scripts run within the main process code and
|
||||
* thus allow improved performances and more customisations in specific
|
||||
* cases. It can be used for example to load a Markdown or editor plugin.
|
||||
*
|
||||
* Note that registering a content script in itself will do nothing - it
|
||||
* will only be loaded in specific cases by the relevant app modules (eg.
|
||||
* the Markdown renderer or the code editor). So it is not a way to inject
|
||||
* and run arbitrary code in the app, which for safety and performance
|
||||
* reasons is not supported.
|
||||
*
|
||||
* 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)
|
||||
*
|
||||
* @param type Defines how the script will be used. See the type definition for more information about each supported type.
|
||||
* @param id A unique ID for the content script.
|
||||
* @param scriptPath Must be a path relative to the plugin main script. For example, if your file content_script.js is next to your index.ts file, you would set `scriptPath` to `"./content_script.js`.
|
||||
* @deprecated Use joplin.contentScripts.register()
|
||||
*/
|
||||
registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
|
||||
}
|
||||
|
||||
@ -1,5 +1,12 @@
|
||||
import Plugin from '../Plugin';
|
||||
import { SettingItem, SettingSection } from './types';
|
||||
export interface ChangeEvent {
|
||||
/**
|
||||
* Setting keys that have been changed
|
||||
*/
|
||||
keys: string[];
|
||||
}
|
||||
export declare type ChangeHandler = (event: ChangeEvent) => void;
|
||||
/**
|
||||
* This API allows registering new settings and setting sections, as well as getting and setting settings. Once a setting has been registered it will appear in the config screen and be editable by the user.
|
||||
*
|
||||
@ -12,6 +19,7 @@ import { SettingItem, SettingSection } from './types';
|
||||
export default class JoplinSettings {
|
||||
private plugin_;
|
||||
constructor(plugin: Plugin);
|
||||
private get keyPrefix();
|
||||
private namespacedKey;
|
||||
/**
|
||||
* Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
|
||||
@ -40,4 +48,10 @@ export default class JoplinSettings {
|
||||
* https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
|
||||
*/
|
||||
globalValue(key: string): Promise<any>;
|
||||
/**
|
||||
* Called when one or multiple settings of your plugin have been changed.
|
||||
* - For performance reasons, this event is triggered with a delay.
|
||||
* - You will only get events for your own plugin settings.
|
||||
*/
|
||||
onChange(handler: ChangeHandler): Promise<void>;
|
||||
}
|
||||
|
||||
@ -28,6 +28,22 @@ export default class JoplinViewsPanels {
|
||||
addScript(handle: ViewHandle, scriptPath: string): Promise<void>;
|
||||
/**
|
||||
* Called when a message is sent from the webview (using postMessage).
|
||||
*
|
||||
* To post a message from the webview to the plugin use:
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(message);
|
||||
* ```
|
||||
*
|
||||
* - `message` can be any JavaScript object, string or number
|
||||
* - `response` is whatever was returned by the `onMessage` handler
|
||||
*
|
||||
* Using this mechanism, you can have two-way communication between the
|
||||
* plugin and webview.
|
||||
*
|
||||
* See the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages) for more details.
|
||||
*
|
||||
*/
|
||||
onMessage(handle: ViewHandle, callback: Function): Promise<void>;
|
||||
/**
|
||||
|
||||
@ -366,9 +366,31 @@ export interface SettingSection {
|
||||
export type Path = string[];
|
||||
|
||||
// =================================================================
|
||||
// Plugins type
|
||||
// Content Script types
|
||||
// =================================================================
|
||||
|
||||
export type PostMessageHandler = (id: string, message: any)=> Promise<any>;
|
||||
|
||||
/**
|
||||
* When a content script is initialised, it receives a `context` object.
|
||||
*/
|
||||
export interface ContentScriptContext {
|
||||
/**
|
||||
* The plugin ID that registered this content script
|
||||
*/
|
||||
pluginId: string;
|
||||
|
||||
/**
|
||||
* The content script ID, which may be necessary to post messages
|
||||
*/
|
||||
contentScriptId: string;
|
||||
|
||||
/**
|
||||
* Can be used by CodeMirror content scripts to post a message to the plugin
|
||||
*/
|
||||
postMessage: PostMessageHandler;
|
||||
}
|
||||
|
||||
export enum ContentScriptType {
|
||||
/**
|
||||
* Registers a new Markdown-It plugin, which should follow the template
|
||||
@ -394,43 +416,56 @@ export enum ContentScriptType {
|
||||
*
|
||||
* ## Exported members
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin -
|
||||
* check the [official
|
||||
* doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* - The **required** `plugin` key is the actual Markdown-It plugin - check
|
||||
* the [official doc](https://github.com/markdown-it/markdown-it) for more
|
||||
* information. The `options` parameter is of type
|
||||
* [RuleOptions](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml.ts),
|
||||
* which contains a number of options, mostly useful for Joplin's
|
||||
* internal code.
|
||||
* which contains a number of options, mostly useful for Joplin's internal
|
||||
* code.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify assets such as
|
||||
* JS or CSS that should be loaded in the rendered HTML document.
|
||||
* Check for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify assets such as JS
|
||||
* or CSS that should be loaded in the rendered HTML document. Check for
|
||||
* example the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* ## Passing messages from the content script to your plugin
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* The application provides the following function to allow executing
|
||||
* commands from the rendered HTML code:
|
||||
*
|
||||
* `webviewApi.executeCommand(commandName, ...args)`
|
||||
* ```javascript
|
||||
* const response = await webviewApi.postMessage(contentScriptId, message);
|
||||
* ```
|
||||
*
|
||||
* So you can use this mechanism to pass messages from the note viewer
|
||||
* to your own plugin. To do so you would define a command, using
|
||||
* `joplin.commands.register`, then you would call this command using
|
||||
* the `webviewApi` object. See again [the
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
|
||||
* to see how this can be done.
|
||||
* - `contentScriptId` is the ID you've defined when you registered the
|
||||
* content script. You can retrieve it from the
|
||||
* {@link ContentScriptContext | context}.
|
||||
* - `message` can be any basic JavaScript type (number, string, plain
|
||||
* object), but it cannot be a function or class instance.
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
* ## Registering an existing Markdown-it plugin
|
||||
*
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of
|
||||
* any Joplin-specific features, you would simply create a file such as
|
||||
* this:
|
||||
* To include a regular Markdown-It plugin, that doesn't make use of any
|
||||
* Joplin-specific features, you would simply create a file such as this:
|
||||
*
|
||||
* ```javascript
|
||||
* module.exports = {
|
||||
@ -443,6 +478,7 @@ export enum ContentScriptType {
|
||||
* ```
|
||||
*/
|
||||
MarkdownItPlugin = 'markdownItPlugin',
|
||||
|
||||
/**
|
||||
* Registers a new CodeMirror plugin, which should follow the template
|
||||
* below.
|
||||
@ -466,42 +502,65 @@ export enum ContentScriptType {
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* - The `context` argument is currently unused but could be used later
|
||||
* on to provide access to your own plugin so that the content script
|
||||
* and plugin can communicate.
|
||||
* - The `context` argument is currently unused but could be used later on
|
||||
* to provide access to your own plugin so that the content script and
|
||||
* plugin can communicate.
|
||||
*
|
||||
* - The `plugin` key is your CodeMirror plugin. This is where you can
|
||||
* register new commands with CodeMirror or interact with the
|
||||
* CodeMirror instance as needed.
|
||||
* register new commands with CodeMirror or interact with the CodeMirror
|
||||
* instance as needed.
|
||||
*
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources
|
||||
* that will be loaded and attached to the CodeMirror module. These
|
||||
* are made up of addons, keymaps, and modes. For example, for a
|
||||
* plugin that want's to enable clojure highlighting in code blocks.
|
||||
* `codeMirrorResources` would be set to `['mode/clojure/clojure']`.
|
||||
* - The `codeMirrorResources` key is an array of CodeMirror resources that
|
||||
* will be loaded and attached to the CodeMirror module. These are made up
|
||||
* of addons, keymaps, and modes. For example, for a plugin that want's to
|
||||
* enable clojure highlighting in code blocks. `codeMirrorResources` would
|
||||
* be set to `['mode/clojure/clojure']`.
|
||||
*
|
||||
* - The `codeMirrorOptions` key contains all the
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config)
|
||||
* options that will be set or changed by this plugin. New options
|
||||
* can alse be declared via
|
||||
* [CodeMirror](https://codemirror.net/doc/manual.html#config) options
|
||||
* that will be set or changed by this plugin. New options can alse be
|
||||
* declared via
|
||||
* [`CodeMirror.defineOption`](https://codemirror.net/doc/manual.html#defineOption),
|
||||
* and then have their value set here. For example, a plugin that
|
||||
* enables line numbers would set `codeMirrorOptions` to
|
||||
* `{'lineNumbers': true}`.
|
||||
* and then have their value set here. For example, a plugin that enables
|
||||
* line numbers would set `codeMirrorOptions` to `{'lineNumbers': true}`.
|
||||
*
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS
|
||||
* assets that should be loaded in the rendered HTML document. Check
|
||||
* for example the Joplin [Mermaid
|
||||
* - Using the **optional** `assets` key you may specify **only** CSS assets
|
||||
* that should be loaded in the rendered HTML document. Check for example
|
||||
* the Joplin [Mermaid
|
||||
* plugin](https://github.com/laurent22/joplin/blob/dev/packages/renderer/MdToHtml/rules/mermaid.ts)
|
||||
* to see how the data should be structured.
|
||||
*
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions`
|
||||
* keys must be provided for the plugin to be valid. Having multiple or
|
||||
* all provided is also okay.
|
||||
* One of the `plugin`, `codeMirrorResources`, or `codeMirrorOptions` keys
|
||||
* must be provided for the plugin to be valid. Having multiple or all
|
||||
* provided is also okay.
|
||||
*
|
||||
* See the [demo
|
||||
* See also the [demo
|
||||
* plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
|
||||
* for an example of all these keys being used in one plugin.
|
||||
*
|
||||
* ## Posting messages from the content script to your plugin
|
||||
*
|
||||
* In order to post messages to the plugin, you can use the postMessage
|
||||
* function passed to the {@link ContentScriptContext | context}.
|
||||
*
|
||||
* ```javascript
|
||||
* const response = await context.postMessage('messageFromCodeMirrorContentScript');
|
||||
* ```
|
||||
*
|
||||
* When you post a message, the plugin can send back a `response` thus
|
||||
* allowing two-way communication:
|
||||
*
|
||||
* ```javascript
|
||||
* await joplin.contentScripts.onMessage(contentScriptId, (message) => {
|
||||
* // Process message
|
||||
* return response; // Can be any object, string or number
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See {@link JoplinContentScript.onMessage} for more details, as well as
|
||||
* the [postMessage
|
||||
* demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages).
|
||||
*
|
||||
*/
|
||||
CodeMirrorPlugin = 'codeMirrorPlugin',
|
||||
}
|
||||
|
||||
6
packages/app-cli/tests/support/plugins/post_messages/.gitignore
vendored
Normal file
6
packages/app-cli/tests/support/plugins/post_messages/.gitignore
vendored
Normal file
@ -0,0 +1,6 @@
|
||||
dist/
|
||||
node_modules/
|
||||
publish/
|
||||
|
||||
|
||||
|
||||
@ -0,0 +1,11 @@
|
||||
*.md
|
||||
!README.md
|
||||
/*.jpl
|
||||
/api
|
||||
/src
|
||||
/dist
|
||||
tsconfig.json
|
||||
webpack.config.js
|
||||
|
||||
|
||||
|
||||
@ -0,0 +1,72 @@
|
||||
# generator-joplin
|
||||
|
||||
Scaffolds out a new Joplin plugin
|
||||
|
||||
## Installation
|
||||
|
||||
First, install [Yeoman](http://yeoman.io) and generator-joplin using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).
|
||||
|
||||
```bash
|
||||
npm install -g yo
|
||||
npm install -g generator-joplin
|
||||
```
|
||||
|
||||
Then generate your new project:
|
||||
|
||||
```bash
|
||||
yo joplin
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
To test the generator for development purposes, follow the instructions there: https://yeoman.io/authoring/#running-the-generator
|
||||
This is a template to create a new Joplin plugin.
|
||||
|
||||
## Structure
|
||||
|
||||
The main two files you will want to look at are:
|
||||
|
||||
- `/src/index.ts`, which contains the entry point for the plugin source code.
|
||||
- `/src/manifest.json`, which is the plugin manifest. It contains information such as the plugin a name, version, etc.
|
||||
|
||||
The file `/plugin.config.json` could also be useful if you intend to use [external scripts](#external-script-files), such as content scripts or webview scripts.
|
||||
|
||||
## Building the plugin
|
||||
|
||||
The plugin is built using Webpack, which creates the compiled code in `/dist`. A JPL archive will also be created at the root, which can use to distribute the plugin.
|
||||
|
||||
To build the plugin, simply run `npm run dist`.
|
||||
|
||||
The project is setup to use TypeScript, although you can change the configuration to use plain JavaScript.
|
||||
|
||||
## Publishing the plugin
|
||||
|
||||
To publish the plugin, add it to npmjs.com by running `npm publish`. Later on, a script will pick up your plugin and add it automatically to the Joplin plugin repository as long as the package satisfies these conditions:
|
||||
|
||||
- In `package.json`, the name starts with "joplin-plugin-". For example, "joplin-plugin-toc".
|
||||
- In `package.json`, the keywords include "joplin-plugin".
|
||||
- In the `publish/` directory, there should be a .jpl and .json file (which are built by `npm run dist`)
|
||||
|
||||
In general all this is done automatically by the plugin generator, which will set the name and keywords of package.json, and will put the right files in the "publish" directory. But if something doesn't work and your plugin doesn't appear in the repository, double-check the above conditions.
|
||||
|
||||
## Updating the plugin framework
|
||||
|
||||
To update the plugin framework, run `npm run update`.
|
||||
|
||||
In general this command tries to do the right thing - in particular it's going to merge the changes in package.json and .gitignore instead of overwriting. It will also leave "/src" as well as README.md untouched.
|
||||
|
||||
The file that may cause problem is "webpack.config.js" because it's going to be overwritten. For that reason, if you want to change it, consider creating a separate JavaScript file and include it in webpack.config.js. That way, when you update, you only have to restore the line that include your file.
|
||||
|
||||
## External script files
|
||||
|
||||
By default, the compiler (webpack) is going to compile `src/index.ts` only (as well as any file it imports), and any other file will simply be copied to the plugin package. In some cases this is sufficient, however if you have [content scripts](https://joplinapp.org/api/references/plugin_api/classes/joplincontentscripts.html) or [webview scripts](https://joplinapp.org/api/references/plugin_api/classes/joplinviewspanels.html#addscript) you might want to compile them too, in particular in these two cases:
|
||||
|
||||
- The script is a TypeScript file - in which case it has to be compiled to JavaScript.
|
||||
|
||||
- The script requires modules you've added to package.json. In that case, the script, whether JS or TS, must be compiled so that the dependencies are bundled with the JPL file.
|
||||
|
||||
To get such an external script file to compile, you need to add it to the `extraScripts` array in `plugin.config.json`. The path you add should be relative to /src. For example, if you have a file in "/src/webviews/index.ts", the path should be set to "webviews/index.ts". Once compiled, the file will always be named with a .js extension. So you will get "webviews/index.js" in the plugin package, and that's the path you should use to reference the file.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Laurent Cozic
|
||||
@ -0,0 +1,24 @@
|
||||
# Joplin Plugin
|
||||
|
||||
This is a template to create a new Joplin plugin.
|
||||
|
||||
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 `npm run update`.
|
||||
|
||||
In general this command tries to do the right thing - in particular it's going to merge the changes in package.json and .gitignore instead of overwriting. It will also leave "/src" as well as README.md untouched.
|
||||
|
||||
The file that may cause problem is "webpack.config.js" because it's going to be overwritten. For that reason, if you want to change it, consider creating a separate JavaScript file and include it in webpack.config.js. That way, when you update, you only have to restore the line that include your file.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user