self-hosted/joplin
1
0
Fork 0
mirror of https://github.com/laurent22/joplin.git synced 2025-01-08 13:06:15 +02:00
Code Issues Releases Activity
ca01eb35aa
joplin/docs/spec/plugins/index.html
Laurent Cozic ca01eb35aa Update website
2021-07-10 11:43:35 +01:00

394 lines
17 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<!--
!!! WARNING !!!
This file was auto-generated from readme/spec/plugins.md and any manual change
made to it will be overwritten. To make a change to this file please modify
the source Markdown file:
https://github.com/laurent22/joplin/blob/dev/readme/spec/plugins.md
-->
<head>
<meta
charset="utf-8"
http-equiv="X-UA-Compatible"
content="IE=edge,chrome=1"
/>
<link rel="icon" href="&#x2F;images/favicon.png" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="theme-color" content="#000000" />
<meta name="description" content="Joplin website" />
<link
rel="stylesheet"
href="&#x2F;css/bootstrap5.0.2.min.css"
as="style"
/>
<link rel="stylesheet" href="&#x2F;css/fontawesome-all.min.css?t=1625913797829">
<link
href="https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600;700&display=swap"
rel="stylesheet"
as="style"
media="all"
onload="this.media='all'; this.onload = null"
/>
<link rel="stylesheet" href="&#x2F;css/site.css?t=1625913797829" as="style" />
<title>Plugin system architecture | Joplin</title>
</head>
<body class="website-env-prod">
<div class="container-fluid generic-template -page" id="main-container">
<div class=" navbar-main white-bg" id="nav-section">
<div class="container">
<div class="row">
<div class="col-3">
<a href="/">
<img
src="&#x2F;images/logo-text-blue.svg"
alt=""
id="top-logo"
width="180"
/>
</a>
</div>
<div class="col-9 text-right d-none d-md-block">
<a href="/help/" class="fw500">Help</a>
<a href="https:&#x2F;&#x2F;discourse.joplinapp.org&#x2F;" class="fw500">Forum</a>
<a class="button-link btn-blue donate-button" href="/donate">
<i class="fas fa-heart heart-full"></i><i class="far fa-heart heart-line"></i>&nbsp;Support
</a> </div>
<div class="col-9 text-right d-block d-md-none">
<span class="pointer"
><img
src="&#x2F;images/mobile-menu-black-open-icon.png"
id="open-menu-mobile"
alt=""
/></span>
&nbsp;&nbsp;
<div id="menu-mobile">
<div>
<div class="text-right">
<img
src="&#x2F;images/close-icon.png"
alt=""
class="pointer"
id="close-menu-mobile"
/>
</div>
<div class="text-center menu-mobile-top">
<a href="https:&#x2F;&#x2F;discourse.joplinapp.org&#x2F;" class="fw500 mobile-menu-link">Forum</a>
<a href="/help/" class="fw500 mobile-menu-link">Help</a>
</div>
<div class="menu-mobile-buttons">
<a class="button-link btn-blue donate-button" href="/donate">
<i class="fas fa-heart heart-full"></i><i class="far fa-heart heart-line"></i>&nbsp;Support
</a> </div>
</div>
<div id="toc-mobile"><div><ul>
<li>
<p>Applications</p>
<ul>
<li><a href="/desktop/">Desktop application</a></li>
<li><a href="/mobile/">Mobile applications</a></li>
<li><a href="/terminal/">Terminal application</a></li>
<li><a href="/clipper/">Web Clipper</a></li>
</ul>
</li>
<li>
<p>Support</p>
<ul>
<li><a href="https://discourse.joplinapp.org">Joplin Forum</a></li>
<li><a href="/markdown/">Markdown Guide</a></li>
<li><a href="/e2ee/">How to enable end-to-end encryption</a></li>
<li><a href="/conflict/">What is a conflict?</a></li>
<li><a href="/debugging/">How to enable debug mode</a></li>
<li><a href="/rich_text_editor/">About the Rich Text editor limitations</a></li>
<li><a href="/faq/">FAQ</a></li>
</ul>
</li>
<li>
<p>Joplin API - Get Started</p>
<ul>
<li><a href="/api/overview/">Joplin API Overview</a></li>
<li><a href="/api/get_started/plugins/">Plugin development</a></li>
<li><a href="/api/tutorials/toc_plugin/">Plugin tutorial</a></li>
</ul>
</li>
<li>
<p>Joplin API - References</p>
<ul>
<li><a href="https://joplinapp.org/api/references/plugin_api/classes/joplin.html">Plugin API</a></li>
<li><a href="/api/references/rest_api/">Data API</a></li>
<li><a href="/api/references/plugin_manifest/">Plugin manifest</a></li>
<li><a href="/api/references/plugin_loading_rules/">Plugin loading rules</a></li>
<li><a href="/api/references/plugin_theming/">Plugin theming</a></li>
</ul>
</li>
<li>
<p>Development</p>
<ul>
<li><a href="https://github.com/laurent22/joplin/blob/dev/BUILD.md">How to build the apps</a></li>
<li><a href="/spec/e2ee/">End-to-end encryption spec</a></li>
<li><a href="/spec/history/">Note History spec</a></li>
<li><a href="/spec/sync_lock/">Sync Lock spec</a></li>
<li><a href="/spec/plugins/">Plugin Architecture spec</a></li>
<li><a href="/spec/search_sorting/">Search Sorting spec</a></li>
<li><a href="/spec/server_file_url_format/">Server: File URL Format</a></li>
<li><a href="/spec/server_delta_sync/">Server: Delta Sync</a></li>
<li><a href="/spec/server_sharing/">Server: Sharing</a></li>
</ul>
</li>
<li>
<p>Google Summer of Code 2021</p>
<ul>
<li><a href="/gsoc2021/index/">Google Summer of Code 2021</a></li>
<li><a href="/gsoc2021/pull_request_guidelines/">How to submit a GSoC pull request</a></li>
<li><a href="/gsoc2021/ideas/">Project Ideas</a></li>
</ul>
</li>
<li>
<p>About</p>
<ul>
<li><a href="/changelog/">Changelog (Desktop App)</a></li>
<li><a href="/changelog_cli/">Changelog (CLI App)</a></li>
<li><a href="/changelog_server/">Changelog (Server)</a></li>
<li><a href="/stats/">Stats</a></li>
<li><a href="/donate/">Donate</a></li>
</ul>
</li>
</ul>
</div></div>
<div>
<p class="light-blue mobile-menu-link-bottom text-center">
Copyright (C) 2016-2021 Laurent&nbsp;Cozic
<br/>
<a href="/privacy/" class="fw500">Privacy Policy</a>
</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="page-container page-plugins">
<div class="container">
<div class="row content-wrapper">
<div id="toc"><div><ul>
<li>
<p>Applications</p>
<ul>
<li><a href="/desktop/">Desktop application</a></li>
<li><a href="/mobile/">Mobile applications</a></li>
<li><a href="/terminal/">Terminal application</a></li>
<li><a href="/clipper/">Web Clipper</a></li>
</ul>
</li>
<li>
<p>Support</p>
<ul>
<li><a href="https://discourse.joplinapp.org">Joplin Forum</a></li>
<li><a href="/markdown/">Markdown Guide</a></li>
<li><a href="/e2ee/">How to enable end-to-end encryption</a></li>
<li><a href="/conflict/">What is a conflict?</a></li>
<li><a href="/debugging/">How to enable debug mode</a></li>
<li><a href="/rich_text_editor/">About the Rich Text editor limitations</a></li>
<li><a href="/faq/">FAQ</a></li>
</ul>
</li>
<li>
<p>Joplin API - Get Started</p>
<ul>
<li><a href="/api/overview/">Joplin API Overview</a></li>
<li><a href="/api/get_started/plugins/">Plugin development</a></li>
<li><a href="/api/tutorials/toc_plugin/">Plugin tutorial</a></li>
</ul>
</li>
<li>
<p>Joplin API - References</p>
<ul>
<li><a href="https://joplinapp.org/api/references/plugin_api/classes/joplin.html">Plugin API</a></li>
<li><a href="/api/references/rest_api/">Data API</a></li>
<li><a href="/api/references/plugin_manifest/">Plugin manifest</a></li>
<li><a href="/api/references/plugin_loading_rules/">Plugin loading rules</a></li>
<li><a href="/api/references/plugin_theming/">Plugin theming</a></li>
</ul>
</li>
<li>
<p>Development</p>
<ul>
<li><a href="https://github.com/laurent22/joplin/blob/dev/BUILD.md">How to build the apps</a></li>
<li><a href="/spec/e2ee/">End-to-end encryption spec</a></li>
<li><a href="/spec/history/">Note History spec</a></li>
<li><a href="/spec/sync_lock/">Sync Lock spec</a></li>
<li><a href="/spec/plugins/">Plugin Architecture spec</a></li>
<li><a href="/spec/search_sorting/">Search Sorting spec</a></li>
<li><a href="/spec/server_file_url_format/">Server: File URL Format</a></li>
<li><a href="/spec/server_delta_sync/">Server: Delta Sync</a></li>
<li><a href="/spec/server_sharing/">Server: Sharing</a></li>
</ul>
</li>
<li>
<p>Google Summer of Code 2021</p>
<ul>
<li><a href="/gsoc2021/index/">Google Summer of Code 2021</a></li>
<li><a href="/gsoc2021/pull_request_guidelines/">How to submit a GSoC pull request</a></li>
<li><a href="/gsoc2021/ideas/">Project Ideas</a></li>
</ul>
</li>
<li>
<p>About</p>
<ul>
<li><a href="/changelog/">Changelog (Desktop App)</a></li>
<li><a href="/changelog_cli/">Changelog (CLI App)</a></li>
<li><a href="/changelog_server/">Changelog (Server)</a></li>
<li><a href="/stats/">Stats</a></li>
<li><a href="/donate/">Donate</a></li>
</ul>
</li>
</ul>
</div></div>
<div class="main-content">
<div class="alert alert-danger alert-env-dev" role="alert">
Running in prod mode!
</div>
<div class="donate-links">
<p><a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&amp;business=E8JMYD2LQ8MMA&amp;lc=GB&amp;item_name=Joplin+Development&amp;currency_code=EUR&amp;bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted"><img src="https://joplinapp.org/images/badges/Donate-PayPal-green.svg" alt="Donate using PayPal"></a> <a href="https://github.com/sponsors/laurent22/"><img src="https://joplinapp.org/images/badges/GitHub-Badge.svg" alt="Sponsor on GitHub"></a> <a href="https://www.patreon.com/joplin"><img src="https://joplinapp.org/images/badges/Patreon-Badge.svg" alt="Become a patron"></a> <a href="https://joplinapp.org/donate/#donations"><img src="https://joplinapp.org/images/badges/Donate-IBAN.svg" alt="Donate using IBAN"></a></p>
</div>
<h1>Plugin system architecture<a name="plugin-system-architecture" href="#plugin-system-architecture" class="heading-anchor">🔗</a></h1>
<p>The plugin system assumes a multi-process architecture, which is safer and easier to manage. For example if a plugin freezes or crashes, it doesn't bring down the app with it. It also makes it easier to find the source of problem when there is one - eg. we know that process X has crashed so the problem is with the plugin running inside. The alternative, to run everything within the same process, would make it very hard to make such a diagnostic. Once a plugin call is frozen in an infinite loop or crashes the app, we can't know anything.</p>
<h2>Main architecture elements<a name="main-architecture-elements" href="#main-architecture-elements" class="heading-anchor">🔗</a></h2>
<h3>Plugin script<a name="plugin-script" href="#plugin-script" class="heading-anchor">🔗</a></h3>
<p>Written by the user and loaded by Joplin, it's a simple JavaScript file that makes calls to the plugin API. It is loaded in a separate process.</p>
<h3>Sandbox proxy<a name="sandbox-proxy" href="#sandbox-proxy" class="heading-anchor">🔗</a></h3>
<p>It is loaded in the same process as the plugin script. Whenever the plugin script calls a plugin API function (eg. joplin.commands.execute) it goes through this proxy. The proxy then converts the call to a plain string and use IPC to send the call to the plugin host. The plugin host executes the function on the plugin API then sends back the result by IPC call again.</p>
<h3>Plugin host<a name="plugin-host" href="#plugin-host" class="heading-anchor">🔗</a></h3>
<p>The plugin host is simply the main application. Its role is to start and initialise the plugin service and to load plugins from the provided script files.</p>
<h3>Plugin service<a name="plugin-service" href="#plugin-service" class="heading-anchor">🔗</a></h3>
<p>It is used to load and run plugins. Running plugins is platform-specific, thus this part is injected into the service via a platform-specific Plugin Runner.</p>
<h3>Plugin runner<a name="plugin-runner" href="#plugin-runner" class="heading-anchor">🔗</a></h3>
<p>This is the platform-specfic way to load and run a plugin. For example, on desktop, it creates a new BrowserWindow (which is a new process), then load the script inside. On Cli, for now the &quot;vm&quot; package is used, so the plugin actually runs within the same process.</p>
<p>The plugin runner also initialises the sandbox proxy and injects it into the plugin code.</p>
<h3>Plugin API<a name="plugin-api" href="#plugin-api" class="heading-anchor">🔗</a></h3>
<p>The plugin API is a light wrapper over Joplin's internal functions and services. All the platforms share some of the plugin API but there can also be some differences. For example, the desktop app exposes the text editor component commands, and so this part of the plugin API is available only on desktop. The difference between platforms is implemented using the PlatformImplementation class, which is injected in the plugin service on startup.</p>
<h2>Handling events between the plugin and the host<a name="handling-events-between-the-plugin-and-the-host" href="#handling-events-between-the-plugin-and-the-host" class="heading-anchor">🔗</a></h2>
<p>Handling events in plugins is relatively complicated due to the need to send IPC messages and the limitations of the IPC protocol, which in particular cannot transfer functions.</p>
<p>For example, let's say we define a command in the plugin:</p>
<pre><code class="language-typescript">joplin.commands.register({
name: 'testCommand1',
label: 'My Test Command 1',
}, {
onExecute: (args:any) =&gt; {
alert('Testing plugin command 1');
},
});
</code></pre>
<p>The &quot;onExecute&quot; event handler needs to be called whenever, for example, a toolbar button associated with this command is clicked. The problem is that it is not possible to send a function via IPC (which can only transfer plain objects), so there has to be a translation layer in between.</p>
<p>The way it is done in Joplin is like so:</p>
<p>In the <strong>sandbox proxy</strong>, the event handlers are converted to string event IDs and the original event handler is stored in a map before being sent to host via IPC. So in the example above, the command would be converted to this plain object:</p>
<pre><code class="language-typescript">{
name: 'testCommand1',
label: 'My Test Command 1',
}, {
onExecute: '___event_handler_123',
}
</code></pre>
<p>Then, still in the sandbox proxy, we'll have a map called something like <code>eventHandlers</code>, which now will have this content:</p>
<pre><code class="language-typescript">eventHandlers['___event_handler_123'] = (args:any) =&gt; {
alert('Testing plugin command 1');
}
</code></pre>
<p>In the <strong>plugin runner</strong> (Host side), all the event IDs are converted to functions again, but instead of performing the action directly, it posts an IPC message back to the sandbox proxy using the provided event ID.</p>
<p>So in the host, the command will now look like this:</p>
<pre><code class="language-typescript">{
name: 'testCommand1',
label: 'My Test Command 1',
}, {
onExecute: (args:any) =&gt; {
postMessage('pluginMessage', { eventId: '___event_handler_123', args: args });
};
}
</code></pre>
<p>At this point, any code in the Joplin application can call the <code>onExecute</code> function as normal without having to know about the IPC translation layer.</p>
<p>When the function onExecute is eventually called, the IPC message is sent back to the sandbox proxy, which will decode it and execute it.</p>
<p>So on the <strong>sandbox proxy</strong>, we'll have something like this:</p>
<pre><code class="language-typescript">window.addEventListener('message', ((event) =&gt; {
const eventId = getEventId(event); // Get back the event ID (implementation might be different)
const eventArgs = getEventArgs(event); // Get back the args (implementation might be different)
if (eventId) {
// And call the event handler
eventHandlers[eventId](...eventArgs);
}
}));
</code></pre>
<div class="bottom-links">
<a href="https://github.com/laurent22/joplin/blob/dev/readme/spec/plugins.md">
<i class="fab fa-github"></i> Improve this doc
</a>
</div>
</div>
</div>
</div>
</div>
<footer class="darkblue-bg">
<div class="container">
<div class="row">
<div class="col-3 d-none d-md-block">
<img src="&#x2F;images/logo-text.svg" alt="" width="150" />
</div>
</div>
<div class="row">
<div class="col-12">
<hr />
</div>
</div>
<div class="row">
<div class="col-12 col-md-6">
<img
src="&#x2F;images/logo-text.svg"
width="120"
class="img-center d-block d-md-none"
alt=""
/>
<br class="d-block d-md-none" />
<p class="text-center-sm">Copyright (C) 2016-2021 Laurent Cozic</p>
</div>
<div class="col-12 col-md-6 right-links">
<p class="text-right text-center-sm">
<a href="https://github.com/laurent22/joplin/" class="github-link"><i class="fab fa-github"></i> GitHub Repository</a>
<a href="/privacy/">Privacy Policy</a>
</p>
</div>
</div>
</div>
</footer>
</div>
<script
src="&#x2F;js/jquery-3.6.0.min.js"
rel="preload"
as="script"
></script>
<script src="&#x2F;js/script.js?t=1625913797829"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-103586105-1', 'auto');
ga('send', 'pageview');
</script> </body>
</html>
Reference in New Issue View Git Blame Copy Permalink